Como migrar da v1 para v2 – Suporte da API

A nova versão da API do Escavador foi feita para que os usuários consigam informações de processos judiciais de forma rápida e mais completa possível. Ela resolve alguns problemas da versão anterior e acrescenta ainda mais valor ao produto.

Um dos problemas que identificamos na primeira versão eram:

Informações de Diários Oficiais separadas das informações dos sistemas dos Tribunais
Busca de processos de envolvidos nos sistemas dos Tribunais apenas de forma assíncrona e uma busca diferente por Tribunal
Necessário buscar o ID da entidade

A nova versão da API resolve esses problemas ao:

Combinar as informações de Diários Oficiais e sistemas dos Tribunais em uma única rota
Permitir a busca de processos de envolvidos nos sistemas dos Tribunais de forma síncrona
Omitir a necessidade de buscar o ID da entidade

Neste artigo, vamos mostrar como é possível atualizar as aplicações que utilizem a versão 1 para a versão 2 da API, tornando elas mais fáceis de usar e resolvendo os problemas que mencionados.

Índice:

Consulta de processos de uma empresa pelo nome

Consulta de processos de uma empresa pelo nome

Para realizar a busca por processos de uma empresa na API v1, a fim de obter informações coletadas de diários oficiais, é necessário seguir um conjunto de etapas. Inicialmente, é preciso efetuar uma pesquisa pelo nome da empresa para recuperar os identificadores (IDs) associados, possibilitando, posteriormente, a consulta aos processos específicos.

Suponhamos que desejemos obter os processos da empresa "Contoso LTDA". Nesse caso, o procedimento envolveria as seguintes requisições:

GET https://api.escavador.com/api/v1/busca?q=Contoso LTDA&qo=i&page=N
- O parâmetro "qo=i" é utilizado para restringir a pesquisa apenas a instituições.
Iterar pelos resultados obtidos e extrair os IDs correspondentes. Na versão v1 da API, é possível que um mesmo nome esteja associado a vários IDs, tornando a iteração essencial.
Para cada ID, GET https://api.escavador.com/api/v1/instituicoes/ID/processos?page=N
- Aqui, a navegação através do campo "links.next" é necessária, já que os processos são apresentados de forma paginada.

Segue um exemplo de código em Python, utilizando a biblioteca do Escavador, que executa as etapas mencionadas:

# -*- coding: utf-8 -*-  
import escavador  
from escavador import TiposTermo  
from escavador.v1 import Busca, Instituicao  
  
escavador.config("SEU TOKEN")  
  
# Entre aspas duplas para buscar o termo exato  
termo = '"Contoso LTDA"'  
  
continua_busca = True  
pagina_busca = 1  
  
while continua_busca:  
    # GET https://api.escavador.com/api/v1/busca?q=Contoso LTDA&qo=i
    resultados = Busca.busca_termo(termo, TiposTermo.INSTITUICOES, page=pagina_busca, limit=60)  
  
    if resultados['resposta']['links']['next'] is None:  
        continua_busca = False  
  
    for item in resultados['resposta']['items']:  
        # Pega o ID  
        id = item['id']  
  
        continua_listagem_processos = True  
        pagina_processos = 1  
  
        while continua_listagem_processos:  
            # Consultar processos da instituicao  
            # GET https://api.escavador.com/api/v1/instituicoes/ID/processos?page=N
            processos = Instituicao.get_processos_instituicao(id, page=pagina_processos, limit=60)  
  
            if processos['resposta']['links']['next'] is None:  
                continua_listagem_processos = False  
  
            for processo in processos['resposta']['items']:  
                print(processo['numero_novo'])  
  
            pagina_processos += 1  
  
    pagina_busca += 1

A v1 da API do Escavador também permite a realização de pesquisas de empresas nos sistemas dos tribunais. Nesse cenário, o Escavador oferece a possibilidade de criar buscas assíncronas, nas quais nossos robôs efetuam consultas nos próprios sistemas dos tribunais em busca de informações. Esse processo pode ser executado seguindo os passos a seguir:

Identificar os Tribunais com funcionalidade de Busca por Nome: GET https://api.escavador.com/api/v1/tribunal/origens
Entre os resultados obtidos, deve-se identificar aqueles em que o parâmetro "busca_nome" seja igual a 1
Para cada Tribunal Identificado (por exemplo: TJSP, TRT-12), prosseguir da seguinte forma: POST https://api.escavador.com/api/v1/tribunal/TJSP/busca-por-nome/async, com o BODY {"nome" => "Contoso LTDA"}
Aguardar o resultados das buscas criadas

Segue abaixo um exemplo de implementação em Python:

# -*- coding: utf-8 -*-  
from time import sleep  
import escavador  
from escavador.v1 import Processo, Tribunal, BuscaAssincrona  
  
escavador.config("SEU TOKEN")  
  
# Entre aspas duplas para buscar o termo exato  
termo = '"Contoso LTDA"'  
  
continua_busca = True  
pagina_busca = 1  
  
# Checa os tribunais que possuem a busca por nome  
# GET https://api.escavador.com/api/v1/tribunal/origens  
resultados_tribunais = Tribunal.sistemas_disponiveis()  
  
tribunais_disponiveis = []  
for tribunal in resultados_tribunais['resposta']['items']:  
    if tribunal['busca_nome'] == 1:  
        tribunais_disponiveis.append(tribunal['sigla'])  
  
buscas_assincronas = []  
tribunais_disponiveis = ['TRT-15', 'TJSP']  
  
for tribunal in tribunais_disponiveis:  
    # POST https://api.escavador.com/api/v1/tribunal/TJSP/busca-por-nome/async  
    busca = Processo.processos_por_nome_no_tribunal(origem=tribunal, nome=termo)  
    buscas_assincronas.append(busca)  
  
processos = []  
  
# Verifica as buscas  
for busca in buscas_assincronas:  
    # Verifica se a busca está pendente  
    id = busca['resposta']['id']  
  
    # GET https://api.escavador.com/api/v1/async/resultados/ID  
    resultado = BuscaAssincrona.por_id(id)  
    while resultado['resposta']['status'] == 'PENDENTE':  
        # Aguarda  
        sleep(30)  
        # GET https://api.escavador.com/api/v1/async/resultados/ID  
        resultado = BuscaAssincrona.por_id(id)  
  
    # Busca finalizada, pega os processos  
    for instancia in resultado['resposta']['resposta']:  
        for processo in instancia['processos']:  
            processos.append(processo['numero_unico'])  
  
for processo in processos:  
    print(processo)

Com a versão 2 da API, o processo de consulta de processos empresariais é significativamente otimizado. Agora, não é mais necessário recuperar o ID da empresa, permitindo a utilização de uma única rota para obter os processos. Além disso, os resultados incluem informações provenientes dos sistemas dos tribunais. Para realizar a consulta de processos de uma empresa utilizando a v2, basta seguir os passos abaixo:

GET https://api.escavador.com/api/v2/envolvido/processos?nome=Contoso LTDA
Efetuar a paginação através do cursor
- Aqui, a navegação através do campo "links.next" é necessária, já que os processos são apresentados de forma paginada.

Segue abaixo um exemplo de implementação em Python:

# -*- coding: utf-8 -*-  
import escavador  
from escavador.v2 import Processo  
  
escavador.config("SEU TOKEN")  
  
# Entre aspas duplas para buscar o termo exato  
termo = 'Contoso LTDA'  
  
# GET https://api.escavador.com/api/v2/envolvido/processos?nome=Contoso LTDA  
envolvido, processos = Processo.por_nome(nome=termo)  
  
while len(processos) > 0:  
    for processo in processos:  
        print(f"{processo.numero_cnj}")  
  
    # GET https://api.escavador.com/api/v2/envolvido/processos?nome=Contoso LTDA&cursor=HASH_PROXIMA_PAGINA  
    processos = processos.continuar_busca()

Consulta de processos de uma empresa pelo nome

Artigos relacionados