Esse texto foi gerado por AI a partir do
repositório disponível no github
Trabalhar com informações de processos judiciais no Brasil costuma ser desafiador: cada consulta passa por regras do CNJ, limites de uso, documentos em formatos diferentes e atualizações que chegam aos poucos. O Escavador reúne grande parte dessa informação em um só lugar — e é uma ferramenta valiosa para quem faz análise de risco, compliance, pesquisa jurídica ou produtos de dados.
Na Murabei, usamos o Escavador em rotinas diárias de coleta e tratamento de dados. Em vez de copiar e colar o mesmo código de integração em projeto após projeto, unificamos a lógica em uma biblioteca Python open source: o escavador-api.
Este texto é um convite para conhecer o pacote. Você verá o que ele faz na prática, como começar em poucos minutos e exemplos que pode colar no seu ambiente e adaptar. O pacote encontra-se disponível no github!
O que é o escavador-api, em uma frase
É um conector pronto entre seus scripts Python e a API do Escavador. Com ele você consulta processos, baixa documentos, lista ligações por CPF ou CNPJ, acompanha novidades e até pede resumos gerados por inteligência artificial — sem precisar montar do zero toda a conversa com a internet, páginas de resultados e mensagens de erro.
Pense nele como um intermediário confiável: você fala em “número do processo” ou “documentos deste CNJ”; a biblioteca cuida dos detalhes técnicos por trás.
Para quem foi feito
O pacote é especialmente útil se você:
- Desenvolve ferramentas internas que cruzam dados de processos com outras bases da empresa.
- Monta relatórios e painéis que dependem de andamentos e partes.
- Automatiza buscas recorrentes (por exemplo, monitorar um termo ou um processo específico).
- Quer ganhar tempo e reduzir bugs ao integrar o Escavador em Python.
Não é necessário ser especialista em tribunais digitais. Basta Python, um token de acesso ao Escavador e vontade de experimentar.
O que você ganha na prática
Você precisa e o pacote ajuda:
- Consultar um processo pelo número CNJ: Validando o formato antes da chamada
- Ver andamentos e documentos: Percorrendo listas longas de forma segura
- Achar processos de uma pessoa ou empresa: Com filtros por CPF, CNPJ ou nome
- Organizar dados para planilhas ou banco: Transformando respostas em tabelas
- Conviver com internet instável: Tentando de novo em falhas temporárias
Tudo isso vem testado no dia a dia das equipes de dados da Murabei — não é um exemplo de tutorial genérico.
Como instalar
Requisito: Python 3.12 ou mais recente.
pip install escavador-api
Suas primeiras linhas de código
O passo central é criar o cliente com o token que o Escavador fornece na sua conta:
from escavador_api.data import EscavadorAPI
api = EscavadorAPI("seu_token_aqui")Antes de consultas que consomem créditos, vale conferir o saldo:
balance = api.get_credit_balance()
print("Créditos:", balance)Consultar um processo
Use o número CNJ — com ou sem pontos e traços. O importante são os 20 dígitos do processo:
cnj = "0000001-66.2026.0.00.0001"
info = api.get_process_info(cnj)
print(info.get("numero_cnj"))
print(info.get("titulo_polo_ativo"))Em poucas linhas você já vê se a integração está funcionando e como os dados chegam estruturados.
Acompanhar o que acontece no processo
Movimentações
Quer saber o histórico de andamentos? O pacote entrega cada evento, um por um — prático para salvar em arquivo ou banco sem travar o computador com listas enormes:
api = EscavadorAPI("seu_token_aqui")
cnj = "00000016620260000001"
for update in api.get_process_updates(cnj):
print(update.get("data"), update.get("descricao"))Documentos públicos
Listar e baixar PDFs também fica direto:
for doc in api.get_process_public_documents(cnj):
print("Documento:", doc.get("key"))
pdf_bytes = api.download_process_file(
cnj, file_key="chave_do_documento_na_api")
with open("documento.pdf", "wb") as arquivo:
arquivo.write(pdf_bytes)Assim você monta fluxos do tipo “todo dia, baixe os novos documentos
destes processos” com bem menos código repetido.
Descobrir processos ligados a alguém ou a uma empresa
Cenário clássico em due diligence: quantos e quais processos estão associados a um CPF, CNPJ ou nome.
api = EscavadorAPI("seu_token_aqui")
processos = api.get_related_processes(
cpf_cnpj="12345678901", status="ATIVO",
limit=100)
print(f"Total encontrado: {len(processos)}")
for processo in processos[:5]:
print(processo.get("numero_cnj"))Dá para refinar por tribunal, datas, valor da causa e outros critérios quando a pergunta de negócio exige mais precisão.
De “lista na API” para tabelas prontas para análise
Muitas vezes a resposta da API é um conjunto grande de registros em formato JSON. Para quem trabalha com planilhas, SQL ou painéis, o módulo de transformação do pacote organiza tudo em três visões úteis: processos, processos por tribunal e envolvidos — com regras que a Murabei já aplica nos seus pipelines.
from escavador_api.data import EscavadorAPI
from escavador_api.transform import TransformProcessData
api = EscavadorAPI("seu_token_aqui")
lista = api.get_related_processes(cpf_cnpj="12345678901")
tabelas = TransformProcessData.process_list(process_list=lista)
processos = tabelas["process"]
envolvidos = tabelas["involved"]
print("Processos:", len(processos))
print("Colunas dos envolvidos:", list(envolvidos.columns))Menos tempo limpando JSON manualmente; mais tempo respondendo perguntas de negócio.
Fique de olho: monitoramento automático
Além de buscas pontuais, dá para avisar quando algo novo aparece.
Novos processos que mencionam uma palavra-chave (empresa, produto, nome):
monitoramento = api.create_monitoring_new_process(
keyword="nome ou termo de interesse",
courts=["TJSP"], # opcional: só alguns tribunais)
for achado in api.get_results_monitoring_new_process(monitoramento["id"]):
print(achado.get("numero_cnj"), achado.get("data_inicio"))Um processo que você já conhece e quer acompanhar de perto:
api.create_monitoring_existing_process( process_number="00000016620260000001")
Ideal para alertas internos, rotinas matinais ou integração com e-mail e Slack no seu próprio sistema.
Resumo com IA e dados mais frescos
Quando o volume de páginas é grande, o Escavador oferece resumo assistido por IA. O pacote expõe o fluxo em etapas simples:
api.request_ai_summary("00000016620260000001")
# No seu script, aguarde a conclusão consultando o status
status = api.get_ai_summary_status("00000016620260000001")
resumo = api.get_ai_summary("00000016620260000001")
print(resumo)Se a informação parecer desatualizada em relação ao tribunal, você pode pedir uma atualização dos dados públicos e acompanhar o andamento desse pedido — também pelo mesmo cliente Python.
Configurações opcionais (quando fizer sentido)
Em ambientes corporativos, às vezes é preciso ajustar tempo de espera, uso de proxy ou limite de páginas em buscas muito amplas. Isso é feito por variáveis de ambiente, por exemplo:
export ESCAVADOR_API__REQUEST_TIMEOUT=90 export ESCAVADOR_API__MAX_PAGES=50
O token continua sendo informado diretamente no código (ou no seu gerenciador de segredos), o que evita expor credencial em arquivos de configuração genéricos.
Erros que fazem sentido — sem adivinhação
Integrações quebram: número de processo errado, token vazio, resposta inesperada da API. Em vez de códigos HTTP crus, a biblioteca levanta erros com nomes claros, para você decidir se tenta de novo, avisa o usuário ou registra no log.
Em falhas passageis de rede, ela insiste algumas vezes sozinha antes de desistir — um detalhe pequeno que evita muita dor de cabeça em produção.
Open source, feito para crescer com a comunidade
O escavador-api é código aberto (licença BSD 3-Clause). Você pode usar, estudar, sugerir melhorias e contribuir com pull requests.
- Documentação oficial da API: Escavador: api.escavador.com](https://api.escavador.com/) |
- Código e issues: GitHub
- Contato Murabei Data Science: a.baceti@murabei.com
Comece hoje
- Clone o repositório e instale o pacote.
- Pegue seu token no Escavador.
- Rode o exemplo de saldo e uma consulta por CNJ.
- Explore processos relacionados ou transformação em tabelas, conforme seu caso.
O escavador-api não substitui a estratégia de dados da sua empresa — ele acelera a parte repetitiva para você investir energia no que importa: perguntas certas, modelos e decisões. Se quiser ajuda, entre em contato com a gente, já são alguns projetos de jurimetria e complience no nosso currículo.
A Murabei acredita em compartilhar ferramentas que funcionam no mundo real. Se este pacote poupar horas da sua equipe, nosso objetivo já valeu a pena. Experimente, conte o que achou e, se quiser, construa com a gente no GitHub.
See you, space cowboys!
(isso aqui não foi a AI que escreveu… ela curte um negrito né?)