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):

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 (OAuth2 Client Credentials)

A API do ilink utiliza o fluxo OAuth2 Client Credentials para autenticação e autorização. Este é o método recomendado para todas as novas integrações.

Obtenção do Token de Acesso

Para aceder à API, é necessário primeiro obter um token de acesso através do endpoint POST /oauth2/token. Este processo requer o envio de 5 parâmetros:

Parâmetro	Valor	Descrição
grant_type	client_credentials	Tipo de concessão OAuth2 (valor fixo)
client_id	Fornecido pela equipa ilink	Identificador único da sua aplicação
timestamp	Timestamp UNIX atual	Tempo atual em segundos. Deve estar sincronizado ou muito próximo da hora atual
nonce	Valor aleatório (até 20 caracteres)	Valor único alfanumérico gerado para cada requisição
signature	Assinatura HMAC-SHA256	Assinatura criptográfica calculada (ver abaixo)

Geração da Assinatura

A assinatura é calculada usando o algoritmo HMAC-SHA256 e deve seguir a fórmula

base64_encode(HMAC_SHA256(CLIENT_ID:TIMESTAMP:NONCE, CLIENT_SECRET))

Exemplo Prático de Autenticação

Suponha que recebeu as seguintes credenciais da equipa ilink:

• client_id: demoapp
• client_secret: qwerty

Passo a passo:

1. Obter timestamp UNIX atual. Exemplo: 1765812050 (segundos desde 1 de janeiro de 1970)
2. Gerar nonce aleatório. Exemplo: aYb89a8yf10
3. Concatenar os valores com ":". Resultado: demoapp:1765812050:aYb89a8yf10
4. Aplicar HMAC-SHA256
   • Usar a chave privada (client_secret): qwerty
   • Ferramenta online: HMAC-SHA256 Generator
   • Resultado: ff293edc63f0134ffa44ae04a6900e2ee43060aff620413b003c4e5eefbea949
5. Codificar em Base64
   • Ferramenta online: Base64 Encoder
   • Assinatura final: ZmYyOTNlZGM2M2YwMTM0ZmZhNDRhZTA0YTY5MDBlMmVlNDMwNjBhZmY2MjA0MTNiMDAzYzRlNWVlZmJlYTk0OQ==

Dados finais a enviar:

POST /oauth2/token

{
    "grant_type": "client_credentials",
    "client_id": "demoapp",
    "timestamp": 1765812050,
    "nonce": "aYb89a8yf10",
    "signature": "ZmYyOTNlZGM2M2YwMTM0ZmZhNDRhZTA0YTY5MDBlMmVlNDMwNjBhZmY2MjA0MTNiMDAzYzRlNWVlZmJlYTk0OQ=="
}

Após enviar os dados acima, será devolvida a resposta abaixo, que contém um token de acesso ao API:

HTTP status: 200 OK

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.vv6zhqgZYACxyALv03AplewBVgDgXq_9vOI4iLcAxWY",
    "token_type": "Bearer",
    "expires_in": 1800,
    "scope": "document_create,document_read,states_read"
}

Este token de acesso tem uma duração de 30 minutos e deve ser incluído em todos os pedidos ao API no header abaixo:

• Authorization: Bearer {ACCESS_TOKEN}

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

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

Importante: Quando o token de acesso expirar, é devolvida a seguinte resposta em todos os pedidos, e será necessário renovar o token de acesso repetindo o processo acima descrito:

HTTP status: 401 Unauthorized

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

Autorização (Legacy)

Nota: Novas integrações devem seguir o método OAuth2 descrito na seção anterior. Para referência, o método Legacy de Autorização é detalhado nesta seçã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.

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

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:

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:

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.