Saldo e extrato

Você adiciona saldo pelo painel e cada consulta concluída debita o preço de tabela.

Quando o débito acontece

O saldo sai quando a consulta é concluída com sucesso. Documento inválido, token sem escopo, saldo insuficiente, origem fora do ar e documento sem registro não debitam nada.

O que vem em cada resposta

Toda resposta de sucesso traz a conta fechada em meta:

Campo	O que é
consulta_id	Identificador único da consulta, o mesmo do extrato
preco	Quanto esta consulta debitou, em centavos
saldo	Saldo disponível depois do débito, em centavos
sandbox	true quando a resposta é simulada e não foi cobrada

Guarde o consulta_id no seu banco junto com o registro do cliente: é o que permite conciliar linha a linha, sem depender de aproximação por horário.

Consultar o saldo

curl https://api.radardata.com.br/api/v2/saldo \
  -H "Authorization: Bearer $RADARDATA_TOKEN"

A rota exige o escopo leitura e não gasta saldo.

Não pagar duas vezes pela mesma consulta

Se a sua chamada estourar o tempo e você repetir, mande o cabeçalho Idempotency-Key com o mesmo valor nas duas tentativas. A segunda devolve o resultado da primeira em vez de consultar e cobrar de novo.

curl -X POST https://api.radardata.com.br/api/v2/cnpj-intermediario \
  -H "Authorization: Bearer $RADARDATA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-48213-cnpj" \
  -d '{"documento": "55016784000138"}'

Use uma chave por operação. Reaproveitar a mesma chave em outra consulta ou outro documento responde 409 com idempotency_conflito.

Evitar parada por saldo

Duas defesas simples:

1. Acompanhe o meta.saldo. Ele chega em toda resposta. Um alerta no seu lado quando cair abaixo de alguns dias de operação custa uma linha.
2. Trate o 402 como aviso, não como erro de código. Se a sua esteira trava inteira ao receber sem_saldo, um domingo à noite vira incidente. Prefira enfileirar e avisar.

Para limitar o estrago de um token com defeito ou vazado, configure um teto de gasto nele.