---
title: "SDK C++"
lang: pt-BR
canonical: https://doc.apibrasil.io/sdks/cpp
markdown: https://doc.apibrasil.io/sdks/cpp.md
source: apibrasil-documentation
---

# SDK C++

- **Situação:** publicado
- **Instalação:** `git clone https://github.com/APIBrasil/apigratis-sdk-cpp`
- **Registry:** GitHub — https://github.com/APIBrasil/apigratis-sdk-cpp
- **Repositório:** https://github.com/APIBrasil/apigratis-sdk-cpp

## Não invente a assinatura

NÃO INVENTE A API DO SDK DE C++. Cada biblioteca deste catálogo tem construtor, nomes de método e formato de retorno próprios, e nenhum deles se deduz do nome do pacote. Abra o README do repositório acima e use exatamente o que está escrito lá. Se você não conseguir abrir o repositório, NÃO CHUTE: escreva o cliente em HTTP puro, seguindo a seção abaixo, e diga na resposta que foi isso que você fez e por quê.

## Como autenticar

O Bearer vai no cabeçalho Authorization, em toda chamada. O DeviceToken só nas APIs cobradas por plano — as por crédito não pedem. É o mesmo par que o SDK põe por você.

Com homolog verdadeiro no corpo, o gateway responde de uma base fixa. O CPF 00000000000 é o dela e não é de ninguém.

## O repositório no GitHub

- **Estrelas:** 0
- **Forks:** 0
- **Issues abertas:** 0
- **Linguagem:** C++
- **Licença:** MIT License
- **Último envio:** 24 de julho de 2026
- **git clone:** `https://github.com/APIBrasil/apigratis-sdk-cpp.git`

## README do repositório

Reproduzido do repositório, no ramo padrão. É a documentação de quem mantém a biblioteca: a assinatura do SDK é o que está aqui, e não o que se deduz do nome do pacote.

# APIBrasil SDK — C++

SDK oficial **C++** da plataforma [APIBrasil](https://apibrasil.com.br) —
WhatsApp, SMS, consultas CPF/CNPJ, veículos, CEP, correios, pagamentos
PIX/boleto e muito mais.

- **C++17**, portável (Linux, macOS, Windows/MSVC).
- Transporte HTTP baseado em **libcurl**; JSON via **nlohmann/json**.
- Retry com backoff, hooks de observabilidade e hierarquia de erros tipados.

---

## Requisitos

- Compilador C++17 (GCC 8+, Clang 7+, MSVC 2019+).
- [CMake](https://cmake.org/) ≥ 3.16.
- [libcurl](https://curl.se/libcurl/) (desenvolvimento).
- [nlohmann/json](https://github.com/nlohmann/json) — encontrado no sistema ou
  baixado automaticamente via `FetchContent`.

No Ubuntu/Debian: `sudo apt install libcurl4-openssl-dev cmake g++`.
No macOS: `brew install curl cmake`.
No Windows: use [vcpkg](https://vcpkg.io/) (`vcpkg install curl nlohmann-json`)
ou o Visual Studio com CMake.

---

## Instalação

### Como subdiretório (mais simples)

Copie/clone este repositório para dentro do seu projeto e no seu `CMakeLists.txt`:

```cmake
add_subdirectory(apigratis-sdk-cpp)
target_link_libraries(seu_app PRIVATE apibrasil::apibrasil)
```

### Via FetchContent

```cmake
include(FetchContent)
FetchContent_Declare(apibrasil
    GIT_REPOSITORY https://github.com/jhowbhz/apigratis-sdk-cpp.git
    GIT_TAG v0.0.2)
FetchContent_MakeAvailable(apibrasil)
target_link_libraries(seu_app PRIVATE apibrasil::apibrasil)
```

Depois, no código:

```cpp
#include <apibrasil/apibrasil.hpp>
```

---

## Autenticação

Pegue suas credenciais em <https://apibrasil.com.br>. Existem dois tipos de
serviço:

| Família | Headers enviados | Serviços |
|---|---|---|
| **Device-based** | `Authorization: Bearer <token>` + `DeviceToken: <token>` | whatsapp, sms, dados, vehicles, cep, correios, ... |
| **Credit-based** | apenas `Authorization: Bearer <token>` (debita saldo) | `consulta.*` |

```cpp
#include <apibrasil/apibrasil.hpp>
using namespace apibrasil;

Config cfg;
cfg.bearerToken = "seu_bearer_token";   // JWT do login
cfg.deviceToken = "seu_device_token";   // serviços device-based
ApiBrasil api(cfg);
```

Ou deixe o SDK ler as variáveis de ambiente automaticamente
(`APIBRASIL_BEARER_TOKEN`, `APIBRASIL_DEVICE_TOKEN`, `APIBRASIL_SECRET_KEY`,
`APIBRASIL_BASE_URL`):

```cpp
ApiBrasil api;  // lê do ambiente
```

### Login por e-mail/senha (token guardado automaticamente)

```cpp
auto result = ApiBrasil::login({{"email", "voce@x.com"}, {"password", "******"}});
auto& api = *result.client;   // o token já está no cliente

// 2FA:
try {
    auto r = ApiBrasil::login({{"email", email}, {"password", senha}});
} catch (const ApiBrasilError& e) {
    // e.code() == "requires_2fa" -> conclua com auth.send2fa()/verify2fa()
}
```

### Criando um device (usa SecretKey)

```cpp
RequestOptions o;
o.secretKey = "SUA_SECRET_KEY";
Json device = api.devices.store({{"device_name", "meu-bot"}, {"type", "server"}}, o);
api.setDeviceToken(device["device"]["device_token"].get<std::string>());
```

---

## Uso

Todas as respostas voltam como `apibrasil::Json` (alias de `nlohmann::json`).

```cpp
// WhatsApp (device-based)
api.whatsapp.start({{"webhook_wh_message", "https://.../mensagens"}});
Json qr = api.whatsapp.qrcode();                 // qr["response"]["qrcode"]
api.whatsapp.sendText({{"number", "5511999999999"}, {"text", "Olá!"}});
api.whatsapp.sendFile({{"number", "..."}, {"path", "https://.../nota.pdf"}});

// Chamada genérica de qualquer action + fila (assíncrono)
api.whatsapp.request("sendLocation", {{"number", "..."}, {"lat", -23.5}, {"lng", -46.6}});
api.whatsapp.queue("sendText", {{"number", "..."}, {"text", "assíncrono"}});

// Consultas por crédito
Json cpf    = api.consulta.cpf({{"cpf", "00000000000"}});
Json socios = api.consulta.cnpj({{"cnpj", "..."}, {"tipo", "lista-socios"}});
Json score  = api.consulta.generic("cpf", {{"cpf", "..."}, {"tipo", "serasa-score-pf"}});
Json teste  = api.consulta.cpf({{"cpf", "..."}, {"homolog", true}});  // sandbox, sem cobrança

// Veículos (device-based) / SMS / Pagamentos
api.vehicles.dados({{"placa", "ABC1234"}});
api.sms.send({{"number", "..."}, {"message", "codigo: 123456"}});
Json pix = api.payments.pixGenerate("mercadopago", {{"amount", 100}});

// Boleto em PDF (bytes brutos)
std::string pdf = api.payments.boletoPdf("inter", "BOLETO_ID");
```

### Múltiplos devices

```cpp
auto comercial = api.withDevice("DEVICE_TOKEN_COMERCIAL");
comercial->whatsapp.sendText({{"number", "..."}, {"text", "..."}});
```

### Escape hatch genérico

```cpp
Json r1 = api.request("POST", "/consulta/cpf/credits", Json{{"cpf", "..."}});
Json r2 = api.request("GET", "/reports/quick-stats");
```

---

## Tratamento de erros

Toda resposta com status `>= 400` lança uma exceção da hierarquia
`apibrasil::ApiBrasilError`:

```cpp
try {
    api.consulta.cpf({{"cpf", "00000000000"}});
} catch (const InsufficientBalanceError& e) {
    // saldo insuficiente (HTTP 402) -> recarregar
} catch (const RateLimitError& e) {
    long ms = e.retryAfterMs().value_or(0);   // aguardar antes de repetir
} catch (const ValidationError& e) {
    // 400/422
} catch (const ApiBrasilError& e) {
    std::cerr << e.what() << " (status " << e.status().value_or(0) << ")\n";
}
```

| Exceção | Status |
|---|---|
| `ValidationError` | 400, 422 |
| `AuthenticationError` | 401 |
| `InsufficientBalanceError` | 402 |
| `PermissionError` | 403 |
| `NotFoundError` | 404, 410 |
| `RateLimitError` (tem `retryAfterMs()`) | 429 |
| `ServerError` | ≥ 500 |
| `NetworkError` / `TimeoutError` | falha de conexão / timeout |

---

## Configuração

```cpp
Config cfg;
cfg.bearerToken = "...";
cfg.deviceToken = "...";
cfg.baseUrl     = "https://gateway.apibrasil.io/api/v2";  // padrão
cfg.timeoutMs   = 30000;                                   // padrão (ms)

// Retry (padrão: 2 tentativas, apenas em 429 e falhas de conexão)
RetryConfig r;
r.retries = 3;
r.retryOnStatuses = {429, 503};
cfg.retry = r;                 // ou RetryConfig::disabled()

// Hooks de observabilidade
cfg.hooks.onRequest  = [](const RequestHookInfo& i)  { /* log */ };
cfg.hooks.onResponse = [](const ResponseHookInfo& i) { /* log */ };
cfg.hooks.onRetry    = [](const RetryHookInfo& i)    { /* log */ };

ApiBrasil api(cfg);
```

Timeouts **nunca** são repetidos automaticamente (para evitar cobranças/envios
duplicados). Não há URL separada de sandbox — a "homologação" das consultas por
crédito é feita por chamada com `{"homolog", true}` no corpo.

### Opções por requisição

Todo método aceita um `RequestOptions` opcional no fim:

```cpp
RequestOptions o;
o.query["page"]   = "2";
o.headers["X-Id"] = "abc";
o.bearerToken     = "token_de_uma_chamada";
o.timeoutMs       = 60000;
api.reports.recentRequests(o);
```

---

## Documentação

- Portal: <https://apibrasil.com.br>
- Docs: <https://doc.apibrasil.io>

## Licença

[MIT](https://github.com/APIBrasil/apigratis-sdk-cpp/blob/main/LICENSE) © APIBrasil.

## A mesma API por HTTP

Endereço base: https://gateway.apibrasil.io/api/v2
O caminho e o método de cada endpoint estão na página daquela API nesta documentação. Não deduza rota a partir do nome do serviço.

### Autenticação, em cabeçalhos HTTP
- `Authorization: Bearer SEU_TOKEN` — em toda chamada.
- `DeviceToken: SEU_DEVICE_TOKEN` — só nas APIs cobradas por plano; as cobradas por crédito não pedem. O nome exato do cabeçalho é o que a página do endpoint declara.

```bash
curl -X POST https://gateway.apibrasil.io/api/v2/dados/cpf \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cpf": "00000000000", "homolog": true}'
```

Com `homolog` verdadeiro no corpo, o gateway responde de uma base fixa e não consome crédito. O CPF 00000000000 é dessa base e não é de ninguém — use-o nos testes, nunca em produção.

## As outras linguagens

- [Python](https://doc.apibrasil.io/sdks/python.md): `pip install api-brasil`
- [Lua](https://doc.apibrasil.io/sdks/lua.md): `luarocks install apibrasil`
- [PHP](https://doc.apibrasil.io/sdks/php.md): `composer require jhowbhz/apigratis-sdk-php`
- [Java](https://doc.apibrasil.io/sdks/java.md): `mvn dependency:get -Dartifact=br.com.apibrasil:apigratis-sdk-java:0.0.1`
- [Ruby](https://doc.apibrasil.io/sdks/ruby.md): `gem install apigratis-sdk-ruby`
- [C# / .NET](https://doc.apibrasil.io/sdks/csharp.md): `dotnet add package ApiBrasil`
- [Node.js / TypeScript](https://doc.apibrasil.io/sdks/javascript.md): `npm install apigratis-sdk-nodejs`
- [Go](https://doc.apibrasil.io/sdks/go.md): `go get github.com/APIBrasil/apigratis-sdk-go`
- [Rust](https://doc.apibrasil.io/sdks/rust.md): `cargo add apibrasil`
- [Dart / Flutter](https://doc.apibrasil.io/sdks/flutter.md): `flutter pub add apigratis_sdk_flutter`
- [Elixir](https://doc.apibrasil.io/sdks/elixir.md): `mix deps.get  # com {:apibrasil, "~> 0.0.1"} no mix.exs`

## Ver também

- SDKs oficiais: [SDKs oficiais](https://doc.apibrasil.io/sdks.md)
- Índice da documentação: https://doc.apibrasil.io/llms.txt
- Versão HTML desta página: https://doc.apibrasil.io/sdks/cpp