Introdução

Nossas APIs permitem conferir ao seu sistema diversos avanços tecnológicos recentes, reduzindo o esforço manual dos usuários finais.

Viabilizamos isto a partir da alimentação automática de dados vindos dos tribunais e melhoria contínua dessas informações com aprendizagem por máquina.

A seguir ilustramos o funcionamento das APIs:

_images/fluxograma-digesto-introducao.png

Como funciona?

Todos os serviços utilizam o padrão HTTP REST no tratamento de requisições. Desta forma é possível construir facilmente uma URL para ser executada em seu navegador, linha de comando ou código. O formato padrão de pedidos e respostas é em JSON o que ajuda na interpretação por humanos e na integração entre máquinas.

Algumas interações com a API são feitas de forma síncrona, quando a resposta a uma operação ou busca feita pelo cliente é retornada imediatamente, no conteúdo da resposta HTTP. Por exemplo para a busca em diários oficiais, inclusão de novos processos e partes monitoradas. Outras interações são assíncronas, ou seja, os sistemas/servidores da Digesto tomam a iniciativa de chamar uma URL no sistema/servidor HTTP do cliente para empurrar alguma informação nova, ou resultado de uma operação solicitada previamente. O principal exemplo é o envio diário de resultados de alertas em Diários Oficiais ou mudanças nos Tribunais, ou o envio dos detalhes dos novos processos distribuidos envolvendo as partes monitoradas.

Por exemplo, o monitoramento por novas distribuições de uma parte monitorada funciona assim:

1. cadastre via API ou portal web Digesto os nomes das partes para monitoramento de novas distribuições; 1. assim que novo processos entram na base buscamos as partes cadastradas nesses novos processos; 1. em caso de match geramos novos eventos do tipo 4 e salvamos internamente; 1. periodicamente fazemos uma chamada HTTP POST com um json para uma url informada por vocês para entregar esses novos eventos (preferível); ou 1. vocês fazem uma chamada para nossa API para listar os últimos n eventos gerados.

Como contratar?

O uso desta API deve ocorrer dentro de um contrato de serviços, onde serão formalizadas as condições de uso. Através deste contrato também serão fornecidas as credenciais mencionadas abaixo. Entre em contato conosco com suas necessidades para entendermos melhor como ajudá-lo.

Comunicação sobre mudanças e status do serviço

Usamos uma lista de distribuição de e-mails para avisos de mudanças na API e indisponibilidades internas ou externas dos serviços. Basta inscrever seu e-mail para receber atualizações.

Formato e URL base para requisições

Todas as requisições para a API são feitas para a URL base https://op.digesto.com.br/api/, acrescida do nome do recurso em questão (proc, cadastro, monitored_person, doc, anexo etc).

O formato de codificação esperado para as entradas (conteúdo do payload HTTP POST) e para o retorno às chamadas é JSON, usando o encoding UTF-8.

Aviso

É obrigatório o envio do campo Content-Type do header em todo request dos tipos POST e PATCH à API como sendo application/json. Também é obrigatório o envio dos campos HTTP Content-length e Host em requisições dos tipos acima.

Métodos HTTP

A semântica dos verbos HTTP usualmente utilizados em API do tipo REST é mantido:

  • POST ou PUT - Para criar recursos ou substituir todo o conteúdo de um recurso
  • PATCH - Para atualizar recursos parcialmente
  • GET - Para pegar um recurso ou lista de recursos
  • DELETE - Para apagar um recurso

Respostas HTTP

O código HTTP de status no retorno às chamadas da API segue o padrão abaixo:

  • 200 OK - a requisição foi bem sucedida.
  • 201 Created - a requisição foi bem sucedida e o recurso foi criado.
  • 204 No Content - a requisição foi bem sucedida, mas não há representação para retornar (ou seja, a resposta está vazia).
  • 400 Bad Request - a requisição não pôde ser entendida ou faltavam os parâmetros necessários.
  • 401 Unauthorized - a autenticação falhou ou o usuário não tem permissões para a operação solicitada.
  • 403 Forbidden - acesso negado.
  • 404 Not Found - o recurso não existe.
  • 405 Method Not Allowed - o método da requisição não é compatível com o recurso.
  • 429 Too Many Requests - ultrapassou os limites da API. Pause as solicitações, espere até um minuto e tente novamente.
  • 503 Service Unavailable - o serviço está temporariamente indisponível (por exemplo, manutenção programada da plataforma). Tente mais tarde.

Criando recursos

Para todas os recursos da API, basta realizar um HTTP POST para o endereço do recurso.

A entidade recém criada é retornada, junto com seu id no campo $uri.

Por segurança, não é permitido forçar qual a user_company de um recurso novo. Ela é inferida da user_company associada ao usuário autenticado. Ou seja, o recurso vai ser criado dentro da user_company do usuário cujo api_key foi fornecido na URL ou nos headers.

POST https://op.digesto.com.br/api/user_company

O exemplo abaixo cria uma nova empresa na API.

Exemplo de chamada:

POST https://op.digesto.com.br/api/user_company HTTP/1.1
Content-Type: application/json

{
  "name": "Nova empresa"
}

Exemplo de resposta:

A entidade recém criada é retornada.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "$uri": "/api/user_company/7",
    "api_name": null,
    "created_at": {
        "$date": 1463940701000
    },
    "enabled_modules": [],
    "is_archived": false,
    "logo_url": null,
    "name": "Nova empresa",
    "trib_monitor_config": {},
    "user_company": {
        "$ref": "/api/user_company/1"
    },
    "users": []
}
Request Headers:
 
Response Headers:
 
Status Codes:

Listando recursos

Todos os recursos disponibilizados pela API podem ser listados de forma idêntica, descrita a seguir.

Filtrando

Filtros podem ser fornecidos diretamente na URL do GET realizado, com o argumento where, conforme exemplos abaixo:

where={"year_published": {"$gt": 1900}}              # Book.year_published > 1900
where={"first_name": {"$startswith": "C"}}           # Author.first_name starts with 'C'
where={"first_name": {"$in": ["Charles", "James"]}}  # Author.first_name in ['Charles', 'James']
where={"title": "The Double Helix", "year_published": {"$lt": 2000}}

Exemplo para listar todos os processos registrados pela empresa atual. Filtra pelos processos registrados que estão sendo monitorados em Tribunais ou Diários Oficiais:

GET https://op.digesto.com.br/api/proc?where={"is_monitored_diario":true}  HTTP/1.1

Filtros disponíveis para todas as colunas de todos recursos:

Nome Description Se aplica a atributos de tipo
— Equal Boolean, String, Integer, Number, ToOne, Date, DateTime, DateString, DateTimeString
$ne Not equal Boolean, String, Integer, Number, ToOne
$in In (expects an Array) String, Integer, Number, Date, DateTime, DateString, DateTimeString
$contains Contains Array, ToMany
$lt Less than String, Integer, Number, Date, DateTime, DateString, DateTimeString
$gt Greater than String, Integer, Number, Date, DateTime, DateString, DateTimeString
$lte Less than or equal String, Integer, Number, Date, DateTime, DateString, DateTimeString
$gte Greater than or equal String, Integer, Number, Date, DateTime, DateString, DateTimeString
$contains Contains (String) String
$icontains Contains (String, case-insensitive) String
$startswith Starts with String
$endswith Ends with String
$istartswith Starts with (case-insensitive) String
$iendswith Ends with (case-insensitive) String
$between Ends with (case-insensitive) Date, DateTime, DateString, DateTimeString
$ref Relacionamento para outra entidade Referências a outros recursos. O valor deve ser o caminho completo na API (Ex.: /api/tipo/3)

Exemplo de chamada para retornar todos os cadastros, de forma paginada, ordenado pela data de criação decrescente e que foram criados pelo usuário (user) de id 21:

GET https://op.digesto.com.br/api/cadastro?page=1&per_page=30&sort={"created_at":true}&where={"user_creator":{"$ref":"/api/user/21"}}  HTTP/1.1

Exemplo de chamada para retornar todos os cadastros criados pelo usuário (user) de id 20 e no dia 19/07/16:

GET https://op.digesto.com.br/api/cadastro?where={"user_creator":{"$ref":"/api/user/20"},"created_at":{"$between":[{"$date":1468897200000},{"$date":1468983600000}]}}  HTTP/1.1

Exemplo de chamada para retornar todos os processos monitorados que possuam certo número CNJ:

GET https://op.digesto.com.br/api/proc?where={"numero_normalizado":"10001962220195020481"}

Exemplo de chamada para retornar todos os eventos de monitoramento de certo número CNJ:

GET https://op.digesto.com.br/api/monitored_event?where={"target_number":"0026481-97.2015.8.07.0003"}

Exemplo de chamada para retornar todos os eventos monitorados registrados para a empresa de id 20 no dia 19/07/16 e do tipo 4 (distribuição):

GET https://op.digesto.com.br/api/monitored_event?where={"evt_type":4,"created_at":{"$between":[{"$date":1468897200000},{"$date":1468983600000}]}}   HTTP/1.1

Para listar por exemplo os eventos de andamentos, teria que trocar na URL o "evt_type":4 por "evt_type":1. O número na data é o unix time (milisegundos desde epoch).

Exemplo de chamada para retornar todos os eventos monitorados do tipo 4 (distribuição de novo processo) registrados para pessoa monitorada id 5:

GET https://op.digesto.com.br/api/monitored_event?api_key=<chave>&where={"evt_type":4,"source_url":{"$contains":"{\"https://op.digesto.com.br/api/monitored_person/5\"}"}}   HTTP/1.1

Paginando

A paginação ao listar entidades na API segue o padrão da GitHub API, onde o corpo do retorno da chamada é uma lista json, com os elementos encontrados. Páginas são solicitadas com os argumentos na string da query (URL) page e per_page.

A primeira página (page) é a de número 1. O tamanho máximo para per_page é 2048 e o default é 30.

Na resposta HTTP, o header Link lista links para: current, first, previous, next, e last page.

Além disso, o header de resposta X-Total-Count contém o total de resultados.

Toda listagem de entidades é paginada por default com page=1&per_page=30, para evitar que queries com muitos resultados demorem muito tempo serializando os dados e prejudiquem outros usuários.

Chamada exemplo:

Retorna lista de processos registrados pela empresa atual. Filtra pelos processos registrados que estão sendo monitorados em Diários Oficiais.

GET https://op.digesto.com.br/api/proc?page=1&per_page=10  HTTP/1.1

Resposta exemplo:

HTTP/1.0 200 OK
Content-Type: application/json
Link: </api/proc?page=1&per_page=20>; rel="self",
      </api/proc?page=3&per_page=20>; rel="last",
      </api/proc?page=2&per_page=20>; rel="next"
X-Total-Count: 55

Note que o total de resultados é retornado no HTTP header X-Total-Count da resposta.

Ordenando

É feito com o parametro sort na chamada HTTP GET de listagem de entidades. Exemplos:

GET https://op.digesto.com.br/api/monitored_event?sort={"created_at": false}                # data de criação, crescente
GET https://op.digesto.com.br/api/proc?sort={"created_at": false, "numero": true} # data de criação crescente, número decrescente.

Tanto o parâmetro where quanto sort devem ser JSON válido, então use aspas dupla (") ao inves de simples (').

Modificando recursos

Para todas os recursos da API, basta realizar um HTTP PATCH para o endereço do recurso, e passar no conteúdo da requisição um JSON com os campos a serem modificados. A entidade recém modificada é retornada.

Exemplo de chamada:

Altera os tribunais monitorados da monitored_person de id 2.
PATCH https://op.digesto.com.br/api/monitored_person/2 HTTP/1.1
Content-Type: application/json

{
    "tribunaisIDs": [1,2,3]
}

Exemplo de resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "$uri": "/api/monitored_person/1",
    "...": "...",
    "tribunaisIDs": [
        1,
        2,
        3
    ]
}

Excluindo recursos

A maioria dos recursos disponibilizados pela API (proc, proc_set, cadastro, monitored_person, user, user_company) possui exclusão lógica. Ou seja, podem ser excluídas e depois recuperadas.

Para excluir uma entidade, basta fazer uma chamada HTTP DELETE no endereço completo dela (ex.: HTTP DELETE https://op.digesto.com.br/api/proc/12).

DELETE https://op.digesto.com.br/api/user_company/(int: id)

Resposta exemplo:

HTTP/1.0 204 NO CONTENT
Parameters:
  • id (int) – identificador numérico do recurso a ser excluído

Também é possível listar, filtrar e paginar recursos já excluídos, usando as mesmas operações da seção acima. Para listar todos os recursos excluídos de um tipo, basta fazer um HTTP GET com o sufixo archive. Por exemplo: HTTP GET https://op.digesto.com.br/api/proc/archive irá retornar um JSON com a lista de processos excluídos.

Para desfazer a exclusão, basta um HTTP POST com o conteúdo vazio, para a URL com prefixo archive e sufixo restore no endereço anterior da entidade excluída (ex.: HTTP POST https://op.digesto.com.br/api/proc/archive/12/restore).

Por exemplo:

POST https://op.digesto.com.br/api/user_company/archive/8/restore

Desfaz exclusão da empresa de id 8. Retorno de sucesso é o HTTP status 200.

Resposta exemplo:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "$uri": "/api/user_company/8",
    "api_name": null,
    "created_at": {
        "$date": 1467718058000
    },
    "enabled_modules": [
        "tribproc.bi",
        "tribproc",
        "cad"
    ],
    "is_archived": false,
    "logo_url": null,
    "name": "legalnote filha",
    "trib_monitor_config": {
        "a": 1
    },
    "user_company": {
        "$ref": "/api/user_company/6"
    },
    "users": []
}

Tags de recursos

Alguns recursos da API podem ser “tagueados”, ou seja, podem ter uma lista de strings arbitrárias associadas a cada instância do recurso.

GET https://op.digesto.com.br/api/live_report_def/3048/tags

Lista as tags do relatório de id 3048.

Retorna uma lista de strings json, uma para cada tag.

POST https://op.digesto.com.br/api/live_report_def/3048/set_tags

Redefine as tags de um relatório.

Enviar o conteúdo do POST: {"new_tags": ["tag1", "tag2"]}

Não há operação para inclusão parcial ou exclusão de tags. Na chamada acima todas as tags que deverão estar associadas ao relatório precisam ser passadas na chamada. Ou seja, após a chamada acima, para excluir a “tag2”, bastaria fazer nova chamada com {"new_tags": ["tag1"]}.

Retorna HTTP 200 em caso de sucesso.

Histórico de modificações de recursos

Registramos mudanças nos atributos de todos os recursos da API. Para consultar o histórico de mudanças de um recurso, basta realizar um HTTP GET no recurso desejado, com o sufixo /history na URL.

Por exemplo:

GET https://op.digesto.com.br/api/proc/122681/history

Traz o histórico de mudanças deste processo monitorado. O formato é uma lista de mudanças. Cada mudança é um objeto JSON com os atributos:

  • changes: lista de campos modificados, com o nome do atributo, valor antigo e novo.
  • updated_at: timestamp da alteração.
  • user_id: id do usuário da API responsável pela modificação.

Resposta exemplo:

HTTP/1.0 200 OK
Content-Type: application/json

[
  {
    "changes": [
      {
        "attribute": "archived_at",
        "new": {
          "$date": 1512046720000
        },
        "old": null
      }
    ],
    "updated_at": {
      "$date": 1512046720000
    },
    "user_id": 1220
  }
]

Documentos e anexos retornados pela API

Todos os PDFs e anexos são retornados pela API através de uma URL (por exemplo URLs com os PDFs das iniciais de um novo processo distribuído). Estas URLs apontam para arquivos hospedados pela Digesto e estarão disponíveis por até 90 dias após a obtenção.

Em alguns casos específicos (resultados de relatórios por exemplo) os arquivos são hospedados por alguns dias apenas. Estes casos são indicados explícitamente na API respectiva.

Formato de datas

Esta API retorna e recebe dados codificados em JSON para todas as chamadas. JSON não tem um tipo nativo para representar datas e horas. Dessa forma, convencionamos duas formas para representar data e hora:

Formato ISO 8601
YYYY-MM-DDTHH:MM:SS.mmmmmm ou, se microsegundos é 0, YYYY-MM-DDTHH:MM:SS. Todas as horas são expressas no fuso-horário (timezone) UTC. Por exemplo: 2015-01-30T19:21:30.340361
Como um inteiro

que representa a quantidade de milisegundos desde Jan 1, 1970 00:00:00 UTC. Nestes casos o campo no JSON possui um sub-objeto de chave $date, por exemplo:

{"$date": 1462922744000}

Em Java esse timestamp pode ser convertido para Date dessa forma:

java.util.Date time = new java.util.Date((long)timeStamp);

Em C#:

DateTime x = new DateTime(1970, 1, 1).AddSeconds(timeStamp/1000);

Versionamento da API

Cada user_company pode ser configurada para receber e enviar dados em uma versão da API.

A versão da API deve sempre ser explicitamente modificada pelo usuário. Cada mudança de versão traz funcionalidades novas e modificações provavelmente incompatíveis no nome ou formato dos campos.

Na tela de Configurações > Integração via API há uma opção que permite modificar a versão.

As empresas-filhas herdam no momento da criação a versão de API da empresa- mãe.

Mais detalhes sobre cada versão está disponível no histórico de mudanças.

Modificar versão da API via chamada

Basta fazer a chamada abaixo usando um token de API de usuário administrador da empresa a ser modificada.

POST https://op.digesto.com.br/api/user_company/update_admin_options

Exemplo de chamada:

O exemplo abaixo modifica a versão da API para a 2.

POST https://op.digesto.com.br/api/user_company/update_admin_options HTTP/1.1
Content-Type: application/json

{
  "config": {
    "api_config": 2
  }
}
Status Codes:
  • 200 OK – opções modificadas com sucesso. O objeto JSON passado na chamada é retornado na resposta.

Limites e restrições

Para garantir um tempo de resposta bom para todos os usuários da API, há um limite por usuário para qualquer chamada de até 5000 requisições por dia ou 120 por minuto. Quando excedido o limite, a API retorna o código de status 429 Too Many Requests.

Os principais recursos da API possuem uma quota de quantidade para cada empresa, para evitar que algum bug do lado do cliente da API registre muitos nomes para monitoramento por exemplo por engano, ou registre uma quantidade muito grande que exija um planejamento/redimensionamento prévio em nossa infraestrutura. As entidades excluídas também contam para esta quota.

Algumas entidades como monitored_person possuem limites na quantidade de variações de nomes encontradas (para evitar partes com muitos homônimos) ou muitos processos distribuídos recentemente. Por exemplo, a quantidade de variações de nomes de uma parte monitorada é limitada a 1000.

Linguagens de programação

Esta API, por ser inteiramente disponibilizada via HTTP, é independente de linguagens de programação. Você pode usar sua biblioteca HTTP/REST preferida de acordo com sua linguagem de programação para fazer as chamadas à API. Listamos a seguir recomendações de bibliotecas.

Python

The Requests HTTP library is recommended. It is simple, elegant and yet very powerful. To install it you would simply run:

pip install requests

You may also need a MultiDict class to represent HTTP requests with multiple values per key. We recommend WebOb’s MultiDict but Werkzeug/Flask also offer MultiDict class.

Recomendamos também a biblioteca Potion-client.

Ruby

Ruby folks recommend rest-client and not without a reason: it is one of the most beautiful REST HTTP libraries we have seen. The library is available as gem, so to install it simply run:

gem install rest-client

Java

Check out the jersey REST client if Java is your weapon of choice. These 3 jars is all you need:

  • jersey-client.jar (version = 1.17 - 1.18.1)
  • jersey-core.jar (version = 1.17 - 1.18.1)
  • jersey-multipart.jar (version = 1.17 - 1.18.1)

C#

For C# developers there is RestSharp. And that’s it, nothing else is required. Standard .NET makes it easy to make HTTP requests.

However, if you are using mono you will most likely need to allow it to do HTTP requests to external sites first. The easiest way to do that is probably by installing Mozilla certificates, like so:

mozroots --import --sync

PHP

Instalação da biblioteca Guzzle para HTTP:

# Install Composer
curl -sS https://getcomposer.org/installer | php

# Add Guzzle as a dependency
php composer.phar require guzzle/guzzle:~3.7

Exemplo script cliente que realiza uma busca em Diários Oficiais:

<?php

require 'vendor/autoload.php';
use Guzzle\Http\Client;

// Create a client and provide a base URL
$client = new Client('https://op.digesto.com.br');

// Create a tweet using POST
$request = $client->post('/api/user_company', array('content-type' => 'application/json'),  '{
    "name": "Nova empresa"
  }'
);

$request->setAuth('<seu Token>', '');
echo $request->getUrl();
echo $request;

// You must send a request in order for the transfer to occur
$response = $request->send();

// echo $response->getBody();

$data = $response->json();
var_dump($data);

?>