Sobre a API

A autenticação é feita através de uma chave de API, chamada token, informada a cada chamada no cabeçalho AUTHORIZATION, seguindo o padrão HTTP Bearer. A chave de API identifica sua conta no sistema e regula as permissões.

O token deve ser obtido diretamente com o administrador da plataforma, que gerencia os tokens através do seu painel de administração.

Durante a criação do token, o administrador da plataforma tem a opção de associar um seller_id. Caso o faça, todas as requisições serão automaticamente filtradas por este vendedor, independente de filtros explícitos que sejam passados nas requisições.

As APIs de listagem (GET) aceitam dois parâmetros opcionais que possibilitam a paginação dos resultados. São eles:

• start: número inteiro, indica o ponto de início dos resultados (quantos registros serão omitidos do início da listagem). Padrão: 0 (zero);
• limit: número inteiro, determina o máximo de registros que serão retornados. Padrão: 20 (vinte).

Todo retorno da API é acompanhado de um código HTTP que indica o status da requisição. Os seguintes status são utilizados para indicar o sucesso:

• 200 (ok): requisição processada com sucesso e retornando algum resultado. Pode ser retornado em chamadas GET e PUT;
• 201 (created): requisição processada com sucesso, gerando um novo recurso, com mais informações inclusas no corpo da resposta. Pode ser retornado em chamadas POST;
• 204 (no content): requisição processada com sucesso, sem nenhum retorno no corpo da resposta. Pode ser retornado em chamadas PUT e DELETE.

Assim como nas requisições de sucesso, as requisições falhas acompanham um código de erro e mais informações esclarecendo o motivo do mesmo.

Os códigos de erro gerados pela API são os seguintes:

• 400 (bad request): parâmetros inválidos na requisição. Verifique a querystring e/ou corpo da requisição;
• 401 (unauthorized): falha de autenticação. Verifique se o token está correto, e se o administrador da plataforma não revogou seu token;
• 404 (not found): recurso não encontrado. Retornado em requisições GET e PUT que indicam um recurso específico por código.

A API lê e retorna data e hora como uma string no padrão ISO 8601, sempre em UTC (timezone 00:00).

Formato:
YYYY-MM-DDThh:mm:ssZ

Exemplo:
2018-12-31T24:59:59Z

Considerando que os webhooks são criados para notificar uma URL no acontecimento de um ou mais eventos, a plataforma de marketplace do Ideia no Ar realizará um POST na(s) URL(s) indicada(s), sempre no seguinte formato:

Você deverá lançar uma nova requisição no endpoint apropriado para obter os detalhes relacionados ao recurso indicado pelo código.

OBS 1: Há um delay de 1 (um) minuto na notificação da url do webhook, podendo ser alterado nas app settings, chave WEBHOOKS:NOTIFY:DELAY (valor inteiro para minutos).

OBS 2: No caso de insucesso na notificação da url do webhook, será feita uma nova tentativa (até 10 retentativas). O tempo entre as tentativas é calculado pela fórmula:

(int)Math.Round( Math.Pow(retryCount - 1, 4) + 15 + random.Next(30) * retryCount)

Toda chamada de webhook incluirá os seguintes cabeçalhos, como forma de validar se a requisição realmente originou da plataforma de marketplace do Ideia no Ar:

• X-VALIDATION-CODE, ex. 243dc729
• X-VALIDATION-HASH, ex. EF978A79DC3B6867EBFAF5ADFAC22885

O código é um valor gerado aleatoriamente em cada requisição enviada pela plataforma de marketplace do Ideia no Ar. O MD5 é o resultado da criptografia deste código, usando seu token de API como Salt.

md5(token + code)

Ao receber uma requisição, você deve criptografar o código informado em MD5, usando seu token de API como Salt, e verificar se o seu resultado corresponde ao resultado que enviamos. Se o resultado for diferente, descarte a requisição, pois a mesma é falsa.

if (hash == md5(token + code)) { // valid. }