API da Lupa Forense

Consulte pela API a base nacional de publicações judiciais (DJEN/CNJ), com as mesmas consultas do painel, e o que consta sobre uma empresa em fontes públicas. Versão atual: v1.

Referência interativa: todas as rotas, parâmetros, respostas e erros, gerados do contrato OpenAPI 3.1. Importe o arquivo no Postman, no Insomnia ou num gerador de SDK.

Abrir a referência Baixar openapi.yaml

Introdução

A API é REST sobre HTTPS e responde em JSON (UTF-8). Todos os endpoints de dados ficam sob o prefixo /v1.

URL base

https://do-api.debit.com.br/v1

Autenticação

Toda requisição exige uma chave de API. Crie e gerencie suas chaves no painel, em Minha conta → API. A chave completa é exibida uma única vez na criação — guarde-a com segurança.

Envie a chave no cabeçalho Authorization:

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://do-api.debit.com.br/v1/me"

Alternativamente, o cabeçalho X-API-Key: SUA_CHAVE também é aceito. Use a chave apenas no servidor, nunca em navegadores ou aplicativos do usuário final.

Ao criar a chave, escolha o que ela pode consultar: Publicações e processos (escopo read, todas as rotas menos as de empresa) e Empresas (escopo empresas, as rotas /v1/empresas). Chaves criadas antes dos escopos só têm read: para consultar empresas, crie uma chave nova.

Limites de uso

Cada chave tem um limite de requisições por minuto. As respostas trazem os cabeçalhos:

X-RateLimit-Limit — teto na janela.
X-RateLimit-Remaining — requisições restantes.
X-RateLimit-Reset — segundos até a janela reiniciar.

Ao exceder o limite, a API retorna 429 Too Many Requests com o cabeçalho Retry-After (segundos).

Cota do plano de API

As rotas de empresa contam também na cota do plano de API (por exemplo, 50 mil consultas em 30 dias), comprado em Compras. Só a resposta de sucesso conta: CNPJ inválido, CNPJ não encontrado ou pedido recusado não gastam consulta. As respostas trazem:

X-Quota-Limit: consultas do plano no período.
X-Quota-Remaining: consultas que ainda restam, já contando esta.

Sem plano, ou com a cota esgotada, a resposta é 402. O uso do período aparece em Minha conta → API.

Paginação

Endpoints de listagem aceitam limit (padrão 25, máximo 200) e offset. A resposta traz total, limit, offset e items.

Erros

Erros seguem o formato:

{ "error": { "code": "unauthorized", "message": "chave de API invalida" } }

HTTP	code	Quando
400	`bad_request`	Parâmetro inválido.
401	`unauthorized`	Chave ausente, inválida, revogada ou expirada.
402	`payment_required`	Rota de empresa sem plano de API vigente.
402	`quota_exceeded`	Cota do plano esgotada no período.
403	`forbidden`	A chave não tem o escopo da rota.
404	`not_found`	Recurso não encontrado.
429	`rate_limited`	Limite por minuto excedido.
500	`internal_error`	Erro interno.

Endpoints

`GET` /v1/empresas/{cnpj}

O que consta sobre a empresa: perfil da Receita Federal, contagem de processos no DJEN (por polo, tribunal, classe e ano, com a cobertura de cada tribunal), sanções CEIS/CNEP, dívida ativa da União e cadastro de empregadores do MTE. A resposta é sempre da empresa (matriz), mesmo quando o CNPJ é de uma filial. Exige o escopo empresas e um plano de API.

Parâmetro	Obrig.	Descrição
`cnpj`	sim	No caminho: CNPJ de 14 caracteres, com ou sem máscara (aceita o alfanumérico), ou a raiz de 8.

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://do-api.debit.com.br/v1/empresas/11222333000181"

`GET` /v1/empresas/{cnpj}/processos

Processos em que a empresa é parte, do mais recente para o mais antigo, no envelope de paginação.

Parâmetro	Obrig.	Descrição
`cnpj`	sim	No caminho: CNPJ de 14 caracteres, com ou sem máscara (aceita o alfanumérico), ou a raiz de 8.
`limit`	não	Itens por página (padrão 50, máx. 200).
`offset`	não	Deslocamento (padrão 0).

`GET` /v1/empresas/{cnpj}/novidades

Publicações novas envolvendo a empresa, em ordem de carga, para alimentar alertas. Guarde proximo_cursor e mande-o como desde na próxima chamada; repita enquanto tem_mais for true.

Parâmetro	Obrig.	Descrição
`cnpj`	sim	No caminho: CNPJ de 14 caracteres, com ou sem máscara (aceita o alfanumérico), ou a raiz de 8.
`desde`	não	Cursor: o proximo_cursor da resposta anterior. Sem ele, os últimos 7 dias.
`limit`	não	Itens por chamada (padrão 100, máx. 200).

Nenhuma rota de empresa traz nome de pessoa física: sócios e outras partes pessoa física vêm só contados. Empresário individual e MEI vêm com restrito: true, sem nome nem processos.

`GET` /v1/communications

Busca publicações do acervo. Retorna uma coleção paginada.

Parâmetro	Obrig.	Descrição
`q`	não	Busca textual no corpo da publicação (mín. 3 caracteres).
`numero_oab`	não	Número da OAB do advogado (use junto com uf_oab).
`uf_oab`	não	UF da OAB (ex.: SP).
`numero_processo`	não	Número CNJ (com ou sem máscara).
`tribunal`	não	Sigla do tribunal (ex.: TJSP).
`tipo_comunicacao`	não	Tipo da comunicação (ex.: Intimação).
`orgao_id`	não	Identificador do órgão.
`data_inicio`	não	Data inicial (YYYY-MM-DD), inclusiva.
`data_fim`	não	Data final (YYYY-MM-DD), inclusiva.
`limit`	não	Itens por página (padrão 25, máx. 200).
`offset`	não	Deslocamento para paginação (padrão 0).

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://do-api.debit.com.br/v1/communications?tribunal=TJSP&q=penhora&limit=25"

`GET` /v1/communications/{id}

Detalhe de uma publicação, com advogados e partes vinculados.

`GET` /v1/processos

Lista processos (número CNJ distinto) com agregados: total de publicações, primeira/última data e tribunal.

Parâmetro	Obrig.	Descrição
`q`	não	Busca textual (mín. 3 caracteres).
`tribunal`	não	Sigla do tribunal.
`data_inicio`	não	Data inicial (YYYY-MM-DD).
`data_fim`	não	Data final (YYYY-MM-DD).
`limit`	não	Itens por página (padrão 25, máx. 200).
`offset`	não	Deslocamento (padrão 0).

`GET` /v1/processos/{numero}

Dossiê do processo: todas as publicações + advogados + partes agregados.

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://do-api.debit.com.br/v1/processos/0000000-00.0000.0.00.0000"

`GET` /v1/lawyers

Busca advogados por OAB e/ou nome (até 200 resultados).

Parâmetro	Obrig.	Descrição
`numero_oab`	não	Número da OAB (use com uf_oab).
`uf_oab`	não	UF da OAB.
`nome`	não	Trecho do nome do advogado.

`GET` /v1/lawyers/{id}

Perfil do advogado + processos em que aparece.

`GET` /v1/parties

Busca partes por nome e/ou tipo (paginada).

Parâmetro	Obrig.	Descrição
`nome`	não	Trecho do nome da parte.
`tipo`	não	Tipo da parte.
`limit`	não	Itens por página (padrão 25, máx. 200).
`offset`	não	Deslocamento (padrão 0).

`GET` /v1/parties/{id}

Perfil da parte + processos em que aparece.

`GET` /v1/tribunals

Lista de tribunais com metadados.

Parâmetro	Obrig.	Descrição
`sigla`	não	Filtro por sigla (correspondência parcial).
`uf`	não	Filtro por UF (exato).
`ativo`	não	true/false para filtrar por tribunal ativo.

`GET` /v1/me

Identidade da chave e limites vigentes — útil para validar a integração.

Rotas sob contrato

Algumas rotas exigem um escopo que não aparece no painel: ele é concedido à mão, sob contrato, porque a rota devolve dado de pessoa física ou atende uma integração específica. Sem o escopo, a resposta é 403. Nenhuma delas conta na cota do plano; todas contam no limite por minuto da chave.

Cadastro da Receita (escopo cadastro): GET /v1/cadastro/{cnpj} e POST /v1/cadastro/consulta, com sócios pessoa jurídica, participações e endereço, até 500 CNPJs por pedido.
Sanções (escopo sancoes): POST /v1/sancoes/consulta, sanções ativas no CEIS e no CNEP de até 500 CPFs e CNPJs.
Precatórios (escopo precatorios): POST /v1/precatorios/consulta, posição na fila do tribunal, ritmo de pagamento do ente e previsão.
DJEN compatível (escopo read, disponível a qualquer chave): GET /v1/djen/api/v1/comunicacao, mesmos parâmetros e envelope da API do DJEN. Basta trocar o baseUrl.

Corpos, respostas e erros de cada uma estão na referência interativa.

OAB e número CNJ

O número CNJ pode ser enviado com ou sem máscara (0000000-00.0000.0.00.0000 ou 20 dígitos) — a API normaliza.
Para OAB, envie numero_oab e uf_oab juntos para maior precisão.
Buscas textuais (q) exigem no mínimo 3 caracteres.

Introdução

Autenticação

Limites de uso

Cota do plano de API

Paginação

Erros

Endpoints

GET /v1/empresas/{cnpj}

GET /v1/empresas/{cnpj}/processos

GET /v1/empresas/{cnpj}/novidades

GET /v1/communications

GET /v1/communications/{id}

GET /v1/processos

GET /v1/processos/{numero}

GET /v1/lawyers

GET /v1/lawyers/{id}

GET /v1/parties

GET /v1/parties/{id}

GET /v1/tribunals

GET /v1/me