> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flunora.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Referência
> Como funciona a consulta cadastral: o que ela devolve, quando custa, e o que os tetos protegem.
A Flunora consulta um bureau de dados brasileiro e devolve a ficha de uma pessoa ou de
uma empresa em JSON. O seu sistema pergunta por um documento, a Flunora responde com
campos nomeados e com a resposta original do bureau ao lado.
Depende de a sua instância ter a consulta de dados habilitada. Sem isso as rotas
respondem `404` com o código `recurso_indisponivel`. Fale com quem cuida da implantação.
## As duas formas de pedir
Para a ficha completa, existe uma rota por tipo de documento, e é o caminho mais curto:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl "https://crm.suaempresa.com/api/v1/cpf/12345678909" \
-H "Authorization: Bearer sk_live_..."
```
Para o resto do catálogo, situação na Receita, óbito, participação societária, protestos,
score, veículo por placa e validação de email, existe uma rota só, que recebe o produto
pelo corpo. Ela é a que não envelhece: produto novo passa a ser atendido ali sem versão
nova da API.
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST "https://crm.suaempresa.com/api/v1/consultas" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "produto": "receita-federal-pj", "documento": "11222333000181" }'
```
A lista do que a sua chave pode pedir sai em [`GET /api/v1/produtos`](/pages/consultas/produtos),
que não gera cobrança e é o jeito barato de descobrir o catálogo em vez de chutar um id
de produto e pagar para ver o erro.
## A resposta é nossa, o bruto vai junto
Os campos nomeados são o contrato: `nome`, `nomeMae`, `nascimento`, `telefones`,
`enderecos`, e os equivalentes de empresa. Eles são estáveis e não mudam quando o bureau
mudar. Programe contra eles.
O campo `bruto` traz a resposta original do fornecedor, inteira e sem tratamento. Ele
existe para você não ficar sem informação que já foi paga, e é onde estão as coisas que
ainda não têm campo próprio, como latitude do endereço, operadora do telefone e CBO do
sócio.
Campo que o bureau não tem vem `null`, nunca preenchido por dedução. Isso vale inclusive
para o que parece booleano: `whatsapp: null` quer dizer que o bureau não informou, e não
que o número não tem WhatsApp.
## Quando custa, e quando não custa
Cada chamada que chega ao bureau é cobrada. Três coisas evitam esse custo, e vale
conhecê-las porque elas mudam como você escreve o seu lado.
**O documento é conferido aqui, de graça.** CPF e CNPJ passam pelo dígito verificador
antes de qualquer chamada. Documento inválido volta `400` sem custo e sem aparecer no seu
extrato. Isso não é só economia: o bureau não valida entrada e chega a devolver a ficha de
outra pessoa para um CPF com dígito errado.
**Consulta repetida sai do histórico.** O mesmo documento no mesmo produto, dentro de 30
dias, volta do que já foi guardado. A resposta traz `cache: true`, não custa nada e não
consome o teto da sua chave. Para forçar dado novo e pagar por ele, acrescente
`?atualizar=true` na rota dedicada, ou `"atualizar": true` no corpo da genérica.
**Escopo errado para antes de gastar.** Uma chave sem o escopo do documento pedido recebe
`403` antes da chamada.
## O que os tetos protegem
A chave tem três limites, e eles têm naturezas diferentes.
O **teto por minuto** é defesa contra abuso e contra laço acidental do seu lado. Ele vale
por instância do servidor, então não o trate como controle de gasto.
Os tetos **por dia e por mês** são o controle de gasto de verdade. Eles contam as
consultas cobradas, e por isso consulta servida do cache não entra na conta.
As respostas trazem `X-RateLimit-Limit` e `X-RateLimit-Remaining`. As de `429` trazem
`Retry-After` quando faz sentido esperar, o que acontece no limite por minuto e no teto
diário, e não no mensal.
O consumo da chave também sai em [`GET /api/v1/consultas`](/pages/consultas/extrato), com o
que foi gasto no dia, no mês e no total, mais a lista do que foi consultado.
## Onde isso aparece dentro do app
A mesma consulta existe na interface, em **Buscar**, aba **Documentos**, para quem prefere
consultar à mão. O histórico é o mesmo, então uma consulta feita na tela serve de cache
para a chamada da API e vice-versa.
A consulta devolve dado pessoal de terceiros. Ter a credencial não é ter finalidade:
consulte apenas quem você tem base legal para consultar, e guarde por quanto tempo
precisar, não por padrão.
## Endpoints
Ficha completa da pessoa.
Ficha completa da empresa.
O catálogo inteiro, numa rota só.
O que a sua chave pode pedir. Sem custo.
Consumo e histórico. Sem custo.