Referência das consultas

Todas as consultas compartilham a mesma assinatura. Aprendida uma, aprendidas todas.

A rota

POST /api/v2/{slug}

O {slug} é o identificador da consulta, que aparece na página de cada uma do catálogo. Por exemplo, cnpj-intermediario ou kyc-estendido. O token precisa do escopo consultas.

O corpo

{ "documento": "55016784000138" }

O campo documento recebe o CPF ou o CNPJ. Pontos, barras e traços são aceitos e descartados.

Algumas consultas aceitam campos adicionais, obrigatórios ou não. A página da consulta lista cada um deles. Campo errado ou faltando responde 422 com entrada_invalida, e a consulta nem chega a ser executada.

A resposta

{
  "data": { },
  "meta": {
    "consulta_id": "0199c8f2-6b1e-7c3a-9d4f-2a5b8e7c1d90",
    "saldo": 48750,
    "preco": 69,
    "sandbox": false
  }
}

O conteúdo de data muda conforme a consulta. O de meta é sempre o mesmo, e está explicado em Saldo e extrato.

Rotas de apoio

Todas exigem o escopo leitura e não gastam saldo.

Rota	O que devolve
GET /api/v2/servicos	As consultas liberadas para a conta, com o preço de cada uma
GET /api/v2/saldo	O saldo da conta
GET /api/v2/openapi.json	A especificação OpenAPI, para gerar cliente ou importar na sua ferramenta

Limite de chamadas

Há um limite de requisições por segundo por token, definido pelo plano da conta. Passou do limite, a resposta é 429 com rate_limit: espere e repita. Precisa de mais vazão? Fale com a gente antes de subir o volume.

Tempo de resposta

Varia bastante conforme a origem do dado: há consultas que respondem em cerca de um segundo e outras que passam de dez. Dimensione o seu timeout pela consulta mais lenta que você usa, e prefira processar em fila o que não precisa de resposta imediata na tela do usuário.

Onde ver os campos de cada consulta

Cada consulta do catálogo tem a sua página, com o que ela devolve, os campos aceitos e um exemplo real de resposta. Comece por /consultas.