Perguntas Frequentes¶

Encontre respostas rápidas para as perguntas mais comuns sobre o ESP32-HTTP-Client. Use as categorias abaixo para ir direto ao que precisa.

Instalação & Configuração
Conceitos Principais & Arquitetura
Sintaxe & Vinculação de JSON
Métodos HTTP & Recursos Avançados
Desempenho & Solução de Problemas

Instalação, Requisitos e Configuração Inicial¶

Como instalo a biblioteca ESP32-HTTP-Client no Arduino IDE?

Vá em Sketch > Incluir Biblioteca > Gerenciar Bibliotecas...
Procure por ESP32-HTTP-Client e clique em Instalar.

Alternativamente, baixe o ZIP no GitHub e adicione via Sketch > Incluir Biblioteca > Adicionar Biblioteca .ZIP...

Quais são os pré-requisitos de hardware e dependências necessárias?

Requisito	Detalhes
Hardware	ESP32 ou microcontrolador compatível
Core	Core padrão do Arduino para ESP32
Dependências	Nenhuma — não requer `ArduinoJson` ou outras bibliotecas externas

A biblioteca vem com seu próprio analisador de fluxo em tempo real (on-the-fly), portanto nenhuma dependência extra é necessária.

Esta biblioteca é compatível com placas ESP8266?

Sim, é compatível

Sim, a biblioteca é compatível com ESP8266 e outras placas compatíveis com Arduino que forneçam interfaces padrão Client. No entanto, observe que o foco principal e as otimizações são voltados especificamente para o ecossistema ESP32.

Como incluo a biblioteca e a inicializo no meu sketch?

#include "ESP32HTTPClient.h"

// Instancie uma vez com sua URL base
ESP32HTTPClient client("https://api.example.com");

void setup() {
    Serial.begin(115200);
    // Configuração do WiFi aqui...

    int value;
    client.get("/endpoint").getBody("field", &value);
}

void loop() {}

Qual configuração é necessária para fazer requisições HTTPS seguras?

Nenhuma configuração necessária

Basta prefixar sua URL com https://. A biblioteca usará automaticamente a porta 443 e lidará com o handshake TLS seguro.

// HTTP  → porta 80 (padrão)
ESP32HTTPClient client("http://api.example.com");

// HTTPS → porta 443 (automático)
ESP32HTTPClient client("https://api.example.com");

Conceitos Principais e Arquitetura¶

O que é o conceito de Vinculação Direta de Variáveis (Direct Variable Binding)?

Vinculação Direta de Variáveis significa associar uma chave JSON da resposta da API diretamente a uma variável C/C++. A biblioteca grava o valor extraído diretamente no endereço de memória da sua variável — nenhuma String intermediária ou JsonDocument é criado.

float temperature; // Sua variável
//       ↓ chave no JSON         ↓ endereço de memória
client.get("/sensor").getBody("temp", &temperature);
//                              └─ valor injetado diretamente aqui

Como funciona a análise do fluxo byte a byte em tempo real?

A biblioteca lê o fluxo da resposta HTTP byte a byte diretamente do buffer de rede:

Fluxo da Rede  →  Analisador busca chave  →  Injeta valor na variável  →  Descarta o restante

Assim que a chave alvo é encontrada e seu valor é copiado para sua variável, os bytes restantes são consumidos e descartados sem nunca serem armazenados na RAM.

Qual é a principal diferença arquitetural em relação ao uso tradicional do ArduinoJson?

Passo	Abordagem Tradicional	ESP32-HTTP-Client
1	`http.getString()` — aloca uma `String` grande	Lê diretamente do fluxo de rede
2	`DynamicJsonDocument(N)` — aloca JSON na heap	Nenhuma alocação de documento
3	`deserializeJson()` — analisa a carga inteira	Valores extraídos em tempo real
4	`doc["key"]` — extração manual	Variáveis preenchidas automaticamente
Sobrecarga de RAM	~58 KB por requisição	~15 bytes por requisição

Por que a biblioteca não exige alocações de buffer na heap para a resposta HTTP?

Porque ela nunca armazena a resposta inteira. O analisador varre o fluxo de caracteres recebidos e injeta imediatamente cada valor desejado em sua variável pré-alocada. Isso resulta em:

Apenas ~15 bytes de heap extra por requisição

Comparado a ~58 KB com a abordagem padrão HTTPClient + ArduinoJson.

Em quais cenários de IoT esta biblioteca é mais recomendada?

Aplicações com restrição de memória — dispositivos com pouca heap livre
Leitura de alta frequência (polling) — ciclos de loop() rápidos que fazem muitas requisições
Backends em nuvem — Firebase, AWS API Gateway, APIs REST
Projetos com uso intendo de HTTPS — o Keep-Alive evita handshakes TLS repetidos
Dispositivos em execução contínua — evita a fragmentação da heap ao longo do tempo

Sintaxe, Vinculação de Dados e Análise de JSON¶

Como mapear um campo simples (int, float ou string) diretamente em uma variável?

InteiroFloatString (char[])Booleano

int count;
client.get("/data").getBody("count", &count);

float temperature;
client.get("/sensor").getBody("temp", &temperature);

char name[64];
client.get("/user").getBody("name", name, sizeof(name));

bool isActive;
client.get("/device").getBody("active", &isActive);

Qual é a sintaxe para extrair dados de objetos JSON aninhados?

Use notação de ponto para navegar em objetos aninhados. Cada segmento separado por . representa um nível de profundidade.

// Resposta da API
{ "sensor": { "location": { "city": "Lisboa" } } }

char city[32];
client.get("/data").getBody("sensor.location.city", city, sizeof(city));
//                          └────────────────────┘
//                         Caminho em notação de ponto

Como posso extrair valores de dentro de arrays JSON?

Use um índice numérico como segmento de caminho para endereçar elementos do array (baseado em zero).

// Resposta da API
[
  { "address": { "city": "Gwenborough" } },
  { "address": { "city": "Wisokyburgh" } }
]

char city[32];
// Obter cidade do SEGUNDO elemento (índice 1)
client.get("/users").getBody("1.address.city", city, sizeof(city));

O que acontece se a chave especificada no getBody() não existir na resposta?

Seguro por design

Se a chave estiver ausente, com erro de digitação ou o caminho não existir, a variável alvo permanece completamente inalterada. A biblioteca não travará, não lançará exceções nem corromperá a memória.

Isso facilita a detecção de campos ausentes — pré-preencha suas variáveis com valores de sentinela:

int userId = -1; // sentinela

client.get("/data").getBody("userId", &userId);

if (userId == -1) {
    Serial.println("Chave não encontrada na resposta!");
}

Como funciona o encadeamento de métodos (API Fluente) para vincular múltiplos campos JSON?

Cada chamada a .getBody() retorna uma referência ao mesmo construtor de requisição, permitindo encadear quantas vinculações forem necessárias em uma única instrução:

int userId;
float temperature;
char city[32];

client.post("/report")
      .body("device", "esp32-cam")
      .body("floor", 3)
      .getBody("userId",          &userId)                  // int
      .getBody("sensor.temp",     &temperature)             // float — aninhado
      .getBody("0.address.city",  city, sizeof(city));      // char* — array + aninhado

Métodos HTTP e Recursos Avançados¶

Como faço requisições POST, PUT e DELETE com corpo de dados?

POSTPUT / AtualizaçãoDELETEPATCH

int newId;
client.post("/users")
      .body("name", "Pedro")
      .body("role", "admin")
      .body("age", 21)
      .getBody("id", &newId);

client.put("/lights/1").body("state", "OFF");
// ou usando o alias:
client.update("/lights/1").body("state", "OFF");

client.del("/logs/system_error.log");

client.patch("/config/wifi").body("ssid", "MinhaRede");

Como posso adicionar autenticação ou cabeçalhos HTTP personalizados?

Use os helpers dedicados de autenticação ou o .setHeader() na instância do cliente. Os cabeçalhos serão enviados com todas as requisições subsequentes.

// Bearer / Token JWT
client.bearer("meu-jwt-token");

// HTTP Basic Auth (codificado em Base64 automaticamente)
client.basic("usuario", "senha");

// Chave de API (API Key)
client.apiKey("x-api-key", "minha-chave-api");

// Cabeçalho HTTP personalizado
client.setHeader("X-Custom-Header", "custom-value");

// Sobrescrever Content-Type
client.setContentType("application/x-www-form-urlencoded");

Tip

Configure a autenticação ou cabeçalhos uma vez durante o setup() e eles persistirão para todas as requisições.

É possível definir uma porta personalizada para a conexão?

Sim, passe a porta como segundo argumento para o construtor:

// Portas padrão: 80 para HTTP, 443 para HTTPS
ESP32HTTPClient client("https://api.example.com");

// Porta personalizada
ESP32HTTPClient client("http://meu-servidor-local.local", 8080);

Como leio o código de status da resposta HTTP e trato erros do servidor?

Chame getStatusCode() no cliente após a requisição ser despachada (ou seja, após chamar .getBody() ou quando o RestRequest sair de escopo):

int userId;
client.get("/users/1").getBody("id", &userId);

int status = client.getStatusCode();

if (status == 200) {
    Serial.println("Sucesso!");
} else {
    Serial.printf("Erro: HTTP %d\n", status);
}

Como posso capturar o corpo da resposta bruta (JSON bruto ou texto simples)?

Vincule a uma String do Arduino passando "" como chave para capturar toda a resposta:

String fullResponse;
client.get("/data").getBody("", &fullResponse);

Para capturar um objeto aninhado ou um elemento específico de array:

String secondUser;
client.get("/users").getBody("1", &secondUser);

Aviso de alocação de heap

Vincular a uma String causa realocação dinâmica de memória à medida que o JSON bruto é copiado caractere por caractere. Evite isso com respostas grandes, pois pode fragmentar ou esgotar a heap do dispositivo.

Desempenho, Memória e Solução de Problemas¶

Quais são as economias reais de memória heap e velocidade de execução?

Os dados a seguir são de um benchmark executando 100 requisições HTTP GET consecutivas contra o endpoint /users do JSONPlaceholder:

Métrica	Padrão (HTTPClient + ArduinoJson)	ESP32-HTTP-Client
Heap por requisição	~58.2 KB	~0.0 KB (15 bytes)
Pegada de RAM	34.2%	24.3%
Heap livre mínima	114.3 KB	128.6 KB
Tempo médio de execução	~750 ms	~59 ms

12x mais rápido, 99.9% menos RAM por requisição

O Keep-Alive reutiliza a conexão TLS, evitando handshakes repetidos. A análise via fluxo elimina todas as alocações de buffers intermediários.

O que acontece se o meu buffer char[] for menor que o valor da string JSON?

Proteção contra estouro de buffer

A biblioteca copiará com segurança apenas a quantidade de caracteres que couber no buffer, até o limite de maxLen informado. Ela nunca gravará além do final do buffer.

char name[8]; // Buffer pequeno
// Se a API retornar "name": "Pedro Fonseca" (13 chars), apenas "Pedro F" será copiado
client.get("/user").getBody("name", name, sizeof(name));

Sempre aloque espaço suficiente para o tamanho máximo esperado do valor.

Como a biblioteca se comporta durante requisições contínuas no loop()?

De forma excelente. Ao manter uma conexão TCP/TLS Keep-Alive persistente, as requisições subsequentes para o mesmo servidor pulam a etapa dispendiosa do handshake:

Primeira requisição: Conexão + Handshake TLS + Requisição → ~750ms
Próximas requisições: Reutiliza conexão + Requisição         → ~59ms  ⚡

void loop() {
    float temp;
    client.get("/sensor").getBody("temp", &temp); // Rápido em cada iteração
    delay(1000);
}

Quais são as melhores práticas para depurar a vinculação de campos?

1. Use valores sentinela — pré-preencha variáveis com um valor visivelmente inválido:

int userId = -999;
client.get("/data").getBody("userId", &userId);

if (userId == -999) Serial.println("⚠ Chave não encontrada!");
else Serial.printf("✔ userId = %d\n", userId);

2. Verifique o código de status — confirme se a requisição em si foi bem-sucedida:

int code = client.getStatusCode();
Serial.printf("Status HTTP: %d\n", code); // Deve ser 200

3. Capture a resposta bruta — vincule temporariamente a uma String para inspecionar todo o conteúdo:

String raw;
client.get("/data").getBody("", &raw);
Serial.println(raw); // Imprime todo o JSON

Como posso evitar problemas de memória durante requisições HTTPS intensas?

Siga estas boas práticas:

Prefira vinculação direta — use getBody("key", &var) para primitivos e arrays char[] fixos
Evite String para respostas grandes — ela fragmenta a heap em realocações repetidas
Chame client.end() — libera o buffer de conexão TLS de ~45 KB quando você terminar uma rajada de requisições
Evite criar múltiplas instâncias do cliente — instancie o ESP32HTTPClient uma vez e reutilize-o

// Após uma sequência de requisições, libere a memória TLS
client.end();

Ainda tem dúvidas?¶

Se você não encontrou a resposta para sua dúvida aqui, sinta-se à vontade para entrar em contato!

GitHub Issues: Abra uma issue no repositório oficial.