Autorização

A autorização na API é feita através do parâmetro de requisição secret em cada requisição, que consiste em uma chave de API UUID no formato RFC 4122. Exemplo:

https://module.api.niduu.com/integrate/?secret=ea0d435e-8111-11eb-a32a-7c8ae1e10db1

Enviar um valor para secret inválido ou deixar de enviar esse parâmetro acarretará na falha na requisição gerando uma resposta do tipo HTTP 403 PERMISSION DENIED.

IMPORTANTE: Não realize requisições para essa API em aplicações do lado cliente (ex.: javascript no navegador de internet), a chave de API secret deve ser armazenada e utilizada de forma segura na aplicação do lado servidor. Por esse motivo, visando ressaltar o uso seguro desta API, o CORS não é habilitado.

Para solicitar acesso à API de integração e obter uma chave de API, contate-nos através do e-mail suporte-tm@gupy.com.br.

Formato

A API de Integração recebe e envia dados no formato JSON, portanto convém enviar o cabeçalho HTTP Content-Type: application/json.

Fuso Horário

Por padrão, todos os valores que representam data e hora retornados nas requisições dessa API estão no fuso horário GMT (UTC+0).

Internacionalização

A API retorna alguns atributos formatados de acordo com a localização e preferências de idioma do cliente, como, por exemplo, mensagens de erro e datas. Para a correta exibição desses atributos envie o cabeçalho HTTP Accept-Language.

Ex.: Accept-Language: pt-BR

Supressão de Requisições

O limite de uso dessa API é 1 requisição por segundo por chave de API. Usando acima desse limite a requisição falhará gerando uma resposta do tipo HTTP 429 TOO MANY REQUESTS.

Paginações

As requisições de listagem retornam em páginas de até 100 registros. Nessa API a estratégia de paginação utilizada é baseada em cursor e consiste no seguinte:

Cada página é identificada por um parâmetro chamado cursor
Cada página contém o cursor para próxima e para a anterior através dos atributos next_cursor e prev_cursor, respectivamente.
Dessa forma não é possível que a aplicação cliente acesse uma página específica (por exemplo page=7), necessitando percorrer as páginas sequencialmente; entretanto esse tipo de paginação oferece vantagens de desempenho em grandes conjuntos de dados e possui tempo de resposta semelhante independente da página solicitada.
Originalmente, na paginação baseada em cursor, não há o conceito do número total de páginas ou de total de registros na listagem, entretanto, para facilidade de uso, foi adicionado a essa API uma rota para consulta do número total de registros, bastando requisitar a rota de listagem adicionando o sufixo /countna URL.