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.

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

As rotas da API V1 contam com a possibilidade de enviar callbacks. Essa é uma forma de receber novos eventos em seus monitoramentos ou resultados em buscas assíncronas, sem a necessidade de fazer novas requisições.

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, novo resultado de monitoramento ou conclusão de busca assíncrona).
  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 monitoramentos e buscas assíncronas. 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 (normalmente em data)
  • 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 é:

{
  "data": [{ "id": 1, "nome": "Exemplo" }],
  "links": {
    "first": "https://api.escavador.com/api/v1/recurso?page=1",
    "last": "https://api.escavador.com/api/v1/recurso?page=42",
    "prev": null,
    "next": "https://api.escavador.com/api/v1/recurso?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 42,
    "per_page": 25,
    "to": 25,
    "total": 1032
  }
}

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).

Na API do Escavador, o formato de paginação não é escolhido pelo consumidor da API. Cada rota já define o modelo de paginação (numerada ou por cursor), e a integração deve seguir o contrato daquela rota.

Na prática:

  • Se a rota retornar campos como current_page, last_page e per_page, trate como paginação numerada.
  • Se a rota retornar cursor/ponteiro de continuidade, siga esse cursor para avançar na navegação.
  • Sempre priorize os links e metadados devolvidos na resposta, em vez de montar URLs manualmente.

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, cursor, 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.