Documentation Index
Fetch the complete documentation index at: https://docs.judit.io/llms.txt
Use this file to discover all available pages before exploring further.
Resposta em cache (
cached_response)Quando você cria uma consulta processual ou histórica, a Judit primeiro verifica se o dado já está em nossa base. Se estiver, devolvemos imediatamente o resultado — tanto na resposta da API quanto via webhook (se você tiver cadastrado) — com o campo cached_response: true.Em paralelo, a Judit dispara uma atualização nos tribunais. Se houver alguma mudança, você recebe uma segunda resposta com cached_response: false. Esse é o resultado mais atual.Por isso, é normal receber dois webhooks aparentemente iguais para o mesmo request_id:- O primeiro vem do cache (
cached_response: true) - O último é o atualizado (
cached_response: false)
POST para a URL configurada com o objeto resposta no corpo. É a forma mais eficiente e barata de integração para fluxos assíncronos.
🤖 Padrão de entrega: HTTP POST com Content-Typeapplication/json. Use uma URL HTTPS pública. Implemente idempotência baseada emrequest_id+cached_response. Em caso de erro 5xx ou timeout, fazemos retry com backoff.
Quando usar
Fluxos assíncronos em escala
Em cargas grandes (centenas/milhares de requisições), webhook elimina o polling e reduz drasticamente o consumo da sua quota.
Notificações de monitoramento
Receba imediatamente quando um monitoramento detectar nova movimentação ou nasceu um novo processo.
Integração com sistemas internos
Fila → handler → ERP/CRM/BI: padrão event-driven sem precisar consultar a Judit constantemente.
Identificação de cache vs. atualização
Use
cached_response para diferenciar a resposta inicial (cache) da posterior (atualizada do tribunal).Como funciona
A cada evento, fazemos umPOST HTTPS para sua URL com o payload em application/json. A entrega é incremental — você pode receber várias respostas para o mesmo request_id antes de chegar o evento request_completed que sinaliza fim do fluxo.
Configurando seu webhook
Existem duas formas de receber retornos:1. Conta-toda (recomendado)
Cadastre uma URL única que recebe todas as respostas (consultas + monitoramentos). Solicite via Suporte — leva poucos minutos.
2. Por requisição
Adicione
callback_url no payload da requisição. Útil para roteamento dinâmico (ex.: webhook por ambiente ou cliente final).O parâmetro
with_attachments aplica-se apenas a consultas processuais (search_type: "lawsuit_cnj").Eventos enviados
event_type | Quando dispara | Payload |
|---|---|---|
response_created | Cada vez que um novo response_data é gerado para a requisição (cache ou tribunal) | Objeto lawsuit, entity, warrant ou execution |
request_completed | Fim do fluxo da requisição (todos os tribunais responderam) | Objeto request final com status: "completed" |
tracking_response | Disparado por monitoramentos (cada nova movimentação detectada) | Mesmo formato de response_created mas via tracking_id |
callback_id— id único da entrega (use para idempotência).reference_id—request_idoutracking_idque originou o evento.payload— conteúdo (resposta processual, dados cadastrais, etc.).
cached_response: lendo as duas entregas
A maior parte das requisições gera duas entregas em sequência: a primeira do cache e a segunda atualizada. Use cached_response para identificar.
| Sequência | event_type | cached_response | Significado |
|---|---|---|---|
| 1 | response_created | true | Veio do datalake JUDIT (resposta inicial rápida). |
| 2 | response_created | false | Coleta atual no tribunal. Sempre que existir, é a versão definitiva. |
| 3 | request_completed | — | Todos os tribunais responderam. Sua aplicação pode encerrar o ciclo. |
⚠️ Em consultas processuais recentemente refrescadas (dentro docache_ttl_in_days), você pode receber apenas a entrega comcached_response: true— não há nova coleta no tribunal porque o cache ainda é válido.
Boas práticas (essencial para produção)
✅ Idempotência
✅ Idempotência
Use
callback_id como chave de idempotência: rejeite duplicatas baseado nele. Em retries, o mesmo callback_id é reentregue.✅ Resposta rápida (HTTP 2xx)
✅ Resposta rápida (HTTP 2xx)
Responda
200 OK em menos de 10 segundos. Processe assincronamente (fila/worker). Se demorar, contamos como falha e fazemos retry.✅ Persistir o evento antes de processar
✅ Persistir o evento antes de processar
Padrão produção: gravar o evento bruto em fila/log e processar depois. Evita perda em caso de erro de aplicação.
✅ Tratar `cached_response: true` como provisório
✅ Tratar `cached_response: true` como provisório
Sempre considere a entrega com
cached_response: false (quando existir) como a versão final. UI/relatórios devem refletir o último valor.✅ Validar origem (HTTPS + IP allowlist)
✅ Validar origem (HTTPS + IP allowlist)
Aceite
POST apenas de IPs Judit (consulte o suporte). Use HTTPS sempre. Em ambientes regulados, valide também o cabeçalho User-Agent.✅ Implementar retry tolerante
✅ Implementar retry tolerante
Em caso de erro 5xx ou timeout, fazemos retries com backoff exponencial. Se sua URL ficar indisponível por muito tempo, perdemos eventos — mantenha o endpoint estável.
Receptor de webhook (exemplo Node.js)
Python (FastAPI)
Envio da resposta
Realizamos uma solicitação POST para o webhook, enviando as respostas conforme os resultados da sua busca. O envio ocorre de forma incremental, à medida que as respostas são geradas, e é concluído quando o status da requisição é atualizado para “completed”.Resposta para consulta histórica:
Exemplo de reposta comcached_response: true:
Ver exemplo de resposta
Ver exemplo de resposta
cached_response: false:
Ver exemplo de resposta
Ver exemplo de resposta
Resposta para consulta processual:
Exemplo de reposta comcached_response: true:
Ver exemplo de resposta
Ver exemplo de resposta
cached_response: false:
Ver exemplo de resposta
Ver exemplo de resposta