Documentação da API ProvJud

ProvJud API — documentação completa

Versão da documentação: 2026-09-01
API base: https://api.provjud.com
OpenAPI: https://api.provjud.com/openapi.json
Swagger interativo: https://api.provjud.com/docs

A ProvJud é uma API privada de discovery judicial, consulta e monitoramento processual, jurisprudência, documentos públicos, dívida ativa federal, certificados A1 e webhooks persistentes.

Esta documentação também foi preparada para consumo por agentes de IA. Valores entre <...> devem ser substituídos. Nunca inclua tokens, senhas administrativas, senhas de certificados ou arquivos PFX em prompts, logs ou repositórios.

1. Conceitos importantes

1.1 Discovery não é certidão negativa

O discovery consulta as fontes integradas e devolve, junto com os processos, um relatório coverage. Um resultado vazio significa apenas que nenhuma ocorrência foi localizada nas fontes e períodos efetivamente cobertos. Não significa inexistência de processos.

Estados usuais de uma execução:

Estados de associação de um processo:

1.2 Operações síncronas e assíncronas

Consultas curtas podem ser síncronas. Pesquisas históricas extensas devem usar jobs:

1. envie POST /v1/discovery/jobs;
2. guarde o job_id;
3. consulte GET /v1/discovery/jobs/{job_id} até o estado terminal;
4. use Idempotency-Key para não duplicar uma solicitação após timeout de rede.

Atualizações processuais seguem o mesmo padrão com POST /v1/processes/{number}/refresh e GET /v1/process-refresh/{job_id}.

2. Autenticação

2.1 Aplicações consumidoras

As aplicações usam Bearer Token:

Authorization: Bearer jd_live_<key_id>.<secret>

Exemplo:

curl --fail-with-body \
  -H "Authorization: Bearer $PROVJUD_TOKEN" \
  -H "X-Request-Id: integracao-123" \
  https://api.provjud.com/v1/sources

O token completo é mostrado somente na criação ou rotação. Armazene-o em um cofre de segredos.

Escopos disponíveis:

Cabeçalhos de resposta relevantes:

X-Request-Id
X-RateLimit-Limit
X-RateLimit-Remaining

2.2 Administração

Os endpoints /v1/admin/* aceitam X-Admin-Key. O console web usa cookie de sessão HttpOnly e proteção CSRF. Não exponha a chave administrativa no frontend da aplicação jurídica.

curl --fail-with-body \
  -H "X-Admin-Key: $PROVJUD_ADMIN_KEY" \
  https://api.provjud.com/v1/admin/api-clients

3. Códigos HTTP e erros

Erro simples:

{"detail":"Credencial de servico obrigatoria"}

Erro de validação:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "String should have at least 3 characters",
      "type": "string_too_short"
    }
  ]
}

4. Início rápido

4.1 JavaScript/TypeScript

const baseUrl = "https://api.provjud.com";
const token = process.env.PROVJUD_TOKEN!;

async function provjud(path: string, init: RequestInit = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "X-Request-Id": crypto.randomUUID(),
      ...init.headers,
    },
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
}

const result = await provjud("/v1/discovery/jobs", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    kind: "company",
    name: "EMPRESA EXEMPLO LTDA",
    identifier: "<CNPJ>",
    aliases: ["EMPRESA EXEMPLO"],
    regions: ["RS", "MG", "SP", "BR"],
    date_start: "2016-01-01",
    date_end: "2026-09-01"
  }),
});

4.2 Python

import os
import uuid
import httpx

headers = {
    "Authorization": f"Bearer {os.environ['PROVJUD_TOKEN']}",
    "X-Request-Id": str(uuid.uuid4()),
}

with httpx.Client(base_url="https://api.provjud.com", headers=headers, timeout=60) as client:
    response = client.get("/v1/jurisprudence/search", params={
        "q": "responsabilidade civil atraso entrega imóvel",
        "court": "STJ",
        "limit": 10,
    })
    response.raise_for_status()
    print(response.json())

5. Discovery

POST /v1/discovery

Executa discovery síncrono. Requer escopo discovery.

curl --fail-with-body -X POST https://api.provjud.com/v1/discovery \
  -H "Authorization: Bearer $PROVJUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind":"company",
    "name":"EMPRESA EXEMPLO LTDA",
    "identifier":"<CNPJ>",
    "aliases":["EMPRESA EXEMPLO"],
    "regions":["RS","MG","SP","BR"],
    "date_start":"2026-08-01",
    "date_end":"2026-09-01"
  }'

Campos:

Resposta ilustrativa:

{
  "run_id": "<uuid>",
  "status": "partial",
  "subject_id": "<uuid>",
  "cases": [
    {
      "cnj_number": "<20-digitos>",
      "court": "TRT4",
      "role": "P",
      "confidence": 0.94,
      "status": "probable",
      "match_basis": ["similar_structured_party_name"],
      "publication_ids": ["<id-origem>"],
      "metadata_available": true
    }
  ],
  "coverage": [
    {"source":"djen","status":"success","results":1,"details":{}},
    {"source":"djen_archive","status":"partial","results":1,"details":{}}
  ],
  "warning": "Ausencia de resultados nao equivale a certidao negativa judicial."
}

POST /v1/discovery/historical

Mesmo contrato de entrada e saída do discovery síncrono, destinado a períodos históricos. Para intervalos extensos prefira o job assíncrono.

POST /v1/discovery/jobs

Cria discovery histórico assíncrono. Aceita Idempotency-Key.

curl --fail-with-body -X POST https://api.provjud.com/v1/discovery/jobs \
  -H "Authorization: Bearer $PROVJUD_TOKEN" \
  -H "Idempotency-Key: discovery-cliente-42-20260901" \
  -H "Content-Type: application/json" \
  -d @discovery.json

Resposta 202:

{"job_id":"<uuid>","status":"queued"}

GET /v1/discovery/jobs/{job_id}

Consulta o job. Trate success, partial e failed como estados terminais. Em partial, sempre leia coverage.

GET /v1/subjects/{identifier}/processes?kind=company

Lista processos já associados ao CPF/CNPJ informado. kind aceita company ou person.

POST /v1/subjects/monitor

Cria monitoramento recorrente do sujeito.

{
  "kind": "company",
  "name": "EMPRESA EXEMPLO LTDA",
  "identifier": "<CNPJ>",
  "aliases": ["EMPRESA EXEMPLO"],
  "regions": ["RS", "MG", "SP", "BR"],
  "frequency": "daily",
  "recurrence_days": 1,
  "lookback_days": 31,
  "callback_url": "https://app.exemplo.com/webhooks/provjud"
}

lookback_days aceita 1 a 3650 e controla as consultas recorrentes. No primeiro cadastro de uma empresa com CNPJ, a ProvJud consulta o cadastro empresarial, adiciona razão social e nome fantasia como aliases, identifica município/UF, inclui automaticamente a região da sede e o escopo nacional (BR) e enfileira um discovery inicial desde a data de abertura. A resposta contém initial_discovery_job_id, initial_discovery_start e company_routing. BR significa todos os tribunais ativos do catálogo nacional; a UF da sede é usada como prioridade operacional, não como exclusão de processos em outros estados. A URL de callback deve usar HTTPS.

6. Processos e documentos

Números CNJ podem ser enviados formatados ou apenas com 20 dígitos.

GET /v1/processes/{number}?refresh=true

Retorna capa, classe, unidade, grau, sigilo, assuntos, partes, movimentações, publicações, documentos públicos, relacionados e informações de cache.

curl --fail-with-body \
  -H "Authorization: Bearer $PROVJUD_TOKEN" \
  "https://api.provjud.com/v1/processes/<NUMERO-CNJ>?refresh=true"

Campos relevantes da resposta:

{
  "cnj_number": "<20-digitos>",
  "formatted_number": "<numero-formatado>",
  "court": "TJMG",
  "degree": "G1",
  "filing_date": "2024-01-10",
  "court_unit": "<unidade>",
  "case_class": "<classe>",
  "confidentiality_level": 0,
  "electronic": true,
  "subjects": [],
  "movements": [],
  "parties": [],
  "public_documents": [],
  "publications": [],
  "related_cases": [],
  "cache": {
    "cached_response": false,
    "collected_at": "2026-09-01T12:00:00Z",
    "age_seconds": 10,
    "stale": false,
    "content_hash": "<sha256>"
  }
}

Recursos especializados do processo

related-precedents aceita q opcional e limit de 1 a 50.

POST /v1/processes/{number}/refresh

Solicita atualização assíncrona.

Atualização pública:

{"scope":"public_documents"}

Tentativa autorizada de autos completos:

{
  "scope": "full_docket",
  "credential_id": "<uuid-do-certificado>",
  "authorization_declaration": "Certificado da própria parte para acesso ao processo em que figura."
}

full_docket exige certificado e declaração. A existência de um certificado válido não garante que o tribunal ofereça autenticação autônoma; o job pode terminar partial ou denied.

Resposta 202:

{"job_id":"<uuid>","status":"queued","scope":"full_docket"}

GET /v1/process-refresh/{job_id}

Retorna estado, tentativas, resultado, erro e timestamps do refresh.

Monitoramento de processo

POST /v1/processes/{number}/monitor

{
  "frequency": "daily",
  "recurrence_days": 1,
  "include_public_documents": true,
  "response_type": "lawsuit",
  "callback_url": "https://app.exemplo.com/webhooks/provjud"
}

Operações:

7. Jurisprudência e pesquisa jurídica

GET /v1/jurisprudence/search

Busca híbrida por texto e similaridade semântica.

Parâmetros:

curl --get https://api.provjud.com/v1/jurisprudence/search \
  -H "Authorization: Bearer $PROVJUD_TOKEN" \
  --data-urlencode "q=responsabilidade civil atraso entrega imóvel" \
  --data-urlencode "court=STJ" \
  --data-urlencode "limit=10"

GET /v1/jurisprudence/decisions/{decision_id}

Retorna a decisão, trechos indexados, metadados e origem preservada.

POST /v1/jurisprudence/research

Pesquisa orientada por pergunta. A resposta é baseada no acervo recuperado; não substitui revisão jurídica.

{
  "question": "Qual é o entendimento recente do STJ sobre atraso na entrega de imóvel e dano moral?",
  "court": "STJ",
  "date_from": "2023-01-01",
  "date_to": "2026-09-01",
  "max_sources": 10
}

max_sources aceita 3 a 30.

Estado do acervo

8. Dívida ativa federal

GET /v1/federal-claims/{cnpj}?sued_only=false

Consulta o snapshot local dos dados abertos da PGFN. sued_only=true restringe a inscrições marcadas como ajuizadas.

Uma fonte sem snapshot carregado é reportada como cobertura partial, com reason=snapshot_not_loaded; isso nunca deve ser interpretado como zero dívidas. O campo sued=true confirma que a inscrição oficial está marcada como ajuizada, mas o número CNJ só é associado quando houver correlação documental auditável.

{
  "cnpj": "<CNPJ>",
  "snapshot": "2026-08",
  "registrations": 2,
  "sued_registrations": 1,
  "consolidated_value": 15000.0,
  "sued_consolidated_value": 10000.0,
  "claims": [
    {
      "registration_number": "<inscricao>",
      "debt_base": "<base>",
      "debtor_name": "EMPRESA EXEMPLO LTDA",
      "sued": true,
      "consolidated_value": 10000.0,
      "correlations": [
        {
          "cnj_number": "<20-digitos>",
          "status": "unverified",
          "confidence": 0.6,
          "source": "trf4_dejf",
          "match_basis": ["nearby_registration_and_process"]
        }
      ]
    }
  ]
}

Uma inscrição ajuizada não equivale automaticamente a um processo distinto. Só trate o número CNJ como confirmado quando correlations[].status for confirmed.

9. Cofre de certificados A1

Requer escopo credentials. O arquivo PKCS#12 e sua senha são cifrados no banco. Metadados podem ser listados; a senha e o PFX nunca são devolvidos.

POST /v1/credentials/certificates

{
  "label": "Certificado Empresa Exemplo 2027",
  "pfx_base64": "<BASE64-DO-PFX>",
  "password": "<SENHA-DO-PFX>",
  "owner_kind": "company",
  "owner_name": "EMPRESA EXEMPLO LTDA",
  "owner_identifier": "<CNPJ>",
  "authorizations": [
    {
      "subject_kind": "company",
      "subject_name": "EMPRESA EXEMPLO LTDA",
      "subject_identifier": "<CNPJ>",
      "relationship": "self",
      "declared_basis": "Certificado pertencente à própria pessoa jurídica.",
      "valid_until": null,
      "evidence": {"source":"client_declaration"}
    }
  ]
}

Relacionamentos aceitos: self, legal_representative, attorney, court_grant.

Regras de segurança:

• o certificado deve corresponder ao identificador do titular;
• autorização de sócio não é presumida para a empresa;
• uso em autos completos exige vínculo provável ou confirmado entre o sujeito autorizado e o processo;
• certificados vencidos são desativados;
• avisos de vencimento podem ser enviados por webhook;
• CAPTCHA ou barreira interativa não é contornado.

Operações:

10. Credenciais PDPJ e Domicílio Judicial

Requer escopo credentials. Este fluxo permite que a própria aplicação jurídica do cliente cadastre as credenciais emitidas pelo Gestão de Clientes/PDPJ. Não envie client_id, client_secret ou tokens em prompts, tickets, URLs ou logs.

Cadastrar pela aplicação cliente

POST /v1/credentials/integrations

Authorization: Bearer jd_live_<key_id>.<secret-provjud>
Content-Type: application/json

{
  "provider": "pdpj",
  "service": "domicilio_judicial",
  "environment": "production",
  "label": "PDPJ Empresa Exemplo",
  "owner_name": "EMPRESA EXEMPLO LTDA",
  "owner_identifier": "00.000.000/0001-00",
  "client_id": "<CLIENT-ID-EMITIDO-PELO-CNJ>",
  "client_secret": "<SECRET-ID-EMITIDO-PELO-CNJ>",
  "token_url": null,
  "api_base_url": null,
  "scopes": ["openid"]
}

Não envie api_client_id: o proprietário é obtido do token ProvJud autenticado. Um cliente não consegue cadastrar, listar ou revogar integrações pertencentes a outro cliente.

Serviços aceitos:

Ambientes aceitos: production e homologation. Para o Domicílio, as URLs oficiais podem ser omitidas; a ProvJud seleciona os endpoints correspondentes ao ambiente durante a validação.

Resposta de criação:

{
  "id": "<uuid-da-integracao>",
  "provider": "pdpj",
  "service": "domicilio_judicial",
  "environment": "production",
  "label": "PDPJ Empresa Exemplo",
  "owner_name": "EMPRESA EXEMPLO LTDA",
  "verification_status": "declared",
  "active": true,
  "created_at": "2026-09-01T16:29:14-03:00"
}

O client_id, o client_secret, o CNPJ completo e qualquer token PDPJ nunca são devolvidos. Os segredos e o payload integral das comunicações são cifrados no banco. Depois do cadastro, um worker valida OAuth, perfil e vínculo do CNPJ e atualiza verification_status para verified ou failed. Integrações verificadas recebem uma fila histórica em janelas de no máximo sete dias, retomável e idempotente, desde a abertura conhecida da empresa; novas janelas mantêm a consulta contínua. A listagem do Domicílio usa somente GET e nunca registra ciência.

Operações do cliente:

O cadastro administrativo equivalente utiliza /v1/admin/integrations e exige api_client_id explícito.

Inteiro teor e registro de ciência

Esta operação pode iniciar prazo processual e tem efeito jurídico. Ela nunca é chamada pelo discovery, por agentes de IA ou por rotinas automáticas. A aplicação cliente deve obter confirmação humana e autorização válida antes da chamada.

POST /v1/credentials/integrations/<integration_id>/communications/<communication_id>/full-text
Authorization: Bearer jd_live_<key_id>.<secret-provjud>
Content-Type: application/json

{
  "register_legal_awareness": true,
  "operator_document": "000.000.000-00",
  "operator_name": "Advogado responsável",
  "authorization_declaration": "Confirmo que possuo autorização para registrar ciência desta comunicação."
}

A ProvJud exige literalmente register_legal_awareness: true, valida o CPF do operador, verifica que integração e comunicação pertencem ao cliente autenticado e aceita apenas credencial ativa e verificada. O conteúdo retornado é cifrado; o CPF é armazenado somente como hash e a declaração, o horário e os identificadores ficam na auditoria. Trate a chamada como não idempotente do ponto de vista jurídico: não repita automaticamente após timeout sem antes consultar o estado.

11. Webhooks persistentes

Webhooks são administrados em /v1/admin/webhooks. O evento é persistido antes da tentativa de entrega. Falhas geram retentativas com atraso crescente e preservação de ordem por assinatura.

Eventos aceitos:

case.updated
case.refresh.failed
jurisprudence.match.created
subject.discovery.completed
subject.case.discovered
discovery.completed
credential.expiring
credential.expired
pdpj.communication.discovered
pdpj.sync.failed

Criar assinatura

POST /v1/admin/webhooks

{
  "name": "Aplicação jurídica principal",
  "api_client_id": "<uuid-do-cliente>",
  "callback_url": "https://app.exemplo.com/webhooks/provjud",
  "event_types": [
    "case.updated",
    "subject.case.discovered",
    "pdpj.communication.discovered",
    "pdpj.sync.failed",
    "jurisprudence.match.created",
    "credential.expiring"
  ]
}

A resposta de criação contém o segredo do webhook uma única vez. Armazene-o em cofre.

Cabeçalhos entregues:

Content-Type: application/json
X-Juridico-Callback-Id: <uuid-da-entrega>
X-Juridico-Event: case.updated
X-Juridico-Signature: sha256=<hex>

Validação em Node.js:

import crypto from "node:crypto";

export function validProvjudWebhook(rawBody: Buffer, signature: string, secret: string) {
  const received = signature.replace(/^sha256=/, "");
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Valide a assinatura sobre os bytes brutos recebidos, antes de converter o JSON. Responda com qualquer status 2xx somente depois de persistir o evento. Use X-Juridico-Callback-Id como chave de idempotência.

Operações administrativas:

12. Administração de clientes da API

O console em https://api.provjud.com/admin usa contas individuais. O primeiro acesso apresenta o cadastro do superadministrador e exige a chave administrativa anterior apenas uma vez, como prova de bootstrap. Em seguida, o usuário lê o QR Code em Google Authenticator, Microsoft Authenticator ou aplicativo TOTP compatível e confirma o primeiro código de seis dígitos.

Cada usuário recebe senha própria, 2FA e sessão revogável em cookie HttpOnly, Secure e SameSite=Strict. As senhas usam Argon2id, sessões expiram após oito horas ou trinta minutos de inatividade, cinco falhas bloqueiam temporariamente a conta e cada código TOTP só pode ser usado uma vez. Dez códigos de recuperação são exibidos somente na ativação e são descartáveis.

Perfis disponíveis:

O superadministrador cadastra o usuário diretamente, informando uma senha inicial forte ou solicitando que a API gere uma. Como ainda não há servidor de e-mail, as credenciais devem ser entregues ao destinatário por um canal seguro. No primeiro acesso, o usuário seleciona Configurar 2FA, informa e-mail e senha e vincula o próprio autenticador. O segredo TOTP aparece somente nesse fluxo de primeiro acesso.

Rotas de usuários:

Cadastro com senha definida pelo administrador:

{
  "email": "advogado@escritorio.com.br",
  "display_name": "Advogado Responsável",
  "role": "operator",
  "password": "Senha-Inicial-Forte-2026!"
}

Para geração segura no servidor, omita password e envie "generate_password": true. A resposta contém temporary_password somente nessa chamada. Nunca grave essa senha em logs.

Edição completa:

{
  "display_name": "Novo Nome",
  "email": "novo-email@escritorio.com.br",
  "role": "auditor",
  "active": true,
  "password": "Nova-Senha-Forte-2026!",
  "reset_mfa": true
}

Alterar a senha, desativar a conta ou redefinir o 2FA revoga as sessões ativas do usuário. Campos não enviados permanecem inalterados.

POST /v1/admin/api-clients

{
  "name": "Sistema Jurídico Principal",
  "scopes": ["discovery", "processes", "jurisprudence", "credentials"],
  "expires_at": null,
  "rate_limit_per_minute": 120
}

Resposta ilustrativa:

{
  "id": "<uuid>",
  "name": "Sistema Jurídico Principal",
  "scopes": ["discovery", "processes", "jurisprudence", "credentials"],
  "token": "jd_live_<key_id>.<secret>"
}

Operações:

Certificados administrativos:

Integrações oficiais administrativas:

13. Catálogo integral de endpoints

Públicos

Discovery e sujeitos — escopo discovery

Processos — escopo processes

Jurisprudência — escopo jurisprudence

Operação — token de serviço

Credenciais — escopo credentials

Administração — sessão individual com senha e TOTP

13. Recomendações para integrações e agentes de IA

1. Consulte openapi.json para tipos canônicos e mudanças de versão.
2. Nunca interprete cases: [] sem examinar coverage.
3. Preserve run_id, job_id, X-Request-Id, fontes, match_basis e confiança em logs internos.
4. Use jobs e idempotência em rotinas longas.
5. Não repita automaticamente operações full_docket bloqueadas por desafio interativo.
6. Não envie PFX, senhas, tokens ou documentos restritos para modelos externos.
7. Exiba ao advogado a fonte, o tribunal, a data e o grau de confiança.
8. Trate sugestões de jurisprudência como apoio revisável, não como conclusão jurídica.
9. Em webhooks, valide HMAC sobre o corpo bruto e deduplique pelo callback ID.
10. Antes de automatizar um endpoint novo, confira o catálogo /v1/sources e o estágio real de cobertura.

14. Recursos oficiais

• Documentação humana: https://provjud.com/documentacao
• Markdown integral: https://provjud.com/provjud-api.md
• Índice para LLMs: https://provjud.com/llms.txt
• Swagger: https://api.provjud.com/docs
• ReDoc: https://api.provjud.com/redoc
• OpenAPI JSON: https://api.provjud.com/openapi.json
• Console administrativo: https://api.provjud.com/admin