O SDK em Python da API do Escavador

Documentação disponível

• API V1
• API V2

Instalação

O SDK pode ser instalado via pip através do comando:

python -m pip install escavador

Requisitos

• Python 3.7+

Como Configurar

No arquivo .env na raíz do seu projeto, crie uma variável chamada ESCAVADOR_API_KEY e atribua a ela o seu token da API. A linha onde a variável é definida deve ficar parecida com:

ESCAVADOR_API_KEY="SUA_API_KEY"

Alternativamente, utilize a função config() durante a execução do seu projeto, antes de utilizar qualquer outro módulo do SDK.

import escavador
escavador.config("SUA_API_KEY")

Para obter seu token da API, acesse o painel de tokens

Exemplos

Consultando os processos de uma empresa pelo CNPJ usando a API V2

Processos de um envolvido pelo seu nome ou documento

from escavador.v2 import Processo

# Chamada inicial na API /api/v2/envolvido/processos?cpf_cnpj=00000000000
envolvido, processos = Processo.por_cnpj(cnpj="00653149000170")  # Também aceita o formato 00.000.000/0000-00)

print(f"Processos da empresa {envolvido.nome}:")

while processos:
    for processo in processos:
        print(f"{processo.numero_cnj}:")
        print(f"Fonte: {processo.fontes[0].nome}")
        print(f"Data de início: {processo.data_inicio}")
        print(f"Última movimentação: {processo.data_ultima_movimentacao}")

    # Chamada para a paginação via cursor na API /api/v2/envolvido/processos?cpf_cnpj=00000000000&cursor=HASH_PROXIMA_PAGINA
    processos = processos.continuar_busca()

Consultando o processo mais recente de um advogado usando a API V2

Consultando processos de um advogado usando sua OAB

from escavador import CriterioOrdenacao, Ordem
from escavador.v2 import Processo

advogado, processos = Processo.por_oab(numero=12345,
                                       estado="SP",
                                       ordena_por=CriterioOrdenacao.INICIO,
                                       ordem=Ordem.DESC)

processo = processos.pop()

print(f"{processo.numero_cnj}: {processo.titulo_polo_ativo} X {processo.titulo_polo_passivo}")

Buscando as movimentações de um processo usando a API V2

Consultando movimentações de um processo

from escavador.v2 import Processo

resultado = Processo.movimentacoes(numero_cnj="0000000-00.0000.0.00.0000")

while resultado:
    for movimentacao in resultado:
        print(f"{movimentacao.data} - {movimentacao.tipo}:")
        print(f"{movimentacao.conteudo}")
        print()
    resultado = resultado.continuar_busca() # Solicita a próxima página de movimentações

Consultando a última movimentação dos processos mais recentes de uma pessoa pelo nome usando a API V2

Processos de um envolvido pelo seu nome ou documento

from escavador import CriterioOrdenacao, Ordem
from escavador.v2 import Processo

envolvido, processos = Processo.por_nome(nome="Fulano de Tal da Silva",
                                         ordena_por=CriterioOrdenacao.INICIO,
                                         ordem=Ordem.DESC)

for processo in processos:
    print(f"{processo.numero_cnj}:")
    print(f"Fonte: {processo.fontes[0].nome}")
    print(f"Data de início: {processo.data_inicio}")
    movimentacoes = Processo.movimentacoes(numero_cnj=processo.numero_cnj)
    if movimentacoes:
        print(f"Última movimentação: {movimentacoes[0].conteudo}")

Solicitar busca assíncrona de processo usando a API V1

Buscando informações do processo no sistema do Tribunal (Assíncrono)

from escavador import Processo

resultado_busca = Processo.informacoes_no_tribunal("0000000-00.0000.0.00.0000")  # Gera uma busca assíncrona

if resultado_busca['resposta']['status'] == 'SUCESSO':
    for instancia in resultado_busca['resposta']['resposta']['instancias']:
        print(instancia['assunto'])

elif resultado_busca['resposta']['status'] == 'PENDENTE':
    # O ID de uma busca assíncrona pode ser usado para consultar seu status 
    # ou identificar a requisição originária ao receber o callback no seu servidor.
    id_async = resultado_busca['resposta']['id']

É recomendado que se utilize o callback ao invés de continuamente consultar o resultado. Entretanto, é possível consultar em massa os seus callbacks cadastrados utilizando a classe Callback.

O módulo server da biblioteca http oferece uma interface simples para receber callbacks. Basta definir o recebimento de requests POST conformando com a documentação do conteúdo dos callbacks.

Consultar manualmente o status de uma busca assíncrona previamente solicitada

Embora não seja recomendado devido à possibilidade de saturação do seu limite de requisições por minuto, é possível consultar periodicamente o status de uma busca assíncrona.

from escavador import BuscaAssincrona
from time import sleep

while True:
    resultado_busca = BuscaAssincrona.por_id(id_async)
    if resultado_busca['resposta']['status'] != 'PENDENTE':
        break
    sleep(15)

if resultado_busca['resposta']['status'] == 'SUCESSO':
    # Os dados consultados estarão disponíveis no campo ['resposta']['resposta']
    pass
elif resultado_busca['resposta']['status'] == 'ERRO':
    print("Algo deu errado, tente novamente mais tarde.")

Criando Monitoramentos na API V1

from escavador import MonitoramentoTribunal, MonitoramentoDiario, TiposMonitoramentosTribunal, TiposMonitoramentosDiario,FrequenciaMonitoramentoTribunal

# Monitoramento nos sisteams dos Tribunais
monitoramento_tribunal = MonitoramentoTribunal.criar(tipo_monitoramento=TiposMonitoramentosTribunal.UNICO,
                                                       valor="0000000-00.0000.0.00.0000",
                                                       tribunal="TJSP",
                                                       frequencia=FrequenciaMonitoramentoTribunal.SEMANAL)

# Monitoramento em Diários Oficiais
monitoramento_diario = MonitoramentoDiario.criar(TiposMonitoramentosDiario.PROCESSO, processo_id=2, origens_ids=[2,4,6])

Consultando os Tribunais e sistemas disponíveis para a API V1

from escavador import Tribunal

tribunais_disponiveis = Tribunal.sistemas_disponiveis()

Módulos Disponíveis e Referência da API

V1:

Módulo	Link API
Busca	https://api.escavador.com/v1/docs/#busca
Processo	https://api.escavador.com/v1/docs/#processos
Callback	https://api.escavador.com/v1/docs/#callback
DiarioOficial	https://api.escavador.com/v1/docs/#dirios-oficiais
Instituicao	https://api.escavador.com/v1/docs/#instituies
Legislacao	https://api.escavador.com/v1/docs/#legislao
Jurisprudencia	https://api.escavador.com/v1/docs/#jurisprudncias
MonitoramentoDiario	https://api.escavador.com/v1/docs/#monitoramento-de-dirios-oficiais
MonitoramentoTribunal	https://api.escavador.com/v1/docs/#monitoramento-no-site-do-tribunal
Movimentacao	https://api.escavador.com/v1/docs/#movimentaes
Pessoa	https://api.escavador.com/v1/docs/#pessoas
Tribunal	https://api.escavador.com/v1/docs/#tribunais
Saldo	https://api.escavador.com/v1/docs/#saldo-da-api

V2:

Módulo	Link API
v2.Processo	https://api.escavador.com/v2/docs/#processos
v2.Tribunal	https://api.escavador.com/v2/docs/#tribunais