Chamadas e Retornos da API#

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. O formato de codificação esperado para as entradas e para o retorno às chamadas é JSON, usando o encoding UTF-8.

Aviso

Em todo request dos tipos POST e/ou PATCH à API é obrigatório o envio do campo Content-Type do header, como sendo application/json. Assim como o envio dos campos HTTP Content-length e Host.

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. Mais informações sobre os limites na seção abaixo.

  • 503 Service Unavailable - o serviço está temporariamente indisponível (por exemplo, manutenção programada da plataforma). Tente mais tarde.

Limites e restrições#

Para garantir um tempo de resposta bom para todos os usuários da API, há um limite por usuário de 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 um limite de quantidade para cada empresa, para evitar que algum bug do lado do cliente da API registre uma quantidade muito grande ou duplicações, por engano, que exija um planejamento/redimensionamento prévio em nossa infraestrutura.

Nota

As entidades excluídas também contam para este limite.

Um exemplo, seria nas entidades monitored_person que possuem limites na quantidade de variações de nomes encontradas, para evitar partes com muitos homônimos ou muitos processos distribuídos recentemente.

Documentos e anexos retornados pela API#

Todos os PDFs e anexos são retornados pela API através de uma URL, que apontam para arquivos hospedados pela Digesto e ficam disponíveis por até 90 dias após a obtenção. Caso, passe os 90 dias será necessário solicitar novamente a requisição.

Em alguns casos específicos, como por exemplo resultados de relatórios, os arquivos são hospedados por alguns dias apenas. Estes casos são indicados explicitamente na API respectiva.