Introdução ao API REST v1
Âmbito
O API REST do ilink permite o controlo programático das principais operações de documentos disponíveis na plataforma ilink, facilitando a integração com sistemas externos.
O ilink suporta 2 fluxos principais de integração: receção e emissão de documentos, com respetivo reporte de estados. Pode implementar ambos os fluxos ou apenas um, consoante as necessidades do seu software.
Pré-requisitos
Para integrar através do API, é necessário contactar primeiro a nossa equipa (apoio@ilink.pt) para solicitar acessos ao ambiente de testes/qualidade.
Os acessos disponibilizados incluem:
- Um token de plataforma, que identifica o sistema/plataforma que acede ao webservice
- Uma chave pública, que identifica o cliente/NIF que pretende aceder ao webservice
Isto significa que cada cliente que pretende emitir ou receber documentos necessita de um pré-registo junto da nossa equipa, para que seja gerada a sua chave pública. O token de plataforma é único para o sistema a integrar (comum a todos os clientes que utilizam o seu sistema) e deve ser usado em todas as chamadas ao API.
Nos acessos de teste, são também disponibilizados 2 clientes/NIFs, juntamente com as respetivas credenciais de acesso ao portal do ilink. Deve usar estas entidades para efetuar transações de documentos entre si e, opcionalmente, aceder ao portal para consulta dos mesmos. Os NIFs atribuídos podem ser alterados se necessário.
Nota: Serão fornecidos novos acessos (token de plataforma e chave pública por NIF) aquando da entrada em produção.
Notas técnicas
- O webservice segue a arquitetura REST
- Os códigos de estado HTTP devolvidos respeitam o RFC 7231
- Todos os dados enviados (incluindo anexos XML) devem ser codificados em UTF-8. Formatos como ANSI, UTF-8 BOM e ISO 8859-1 devem ser evitados para garantir compatibilidade com todos os sistemas recetores
- As respostas (payloads) são devolvidas em formato JSON
- Os servidores do ilink funcionam exclusivamente através de HTTPS, com versão TLS 1.2 (em caso de problemas de comunicação, consulte possíveis soluções para Java e C#)
- A especificação e cliente de demonstração swagger está disponível aqui
Ambientes e considerações importantes
- Existem 2 ambientes distintos, com URLs base e condições de utilização diferentes:
| Ambiente | URL base |
|---|---|
| Testes/pré-produção | https://ilink.acin.pt/ilinktests-api/api/v1/pt |
| Produção | https://ilink.pt/ilink-api/api/v1/pt |
- O ambiente de testes apenas está disponível em Portugal e Espanha.
- O ambiente de produção apresenta um SLA de disponibilidade global de 99.90%, de acordo com os nossos termos de serviço.
- Existe uma limitação de utilização de 200 pedidos/minuto. Após exceder este limite, o software fica bloqueado por 2 minutos.
Nota: Os documentos emitidos e recebidos através do API podem ser consultados no portal de testes do ilink usando as credenciais que lhe foram fornecidas.