API - dingo! gestor

A API dingo! gestor fornece um meio de comunicação entre sistemas eletrônicos para troca de dados através do protocolo HTTP (padrão RESTful).

Recomendamos a leitura completa das informações a seguir para a correta utilização da API.

1. Protocolo HTTP

1.1 O que é HTTP?

HTTP é o protocolo de comunicação mais utilizado na navegação de internet, e funciona no modelo requisição-resposta/cliente-servidor através de métodos/verbos. Ao utilizar o protocolo HTTP devemos ter alguns pontos em mente:

1.2 Qual o objetivo da minha requisição?

Uma requisição pode ter por objetivo obter dados, cadastrar novos dados, alterar dados existentes ou remover dados. Isto está diretamente ligado aos métodos/verbos HTTP da qual falaremos à frente.

1.3 Qual o endereço do recurso?

Uma API que segue os padrões RESTful tem um ENDPOINT (terminação) para cada recurso. Por exemplo: caso o endereço da API seja ‘https://minha-api.com.br’, e você queira acessar a lista de clientes, o ENDPOINT poderá ser algo como ‘https://minha-api-de-exemplo.com.br/v1/clientes’, para acessar produtos, algo como ‘https://minha-api-de-exemplo.com.br/v1/produtos’, e assim por diante. No exemplo, o ‘/v1’ é utilizado para descrever a versão da API.

1.4 Qual o endereço da API dingo! gestor?

O endereço da API dingo! gestor é https://api.dingo.com.br.

2. Métodos/Verbos HTTP

Os Métodos/Verbos utilizados na API dingo! gestor são:

GET – Utilizado para obter dados
POST – Utilizado para cadastrar dados novos
PUT – Utilizado para alterar dados previamente existentes
DELETE – Utilizado para excluir dados

3. Retornos do Servidor

Os retornos do servidor (HTTP CODES) informam o resultado da requisição, sendo um meio de identificar se houve sucesso ou não.

200 – OK
A requisição foi bem sucedida, e o recurso da requisição foi processado e/ou retornado conforme esperado. Ao utilizar os métodos GET, PUT E DELETE, este é o retorno desejado.

201 – Created
Este retorno informa que o recurso foi criado conforme o esperado. Ao utilizar o método POST este é o retorno desejado.

400 – Bad Request
A requisição não atende aos critérios esperados pelo servidor, ou seja, alguma informação enviada está incorreta ou incompleta.

403 – Forbidden
Não autorizado. Este erro significa que por algum motivo a requisição foi barrada pelo sistema de autenticação do servidor. No caso da API dingo! gestor, a autenticação é feita por meio de um TOKEN de segurança.

404 – Not Found
O recurso solicitado não existe ou já foi removido.

429 – Too Many Requests
O servidor atingiu seu limite de requisições de segurança e sua solicitação não pôde ser atendida.

4. JSON

Utilizamos JSON, que é um formato de troca de dados amplamente utilizado por sua simplicidade. Ao consumir a API dingo! gestor, além de utilizar este formato, você deverá informar (nos métodos POST e PUT) no cabeçalho (header) a chave-valor ‘Content-Type: application/json; charset=utf-8’. Caso contrário você receberá o retorno ‘415 Unsupported Media Type’.

5. Autenticação

A autenticação da API dingo! gestor é feita através de um TOKEN de segurança de 64 posições, que deve ser informado em todas as requisições como valor do atributo apiKey.

5.1 Obtendo um ‘apiKey‘

O Token de segurança é gerado a partir do cadastro de usuários do dingo! gestor. Apenas usuários administradores podem acessar a API.

6. Paginação

Os métodos que retornam listas de dados (GET sem especificar o ID) são paginados, e a adoção deste padrão de consumo é uma boa prática, pois evita a sobrecarga tanto do servidor, quanto da aplicação cliente e da rede que os liga.

Estes métodos possuem dois parâmetros para esta funcionalidade:

limite – Define a quantidade máxima de registros que deverão ser retornados. Caso este campo não seja informado, o servidor limitará o resultado à 100 registros.

pagina – Define em qual página inicial dos resultados da busca. Caso este campo não seja informado, o servidor retornará a pagina 1.

Ainda como ferramentas para a paginação, o servidor envia como cabeçalho da resposta algumas informações valiosas para a implementação da paginação:

x-limite – Informa qual foi o limite de resultados da consulta.
x-pagina – Informa a página atual da consulta.
x-list-count – Informa a quantidade de registros da consulta paginada.
x-total-count – Informa a quantidade total de registros, independente da página e limite.
x-total-pages – Informa a quantidade de páginas que a consulta gera.

Exemplo:

Supondo que você queria obter a lista com todos os produtos da base, e que existam 1020 produtos cadastrados. Caso não seja informado outro limite, o servidor irá assumir o limite de 100 registros por consulta, e a requisição retornará o seguinte resultado:

No corpo da resposta:

• Uma lista JSON de objetos com os 100 primeiros produtos da base.

No cabeçalho da resposta:

• x-limite: 100
• x-pagina: 1
• x-list-count: 100
• x-total-count: 1020
• x-total-pages: 11

Com essa informação em mãos, podemos preparar nossa próxima requisição, a fim de obter os próximos 100 registros (página 2). Neste caso basta repetir a mesma consulta, porém informando a pagina = 2. Também podemos concluir que serão necessárias 11 requisições no total, para carregar todas as páginas (x-total-pages).

7. Campo “ultima_alteracao”

As entidades da API dingo! gestor possuem um campo chamado ‘ultima_alteracao‘ que é atualizado quando o registro é criado ou alterado. As listas geradas pela API são ordenadas por este campo, e você pode limitar as listas de dados solicitadas com base neste campo (através da variável de requisição ‘alterado_apos’, exemplo: https://api.dingo.com.br/v1/clientes?alterado_apos=2022-08-03%2015:30:00). Desta forma, você pode implementar uma lógica que registra a data/horário do último dado recebido, a na próxima requisição, solicitar apenas os dados deste momento em diante.

8. Throttling

Para evitar o uso abusivo da API, bem como garantir um fluxo de requisições saudável para o servidor, esta API implementa o Leaky Bucket Algorithm, que estabelece um fluxo máximo de requisições por período, e nega as requisições excedentes, evitando sobrecarga.

Caso este limite seja atingido, a requisição receberá a resposta 429 – Too Many Requests, e no cabeçalho a informação x-rate-limit-retry-after-seconds, com a quantidade de segundos que deverá ser aguardada até uma nova requisição.

9. Documentação técnica

A documentação técnica da API, contendo a descrição dos métodos e entidades pode ser acessada pelo link a seguir