InfraJus: API de Raspagem (v1)

Consulta programática de multas, pontuação e processos de suspensão/cassação de condutores no DETRAN-RJ.

Base URL de produção: https://api.infrajus.com.br/v1

Autenticação

Toda requisição precisa do header x-api-key com a chave fornecida pela InfraJus.

x-api-key: ijs_live_xxxxxxxxxxxxxxxxxxxxxxxx

A chave pertence ao seu escritório: tudo que você cadastra por ela fica isolado no seu tenant, e você só consegue ler o que cadastrou. A chave é exibida uma única vez, no momento da emissão. Se perder, peça a revogação e a emissão de outra.

A única rota sem autenticação é esta documentação (GET /v1/docs). Todas as demais exigem a chave.

Como funciona

A consulta ao DETRAN-RJ não é instantânea: o portal exige CAPTCHA, tem limite de ritmo e cai com frequência. Por isso o fluxo é em duas etapas.

1. POST /v1/clientes cadastra o condutor e coloca a raspagem na fila. Responde na hora.
2. GET /v1/clientes/{id} devolve o JSON completo quando a raspagem termina.

Uma consulta completa costuma levar de 1 a 5 minutos. Se o DETRAN estiver instável, o sistema re-tenta sozinho (3 tentativas com backoff, mais um job de catch-up de hora em hora). Não é preciso reenviar o POST.

POST /v1/clientes

Cadastra o condutor e enfileira a raspagem.

É idempotente por CPF. Reenviar o mesmo CPF devolve o mesmo cliente_id em vez de erro de duplicado. Use isso para recuperar o id a qualquer momento.

Corpo

Campo desconhecido no corpo gera erro 400 em vez de ser ignorado. Isso é proposital, para que erro de digitação apareça na integração e não em produção.

Sobre os três campos marcados: o DETRAN-RJ só libera a consulta de processos de suspensão e de cassação com CNH + data de nascimento + data da primeira habilitação. Sem os três, você ainda recebe multas e pontuação, mas o JSON volta sem os processos administrativos. A resposta avisa quando isso acontece.

Exemplo

curl -X POST https://api.infrajus.com.br/v1/clientes \
  -H "x-api-key: $INFRAJUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Souza",
    "cpf": "123.456.789-00",
    "cnh_numero": "01234567890",
    "cnh_uf": "RJ",
    "data_nascimento": "1985-03-12",
    "data_primeira_cnh": "2004-07-30"
  }'

Resposta: 201 quando o condutor foi criado agora, 200 quando já existia

{
  "success": true,
  "data": {
    "cliente_id": "8f1c...c2",
    "cpf": "12345678900",
    "nome": "Maria Souza",
    "criado": true,
    "raspagem": {
      "status": "em_fila",
      "consultado_em": null,
      "consulta_cobrada": true
    },
    "avisos": []
  }
}

consulta_cobrada indica se esse POST disparou uma raspagem nova. Quando o CPF já tinha uma consulta de menos de 12 horas, reaproveitamos o resultado, consulta_cobrada vem false e nada é debitado da sua cota.

GET /v1/clientes/{cliente_id}

Devolve o JSON completo da última raspagem.

curl https://api.infrajus.com.br/v1/clientes/8f1c...c2 -H "x-api-key: $INFRAJUS_API_KEY"

Enquanto a raspagem não terminou

{
  "success": true,
  "data": {
    "cliente_id": "8f1c...c2",
    "raspagem": { "status": "em_fila", "consultado_em": null },
    "dados": null,
    "avisos": ["A raspagem ainda está na fila do DETRAN-RJ. ..."]
  }
}

Faça polling neste endpoint. Sugestão: a cada 30 segundos, por até 15 minutos.

Só considere o resultado seu quando status for concluida. Duas situações fazem o status continuar em em_fila mesmo com dados preenchido, e nas duas o avisos explica o que houve:

• Re-consulta de um condutor que você já tinha consultado antes. O dados traz o extrato da consulta anterior, e raspagem.consultado_em traz a data daquele extrato. Use se serve, ou continue no polling até virar concluida.
• A tentativa mais recente não completou (o DETRAN-RJ oscila). Entregamos o último extrato válido que temos e re-tentamos automaticamente por conta própria. Você não precisa reenviar o POST nem gasta nova consulta.

Em nenhum caso devolvemos JSON vazio se existir um extrato bom para entregar. Um dados sem multas significa condutor sem multas, nunca falha de consulta.

Quando terminou

{
  "success": true,
  "data": {
    "cliente_id": "8f1c...c2",
    "nome": "Maria Souza",
    "cpf": "12345678900",
    "raspagem": { "status": "concluida", "consultado_em": "2026-08-01T14:32:10.221Z" },
    "resumo": {
      "pontos_detran": 17,
      "pontuacao_atual": 17,
      "total_suspensoes": 1,
      "total_cassacoes": 0,
      "valor_total_multas": 4382.51
    },
    "dados": {
      "provider": "detran-rj",
      "multas": [ ... ],
      "pontuacao": { ... },
      "cnh": null,
      "recurso_suspensao": { "processos": [ ... ], "consultado_em": "..." },
      "recurso_cassacao": { "processos": [ ... ], "consultado_em": "..." },
      "erros": { "multas": null, "pontuacao": null, "cnh": "Endpoint indisponível no DETRAN-RJ", "recurso_suspensao": null, "recurso_cassacao": null },
      "consultado_em": "2026-08-01T14:32:10.221Z"
    },
    "avisos": []
  }
}

dados.multas[]

dados.pontuacao

Use sempre o *_detalhado[] para exibir status. O booleano global só diz que existe pelo menos um processo ativo. Um condutor pode ter 1 ativo e 2 cancelados ao mesmo tempo.

dados.recurso_suspensao.processos[] e dados.recurso_cassacao.processos[]

Tabela rica dos endpoints de acompanhamento, com processos em qualquer fase (defesa prévia, arquivado, deferido, suspenso, bloqueada):

numero, data_processo, situacao_atual, prazo_suspensao, total_multas, total_pontos.

Resultado vazio legítimo

Quando o DETRAN responde de forma terminal, pontuacao.sem_registro_detran vem preenchido e avisos explica em português o que fazer:

Isso não é falha: é resposta oficial do portal.

dados.cnh

Sempre null. O endpoint de consulta de CNH do DETRAN-RJ está fora do ar (404) e não faz parte da entrega.

dados.erros

Uma entrada por subconsulta, dizendo se ela completou. null significa que aquela subconsulta foi bem. Quando não, o valor é uma frase fixa ("Consulta indisponível no DETRAN-RJ nesta tentativa"). Serve para você saber o que faltou naquele extrato, e o retry automático já está em curso.

Limites

A cota conta raspagens disparadas, não requisições HTTP. GET nunca consome cota.

Erros

Todos no mesmo formato:

{ "success": false, "error": { "code": "QUOTA_EXCEEDED", "message": "..." } }

Proteção de dados

Os CPFs enviados são dados pessoais de terceiros. O escritório que envia é o controlador e declara ter base legal (procuração do titular) para a consulta; a InfraJus atua como operador, tratando os dados apenas para executar a raspagem contratada. O uso da chave está condicionado ao contrato assinado com essa cláusula.

InfraJus, API de Raspagem v1. Dúvidas de integração ou pedido de ampliação de cota: fale com o seu contato na InfraJus.