> ## Documentation Index > Fetch the complete documentation index at: https://docs.jusfy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Inicia uma consulta do JusScore > Recebe um CPF ou CNPJ e inicia a busca de processos judiciais. A consulta é **assíncrona**: a resposta normal traz `situacao: "PROCESSANDO"` e o `id_consulta`, que deve ser consultado em `GET /api/jus-score/{id_consulta}` até concluir. Quando o mesmo documento já foi consultado nos últimos 30 dias, o resultado completo vem já nesta resposta, com `situacao: "CONCLUIDA"`. ## Acompanhando a consulta (polling) - **Intervalo**: repita o `GET` a cada ~15 segundos enquanto a `situacao` for `"PROCESSANDO"`. - **Custo**: a consulta é cobrada uma única vez, no `POST`. Os `GET`s de acompanhamento não são cobrados, em nenhuma situação. - **Estados**: `situacao` só tem `"PROCESSANDO"` e `"CONCLUIDA"`; não existe estado de falha. Erros de comunicação com a base de processos voltam como `502`/`504` no `GET` e a consulta segue válida: repita em instantes. - **Quando desistir**: tempo esperado de conclusão e limite de espera _pendente: produto_. - **Passado o limite**: o que fazer (novo `POST` ou suporte) _pendente: produto_. ## Webhook (opcional) Informe `url_retorno` (https) e nós entregamos o resultado por `POST` nela assim que a consulta concluir — sem necessidade de polling. A entrega leva a **sua API key** no header `x-api-key`: é assim que você confirma que a chamada veio da Jusfy. Compare com a sua key antes de aceitar o payload. Responda **2xx** para confirmar o recebimento. Qualquer outra resposta (ou timeout de 15s) é retentada 5 vezes, com espera crescente de 1min, 5min, 15min, 1h e 6h. Esgotadas as tentativas, a entrega é registrada como falha e o resultado continua disponível pelo `GET`. Headers da entrega: `x-api-key` (sua key), `x-jusfy-event` (`jus_score.concluida`) e `x-jusfy-delivery` (o `id_consulta`, útil para deduplicar). ## OpenAPI ````yaml /openapi/legado.json post /api/jus-score openapi: 3.0.0 info: title: Calculadoras Jusfy API description: >- Rotas sem versão (`/api/...`). Continuam funcionando, mas a versão atual da API é a v1 (`/api/v1`): para integrações novas, use a v1 e siga o [guia de migração](https://docs.jusfy.com.br/fundamentos/migracao-do-legado). A política de versionamento e depreciação está na [política de versionamento](https://docs.jusfy.com.br/fundamentos/migracao-do-legado#pol%C3%ADtica-de-versionamento). version: legacy contact: {} servers: - url: https://api.jusfy.dev/calculators security: [] tags: - name: Calculadoras description: >- Execução das calculadoras jurídicas e consulta dos índices de correção. Cada cálculo recebe um payload, retorna o resultado processado e exige API key no header `x-api-key`. - name: Consultas description: >- Consultas de dados (veículos, condutores e documentos). Cada consulta recebe o documento, retorna os dados encontrados e exige API key no header `x-api-key`. A maioria responde na mesma requisição; o **rastreamento veicular** e o **buscador processual** são assíncronos — devolvem `202` com um protocolo e entregam o resultado por webhook e/ou pelo `GET` do protocolo. - name: JusScore description: >- Consulta de processos judiciais por CPF/CNPJ, com score de risco consolidado e a lista detalhada dos processos. É assíncrona: o POST inicia a consulta e o GET devolve o resultado quando pronto. Exige API key no header `x-api-key`. - name: Consumo description: >- Consumo da própria API key: quantas chamadas cada produto recebeu num período, separando as cobradas das não cobradas. Não exige escopo; exige API key no header `x-api-key`. - name: Health description: >- Verificações de disponibilidade do serviço (liveness e readiness). Rotas abertas, sem autenticação. paths: /api/jus-score: post: tags: - JusScore summary: Inicia uma consulta do JusScore description: >- Recebe um CPF ou CNPJ e inicia a busca de processos judiciais. A consulta é **assíncrona**: a resposta normal traz `situacao: "PROCESSANDO"` e o `id_consulta`, que deve ser consultado em `GET /api/jus-score/{id_consulta}` até concluir. Quando o mesmo documento já foi consultado nos últimos 30 dias, o resultado completo vem já nesta resposta, com `situacao: "CONCLUIDA"`. ## Acompanhando a consulta (polling) - **Intervalo**: repita o `GET` a cada ~15 segundos enquanto a `situacao` for `"PROCESSANDO"`. - **Custo**: a consulta é cobrada uma única vez, no `POST`. Os `GET`s de acompanhamento não são cobrados, em nenhuma situação. - **Estados**: `situacao` só tem `"PROCESSANDO"` e `"CONCLUIDA"`; não existe estado de falha. Erros de comunicação com a base de processos voltam como `502`/`504` no `GET` e a consulta segue válida: repita em instantes. - **Quando desistir**: tempo esperado de conclusão e limite de espera _pendente: produto_. - **Passado o limite**: o que fazer (novo `POST` ou suporte) _pendente: produto_. ## Webhook (opcional) Informe `url_retorno` (https) e nós entregamos o resultado por `POST` nela assim que a consulta concluir — sem necessidade de polling. A entrega leva a **sua API key** no header `x-api-key`: é assim que você confirma que a chamada veio da Jusfy. Compare com a sua key antes de aceitar o payload. Responda **2xx** para confirmar o recebimento. Qualquer outra resposta (ou timeout de 15s) é retentada 5 vezes, com espera crescente de 1min, 5min, 15min, 1h e 6h. Esgotadas as tentativas, a entrega é registrada como falha e o resultado continua disponível pelo `GET`. Headers da entrega: `x-api-key` (sua key), `x-jusfy-event` (`jus_score.concluida`) e `x-jusfy-delivery` (o `id_consulta`, útil para deduplicar). operationId: JusScoreController_iniciar[0] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IniciarConsultaDto' responses: '200': description: >- Consulta iniciada (`PROCESSANDO`) ou resultado completo, quando o documento já estava em cache. content: application/json: schema: example: statusCode: 200 message: Consulta do JusScore em processamento timestamp: '2026-09-03T18:00:00.000Z' path: /api/jus-score result: situacao: PROCESSANDO id_consulta: jsq_7c1f9a52-3d84-4a0b-9f26-1e5c0b8a4d31 '400': description: >- Documento inválido. `message` é a **lista** de erros de validação desta API (campo + motivo), diferente dos demais erros, em que é uma string. content: application/json: schema: example: statusCode: 400 code: invalid_request message: - >- documento deve ser um CPF (11 dígitos) ou CNPJ (14 dígitos) requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-03T18:00:00.000Z' path: /api/jus-score '401': description: >- API key ausente ou que não pertence a nenhum cliente (`code: invalid_api_key`). A `message` diz qual dos dois. content: application/json: examples: missing: summary: Key ausente value: statusCode: 401 message: Missing API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/jus-score invalid: summary: Key inválida value: statusCode: 401 message: Invalid API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/jus-score '403': description: >- Acesso negado. Dois motivos, distinguidos pelo `code`: o cliente não está ativo (`inactive_client`), ou a API key não tem o escopo deste produto (`insufficient_scope`, com o escopo na `message`). A liberação de produtos é feita pela equipe Jusfy. content: application/json: examples: inactive_client: summary: Cliente não ativo value: statusCode: 403 message: Client is not active code: inactive_client requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/jus-score insufficient_scope: summary: Sem o escopo do produto value: statusCode: 403 message: 'Missing scope: ' code: insufficient_scope requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/jus-score '422': description: Documento recusado pelo backend da Jusfy. content: application/json: schema: example: statusCode: 422 code: payload_rejected message: documento inválido requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-03T18:00:00.000Z' path: /api/jus-score '429': description: >- Limite de requisições por minuto do cliente neste produto excedido. `Retry-After` diz em quantos segundos a janela vira. Toda resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. content: application/json: schema: example: statusCode: 429 code: rate_limit_exceeded message: >- Rate limit exceeded for jus-score:execute: 60 requests per minute. Retry in 42s. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/jus-score '502': description: >- Falha ao falar com a base de processos. A consulta **não** foi executada e pode ser repetida — repetir inicia uma consulta nova. content: application/json: schema: example: statusCode: 502 code: upstream_error message: >- Não foi possível iniciar a consulta de processos. Tente novamente em instantes. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-03T18:00:00.000Z' path: /api/jus-score '504': description: Tempo limite ao falar com o backend da Jusfy. content: application/json: schema: example: statusCode: 504 code: upstream_timeout message: JusScore provider timed out requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-03T18:00:00.000Z' path: /api/jus-score security: - api-key: [] components: schemas: IniciarConsultaDto: type: object properties: documento: type: string description: >- CPF (11 dígitos) ou CNPJ (14 dígitos) do consultado, com ou sem máscara. Separadores são aceitos e ignorados. example: '14065221803' url_retorno: type: string description: >- URL https que receberá o resultado por POST quando a consulta concluir. Opcional — sem ela, consulte o resultado pelo GET. A entrega inclui sua API key no header `x-api-key`. example: https://seu-sistema.com.br/webhooks/jus-score required: - documento securitySchemes: api-key: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.