Ciclo de uma consulta
Criar, acompanhar e receber: os três status, o polling e quando o saldo é debitado e estornado.
A consulta depende de fontes externas e leva de alguns segundos a alguns minutos. Por isso você não recebe o resultado na mesma resposta: primeiro cria a consulta, depois busca o resultado, por polling ou por webhook.
Debita o saldo e devolve o id
A base é consultada. Segundos, ou até ~2 min numa placa fria.
dados, veiculo e pdf_url
Valor estornado. Leia retryable.
Criar x consultar: o erro mais comum
São endpoints parecidos, mas o método e a URL mudam. Trocar isso é o motivo número um de receber 404 ROTA_NAO_ENCONTRADA.
| Você quer | Método | URL |
|---|---|---|
| Criar | POST | /v1/consultas |
| Ver o resultado | GET | /v1/consultas/{id} |
| Baixar o documento | GET | /v1/consultas/{id}/pdf |
POST /v1/consultas/{id} não existe. Para ver um resultado, use GET com o id; para criar, POST sem o id.Acompanhar o resultado (polling)
Depois de criar, pergunte pelo resultado em intervalos até ele ficar pronto. A regra que funciona: a cada 3 a 5 segundos, com teto de 5 minutos. Desistir antes disso abandona uma consulta que vai concluir e que já foi debitada.
O tempo varia conforme a base e a UF. A base estadual (Consulta Simples e família da Completa) pode levar cerca de 2 minutos numa placa consultada pela primeira vez no dia; a mesma placa, repetida, volta mais rápido.
| status | O que significa | O que fazer |
|---|---|---|
| processando | Ainda buscando na base. | Espere 3 a 5 s e consulte de novo. |
| concluido | Pronto. Vêm dados (quando o serviço tem JSON) e pdf_url. | Use os dados ou baixe o documento. |
| erro | Não foi possível concluir. Estado final: este id não muda mais. | O valor é estornado. Se retryable: true, crie uma consulta nova; não repita o GET no mesmo id. |
processando: a resposta é 400 PDF_NOT_READY. Espere o concluido.CRLV-e em alguns estados
Em CE, DF, ES, PB, RJ, RN, RS e SC, a emissão do CRLV é processada pelo DETRAN de forma assíncrona e pode ficar alguns minutos em processando. Não trate isso como erro. Aumente a janela de polling ou, melhor, cadastre um webhook e reaja ao query.completed. A 2ª via do ATPV-e também é emissão e leva cerca de 1 minuto.
Quando o seu teto de espera estoura
O timeout do seu polling não cancela nada: a consulta segue viva e foi cobrada. Guarde o id e consulte depois, ou deixe o webhook avisar. Criar outra consulta nesse momento é pagar duas vezes pelo mesmo resultado.
Cobrança e estorno
Cada consulta desconta do saldo da carteira o valor vigente do catálogo da API, que GET /v1/servicos já devolve com o seu preço (preço personalizado e grupo de desconto aplicados). Os valores da API seguem o catálogo de integrações (GET /v1/servicos) e podem diferir das condições disponíveis no Portal do Cliente. Exemplo: a Tabela FIPE é gratuita no painel e cobrada por requisição na API.
O débito acontece no POST, antes do processamento, e a resposta devolve valor_cobrado e saldo_restante para você conferir.
{
"id": "6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
"servico": "consulta",
"status": "processando",
"valor_cobrado": 5.38,
"preco_base": 5.98,
"desconto": { "grupo": "Integradores", "percentual": 10, "valor": 0.6 },
"saldo_restante": 465.01,
"resultado_url": "/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f"
}| Pergunta | Resposta |
|---|---|
| Quando o saldo é debitado? | No POST, na mesma transação que cria a consulta. Se o débito não passa, a consulta não existe. |
| E sem saldo? | 402 SALDO_INSUFICIENTE, com o seu saldo atual na resposta. Nada é criado nem cobrado. |
| Quando há estorno? | Automaticamente, quando a consulta termina em status: "erro", qualquer que seja o motivo. O valor volta ao saldo sem você pedir. |
| Erro sempre estorna? | Sim, nas consultas da API (sempre pagas com saldo). A única falha sem estorno é a detectada depois de a consulta ter sido entregue como concluída; nesse caso o status também não vira erro e o resultado recebido continua válido. |
| O estorno pode acontecer duas vezes? | Não. Se já existe a devolução daquela consulta, nada é creditado de novo. |
| Repetir uma consulta que falhou cobra de novo? | Sim. Uma consulta nova é um débito novo, mas o valor da que falhou já voltou: você não paga duas vezes pelo mesmo resultado. |
| A Idempotency-Key evita nova cobrança? | Sim, para a mesma requisição repetida (retry de rede). Ela não se aplica à nova tentativa de uma consulta que falhou, que é por definição outra consulta. Ver Idempotência. |
| Erro 4xx ou 429 cobra? | Não. Nada recusado antes da criação consome saldo: 400, 401, 402, 409, 422 e 429. |
| Ler o resultado ou baixar o PDF custa? | Não. GET /v1/consultas/{id}, o documento e as imagens são gratuitos (dentro do limite de requisições). Você paga pela consulta, não por lê-la. |
Cobranças parciais
consulta-completa com incluir_fipe: true, a FIPE é uma parcela separada: se só ela falhar, só ela é estornada, a consulta segue concluída e dados.fipe vem null com o motivo em dados.fipeErro. Nos endpoints síncronos de FIPE, falha ou ausência de valor estorna o valor inteiro.Pedido duplicado em andamento
Mesmo sem Idempotency-Key, um POST do mesmo serviço para o mesmo identificador (placa, chassi, motor ou documento) enquanto a consulta anterior ainda está em processamento devolve 200 com reaproveitada: true, valor_cobrado: 0 e o id da consulta existente. Trate como sucesso e acompanhe esse id. Depois que a anterior termina, um POST novo cria (e cobra) outra consulta. Detalhes em Limites e idempotência.