Pular para o conteúdo principal

Especificação técnica

Documentação Swagger​

O ilink utiliza uma especificação OpenAPI 3 num cliente Swagger, disponível aqui. Neste cliente web, pode efetuar chamadas de teste ao nosso API, analisar as respostas obtidas e verificar os dados a enviar para cada endpoint/método.

O cliente swagger disponibilizado acima deve acompanhar o seu processo de desenvolvimento. É também possível verificar como as chamadas ao API são construídas através do cURL (consulte o exemplo abaixo):

img info

Nota: São também disponibilizados vários clientes HTTP, em mais de 50 linguagens e frameworks, gerados automaticamente a partir da nossa especificação, que podem servir de suporte inicial ao processo de integração.

Autorização​

Todos os pedidos efetuados ao API devem conter obrigatoriamente o header de autorização abaixo:

  • Authorization: Bearer {TOKEN_PLATAFORMA}

No cliente Swagger, o processo de autorização é efetuado inserindo o token de plataforma após clicar no botão Authorize.

img info

Após esta operação, deve notar que todos os pedidos subsequentes ao API incluem o header Authorization:

img info

Autenticação​

Antes de efetuar a primeira consulta ao API do ilink, é obrigatório efetuar uma autenticação por cliente/NIF. Esta autenticação serve de handshake inicial entre o cliente e o ilink e é efetuada através do endpoint POST /apps/authentications:

img info

Uma autenticação válida deve retornar esta resposta:

HTTP status: 200 OK

{
  "success": true,
  "message": {
    "code":"e123",
    "msg":"Integração realizada com sucesso."
  }
}

A autenticação tem duração ilimitada (só precisa de ser invocada 1 vez por cliente/NIF que acede ao API). Pode também ser revogada através do método DELETE /apps/authentications:

img info

Se o processo de autenticação não for concluído, ou o header Authorization não for enviado nos pedidos ao API, todas as chamadas serão recusadas para esse NIF com o seguinte erro:

HTTP status: 401 Unauthorized

{
  "success": false,
  "errors": [
    {
      "code": "e069",
      "msg": "Autenticação inválida"
    }
  ]
}

Nota: Em ambiente de produção é necessário autenticar novamente cada cliente/NIF.