title: Referência da Classe ESP32HTTPClient - Métodos e Assinaturas C++ description: Documentação de API completa para a classe ESP32HTTPClient: construtor, métodos de verbos HTTP, cabeçalhos persistentes, autenticação e timeouts. keywords: classe ESP32HTTPClient, construtor ESP32HTTPClient, referencia biblioteca C++ ESP32 HTTP, metodos cliente HTTP ESP32 tags: - api - client - class

ESP32HTTPClient¶

O principal ponto de entrada da biblioteca. Crie uma instância por URL base de servidor e reutilize-a em todas as requisições.

Cabeçalho: #include "ESP32HTTPClient.h"

Construtor¶

`ESP32HTTPClient(baseUrl)`¶

Cria um cliente com seleção automática de porta (80 para HTTP, 443 para HTTPS).

ESP32HTTPClient(const char* baseUrl);

Parâmetros:

Parâmetro	Tipo	Descrição
`baseUrl`	`const char*`	A URL base incluindo protocolo (ex: `"https://api.example.com"`). Não inclua uma barra no final.

Exemplo:

ESP32HTTPClient client("https://api.example.com");

`ESP32HTTPClient(baseUrl, port)`¶

Cria um cliente direcionado a uma porta específica.

ESP32HTTPClient(const char* baseUrl, int port);

Parâmetros:

Parâmetro	Tipo	Descrição
`baseUrl`	`const char*`	A URL base incluindo o protocolo.
`port`	`int`	A porta TCP alvo (ex: `8080`, `443`).

Exemplo:

ESP32HTTPClient client("http://192.168.1.100", 8080);

Métodos de Requisição HTTP¶

Cada método retorna um RestRequest que pode ser encadeado com .query(), .body() e .getBody(). A requisição HTTP é enviada quando o objeto RestRequest sai de escopo ou quando o primeiro .getBody() é adicionado.

`get(path)`¶

Envia uma requisição GET para baseUrl + path.

RestRequest get(const char* path);

Exemplo:

client.get("/todos/1").getBody("title", title, sizeof(title));

`post(path)`¶

Envia uma requisição POST para baseUrl + path.

RestRequest post(const char* path);

Exemplo:

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

`put(path)`¶

Envia uma requisição PUT para baseUrl + path.

RestRequest put(const char* path);

Exemplo:

client.put("/posts/1").body("title", "novo título");

`update(path)`¶

Alias semântico para put(). Envia uma requisição HTTP PUT idêntica.

RestRequest update(const char* path);

Exemplo:

client.update("/lights/1").body("state", "OFF");

`patch(path)`¶

Envia uma requisição PATCH para baseUrl + path para atualizações parciais.

RestRequest patch(const char* path);

Exemplo:

client.patch("/config").body("timeout", 30);

`del(path)`¶

Envia uma requisição DELETE para baseUrl + path.

RestRequest del(const char* path);

Exemplo:

client.del("/sessions/42");

`soap(path)`¶

Inicia uma requisição SOAP direcionada para baseUrl + path, retornando um builder SoapRequest.

SoapRequest soap(const char* path = "");

Exemplo:

client.soap("/ws")
      .soapAction("http://example.org/GetPrice")
      .body("<m:GetPrice xmlns:m=\"http://example.org\"><m:Item>Widget</m:Item></m:GetPrice>")
      .getBody("Price", &preco);

`graphql(path)` / `graphqlPost(path)`¶

Inicia uma requisição GraphQL para baseUrl + path (padrão POST), retornando um builder GraphQLRequest.

GraphQLRequest graphql(const char* path = "/graphql");
GraphQLRequest graphqlPost(const char* path = "/graphql");

Exemplo:

client.graphql("/graphql")
      .query("query { user { id name } }")
      .getData("user.name", &nome);

`graphqlGet(path)`¶

Inicia uma consulta GraphQL para baseUrl + path via HTTP GET, codificando query e variáveis como parâmetros na URL.

GraphQLRequest graphqlGet(const char* path = "/graphql");

Exemplo:

client.graphqlGet("/graphql")
      .query("{ statusSistema }")
      .getData("statusSistema", &status);

`graphqlBatch(path)`¶

Inicia um lote de múltiplas operações GraphQL para baseUrl + path enviadas em uma única requisição HTTP POST, retornando um builder GraphQLBatchRequest.

GraphQLBatchRequest graphqlBatch(const char* path = "/graphql");

Exemplo:

auto batch = client.graphqlBatch("/graphql");
batch.addQuery("query { user { name } }").getData("user.name", &nome);
batch.addQuery("query { config { tema } }").getData("config.tema", &tema);
batch.execute();

Métodos de Configuração¶

`setHeader(name, value)`¶

Registra um cabeçalho HTTP personalizado enviado com todas as requisições subsequentes.

void setHeader(const char* name, const char* value);

Parâmetro	Limite
`name`	Até 63 caracteres
`value`	Até 255 caracteres

Exemplo:

client.setHeader("Authorization", "Bearer meu-token");
client.setHeader("X-Device-ID",   "ESP32-001");

Note

Cabeçalhos persistem durante todo o ciclo de vida da instância do cliente. Chame setHeader() novamente com o mesmo nome para sobrescrevê-lo.

Lendo cabeçalhos de resposta

setHeader() define cabeçalhos a serem enviados na requisição. Para ler cabeçalhos retornados pelo servidor na resposta, utilize RestRequest::getHeader.

`bearer(token)`¶

Define o cabeçalho Authorization: Bearer <token> enviado com todas as requisições subsequentes.

void bearer(const char* token);

Parâmetro	Tipo	Descrição
`token`	`const char*`	A string do token Bearer / JWT.

Exemplo:

client.bearer("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");

`basic(user, password)`¶

Codifica as credenciais em Base64 e define o cabeçalho Authorization: Basic <base64> enviado com todas as requisições subsequentes.

void basic(const char* user, const char* password);

Parâmetro	Tipo	Descrição
`user`	`const char*`	Nome de usuário.
`password`	`const char*`	Senha.

Exemplo:

client.basic("admin", "secret123");

`apiKey(name, key)`¶

Define um cabeçalho de chave de API (ex: x-api-key) enviado com todas as requisições subsequentes.

void apiKey(const char* name, const char* key);

Parâmetro	Tipo	Descrição
`name`	`const char*`	Nome do cabeçalho (ex: `"X-API-Key"` ou `"x-api-key"`).
`key`	`const char*`	String da chave de API.

Exemplo:

client.apiKey("x-api-key", "minha-chave-api-secreta");

`cookie(nome, valor)`¶

Anexa ou cria um cabeçalho Cookie no cliente. Retorna uma referência para ESP32HTTPClient, permitindo que você encadeie chamadas .get(), .post() ou até mesmo outros .cookie() diretamente no cliente.

ESP32HTTPClient& cookie(const char* name, const char* value);

Parâmetros: * nome: O nome do cookie (ex: "session_id"). * valor: O valor do cookie (ex: "abc1234").

Exemplo:

client.cookie("session_id", "abc1234")
      .cookie("device_id", "esp32-01")
      .get("/perfil");

`setBaseUrl(baseUrl, port)`¶

Altera a URL base e a porta de destino em tempo de execução para as requisições subsequentes.

void setBaseUrl(const char* baseUrl, int port = 0);

Exemplo:

client.setBaseUrl("https://api.v2.exemplo.com", 443);

`setUrl(baseUrl)`¶

Atalho para atualizar apenas a URL base em tempo de execução.

void setUrl(const char* baseUrl);

`setPort(port)`¶

Atualiza a porta TCP de destino em tempo de execução.

void setPort(int port);

`getBaseUrl()`¶

Retorna a URL base atual configurada.

const char* getBaseUrl() const;

`getPort()`¶

Retorna a porta TCP configurada (ou 0 se padrão).

int getPort() const;

`setTimeout(timeoutMs)`¶

Configura o tempo limite (timeout) padrão em milissegundos para todas as requisições deste cliente. O padrão é 60000 ms (1 minuto).

void setTimeout(uint16_t timeoutMs);

Exemplo:

client.setTimeout(10000); // 10 segundos

`getTimeout()`¶

Retorna o timeout configurado em milissegundos.

uint16_t getTimeout() const;

`setMaxRetry(maxRetry)`¶

Configura o número máximo de tentativas automáticas em caso de falha de rede. O padrão é 1 tentativa.

void setMaxRetry(int maxRetry);

Exemplo:

client.setMaxRetry(3); // Até 3 tentativas

`getMaxRetry()`¶

Retorna o número máximo configurado de tentativas.

int getMaxRetry() const;

`setContentType(contentType)`¶

Sobrescreve o cabeçalho Content-Type usado no corpo das requisições. O padrão é application/json.

void setContentType(const char* contentType);

Exemplo:

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

Inspeção de Resposta e Tratamento de Erros¶

`getStatusCode()`¶

Retorna o código de status HTTP da última requisição concluída.

int getStatusCode() const;

Valores de retorno:

Valor	Significado
`> 0`	Código de status HTTP padrão (200, 201, 404, 500…)
`< 0`	Erro no nível de rede (sem conexão, timeout, etc.)
`0`	Nenhuma requisição foi realizada ainda

`isSuccess()`¶

Retorna true se a última requisição foi concluída com status HTTP de sucesso 2xx (200 <= code < 300).

bool isSuccess() const;

Exemplo:

client.get("/data").getBody("val", &val);
if (client.isSuccess()) {
    Serial.println("Requisição bem-sucedida!");
}

`hasError()`¶

Retorna true se a última requisição falhou devido a um erro de rede (code < 0) ou erro HTTP de cliente/servidor (code >= 400).

bool hasError() const;

Exemplo:

client.get("/data").getBody("val", &val);
if (client.hasError()) {
    Serial.printf("Erro (%d): %s\n", client.getStatusCode(), client.getErrorMessage().c_str());
}

`getErrorMessage()`¶

Retorna uma descrição legível do último código de status ou de erro retornado.

String getErrorMessage() const;

`errorToString(code)`¶

Método estático auxiliar que converte qualquer código de status HTTP ou código de erro negativo em uma descrição textual.

static String errorToString(int code);

Serialização & Desserialização de Structs¶

Métodos utilitários estáticos para conversão entre structs C++ mapeadas e strings JSON.

`toJson(struct)`¶

Serializa uma struct mapeada com REST_JSON_MAP em uma string JSON.

template <typename T>
static String toJson(const T& obj);

Exemplo:

User user = {15, "Pedro", 9.5f, true};
String json = ESP32HTTPClient::toJson(user);

`fromJson(json, struct)`¶

Preenche uma struct mapeada com REST_JSON_MAP a partir de uma string JSON.

template <typename T>
static void fromJson(const String& json, T* target);
template <typename T>
static void fromJson(const char* json, T* target);

Exemplo:

User user;
ESP32HTTPClient::fromJson("{\"id\":15,\"name\":\"Pedro\"}", &user);

Callbacks¶

Você pode registrar callbacks globais na instância do cliente que são executados sempre que qualquer requisição é finalizada.

`onSuccess(callback)`¶

Registra um callback executado quando qualquer requisição finaliza com sucesso 2xx (200 <= code < 300).

void onSuccess(HttpResponseCallback cb);

Exemplo:

client.onSuccess([](int code) {
    Serial.printf("Requisição bem-sucedida com status %d\n", code);
});

`onError(callback)`¶

Registra um callback executado quando qualquer requisição falha com erro (code < 200 || code >= 400).

void onError(HttpErrorCallback cb);
void onError(HttpResponseCallback cb);

Exemplo:

client.onError([](int code, const char* message) {
    Serial.printf("Requisição falhou (%d): %s\n", code, message);
});

`onResponse(callback)`¶

Registra um callback executado em qualquer requisição concluída, independentemente de ter sucesso ou falhado.

void onResponse(HttpResponseCallback cb);

Exemplo:

client.onResponse([](int code) {
    Serial.printf("Resposta recebida com código %d\n", code);
});

`onObservability(cb)`¶

Registra um callback global invocado ao final de cada requisição, fornecendo métricas de performance (tempos, tamanho de payload, uso de heap).

void onObservability(ObservabilityCallback cb);

Definição do Struct (ObservabilityMetrics):

struct ObservabilityMetrics {
    unsigned long totalTimeMs;
    unsigned long ttfbMs;
    size_t txBytes;
    size_t rxBytes;
    int retries;
    uint32_t freeHeapBefore;
    uint32_t freeHeapAfter;
};

Exemplo:

client.onObservability([](const ObservabilityMetrics& m) {
    Serial.printf("TTFB: %lu ms | TX: %d | RX: %d\n", m.ttfbMs, m.txBytes, m.rxBytes);
});

Gerenciamento de Conexão¶

`end()`¶

Fecha a conexão TCP/TLS Keep-Alive persistente e libera seus buffers de memória.

void end();

Chame este método após uma sequência de requisições para liberar ~45KB de memória TLS durante um período de inatividade longo. A próxima requisição restabelecerá a conexão automaticamente.

Exemplo:

client.get("/data1").getBody("v", &v1);
client.get("/data2").getBody("v", &v2);

client.end(); // libera memória TLS
delay(60000);

client.get("/data3").getBody("v", &v3); // reconecta automaticamente

Códigos de Erro e Códigos de Status HTTP¶

Código	Significado	Categoria
`-1`	Conexão Recusada	Erro do cliente
`-2`	Falha ao Enviar Cabeçalho	Erro do cliente
`-3`	Falha ao Enviar Payload	Erro do cliente
`-4`	Não Conectado	Erro do cliente
`-5`	Conexão Perdida	Erro do cliente
`-6`	Sem Stream	Erro do cliente
`-7`	Sem Servidor HTTP	Erro do cliente
`-8`	Memória RAM Insuficiente	Erro do cliente
`-9`	Erro de Codificação	Erro do cliente
`-10`	Erro de Escrita no Stream	Erro do cliente
`-11`	Tempo Limite de Leitura	Erro do cliente
`200`	OK	Sucesso HTTP
`201`	Criado	Sucesso HTTP
`202`	Aceito	Sucesso HTTP
`204`	Sem Conteúdo	Sucesso HTTP
`400`	Requisição Inválida	Erro do cliente HTTP
`401`	Não Autorizado	Erro do cliente HTTP
`403`	Proibido	Erro do cliente HTTP
`404`	Não Encontrado	Erro do cliente HTTP
`405`	Método Não Permitido	Erro do cliente HTTP
`408`	Tempo Limite da Requisição	Erro do cliente HTTP
`409`	Conflito	Erro do cliente HTTP
`429`	Muitas Requisições	Erro do cliente HTTP
`500`	Erro Interno do Servidor	Erro do servidor HTTP
`501`	Não Implementado	Erro do servidor HTTP
`502`	Gateway Inválido	Erro do servidor HTTP
`503`	Serviço Indisponível	Erro do servidor HTTP
`504`	Tempo Limite do Gateway	Erro do servidor HTTP
`0`	Não Executado	Estado interno

Comportamento Genérico de Fallback¶

Códigos negativos desconhecidos → Erro de Cliente Desconhecido
200–299 → Sucesso
300–399 → Redirecionamento
400–499 → Erro do Cliente
500–599 → Erro do Servidor
Outros valores → Status HTTP Desconhecido

Exemplo¶

Um pequeno exemplo de uso mostrando como aplicações podem tratar tanto erros de transporte quanto erros HTTP:

int status = client.get("/api/data").getStatusCode();

if (client.isSuccess()) {
    // Tratar resposta bem-sucedida
} else {
    Serial.println(client.getErrorMessage());
}

ESP32HTTPClient¶

Construtor¶

ESP32HTTPClient(baseUrl)¶

ESP32HTTPClient(baseUrl, port)¶

Métodos de Requisição HTTP¶

get(path)¶

post(path)¶

put(path)¶

update(path)¶

patch(path)¶

del(path)¶

soap(path)¶

graphql(path) / graphqlPost(path)¶

graphqlGet(path)¶

graphqlBatch(path)¶

Métodos de Configuração¶

setHeader(name, value)¶

bearer(token)¶

basic(user, password)¶

apiKey(name, key)¶

cookie(nome, valor)¶

setBaseUrl(baseUrl, port)¶

setUrl(baseUrl)¶

setPort(port)¶

getBaseUrl()¶

getPort()¶

setTimeout(timeoutMs)¶

getTimeout()¶

setMaxRetry(maxRetry)¶

getMaxRetry()¶

setContentType(contentType)¶

Inspeção de Resposta e Tratamento de Erros¶

getStatusCode()¶

isSuccess()¶

hasError()¶

getErrorMessage()¶

errorToString(code)¶

Serialização & Desserialização de Structs¶

toJson(struct)¶

fromJson(json, struct)¶

Callbacks¶

onSuccess(callback)¶

onError(callback)¶

onResponse(callback)¶

onObservability(cb)¶

Gerenciamento de Conexão¶

end()¶

Códigos de Erro e Códigos de Status HTTP¶

Comportamento Genérico de Fallback¶

Exemplo¶

`ESP32HTTPClient(baseUrl)`¶

`ESP32HTTPClient(baseUrl, port)`¶

`get(path)`¶

`post(path)`¶

`put(path)`¶

`update(path)`¶

`patch(path)`¶

`del(path)`¶

`soap(path)`¶

`graphql(path)` / `graphqlPost(path)`¶

`graphqlGet(path)`¶

`graphqlBatch(path)`¶

`setHeader(name, value)`¶

`bearer(token)`¶

`basic(user, password)`¶

`apiKey(name, key)`¶

`cookie(nome, valor)`¶

`setBaseUrl(baseUrl, port)`¶

`setUrl(baseUrl)`¶

`setPort(port)`¶

`getBaseUrl()`¶

`getPort()`¶

`setTimeout(timeoutMs)`¶

`getTimeout()`¶

`setMaxRetry(maxRetry)`¶

`getMaxRetry()`¶

`setContentType(contentType)`¶

`getStatusCode()`¶

`isSuccess()`¶

`hasError()`¶

`getErrorMessage()`¶

`errorToString(code)`¶

`toJson(struct)`¶

`fromJson(json, struct)`¶

`onSuccess(callback)`¶

`onError(callback)`¶

`onResponse(callback)`¶

`onObservability(cb)`¶

`end()`¶