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úmeroO que significa
R$ 20A recarga mínima é R$ 20 (2.000 créditos), por PIX, boleto ou cartão.
3 créditosHTTP/1.1 402 Payment Required { "erro": "saldo_insuficiente", "mensagem": "Seu saldo é de 3 créditos e esta consulta custa 5.
5 créditosListar marcas, modelos e anos não gasta crédito; o preço custa 5 créditos.
150 créditosCada 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ãoGET/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.

https://certu.com.br/api/mercado/v1
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:

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çalhoO que é
X-Creditos-UsadosQuanto a chamada custou.
X-Creditos-RestantesSaldo 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:

APIValorResposta
CNPJ00000000000191Empresa ativa
CNPJ00000000000272404, não encontrado
CEP01001000Endereço completo
CPF12345678909 + 2000-01-01CPF 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."
}
HTTPerroQuando
400parametro_invalidoCNPJ, CEP ou CPF em formato errado.
401chave_invalidaChave ausente, errada ou apagada.
402saldo_insuficienteO saldo não cobre a consulta.
403nao_liberadoAPI que pede verificação (CPF) ainda não liberada pra sua conta.
404nao_encontradoO dado não existe na fonte.
429limite_por_minutoMais de 120 chamadas por minuto na mesma chave. Espere o tempo do cabeçalho Retry-After.
503fonte_indisponivelA 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.

GET/v1/cnpj/{cnpj}
{
  "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.

GET/v1/cep/{cep}
{
  "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.

GET/v1/fipe/{tipo}/marcas
GET/v1/fipe/{tipo}/marcas/{marca}/modelos
GET/v1/fipe/{tipo}/marcas/{marca}/modelos/{modelo}/anos
GET/v1/fipe/{codigo_fipe}/{ano}?tipo=carros

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.

POST/v1/cpf/validar
CampoTipoDescrição
cpftexto11 dígitos, com ou sem pontuação.
nascimentotextoData no formato AAAA-MM-DD.
finalidadetextoUma 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).

GET/v1/ia/modelos

Lista os modelos com o preço em reais por 1 milhão de tokens. Não gasta crédito.

POST/v1/ia/chat
CampoTipoDescrição
modelotextoOpcional. Um id de /v1/ia/modelos, como openai/gpt-5-5.
mensagenslistaDe 1 a 100 itens com papel (sistema, usuario ou assistente) e conteudo. A última é do usuario.
max_tokensnúmeroOpcional. 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.

POST/v1/ia/transcrever
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.

GET/v1/saldo
{ "creditos": 1995.37, "reais": 19.95 }