A APIBrasil reúne mais de 170 APIs brasileiras (CEP, CNPJ, CPF, placa de veículo, SMS, WhatsApp, análise de crédito e muito mais) atrás de um único gateway. Isso significa que, depois de aprender a fazer uma chamada, você sabe fazer todas: o endereço base, a autenticação e o formato da resposta são sempre os mesmos.
Neste guia de primeiros passos na APIBrasil você vai pegar o seu Bearer Token, fazer a primeira requisição em homologação (sem gastar crédito) e aprender a ler a resposta do gateway do jeito certo. É a base de todos os outros tutoriais da série.
O que você precisa antes de começar
- Uma conta na APIBrasil, criada em app.apibrasil.io.
- Um terminal com
curl(já vem no macOS, no Linux e no Windows 10 ou mais novo). - Opcional: Postman, Insomnia ou o próprio simulador da documentação.
Não é preciso saber programar para acompanhar este primeiro passo. Os próximos tutoriais trazem o mesmo fluxo em Python, PHP e Node.js.
Como a APIBrasil funciona: um gateway, um token
Todas as APIs do catálogo passam pelo mesmo endereço, https://gateway.apibrasil.io/api/v2/, e usam o mesmo cabeçalho de autenticação. O que muda de uma API para outra é a rota e o corpo da requisição.
| Item | Como funciona na APIBrasil |
|---|---|
| Endereço base | https://gateway.apibrasil.io/api/v2/ |
| Método | POST com corpo em JSON |
| Autenticação | Cabeçalho Authorization: Bearer SEU_TOKEN |
| Cobrança | A maioria das APIs cobra por consulta, debitando do saldo da conta |
| Testes | Campo homolog: true no corpo, sem tarifação |
A documentação informa que, das 176 APIs do catálogo, 171 cobram por consulta e pedem só o Bearer Token. As outras 5 funcionam por plano e exigem também um DeviceToken, caso das APIs de WhatsApp. Neste guia vamos ficar nas APIs por consulta, que são a maioria.
Passo 1: pegue o seu Bearer Token
Depois de entrar em app.apibrasil.io, abra o menu Credenciais. É ali que fica o token que identifica a sua conta em todas as chamadas.
Trate esse token como uma senha:
- Nunca coloque o token direto no código que vai para o GitHub.
- Guarde em variável de ambiente ou em um arquivo
.envfora do controle de versão. - Se o token vazar, gere outro no painel e troque nas suas aplicações.
No terminal, a forma mais simples é exportar o token numa variável de ambiente:
export APIBRASIL_TOKEN="seu_token_aqui"No Windows (PowerShell), o equivalente é $env:APIBRASIL_TOKEN="seu_token_aqui". Se quiser se aprofundar nisso, veja o tutorial Variáveis de ambiente e arquivo .env.
Passo 2: escolha a API na documentação
Em doc.apibrasil.io você encontra o catálogo completo, organizado em 20 categorias. Cada API tem uma página com:
- A rota e o preço por consulta.
- O corpo de exemplo de cada endpoint.
- Um simulador para testar a chamada pelo navegador.
- A aba Instruções para IA, com a especificação pronta para você colar no seu assistente de código.
Para a primeira chamada vamos usar a API CEP com IBGE, que é simples e barata. A rota é consulta/cep/credits e o corpo pede apenas o tipo e o CEP.
Passo 3: faça a primeira chamada em homologação
Toda API da APIBrasil aceita o campo homolog no corpo. Com homolog: true, a resposta volta com dados válidos, mas a requisição não é tarifada nem contabilizada. É o modo certo para desenvolver e rodar testes automatizados.
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/cep/credits" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $APIBRASIL_TOKEN" \
-d '{"tipo":"cep","cep":"31585230","homolog":true}' \
--max-time 120
Passo 4: entenda a resposta do gateway
Toda resposta de sucesso da APIBrasil segue o mesmo envelope. O resultado da consulta fica em data, e em volta dele vêm os campos de controle:
| Campo | O que significa |
|---|---|
error | false quando a consulta deu certo. Sempre confira este campo. |
message | Texto explicando o resultado, inclusive se houve tarifação |
balance | Saldo restante na conta, como texto no formato brasileiro |
tax | Quanto esta consulta custou |
valor_consulta | O preço da consulta, como número |
api_limit_for | credit em produção, homolog em homologação |
data | O resultado da API: endereço, empresa, veículo etc. |
As três regras que evitam 90% dos bugs
A própria documentação da APIBrasil destaca alguns comportamentos que fogem do padrão REST. Vale gravar desde o primeiro dia:
- O erro pode chegar com HTTP 200. Não basta checar o status HTTP: confira sempre
error === falseantes de lerdata. balanceetaxsão texto, não número. Eles vêm como"105,660"ou"0.19", e o separador pode variar entre APIs. Converta com uma função própria antes de fazer qualquer conta.- HTTP 402 significa saldo insuficiente. Repetir a chamada não resolve: é preciso recarregar em app.apibrasil.io/recargas.
O tutorial Boas práticas para integrar a APIBrasil em produção mostra um cliente completo que trata tudo isso.
Passo 5: saindo da homologação
Quando o fluxo estiver funcionando, basta trocar homolog: true por homolog: false (ou remover o campo) para passar a receber dados reais e ser tarifado por consulta. Antes disso:
- Confira se há saldo na conta, na área Financeiro do painel.
- Deixe o
homologconfigurável por variável de ambiente, ligado em desenvolvimento e desligado em produção. - Registre em log o
taxe obalancede cada chamada para acompanhar o consumo.
Outras formas de usar a APIBrasil
Além de HTTP puro, a documentação oferece outros caminhos para as mesmas APIs:
- SDKs oficiais em várias linguagens, que já cuidam da autenticação.
- MCP, para que assistentes como Claude e Cursor chamem as APIs sozinhos. Veja como configurar o MCP da APIBrasil.
- Webhooks e Socket.IO, para receber eventos de SMS e WhatsApp sem ficar consultando.
Perguntas frequentes
A homologação devolve dados de verdade?
Depende da API. Algumas devolvem dados reais de exemplo, outras devolvem dados simulados e marcados como tal. Em todos os casos a requisição não é tarifada.
Preciso de um token diferente para cada API?
Não. O mesmo Bearer Token vale para todo o catálogo. Só as APIs por plano, como as de WhatsApp, pedem também um DeviceToken.
Onde vejo o preço de cada consulta?
Na página de cada API em doc.apibrasil.io, ao lado da rota, e na tela Preços do painel.
Próximos passos
Com o token em mãos e a primeira chamada funcionando, escolha o próximo tutorial da série: consultar CNPJ com Python, consulta de placa com valor FIPE em Node.js ou verificação por SMS OTP.
