# O SDK em Python da API do Escavador
## Documentação disponível
- [API V1](https://api.escavador.com/v1/docs/)
- [API V2](https://api.escavador.com/v2/docs/)
## Instalação
O SDK pode ser instalado via `pip` através do comando:
```bash
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:
```bash
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.
```py
import escavador
escavador.config("SUA_API_KEY")
```
Para obter seu token da API, acesse o [painel de tokens](https://api.escavador.com/tokens)
## Exemplos
### Consultando os processos de uma empresa pelo CNPJ usando a API V2
[Processos de um envolvido pelo seu nome ou documento](https://api.escavador.com/v2/docs/#processos-de-envolvidos-por-nome-ou-cpfcnpj)
```py
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](https://api.escavador.com/v2/docs/#processos-de-um-advogado-por-oab)
```py
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](https://api.escavador.com/v2/docs/#movimentaes-de-um-processo)
```py
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](https://api.escavador.com/v2/docs/#processos-de-envolvidos-por-nome-ou-cpfcnpj)
```py
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](https://api.escavador.com/v1/docs/#pesquisar-processo-no-site-do-tribunal-assncrono) (Assíncrono)
```py
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](https://api.escavador.com/v1/docs/#detalhes-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.
```py
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
```py
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
```py
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 |
Raw data
{
"_id": null,
"home_page": "https://www.escavador.com",
"name": "escavador",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": "escavador, api, python",
"author": "Gabriel",
"author_email": "gabriel@escavador.com",
"download_url": "https://files.pythonhosted.org/packages/8f/d1/96ac501e3514fd56b96e772528adc60cde706d366776a0b6aae73550a3ee/escavador-0.9.0.tar.gz",
"platform": null,
"description": "# O SDK em Python da API do Escavador\n\n## Documenta\u00e7\u00e3o dispon\u00edvel\n\n- [API V1](https://api.escavador.com/v1/docs/)\n- [API V2](https://api.escavador.com/v2/docs/)\n\n## Instala\u00e7\u00e3o\n\nO SDK pode ser instalado via `pip` atrav\u00e9s do comando:\n```bash\npython -m pip install escavador\n```\n\n## Requisitos\n\n- Python 3.7+\n\n## Como Configurar\n\nNo arquivo `.env` na ra\u00edz do seu projeto, crie uma vari\u00e1vel chamada `ESCAVADOR_API_KEY` e atribua a ela o seu token da API. A linha onde a vari\u00e1vel \u00e9 definida deve ficar parecida com:\n```bash\nESCAVADOR_API_KEY=\"SUA_API_KEY\"\n```\n\nAlternativamente, utilize a fun\u00e7\u00e3o `config()` durante a execu\u00e7\u00e3o do seu projeto, antes de utilizar qualquer outro m\u00f3dulo do SDK.\n```py\nimport escavador\nescavador.config(\"SUA_API_KEY\")\n```\n\nPara obter seu token da API, acesse o [painel de tokens](https://api.escavador.com/tokens)\n\n## Exemplos\n\n### Consultando os processos de uma empresa pelo CNPJ usando a API V2\n\n[Processos de um envolvido pelo seu nome ou documento](https://api.escavador.com/v2/docs/#processos-de-envolvidos-por-nome-ou-cpfcnpj)\n\n```py\nfrom escavador.v2 import Processo\n\n# Chamada inicial na API /api/v2/envolvido/processos?cpf_cnpj=00000000000\nenvolvido, processos = Processo.por_cnpj(cnpj=\"00653149000170\") # Tamb\u00e9m aceita o formato 00.000.000/0000-00)\n\nprint(f\"Processos da empresa {envolvido.nome}:\")\n\nwhile processos:\n for processo in processos:\n print(f\"{processo.numero_cnj}:\")\n print(f\"Fonte: {processo.fontes[0].nome}\")\n print(f\"Data de in\u00edcio: {processo.data_inicio}\")\n print(f\"\u00daltima movimenta\u00e7\u00e3o: {processo.data_ultima_movimentacao}\")\n\n # Chamada para a pagina\u00e7\u00e3o via cursor na API /api/v2/envolvido/processos?cpf_cnpj=00000000000&cursor=HASH_PROXIMA_PAGINA\n processos = processos.continuar_busca()\n```\n\n### Consultando o processo mais recente de um advogado usando a API V2\n\n[Consultando processos de um advogado usando sua OAB](https://api.escavador.com/v2/docs/#processos-de-um-advogado-por-oab)\n\n```py\nfrom escavador import CriterioOrdenacao, Ordem\nfrom escavador.v2 import Processo\n\nadvogado, processos = Processo.por_oab(numero=12345,\n estado=\"SP\",\n ordena_por=CriterioOrdenacao.INICIO,\n ordem=Ordem.DESC)\n\nprocesso = processos.pop()\n\nprint(f\"{processo.numero_cnj}: {processo.titulo_polo_ativo} X {processo.titulo_polo_passivo}\")\n```\n\n### Buscando as movimenta\u00e7\u00f5es de um processo usando a API V2\n\n[Consultando movimenta\u00e7\u00f5es de um processo](https://api.escavador.com/v2/docs/#movimentaes-de-um-processo)\n\n```py\nfrom escavador.v2 import Processo\n\nresultado = Processo.movimentacoes(numero_cnj=\"0000000-00.0000.0.00.0000\")\n\nwhile resultado:\n for movimentacao in resultado:\n print(f\"{movimentacao.data} - {movimentacao.tipo}:\")\n print(f\"{movimentacao.conteudo}\")\n print()\n resultado = resultado.continuar_busca() # Solicita a pr\u00f3xima p\u00e1gina de movimenta\u00e7\u00f5es\n```\n\n### Consultando a \u00faltima movimenta\u00e7\u00e3o dos processos mais recentes de uma pessoa pelo nome usando a API V2\n\n[Processos de um envolvido pelo seu nome ou documento](https://api.escavador.com/v2/docs/#processos-de-envolvidos-por-nome-ou-cpfcnpj)\n\n```py\nfrom escavador import CriterioOrdenacao, Ordem\nfrom escavador.v2 import Processo\n\nenvolvido, processos = Processo.por_nome(nome=\"Fulano de Tal da Silva\",\n ordena_por=CriterioOrdenacao.INICIO,\n ordem=Ordem.DESC)\n\nfor processo in processos:\n print(f\"{processo.numero_cnj}:\")\n print(f\"Fonte: {processo.fontes[0].nome}\")\n print(f\"Data de in\u00edcio: {processo.data_inicio}\")\n movimentacoes = Processo.movimentacoes(numero_cnj=processo.numero_cnj)\n if movimentacoes:\n print(f\"\u00daltima movimenta\u00e7\u00e3o: {movimentacoes[0].conteudo}\")\n```\n\n### Solicitar busca ass\u00edncrona de processo usando a API V1\n[Buscando informa\u00e7\u00f5es do processo no sistema do Tribunal](https://api.escavador.com/v1/docs/#pesquisar-processo-no-site-do-tribunal-assncrono) (Ass\u00edncrono)\n```py\nfrom escavador import Processo\n\nresultado_busca = Processo.informacoes_no_tribunal(\"0000000-00.0000.0.00.0000\") # Gera uma busca ass\u00edncrona\n\nif resultado_busca['resposta']['status'] == 'SUCESSO':\n for instancia in resultado_busca['resposta']['resposta']['instancias']:\n print(instancia['assunto'])\n\nelif resultado_busca['resposta']['status'] == 'PENDENTE':\n # O ID de uma busca ass\u00edncrona pode ser usado para consultar seu status \n # ou identificar a requisi\u00e7\u00e3o origin\u00e1ria ao receber o callback no seu servidor.\n id_async = resultado_busca['resposta']['id']\n```\n\n\u00c9 recomendado que se utilize o callback ao inv\u00e9s de continuamente consultar o resultado. Entretanto, \u00e9 poss\u00edvel consultar em massa os seus callbacks cadastrados utilizando a classe `Callback`.\n\nO m\u00f3dulo `server` da biblioteca `http` oferece uma interface simples para receber callbacks. Basta definir o recebimento de requests `POST` conformando com [a documenta\u00e7\u00e3o do conte\u00fado dos callbacks](https://api.escavador.com/v1/docs/#detalhes-dos-callbacks).\n\n### Consultar manualmente o status de uma busca ass\u00edncrona previamente solicitada\n\nEmbora n\u00e3o seja recomendado devido \u00e0 possibilidade de satura\u00e7\u00e3o do seu limite de requisi\u00e7\u00f5es por minuto, \u00e9 poss\u00edvel consultar periodicamente o status de uma busca ass\u00edncrona.\n\n```py\nfrom escavador import BuscaAssincrona\nfrom time import sleep\n\nwhile True:\n resultado_busca = BuscaAssincrona.por_id(id_async)\n if resultado_busca['resposta']['status'] != 'PENDENTE':\n break\n sleep(15)\n\nif resultado_busca['resposta']['status'] == 'SUCESSO':\n # Os dados consultados estar\u00e3o dispon\u00edveis no campo ['resposta']['resposta']\n pass\nelif resultado_busca['resposta']['status'] == 'ERRO':\n print(\"Algo deu errado, tente novamente mais tarde.\")\n```\n\n### Criando Monitoramentos na API V1\n\n```py\nfrom escavador import MonitoramentoTribunal, MonitoramentoDiario, TiposMonitoramentosTribunal, TiposMonitoramentosDiario,FrequenciaMonitoramentoTribunal\n\n# Monitoramento nos sisteams dos Tribunais\nmonitoramento_tribunal = MonitoramentoTribunal.criar(tipo_monitoramento=TiposMonitoramentosTribunal.UNICO,\n valor=\"0000000-00.0000.0.00.0000\",\n tribunal=\"TJSP\",\n frequencia=FrequenciaMonitoramentoTribunal.SEMANAL)\n\n# Monitoramento em Di\u00e1rios Oficiais\nmonitoramento_diario = MonitoramentoDiario.criar(TiposMonitoramentosDiario.PROCESSO, processo_id=2, origens_ids=[2,4,6])\n```\n\n### Consultando os Tribunais e sistemas dispon\u00edveis para a API V1\n\n```py\nfrom escavador import Tribunal\n\ntribunais_disponiveis = Tribunal.sistemas_disponiveis()\n```\n\n### M\u00f3dulos Dispon\u00edveis e Refer\u00eancia da API\n\n#### V1:\n| M\u00f3dulo | Link API |\n|-----------------------|----------------------------------------------------------------------|\n| Busca | https://api.escavador.com/v1/docs/#busca |\n| Processo | https://api.escavador.com/v1/docs/#processos |\n| Callback | https://api.escavador.com/v1/docs/#callback |\n| DiarioOficial | https://api.escavador.com/v1/docs/#dirios-oficiais |\n| Instituicao | https://api.escavador.com/v1/docs/#instituies |\n| Legislacao | https://api.escavador.com/v1/docs/#legislao |\n| Jurisprudencia | https://api.escavador.com/v1/docs/#jurisprudncias |\n| MonitoramentoDiario | https://api.escavador.com/v1/docs/#monitoramento-de-dirios-oficiais |\n| MonitoramentoTribunal | https://api.escavador.com/v1/docs/#monitoramento-no-site-do-tribunal |\n| Movimentacao | https://api.escavador.com/v1/docs/#movimentaes |\n| Pessoa | https://api.escavador.com/v1/docs/#pessoas |\n| Tribunal | https://api.escavador.com/v1/docs/#tribunais |\n| Saldo | https://api.escavador.com/v1/docs/#saldo-da-api |\n\n\n#### V2:\n\n| M\u00f3dulo | Link API |\n|-------------|----------------------------------------------|\n| v2.Processo | https://api.escavador.com/v2/docs/#processos |\n| v2.Tribunal | https://api.escavador.com/v2/docs/#tribunais |\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library to interact with Escavador API",
"version": "0.9.0",
"project_urls": {
"Documentation": "https://api.escavador.com/docs/",
"Homepage": "https://www.escavador.com",
"Repository": "https://github.com/Escavador/escavador-python"
},
"split_keywords": [
"escavador",
" api",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "719ef872dd26136c95597a2bf7fa9555ff45af37296fc8a02ffef49f262d254a",
"md5": "bc8f73158879799b9937f9e063b0009e",
"sha256": "ddea120a3e021f2eb51ba771110b88b70ce7f5370a820fffcb0355b59b68e861"
},
"downloads": -1,
"filename": "escavador-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc8f73158879799b9937f9e063b0009e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 38681,
"upload_time": "2024-07-09T14:15:06",
"upload_time_iso_8601": "2024-07-09T14:15:06.525087Z",
"url": "https://files.pythonhosted.org/packages/71/9e/f872dd26136c95597a2bf7fa9555ff45af37296fc8a02ffef49f262d254a/escavador-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8fd196ac501e3514fd56b96e772528adc60cde706d366776a0b6aae73550a3ee",
"md5": "73efa1d2fa245d3c117cb2c35a4b0ccb",
"sha256": "79738945c695ae6e16a7dbe96634cf2f40345b7e0c89982b33ad286dbfc73222"
},
"downloads": -1,
"filename": "escavador-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "73efa1d2fa245d3c117cb2c35a4b0ccb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 27264,
"upload_time": "2024-07-09T14:19:44",
"upload_time_iso_8601": "2024-07-09T14:19:44.474389Z",
"url": "https://files.pythonhosted.org/packages/8f/d1/96ac501e3514fd56b96e772528adc60cde706d366776a0b6aae73550a3ee/escavador-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-09 14:19:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Escavador",
"github_project": "escavador-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "escavador"
}
JSON
