Webhooks iLink
1. Âmbito
Neste modelo de comunicação, o ilink toma a iniciativa de comunicar ao ERP no momento que um determinado evento ocorre, dispensando de consultas frequentes ao API.
O ilink disponibiliza 2 webhooks:
- Webhook de novo documento - enviado ao receptor cada vez que um novo documento lhe é encaminhado
- Webhook de mudança de estado de documento - enviado ao emissor cada vez que um documento previamente emitido altera o seu estado
Para qualquer dos webhooks acima funcionar é necessário:
- Implementar um endpoint Web, disponível publicamente aos servidores do ilink, ao qual o ilink irá comunicar via HTTP. Os dados enviados do ilink para este URL público estão de acordo com o webhook que pretendem implementar (ver abaixo)
- Comunicar à equipa do ilink que pretendem implementar o Webhook específico para o vosso cliente, e indicar-nos uma chave de acesso e o URL público do vosso endpoint.
Este método, apesar de implementação mais extensa, tem a vantagem de evitar polling constante aos nossos servidores, consumir menos recursos em ambos os sistemas, e permite aceder a toda a informação em tempo real. Só recomendamos optar pela consulta manual caso existam implicações de segurança na abordagem dos Webhooks (ver abaixo).
2. Informação importante / Implicações de Segurança
Esta opção assume que o URL/porta em questão está disponível publicamente, ou pelo menos acessível aos nossos ambientes de testes e produção! Para tal, poderá ser necessário abrir portas ou criar as seguintes excepções no firewall da máquina que executa o serviço web:
- https://ilink.acin.pt (62.28.56.162:443) - testes
- https://ilink.pt (
194.38.136.153:443193.43.40.153:443) - produção
Nota: caso falhe o processo de comunicação de um documento, o ilink irá tentar comunicar novamente até 10 vezes nos próximos 7 dias, com intervalos incrementalmente maiores por cada tentativa. Após 10 tentativas falhadas de comunicação, o ilink irá deixar de tentar comunicar esse documento ao ERP.
Um documento é considerado entregue com sucesso ao ERP quando a reposta do webhook retorna um HTTP status code 200 (independentemente do conteúdo da resposta)
Nota: Na implementação deste endpoint, o ERP tem a responsabilidade de validar a chave de acesso e posteriormente registar a informação recebida no seu sistema. Recomendamos vivamente ao vosso sistema validar a chave de acesso enviada nos headers da nossa resposta, caso contrário estão a aceitar dados provenientes de origem desconhecida.
3. Webhooks
3.1 Webhook de novo documento
O webhook de novo documento é uma alternativa à consulta frequente de documentos por parte da entidade receptora. Cada vez que chega um novo documento a esta entidade, o callback de novo documento será invocado.
O endpoint implementado deverá esperar os seguintes dados desta especificação.
3.2 Webhook de mudança de estado de documento
O webhook de mudança de estado de documento é uma alternativa à consulta frequente dos estados de cada documento emitido por parte da entidade emissora. Cada vez que o receptor do um documento emitido aceitar, recusar ou receber o mesmo, este callback será invocado.
O endpoint implementado deverá esperar os seguintes dados desta especificação.