Quais são os 7 fatos principais?
- Faça uma chamada HTTPS com a sua chave no cabeçalho.
- Crie a conta com o CNPJ da sua empresa e receba duas chaves no painel: sk_teste_... responde com dados de exemplo e não gasta crédito. sk_vivo_... consulta de verdade e desconta do saldo.
- Mande a chave no cabeçalho Authorization: Bearer <chave>.
- A recarga mínima é R$ 20 (2.000 créditos), por PIX, boleto ou cartão.
- Teste sem gastar: com a chave sk_teste_, cada API devolve uma resposta de exemplo com o mesmo formato da real.
- Trate o erro pelo código HTTP, que diz o que aconteceu.
- O corpo sempre tem erro (código fixo pra você tratar) e mensagem (explicação em texto, pra mostrar no seu log).
Quais são os números principais?
| Número | O que significa |
|---|---|
| R$ 20 | A recarga mínima é R$ 20 (2.000 créditos), por PIX, boleto ou cartão. |
| 3 créditos | HTTP/1.1 402 Payment Required { "erro": "saldo_insuficiente", "mensagem": "Seu saldo é de 3 créditos e esta consulta custa 5. |
| 5 créditos | Listar marcas, modelos e anos não gasta crédito; o preço custa 5 créditos. |
| 150 créditos | Cada modelo tem o seu preço por token; sem modelo, vale o Gemini 2.5 Flash-Lite (150 créditos por 1 milhão de tokens de entrada e 600 de saída). |
| 1 milhão | GET/v1/ia/modelos Lista os modelos com o preço em reais por 1 milhão de tokens. |
Primeira consulta
Faça uma chamada HTTPS com a sua chave no cabeçalho. Toda resposta é JSON em UTF-8. Os valores nas respostas desta página são exemplos.
curl https://certu.com.br/api/mercado/v1/cep/88010000 \ -H "Authorization: Bearer sk_teste_SUA_CHAVE"
Autenticação
Crie a conta com o CNPJ da sua empresa e receba duas chaves no painel:
sk_teste_...responde com dados de exemplo e não gasta crédito.sk_vivo_...consulta de verdade e desconta do saldo.
Mande a chave no cabeçalho Authorization: Bearer <chave>. Nunca coloque a chave no navegador ou no app do celular: chame a API do seu servidor. Você pode criar, limitar por API e apagar chaves no painel.
Créditos
Conte em créditos: 1 crédito vale R$ 0,01. A recarga mínima é R$ 20 (2.000 créditos), por PIX, boleto ou cartão. Crédito não vence.
Toda resposta traz dois cabeçalhos:
| Cabeçalho | O que é |
|---|---|
X-Creditos-Usados | Quanto a chamada custou. |
X-Creditos-Restantes | Saldo depois da chamada. |
Chamada que volta com erro (4xx ou 5xx) não gasta crédito. Consulta que não encontrou o dado (404) também não.
Sandbox
Teste sem gastar: com a chave sk_teste_, cada API devolve uma resposta de exemplo com o mesmo formato da real. Use estes valores pra testar cada caso:
| API | Valor | Resposta |
|---|---|---|
| CNPJ | 00000000000191 | Empresa ativa |
| CNPJ | 00000000000272 | 404, não encontrado |
| CEP | 01001000 | Endereço completo |
| CPF | 12345678909 + 2000-01-01 | CPF e nascimento batem |
Erros
Trate o erro pelo código HTTP, que diz o que aconteceu. O corpo sempre tem erro (código fixo pra você tratar) e mensagem (explicação em texto, pra mostrar no seu log).
HTTP/1.1 402 Payment Required
{
"erro": "saldo_insuficiente",
"mensagem": "Seu saldo é de 3 créditos e esta consulta custa 5. Recarregue no painel."
}
| HTTP | erro | Quando |
|---|---|---|
| 400 | parametro_invalido | CNPJ, CEP ou CPF em formato errado. |
| 401 | chave_invalida | Chave ausente, errada ou apagada. |
| 402 | saldo_insuficiente | O saldo não cobre a consulta. |
| 403 | nao_liberado | API que pede verificação (CPF) ainda não liberada pra sua conta. |
| 404 | nao_encontrado | O dado não existe na fonte. |
| 429 | limite_por_minuto | Mais de 120 chamadas por minuto na mesma chave. Espere o tempo do cabeçalho Retry-After. |
| 503 | fonte_indisponivel | A fonte do dado não respondeu. Tente de novo em instantes. |
CNPJ
Receba os dados cadastrais da empresa a partir dos dados abertos da Receita Federal, atualizados todo mês. Aceita CNPJ numérico e alfanumérico, com ou sem pontuação. Custa 5 créditos.
{
"cnpj": "33000167000101",
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"nome_fantasia": "PETROBRAS",
"situacao": "ATIVA",
"data_abertura": "1966-09-28",
"natureza_juridica": "2038 - Sociedade de Economia Mista",
"porte": "DEMAIS",
"cnae_principal": { "codigo": "0600001", "descricao": "Extração de petróleo e gás natural" },
"cnaes_secundarios": [],
"endereco": {
"logradouro": "AV REPUBLICA DO CHILE", "numero": "65", "complemento": null,
"bairro": "CENTRO", "cep": "20031912", "municipio": "RIO DE JANEIRO", "uf": "RJ"
},
"socios": [
{ "nome": "NOME DO SOCIO", "cpf_mascarado": "***123456**", "qualificacao": "Diretor" }
],
"fonte": "receita_federal_dados_abertos",
"atualizado_em": "2026-11-01",
"custo_creditos": 5
}
CEP
Preencha o endereço a partir do CEP. Custa 2 créditos.
{
"cep": "01001000",
"logradouro": "Praça da Sé",
"complemento": "lado ímpar",
"bairro": "Sé",
"municipio": "São Paulo",
"uf": "SP",
"ibge": "3550308",
"custo_creditos": 2
}
Tabela FIPE
Navegue marca, modelo e ano e receba o preço médio de referência do mês. Listar marcas, modelos e anos não gasta crédito; o preço custa 5 créditos.
tipo: carros (padrão), motos ou caminhoes. ano: ano-modelo com combustível, como 2020-1 (gasolina) ou 2020-3 (diesel), do jeito que a lista de anos devolve. As listas vêm como { "itens": [{ "codigo", "nome" }] }.
{
"codigo_fipe": "005340-6",
"marca": "VW - VolksWagen",
"modelo": "Gol 1.0 Flex 12V 5p",
"ano_modelo": 2020,
"combustivel": "Gasolina",
"preco": 47890.00,
"referencia": "novembro de 2026",
"custo_creditos": 5
}
CPF
Confirme que o CPF existe, se está regular na Receita e se a data de nascimento bate. A API não devolve nome nem endereço. Custa 99 créditos.
Disponível só para contas com CNPJ verificado que declararam no painel a finalidade (por exemplo: cadastro de cliente, prevenção a fraude) e a base legal da LGPD. Toda consulta fica registrada com data, chave e finalidade. Sem isso, a API responde 403 nao_liberado.
| Campo | Tipo | Descrição |
|---|---|---|
cpf | texto | 11 dígitos, com ou sem pontuação. |
nascimento | texto | Data no formato AAAA-MM-DD. |
finalidade | texto | Uma das finalidades declaradas no painel. |
curl -X POST https://certu.com.br/api/mercado/v1/cpf/validar \
-H "Authorization: Bearer sk_vivo_..." \
-H "Content-Type: application/json" \
-d '{"cpf":"12345678909","nascimento":"1990-05-17","finalidade":"cadastro_cliente"}'
{
"cpf_valido": true,
"nascimento_confere": true,
"situacao": "REGULAR",
"custo_creditos": 99
}
Chat com IA
Escolha entre todos os modelos do catálogo (OpenAI, Anthropic, Google, DeepSeek, Qwen, Meta, Mistral e outros) pela mesma chave, sem conta em cada provedor. Cada modelo tem o seu preço por token; sem modelo, vale o Gemini 2.5 Flash-Lite (150 créditos por 1 milhão de tokens de entrada e 600 de saída).
Lista os modelos com o preço em reais por 1 milhão de tokens. Não gasta crédito.
| Campo | Tipo | Descrição |
|---|---|---|
modelo | texto | Opcional. Um id de /v1/ia/modelos, como openai/gpt-5-5. |
mensagens | lista | De 1 a 100 itens com papel (sistema, usuario ou assistente) e conteudo. A última é do usuario. |
max_tokens | número | Opcional. Teto da resposta, até 4.096. Padrão 1.024. |
{
"modelo": "google/gemini-2-5-flash-lite",
"mensagens": [
{ "papel": "sistema", "conteudo": "Responda em uma frase." },
{ "papel": "usuario", "conteudo": "Resuma: o cliente quer trocar o produto porque veio com defeito." }
],
"max_tokens": 200
}
→ {
"modelo": "google/gemini-2-5-flash-lite",
"resposta": "O cliente pede a troca de um produto que chegou com defeito.",
"tokens": { "entrada": 31, "saida": 14 },
"custo_creditos": 0.0131
}
O saldo é descontado com até quatro casas decimais, então chamadas pequenas custam frações de crédito. Antes de chamar o modelo, a API confere se o saldo cobre o pior caso (entrada + max_tokens) e desconta só o que foi usado.
Transcrição de áudio
Envie um áudio e receba o texto em português. Aceita MP3, M4A, OGG/Opus (áudio de WhatsApp), WAV e WEBM até 25 MB. Custa 5 créditos por minuto, contado por segundo.
curl -X POST https://certu.com.br/api/mercado/v1/ia/transcrever \
-H "Authorization: Bearer sk_vivo_..." \
-F "arquivo=@audio.ogg"
{
"texto": "Oi, queria saber se vocês abrem no sábado.",
"duracao_segundos": 4.2,
"custo_creditos": 0.35
}
Saldo
Consulte o saldo da conta. Não gasta crédito.
{ "creditos": 1995.37, "reais": 19.95 }