> ## 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. # Dispara a busca de processos de um CPF ou CNPJ (assíncrona) > Inicia a busca por processos judiciais associados ao documento. **A consulta não responde na hora**: o fornecedor processa por tempo indeterminado, então esta rota devolve `202` com um protocolo. O resultado é obtido em duas partes: o **resumo** (quantos processos foram encontrados) chega por webhook e pelo `GET` do protocolo, e os **processos** vêm por `GET /api/consultas/buscador-processual/{id}/processos`, paginado. Eles não vêm no webhook porque um documento com muitos processos gera megabytes de payload. **Guardamos no máximo 1.000 processos por consulta.** Acima disso a resposta traz `truncated: true` — e, nesse caso, os processos devolvidos são uma **amostra arbitrária**: a ordem em que o fornecedor os entrega não é cronológica, então eles **não** são "os mais recentes". **A consulta é cobrada neste disparo**, não na entrega — inclusive se o processamento depois expirar. Não há deduplicação: dois disparos para o mesmo documento são duas consultas cobráveis. Em caso de erro de rede sem resposta, prefira consultar antes de repetir — nesta consulta um erro **não garante** que nada foi cobrado. ## OpenAPI ````yaml /openapi/legado.json post /api/consultas/buscador-processual 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://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado). A política de versionamento e depreciação está na [política de versionamento](https://api.jusfy.dev/calculators/api/reference/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/consultas/buscador-processual: post: tags: - Consultas summary: Dispara a busca de processos de um CPF ou CNPJ (assíncrona) description: >- Inicia a busca por processos judiciais associados ao documento. **A consulta não responde na hora**: o fornecedor processa por tempo indeterminado, então esta rota devolve `202` com um protocolo. O resultado é obtido em duas partes: o **resumo** (quantos processos foram encontrados) chega por webhook e pelo `GET` do protocolo, e os **processos** vêm por `GET /api/consultas/buscador-processual/{id}/processos`, paginado. Eles não vêm no webhook porque um documento com muitos processos gera megabytes de payload. **Guardamos no máximo 1.000 processos por consulta.** Acima disso a resposta traz `truncated: true` — e, nesse caso, os processos devolvidos são uma **amostra arbitrária**: a ordem em que o fornecedor os entrega não é cronológica, então eles **não** são "os mais recentes". **A consulta é cobrada neste disparo**, não na entrega — inclusive se o processamento depois expirar. Não há deduplicação: dois disparos para o mesmo documento são duas consultas cobráveis. Em caso de erro de rede sem resposta, prefira consultar antes de repetir — nesta consulta um erro **não garante** que nada foi cobrado. operationId: AsyncQueriesController_buscadorProcessual[0] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LawsuitQueryDto' responses: '202': description: >- Consulta aceita e em processamento. Guarde o `id` — e o `signingSecret`, que **não é exibido novamente**. content: application/json: schema: type: object example: statusCode: 202 message: Consulta assíncrona aceita timestamp: '2026-09-08T18:00:00.000Z' path: /api/consultas/buscador-processual result: id: aqry_7c2e1a90-3b4d-5e6f-8a91-b2c3d4e5f607 consulta: buscador-processual status: pending createdAt: '2026-09-08T18:00:00.000Z' expiresAt: '2026-09-08T18:30:00.000Z' statusUrl: >- /api/consultas/buscador-processual/aqry_7c2e1a90-3b4d-5e6f-8a91-b2c3d4e5f607 url_retorno: https://cliente.exemplo.com/webhooks/jusfy signingSecret: whsec_Jd3nP8xQ2vR7tY1uW4zA6bC9eF0gH5iK8lM3oN7qS2u '400': description: >- Documento ou `url_retorno` inválidos. `message` é a **lista** de erros de validação desta API. Nada é cobrado. content: application/json: schema: example: statusCode: 400 code: invalid_request message: - document deve ser um CPF ou CNPJ válido requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-02T18:00:00.000Z' path: /api/consultas/buscador-processual '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/consultas/{consulta} 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/consultas/{consulta} '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/consultas/{consulta} 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/consultas/{consulta} '422': description: Payload recusado pelo provedor da consulta. content: application/json: schema: example: statusCode: 422 code: payload_rejected message: Invalid query payload requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-02T18:00:00.000Z' path: /api/consultas/buscador-processual '429': description: >- Consultas assíncronas simultâneas demais para este cliente, somando todos os tipos. Aguarde as atuais terminarem; `Retry-After` sugere quando tentar de novo (estimativa, não garantia). Nada é cobrado (`code: too_many_pending_queries`). Também sai quando o limite de requisições por minuto do cliente é excedido (`code: rate_limit_exceeded`), com `Retry-After` exato. content: application/json: schema: example: statusCode: 429 code: too_many_pending_queries message: Too many pending async queries requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-02T18:00:00.000Z' path: /api/consultas/buscador-processual '503': description: >- Provedor temporariamente indisponível. A consulta **pode** ter sido iniciada mesmo assim — consulte antes de repetir. content: application/json: schema: example: statusCode: 503 code: upstream_unavailable message: >- A consulta de processos está temporariamente indisponível, tente novamente mais tarde. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-09-02T18:00:00.000Z' path: /api/consultas/buscador-processual security: - api-key: [] components: schemas: LawsuitQueryDto: type: object properties: document: type: string description: >- CPF ou CNPJ do titular consultado, com ou sem máscara. Separadores (incluindo a barra do CNPJ) são aceitos e ignorados. O dígito verificador é validado antes da consulta. example: '52998224725' url_retorno: type: string description: >- URL `https` que receberá o aviso quando a consulta terminar. Opcional: sem ela, o resultado é obtido apenas pelas rotas de protocolo. **O webhook leva os processos quando eles cabem no corpo** (teto de 64 KiB, ~16 processos); acima disso leva só o resumo (`totalFound`, `returned`, `truncated`). O campo `dataIncluded`, no topo do corpo, diz qual dos dois casos ocorreu — e quando é `false` a chave `lawsuits` fica **ausente**, nunca vazia. Em qualquer caso os processos podem ser buscados em `GET /api/consultas/buscador-processual/{id}/processos`, paginado. Deve apontar para um domínio público na porta 443; endereços IP, hosts internos e `http` são recusados. A entrega é assinada; o segredo vem no campo `signingSecret` da resposta e **não** é exibido novamente. example: https://cliente.exemplo.com/webhooks/jusfy required: - document 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.