Baixar Collection

Escavador API - Documentação

Bem-vindo à API do Escavador

A API do Escavador foi criada para simplificar o acesso a dados públicos jurídicos no Brasil por meio de uma integração confiável, padronizada e pronta para uso em produção.

Com ela, sua aplicação pode consultar e processar informações de pessoas, empresas e processos de forma estruturada, sem depender de coletas manuais em múltiplas fontes.

Nesta documentação, você encontrará:

  • Descrição funcional de cada endpoint.
  • Exemplos de requisição e resposta.
  • Modelos prontos de uso em bash, javascript, php e python.
  • Orientações de autenticação, callbacks e paginação para integrações server-to-server.

Limite de requisições

O limite de requisições no uso da API é de 500 requisições por minuto.

Para mais informações, fale conosco.

Versões

A API do Escavador possui duas versões: V1 e V2. Você pode encontrar mais informações sobre cada uma delas abaixo. Também consulte a página de preços para saber mais sobre os custos de cada versão. É importante identificar quais recursos da API você irá utilizar para escolher a versão mais adequada.

API V1: Conta com funcionalidades de busca e monitoramento de processos, pessoas e empresas, além de consulta e monitoramento em diários oficiais.

API Endpoint: https://api.escavador.com/api/v1

Para acessar a documentação da V1 da API, clique aqui.

API V2: Conta com a funcionalidade de busca de processos e se diferencia da V1 por ter uma maior quantidade de informações estruturadas, de forma mais detalhada.

API Endpoint: https://api.escavador.com/api/v2

Para acessar a documentação da V2 da API, clique aqui.

Autenticação

Personal Access Token (PAT) no padrão Bearer

A API do Escavador utiliza autenticação baseada em Personal Access Tokens (PAT) no padrão Bearer Token, amplamente adotado em integrações server-to-server.

Nesse modelo, o cliente gera, por meio de um painel seguro de gerenciamento, um token de acesso privado de visualização única. Após a criação, esse segredo não é exibido novamente. Para isso, é necessário ter uma conta na plataforma. Você pode fazer isso aqui.

O token deve ser enviado em todas as requisições HTTP no cabeçalho Authorization, com o prefixo Bearer.

Authorization: Bearer seu-token-aqui

Regras de uso do PAT

  • O PAT é destinado exclusivamente a comunicações server-to-server.
  • O token não deve ser exposto em aplicações cliente (frontend), reduzindo a superfície de ataque.
  • O token não substitui nem reutiliza credenciais sensíveis do usuário, como login e senha.

Práticas de segurança adotadas

  • Transmissão segura via HTTPS (TLS 1.2 ou superior), protegendo o token contra interceptação.
  • Revogação imediata pelo próprio cliente, diretamente na plataforma.
  • Escopo de uso controlado, limitado ao contexto da integração.

Responsabilidade e resposta a incidentes

A guarda segura do token é uma responsabilidade compartilhada entre plataforma e cliente, seguindo o modelo padrão da indústria para credenciais de integração. Em caso de suspeita de comprometimento, o token pode ser revogado e substituído rapidamente, sem impacto em outras credenciais ou acessos.

Autenticando na API

Acesse o painel da API na página de gestão de tokens. Clique no botão + Criar Token, forneça um nome para seu token e certifique-se de copiar o token gerado, pois ele não será exibido novamente. Use o token gerado no cabeçalho das requisições para se autenticar na API.

Com o token gerado, envie o header Authorization com o valor Bearer {seu-token-gerado}.

Painel da API

O painel da API do Escavador é uma ferramenta que facilita o gerenciamento do seu uso da API. Nele, você pode acessar:

  • Histórico de requisições
  • Gerenciamento de tokens
  • Configuração e monitoramento de callbacks
  • Recarga de créditos
  • Visualização de monitoramentos de tribunais e diários oficiais
  • Faturas
  • Preços das rotas

Bibliotecas

Python

Possuímos um SDK em Python com suporte para ambas as versões da API. Para entender como utilizar o SDK, consulte nosso repositório no GitHub.

Callbacks

Na API V2, é possível receber callbacks para diversos eventos, como o callback associado a uma solicitação de atualização de um processo. Para fazer uso dessa funcionalidade, é necessário configurar uma URL de callback no painel da API.

O que é um callback

Um callback (também chamado de webhook) é uma chamada HTTP enviada pela API para uma URL da sua aplicação sempre que um evento relevante acontece. Em vez de sua aplicação consultar a API repetidamente para saber se houve atualização (polling), a API notifica você automaticamente.

Como o mecanismo funciona

  1. Você cadastra uma URL de callback no painel da API.
  2. Um evento acontece na plataforma (por exemplo, atualização de processo ou novo resultado assíncrono).
  3. A API envia uma requisição HTTP para a URL cadastrada, com os dados do evento.
  4. Sua aplicação processa a notificação e retorna uma resposta HTTP de sucesso.

Configurando uma URL de callback

Para configurar sua URL de callback, acesse a página de callbacks no painel da API. Nessa página, você pode informar a URL que receberá as notificações de eventos da API, como atualizações de processo e resultados assíncronos. Quando novos eventos ou resultados forem gerados, eles serão enviados para a URL configurada.

Token para validar callbacks da API

Com a URL de callbacks configurada, é importante validar se o callback recebido é, de fato, da API do Escavador. Para isso, gere um token de segurança no painel da API. Ao receber novos callbacks do Escavador, você pode validar se o token enviado é o mesmo que você gerou. O token é enviado no header Authorization.

Boas práticas de implementação

  • Exponha um endpoint específico para callbacks, com HTTPS obrigatório.
  • Valide a autenticidade da chamada (conforme subseção de token para validação de callbacks).
  • Trate o recebimento como processo idempotente: o mesmo evento não deve gerar efeitos duplicados.
  • Responda rapidamente a requisição e processe tarefas pesadas de forma assíncrona no seu backend.
  • Registre logs de recebimento e falha para facilitar observabilidade e auditoria.

Saldo

Você pode consultar o custo, em centavos, de uma requisição no header Creditos-Utilizados, presente na resposta. Visite a página de histórico para saber como consultar seu saldo. Consulte também a página de preços para saber mais sobre os custos de cada versão.

Paginação

Algumas rotas da API utilizam paginação para retornar resultados em blocos menores, evitando respostas muito grandes e tornando o consumo da API mais eficiente.

Em geral, as respostas paginadas retornam:

  • Os dados da página atual (em items)
  • Metadados de paginação (como página atual, total de páginas e total de itens)
  • Links para navegação entre páginas

Um exemplo comum de estrutura paginada é:

{
  "items": [{ "id": 1, "nome": "Exemplo" }],
  "links": {
    "first": "https://api.escavador.com/api/v2/recurso?page=1",
    "last": "https://api.escavador.com/api/v2/recurso?page=2",
    "prev": null,
    "next": "https://api.escavador.com/api/v2/recurso?page=2"
  },
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 50,
    "total_pages": 2
  }
}

Paginação numerada x paginação por cursor

Existem dois formatos comuns de paginação em APIs:

  1. Paginação numerada (offset/page): navegação por número de página, como ?page=2&per_page=25.
  2. Paginação por cursor (cursor-based): navegação por um marcador de continuidade, como ?cursor=eyJpZCI6MTIzfQ==&limit=25.

Principais diferenças:

  • Navegação: paginação numerada permite pular para páginas específicas; cursor segue fluxo sequencial (próximo/anterior).
  • Estabilidade em bases dinâmicas: cursor tende a ser mais estável quando dados são inseridos ou alterados durante a leitura, reduzindo duplicidades ou lacunas.
  • Simplicidade: paginação numerada é mais simples para interfaces com paginação visual tradicional (ex.: página 7 de 42).
  • Performance em grandes volumes: cursor costuma escalar melhor em listagens grandes e ordenadas por chave estável (ex.: id, created_at).

Como percorrer as páginas

  1. Faça a primeira requisição conforme os parâmetros esperados pela rota.
  2. Processe os itens retornados em data.
  3. Use os metadados e links de paginação retornados (next, current_page, etc.).
  4. Continue requisitando enquanto houver próxima página.

Boas práticas

  • Sempre utilize os links de paginação retornados pela API, quando disponíveis.
  • Evite assumir quantidade fixa de páginas: novos registros podem alterar o total durante a coleta.
  • Em sincronizações longas, registre a última página processada para retomada em caso de falha.
  • Considere o limite de requisições por minuto ao iterar muitas páginas.

Atenção a mudanças de dados durante a navegação

Em consultas com atualização frequente, o conjunto de resultados pode mudar entre uma página e outra. Para minimizar duplicidades ou perdas:

  • Utilize filtros determinísticos (por exemplo, período, ordenação e status), quando a rota permitir.
  • Armazene um identificador único dos itens já processados.
  • Trate o consumo de dados paginados como um processo incremental, garantindo idempotência no processamento dos itens, independentemente de inconsistências na paginação.