Integração via API REST

1. Âmbito

O API REST do ilink permite um controlo programático das principais operações de documentos presentes no ilink, facilitando a integração com programas externos.

O ilink distingue 2 fluxos principais de integração: receção e emissão de documentos, dos quais poderão ser implementados ambos ou apenas um, dependendo das necessidades do software a integrar.

2. Notas Técnicas

• O webservice segue a estrutura REST
• Os HTTP status codes devolvidos respeitam o RFC 7231
• Todos os dados enviados (incluindo anexos XML) deverão ser representados em UTF-8. Formatos como ANSI, UTF-8 BOM e ISO 8859-1 devem ser evitados de modo a garantir compatibilidade com todos os sistemas recetores
• As respostas (payloads) são devolvidas em formato JSON
• Os servidores do ilink funcionam exclusivamente por HTTPS, com versão TLS 1.2 (em caso de problemas com a comunicação, ver possíveis resoluções para [Java], e [C#])
• A especificação e cliente de demonstração swagger está disponível aqui
• Existem 2 ambientes distintos, com URLs base diferentes:

  • Testes/pré-produção: https://ilink.acin.pt/ilinktests-api/api/v1/pt
  • Produção: https://ilink.pt/ilink-api/api/v1/pt

Nota: Os documentos emitidos e recebidos via API podem ser consultados no portal de testes do ilink usando as credenciais que vos foram enviadas.

3. Pré requisitos

De modo a integrar via API, será necessário primeiro entrar em contacto com a nossa equipa (apoio@ilink.pt) de modo a pedir acessos ao nosso ambiente de testes/qualidade.

Os acessos disponibilizados serão os seguintes:

• Um token de plataforma, que identifica o sistema/plataforma a aceder ao webservice
• Uma chave pública, que identifica o cliente/NIF que pretende aceder ao webservice

Isto significa que cada cliente que permite emitir ou receber documentos necessita de um pré-registo com a nossa equipa, de modo a ser gerada a sua chave pública. O token de plataforma será único para o sistema a integrar (comum a todos os clientes que utilizam o vosso sistema), e deverá ser usado em todas as chamadas ao API.

Nos acessos de teste, também são disponibilizados 2 clientes/NIFs, juntamente com os seus logins de acesso ao portal do ilink. Deverão usar estas entidades para transacionar 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 enviados novos acessos (token de plataforma e chave pública por NIF) mediante entrada em produção.

4. Especificação técnica

Aceder à especificação swagger

O ilink utiliza uma especificação OpenApi 3, e está disponível aqui. Neste cliente web, poderá efetuar chamadas de teste ao nosso API, analisar as respostas obtidas bem como os dados a enviar para cada endpoint/método.

O cliente swagger disponibilizado acima deverá acompanhar o vosso processo de desenvolvimento. É também possível verificar como as chamadas ao API são construídas via cURL (ver exemplo abaixo):

Nota: São também disponibilizados vários clientes HTTP, em mais de 50 linguagens e frameworks (Java, C#, .NET, PHP, NodeJS, etc.), gerados automaticamente a partir da nossa especificação, que poderão servir de suporte inicial ao processo de integração.

4.1 Autorização

Todos os pedidos a efetuar ao API têm de conter obrigatoriamente o header de autorização: Authorization: Bearer <TOKEN_PLATAFORMA>

No cliente Swagger, o processo é feito inserindo o token de plataforma após clicar no botão Authorize

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

4.2 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 é feita com recurso ao endpoint POST /apps/authentications:

Uma autenticação válida deverá 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 um 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.

5. Emissão de documentos

5.1 Âmbito

Permite à plataforma integradora emitir documentos no ilink, que são posteriormente enviados para o seu destinatário. O destinatário dos documentos tem configurado no portal do ilink para que sistemas externos os documentos devem ser remetidos. Isto significa que o processo de envio de documentos aos ERP's e EDI's adequados de cada cliente é transparente ao API e fica à responsabilidade do ilink. Estas configurações são efetuadas pela equipa de apoio do ilink.

A plataforma ilink permite o envio de faturas eletrónicas em 2 cenários distintos:

• Envio de PDF assinado via e-mail para consumidores ou empresas privadas

  • Neste cenário, não será necessário criar ligações entre outros EDI's para o envio de documentos. Basta indicar ao endpoint de criação de documento o(s) endereço(s) de e-mail a remeter o mesmo. Para mais informações, consulte a secção Métodos de envio.
• Envio de XML CIUS-PT para entidades públicas

  • Neste cenário, será necessário configurar previamente as ligações entre NIFs e possivelmente entre outros brokers EDI externos.

Como são enviados os documentos para outros brokers EDI? Na fase de passagem a produção, deverá ser feito um levantamento de todas as entidades que irão receber documentos via EDI, bem como os seus brokers EDI em uso. De seguida, a equipa de apoio (apoio@ilink.pt) irá configurar as ligações necessárias de modo a que os documentos sejam integrados automaticamente no sistema de cada recetor. Antes de enviar documentos para a solução FE-AP da eSPap, será também necessário cada emissor de faturas completar o processo de adesão de fornecedores FE-AP.

Todos os documentos emitidos ficam disponíveis no portal do ilink tanto na entidade emissora como na entidade recetora dos mesmos.

Nota: No nosso ambiente de testes, devem emitir documentos apenas entre as 2 entidades que receberam acessos. Caso pretendam verificar o funcionamento do envio de documentos para um consumidor final (NIF arbitrário), deverão sempre emitir o mesmo por uma das entidades que receberam acessos.

IMPORTANTE: Para a emissão de documentos a entidades públicas, recomendamos fortemente implementar os seguintes pontos, sob pena de não integrar os documentos com certos sistemas:

• Envio do número de compromisso
• Envio do ficheiro PDF original da fatura
• Envio do número de encomenda ou requisição (se aplicável)
• Envio do Capital Social do fornecedor
• Envio do endereço de e-mail do cliente (apenas para as secretarias do Governo Regional da Madeira)
• Envio de todos os dados da morada do fornecedor (rua, código-postal, cidade, etc.)
• Envio do GLN do cliente (se aplicável)
• Consulta dos estados do documento
• Possibilidade de reenvio do documento mediante o estado obtido (útil para corrigir e reenviar um documento previamente rejeitado)

5.2 Assinatura digital

O ilink permite assinar automaticamente os anexos dos documentos emitidos na plataforma (XML e PDF), desde que a entidade emissora tenha adquirido e configurado o selo de um dos provedores de assinaturas digitais qualificadas. Neste momento, apenas o GTS - Global Trusted Sign é suportado, mas existem planos de suportar os restantes provedores em Portugal (Multicert e DigitalSign).

Isto significa que o ERP não é obrigado a integrar com um provedor de assinaturas, deixando (opcionalmente) o processo de certificação à responsabilidade do ilink. A outra alternativa será o próprio ERP efetuar o processo de certificação e enviar os documentos previamente assinados para o ilink.

Nota: No caso de assinatura via ilink, todos os ficheiros resultantes serão assinados no momento de entrada (xml e pdf), e só depois remetidos ao cliente. Este processo é configurado no portal web, ficando fora da responsabilidade do API.

No caso de assinatura via ERP, a assinatura digital do documento será validada a nível criptográfico para todos os documentos que entram no sistema, e um documento com assinatura inválida, tanto no XML como no PDF irá retornar sempre um erro via API como o seguinte:

HTTP status: 400 Bad request
 
{
	success:  false,
	errors:{
		document:{
			code: "e217", 
			msg: "A assinatura do documento não é válida."
		}
	}
}

O erro anterior indica que o documento sofreu alterações desde o momento que foi assinado, ou que a assinatura do mesmo foi gerada incorretamente. O seguinte validador pode ser utilizado para verificar a validade da assinatura dos documentos. Os formatos de assinatura reconhecidos pelo ilink são PADES e PKCS7-B (PDF), ou XMLDSig e XADES-BES (XML).

Nota: Os requisitos legais de assinatura das faturas eletrónicas estão disponíveis no Decreto-Lei 28/2019, secção II, artigo 12º.

Nota: O ilink assina os documentos PDF em PADES e os documentos XML em XADES-BES enveloped.

5.3 Métodos de envio

Após efetuada a autenticação com sucesso, estamos em condições de começar a enviar documentos. O API do ilink possibilita 2 métodos de envio de documentos:

a) Envio do XML em formato UBL 2.1 CIUS-PT (ou UBL 2.1 PEPPOLBIS3 - Encomendas)

Neste método, o sistema a integrar tem de gerar corretamente o ficheiro XML antes de enviar o mesmo ao ilink. Todos os ficheiros XML enviados por este método são verificados de acordo com o validador oficial da eSPap, versão 2.1.2, e o API irá retornar um erro caso se verifiquem inconsistências sintáticas. A eSPap disponibiliza um validador Schematron que implementa todas as validações da Norma Europeia EN16931 CIUS e as validações adicionais do CIUS-PT, e está disponível online neste link. Se os ficheiros validam sintaticamente no validador online, então deverão validar no ilink.

Nota: Para incluir um ficheiro PDF e outras situações habituais, consultar a secção casos de uso.

Nota: Podem consultar vários exemplos, bem como toda a especificação do CIUS-PT aqui.

Ver casos de uso

Alguns exemplos de erros no processo de validação XML:

HTTP status: 400 Bad request
 
{
	success: false,
	errors:{
		document:{
			code:"e217",
			msg:"[BR-CO-25]-Caso o valor a pagar (BT-115) seja positivo, deve indicar a data de vencimento (BT-9) ou a nota da condição de pagamento (BT-20)."
		}
	}
}

HTTP status: 400 Bad request
 
{
	success: false,
	errors:{
		document:{
			code:"e217",
			msg:"[DT-CIUS-PT-166]-Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) -Paid amount (BT-113) +Rounding amount (BT-114), with an acceptance range of 1.00 € (it does not mean that this tolerance is accepted by the customer)."
		}
	}
}

O método a utilizar para envio do XML é o POST /apps/documentsUBL. Neste contexto, a chave pública identifica o emissor do documento e tem de ser a chave associada ao NIF do emissor do documento especificado no XML (AccountingSupplierParty>Party>PartyTaxScheme>CompanyID para faturas/notas de crédito, ou AccountingCustomerParty>Party>PartyTaxScheme>CompanyID para encomendas). Caso isto não se verifique, o API irá retornar o seguinte erro:

HTTP status: 400 Bad request
 
{
	success: false,
	errors:{
		supplier:{ 
			code:"e199",
			msg:"A entidade criadora do documento deve ser cliente ou fornecedor do novo documento."
		}
	}
}

Se o XML for válido e respeitar todas as validações XML, bem como regras de negócio adicionais do recetor, o API devolve uma resposta de sucesso, juntamente com os dados principais do documento criado:

HTTP status: 201 Created
 
{
	success: true,
	message:{
		code:"s011",
		msg:"Documento criado com sucesso"
	},
	response:{
		data:{
			id:"60796c3c2a6fa2.53909016",
			number:"7411111",
			emission_date:"2021-04-15",
			type_document_fact:{
				id:"5c9cb870a5ef57.36583702",
				code:"380",
				alias:"invoice",
				type:"FT",
				description:"Fatura"
			},
			type_document:{
				alias:"issued",
				description:"Emitido"
			},
			state_document:{
				id:"5c9cb878745b16.4225687",
				alias:"sent",
				description:"Enviado ao cliente."
			}
		}
	}
}

Nota: Um documento é enviado com sucesso ao destinatário via EDI quando o campo state_document.alias tem o valor sent ou accepted. Caso se apenas pretenda que o documento seja enviado via e-mail, o estado do documento deve ser ignorado, e devemos consultar os e-mails enviados através da consulta de estado do mesmo.

b) Envio dos dados estruturados do documento

Ao adotar esta opção, o ERP dispensa de efetuar a geração completa do XML, ficando assim o ilink responsável por gerar o XML final. Assim, o ERP apenas necessita de enviar ao ilink todos os dados referentes ao documento. O endpoint a adotar aqui será o POST /apps/documents

A especificação deste método é extensa, pois cobre todos os campos possíveis de um fatura/encomenda, que estão devidamente documentados acima. Todos os documentos criados por este endpoint estão sujeitos às mesmas validações que os documentos enviados pelo método POST /apps/documentsUBL, ou seja, o XML resultante dos dados inseridos será validado de acordo com o validador oficial da eSPap, que pode ser consultado online neste link, e segundo as regras de negócio adicionais do recetor do documento, caso existam.

Nota: Para incluir um ficheiro PDF e outras situações habituais, consultar a secção casos de uso.

Nota: É possível enviar vários anexos num documento através do campo files[] (ver especificação acima). Contudo, a representação visual do documento (i.e PDF original da fatura usado na impressão) deve ser enviado sempre no campo file, sendo o campo files[] reservado para ficheiros adicionais (notas de encomenda, avisos de despacho, guias de transporte, etc.). Se o emissor do documento tem uma assinatura digital ativa no ilink, todos os anexos serão assinados.

5.4 Envio do documento

5.4.1 Envio via EDI

Um documento, após criação com sucesso (HTTP status 200) por qualquer um dos métodos acima (envio de XML ou envio de dados), será enviado automaticamente ao destinatário por EDI. Contudo, em casos pontuais, este poderá não ser entregue imediatamente ao destinatário via EDI devido a configurações em falta e/ou outras anomalias na plataforma ilink ou no sistema do recetor. Caso isto se verifique, será devolvido um campo to_send_status na resposta do documento a detalhar a situação:

HTTP status: 200 OK
 
{
	success: true,
	message:{
		code:"s011",
		msg:"Documento criado com sucesso"
	},
	response:{
		data:{
			id:"60796c3c2a6fa2.53909016",
			state_document:{
				id:"5c9cb870f34b16.42025494",
				alias:"tosend",
				description:"Por enviar ao cliente."
			},
			to_send_status:{
				code: "sent_connection", 
				title: "Aguardar a aceitação de ligação com o destinatário do documento."
			}
		}
	}
}

Nota: Pode-se verificar que o documento NÃO foi entregue via EDI pois o campo state_document.alias assume o valor 'tosend'.

Os motivos possíveis (code) para um documento não ser entregue são:

• sent_connection, no_connection: Ligação com o destinatário em falta
• registered_entity: O destinatário não está registado no ilink
• received_pay_transactions: O destinatário suporta os custos dos documentos recebidos mas não dispõe de transações suficientes

Após regularizar a situação de erro, será possível enviar o documento novamente (ver secção de reenvio de documentos).

Nota: O estado do documento é apenas aplicável a envios EDI. Caso o documento seja enviado para um cliente arbitrário via e-mail (PDF), o estado de envio (state_document) não reflete o envio do e-mail (ver seção seguinte).

5.4.2 Envio via e-mail

Um documento, após criação com sucesso (HTTP status 200) por qualquer um dos métodos acima (envio de XML ou envio de dados), será remetido via e-mail ao destinatário caso seja especificado o campo send_by_email com o valor 1. O(s) endereço(s) do(s) recetor(es) do documento pode(m) ser especificado(s) de 3 modos:

• no campo additional_emails[] (em ambos os métodos de envio)
• no campo customer[email] (apenas no método de envio de dados)
• no elemento cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail do XML (apenas no método de envio de XML).

Para consultar o envio dos e-mails e leitura dos mesmos para o cliente, ver secção b) de consulta de estado de documentos emitidos.

5.4.3 Criação de documentos e consumo de assinaturas digitais qualificadas

Esta secção é apenas relevante para clientes que utilizam o ilink para assinar digitalmente os documentos. (ver detalhes)

Caso esteja configurada uma assinatura digital qualificada no ilink, todos os documentos serão assinados no momento da sua criação, incluindo todos os ficheiros resultantes (xml e pdf). Dado que a assinatura dos documentos não é obrigatória por lei em todos os cenários de utilização, é possível controlar individualmente a assinatura dos ficheiros xml e pdf no momento da criação do documento com recurso aos os campos disable_xml_sign e disable_pdf_sign. Isto permite reduzir o consumo de assinaturas, bem como otimizar o processo de criação de documentos.

Ver especificação de criação manual ou por ficheiro UBL.

Ou seja:

• No envio de fatura digital via PDF assinado para um consumidor final ou cliente privado, não será obrigatório assinar o ficheiro XML, pelo que recomendamos a utilização do campo disable_xml_sign: 1
• No envio de fatura eletrónica para a Administração Pública via EDI (exemplo eSPap), não é obrigatório assinar o documento, no entanto é recomendada a assinatura de ambos os ficheiros por motivos de segurança adicional e integridade.
• Os campos acima apenas têm efeito quando é configurada uma assinatura digital qualificada para o emissor do documento no ilink.

5.5 Validações adicionais

É possível o recetor da fatura parametrizar no ilink a obrigatoriedade de certos campos (regras de negócio), mesmo que estes não sejam estritamente obrigatórios na especificação CIUS-PT. Por exemplo, um cliente poderá apenas aceitar faturas que incluem o ficheiro PDF anexado, ou o número de compromisso especificado. É importante que estes dados sejam pré-acordados com o vosso cliente/destinatário antes da passagem a produção para evitar erros de integração.

Caso o recetor do documento obrigue a presença de algum campo não especificado no XML, o API irá retornar um erro como abaixo e o documento não será gerado:

HTTP status: 400 Bad request
 
{
	success: false,
	errors:{
		commitment_number:{
			code:"e048",
			msg:"O número de compromisso é obrigatório."
		}
	}
}

5.6 Criar/editar documento

Um documento pode ser editado e reenviado ao destinatário

• se ainda não foi enviado ao cliente final
• ou se já foi enviado ao cliente e o cliente pediu uma regularização do mesmo

Em termos práticos, a possibilidade de reenvio pode ser consultada através do campo de resposta do documento:

state_edi_document:{
	alias: <estado> // estados possíveis de reenvio: 'regularization' ou 'reception' ou 'error'
}

Para consultar o estado de um documento, ver secção de consulta de estado de documentos emitidos.

Para editar um documento existente, basta repetir o pedido POST /apps/documentsUBL ou POST /apps/documents com os dados corrigidos, mantendo o número, tipo e data de emissão do documento anterior:

HTTP status: 200 OK
 
{
	success: true,
	message:{
		code:"s012",
		msg:"Documento editado com sucesso"
	},
	response:{
		data:{
			id:"60796c3c2a6fa2.53909016",
			number:"7411111",
			emission_date:"2021-04-16",
			type_document_fact:{
				id:"5c9cb870a5ef57.36583702",
				code:"380",
				alias:"invoice",
				type:"FT",
				description:"Fatura"
			},
			type_document:{
				alias:"issued",
				description:"Emitido"
			},
			state_document:{
				id:"5c9cb870f34b16.42025494",
				alias:"tosend",
				description:"Por enviar ao cliente."
			}
		}
	}
}

Caso o documento não seja elegível para edição (i.e já foi enviado ou foi aceite pelo cliente final), será apresentado um erro:

HTTP status: 400 Bad request
 
{
	success: false,
	errors:{
		number:{
			code:"e200",
			msg:"Documento já existe."
		}
	}
}

5.7 Acesso a documentos emitidos

Quando um documento é registado com sucesso, será sempre devolvido um ID nas respostas, que identifica o mesmo perante o ilink. Poderá ser útil guardar este identificador para consultas futuras ao documento.

HTTP status: 201 Created
 
{
	success: true,
	message:{
		code:"s011",
		msg:"Documento criado com sucesso"
	},
	response:{
		data:{
			id:"60796c3c2a6fa2.53909016",
		}
	}
}

O API permite também aceder a todos os dados (inclusive ao XML e PDF) de todos os documentos previamente emitidos. Para tal, deverão usar o método GET /apps/documents/{id}. O ID recebido na criação do documento deve ser usado como parâmetro aqui para aceder ao documento em questão.

Todos os dados retornados por este método estão disponíveis na especificação acima.

Nota: Caso a entidade emissora do documento tenha configurado a assinatura automática de documentos no ilink, os URLs públicos de acesso ao XML e ao PDF já retornam os ficheiros assinados.

5.8 Consulta de documentos emitidos no portal (opcional)

Os documentos podem também ser consultados no portal de testes do ilink usando as credenciais das entidades que vos foram enviadas. Aqui podem validar visualmente se a informação apresentada está coerente com os dados enviados via API:

Para aceder aos anexos de um documento, deverão aceder ao documento da tabela acima, e aceder ao ícone da lupa:

Nota: Os documentos deverão estar presentes tanto na entidade emissora (seção de documentos emitidos), bem como na entidade recetora (seção de documentos recebidos).

5.9 Consulta de estado de documentos emitidos

É também possível aceder ao estado atual dos documentos previamente emitidos. Esta operação permite ao emissor do documento consultar se o documento foi aceite pelo cliente, ou se está pendente de reenvio/regularização, bem como os motivos que levaram a tal.

5.9.1 Consulta de estado de documento enviado via EDI

O ilink contempla 4 estados possíveis de documento:

• Por enviar (tosend) - o documento não foi enviado ao cliente. Provavelmente significa que falta alguma configuração no ilink, emissor/recetor não autorizam ligação entre eles, ou que alguma das entidades presentes no documento não tem transações suficientes para proceder ao envio.
• Enviado (sent) - o documento foi enviado ao cliente e está pendente de aceitação.
• Aceite (accepted) - o documento foi enviado e o cliente aceitou o mesmo. Estado final.
• Recusado (rejected) - o documento foi enviado e o cliente rejeitou o mesmo devido a uma incoerência. O motivo de recusa é disponibilizado na resposta no campo reasons. O documento poderá ser enviado novamente caso seja solicitada uma regularização do mesmo.

Nota: O ilink devolve também o estado de processamento EDI atual do documento (state_edi_document), que é independente dos estados acima. Para mais informação, consultar o Guia de Transmissão de Documentos FE-AP, página 7. Contudo, a leitura do estado EDI nem sempre é relevante para os softwares de faturação.

Existem 3 abordagens para aceder ao estado de um documento previamente emitido: Consulta individual, Webhook de mudança de estado e Reporte de estados.

• Na Consulta individual de estado, basta efetuar a chamada GET /apps/documents/{id}. O ID recebido na criação do documento deve ser usado como parâmetro para aceder ao documento em questão. O estado é devolvido no campo state_document (ver especificação acima). Este método apenas permite consultar o estado de um documento de cada vez.

• No Webhook de mudança de estado (recomendado), o ilink tem a iniciativa de informar ao emissor do documento cada vez que o mesmo muda de estado. Para mais informação, consultar a secção Webhooks.

• No Reporte de estados, a aplicação a integrar tem a iniciativa de consultar os diversos eventos que levaram às alterações de estado dos documentos emitidos. Para tal, basta efetuar a chamada GET /apps/states-report/documents. Cada evento identifica o documento e o estado alterados. É possível filtrar os eventos retornados por ID de documento, número de documento, intervalos de datas, entre outros (ver especificação acima). Este método permite a aplicação consultar o estado de vários documentos em simultâneo.

  De modo a facilitar a utilização do reporte de estados, é adicionalmente disponibilizado o endpoint de leitura de eventos POST /apps/states-report/documents/read, que permite marcar um ou mais IDs de evento obtidos acima como lido(s). Os eventos marcados como lidos não são retornados novamente no endpoint de reporte de estados.

5.9.2 Consulta de estado de documento enviado via e-mail

No envio de documento via e-mail, é possível consultar o registo de envio e de leitura dos e-mails enviados ao cliente. Note-se que o estado do documento retornado (state_document) não é aplicável neste cenário, pois o documento por norma não é enviado via EDI, e como tal, o seu estado de envio será habitualmente to_send. Este estado deve ser ignorado.

Existem 2 abordagens para aceder ao registo de e-mails enviados de um documento: Consulta individual e Consulta de histórico de documento.

• Na Consulta individual, basta efetuar a chamada GET /apps/documents/{id}. O ID recebido na criação do documento deve ser usado como parâmetro para aceder ao documento em questão. Na resposta, devem aceder à propriedade emails, que retorna uma lista dos e-mails enviados e o seu estado de receção e leitura. Este método apenas permite consultar o estado de um documento de cada vez (exemplo abaixo):

HTTP status: 200 OK
 
{
	success: true,
	response:{
		data:{
			id:"60796c3c2a6fa2.53909016",
			...
			emails: [{
				id: "634672bab0f3b8.40302642", 
				b_open: true, // true caso o email tenha sido lido pelo recetor
				b_sent: true, // true caso o email tenha sido enviado com sucesso
				created_at: "2022-10-12 08:54:34", // data e hora de envio do email
				opened_at: "2022-10-12 09:14:16", // data e hora de leitura do email
				address: {
				    emails: ["joao.freitas@email.com"] // endereço de envio
				}
			}]
		}
	}
}

Nota: Certos clientes de e-mail (Outlook, etc.) podem bloquear o registo de leitura dos e-mails ao ilink, ficando o b_open a false mesmo que o e-mail tenha sido aberto em algumas situações.

• Para a Consulta de histórico de documento, consultar a seção seguinte.

5.10 Consulta de histórico de documentos emitidos

Em modo complementar, é também possível consultar o histórico processual de um determinado documento. Este histórico irá listar todas as alterações de estado que ocorreram no documento por ordem cronológica, bem como os registos dos envios de e-mail para o destinatário, o que permite um rastreio completo de auditoria. Pode ser acedido através de GET /apps/documents/{id}/history.

6. Receção de documentos

6.1 Âmbito

Permite dar entrada aos documentos de faturação no ERP do recetor da fatura, permitindo a sua integração automática nos sistemas contabilísticos. Também permite a comunicação de estados de aceitação dos documentos ao emissor dos mesmos (pago, aceite, recusado, etc.).

Neste fluxo de integração, recomendamos que sejam implementados os seguintes aspetos:

• Leitura do XML ou dados estruturados do documento de modo a registar as informações necessárias no ERP
• Comunicação do estado de integração do documento ao ilink
• Comunicação do estado de aceitação do documento (incluindo o envio de mensagens em caso de erro)

6.2 Métodos de receção

Permite consultar e integrar documentos no sistema em questão. A receção de documentos pode ser efetuada por 2 métodos: Consulta manual de documentos ou Webhook de receção.

• a) Consulta manual de documentos

Neste modo, é necessário aceder ao endpoint GET /apps/documents. É possível especificar diversos parâmetros de pesquisa de modo a filtrar os resultados obtidos. A resposta deste método inclui os dados principais dos documentos, e adicionalmente a paginação através das propriedades rows (número de elementos por página) e page (número da página a consultar). Consulte a especificação acima para mais detalhes.

Para consultar os detalhes de um documento, bem como os links para os ficheiros XML e PDF do mesmo, deverá ser utilizado o método GET /apps/documents/{id}, usando um dos IDs retornados na lista de documentos anterior.

O endpoint de consulta pode ser acedido periodicamente (num processo em segundo plano), ou mediante a consulta de um utilizador no sistema (em tempo real).

Nota: Aqui, a chave pública é usada no contexto da entidade recetora dos documentos, ou seja, deverão utilizar a chave pública que identifica a entidade que consulta os documentos recebidos.

Importante: Recomendamos uma utilização responsável deste endpoint. Chamadas excessivas a este recurso são de evitar, e poderão levar a 'time-outs' e restrições de acesso.

• b) Webhook de receção (recomendado)

Neste modo, o ilink toma a iniciativa de comunicar ao ERP quando chega um novo documento ao cliente, dispensando de consultas frequentes ao endpoint GET /apps/documents. Para mais informação, consultar a secção Webhooks.

Nota: Segundo especificação, serão retornados os dados dos documentos num formato estruturado, bem como os URLs públicos para o acesso aos ficheiros XML e PDF do documento.

6.3 Importação e aceitação

Após consultar o documento pretendido, é recomendado que o ERP comunique ao ilink o estado de processamento do mesmo, ou seja, se este integrou corretamete no sistema ou se é necessário retificar/regularizar o documento. Para tal, são necessários 2 passos:

• 1. Comunicar o estado do documento

  • É feito com o pedido POST /apps/documents/{id}/accepted. Aqui é indicado se o documento foi aceite ou não, e caso contrário, o motivo que levou à sua rejeição
  • É obrigatório indicar o motivo de rejeição de um documento caso não seja aceite
  • Um documento rejeitado poderá ser reenviado pelo emissor com os dados corrigidos

• 2. Comunicar a importação do documento (apenas na aceitação com sucesso)

  • Caso o passo anterior seja concluído com sucesso (i.e. o documento está em condições de ser integrado no ERP), deverão invocar o método POST /apps/documents/{id}

Nota: Não é necessário importar um documento rejeitado.

A correta comunicação de documentos aceites e/ou importados cria um histórico de auditoria e facilita o consumo do API, dado que, caso estejam a adotar a receção de documentos pelo método de consulta manual, quaisquer documentos que tenham sido importados ou rejeitados não são devolvidos novamente. Ou seja, as chamadas a GET /apps/documents não devolvem documentos previamente rejeitados ou importados.

A imagem abaixo demonstra como todas as operações realizadas pelo ERP são registadas no portal do ilink:

6.4 Estados de Processo

Nota: Esta funcionalidade é opcional e não afecta o funcionamento do fluxo de receção de documentos.

O ilink também permite a criação de estados de documento personalizáveis para os documentos recebidos. Caso esta funcionalidade esteja em uso pela entidade atual, será possível listar e alterar este estado de um documento via API. Isto permite a um software externo (como gestão documental) alterar o estado processual do documento no ilink de forma integrada. Todas as alterações de estado de processo ficam registadas no histórico do documento.

O estado do processo é independente do estado normal de um documento (recebido, aceite, etc.). É usado apenas para fins de organização e registo de operações.

Para consultar todos os estados de processo disponíveis na entidade em questão, deverá ser usado o método GET /apps/processstates, que retorna a lista completa de estados, juntamente com o seu identification_code. Para alterar o estado de processo de um documento, deverá ser usado o método PUT /apps/documents/{id}/processstates, usando o campo identification_code para atribuir o novo estado.

Para definir estados de processo para uma entidade, consulte o manual.

7. Casos de uso

A seguinte secção exemplifica algumas situações comuns na criação de documentos CIUS-PT.

7.1 Criação de documentos por envio de dados

• Indicar as condições de pagamento

  payment_terms[note]: 30 dias

• Indicar um local de consumo (CPE) numa das linhas do documento

  lines[0][additional_property][0][name]: CPE
  lines[0][additional_property][0][value]: PT1234567890

• Envio do número de compromisso no cabeçalho do documento

  commitment_number: 2021/451

• Envio do número de compromisso nas linhas do documento

  lines[0][commitment][number]: 2021/123
  lines[0][commitment][line]: 1

• Envio do número de encomenda

  references[0][document_type]: order
  references[0][number]: 1234

• Envio do PDF anexado (UTF-8)

  file: (binary)

• Envio de outros anexos secundários

  files[0]: (binary)
  files[1]: (binary)

  Nota: O PDF de representação do documento deve ser sempre enviado no campo file.

• Desconto no cabeçalho do documento

  discounts_charges[0][type]: false // usar true para encargo
  discounts_charges[0][reason]: desconto comercial
  discounts_charges[0][percent]: 23.00
  discounts_charges[0][tax_code]: NOR
  discounts_charges[0][amount]: 8.13 // refere-se ao valor sem imposto (ou seja, este desconto é de 10.00 EUR após a aplicação de IVA)
  discount_amount: 8.13 // refere-se ao total de descontos de cabeçalho aplicados ao documento (NÃO inclui descontos nas linhas)

• Desconto ou encargo na linha do documento

  lines[0][discounts_charges][0][type]: false // usar true para encargo
  lines[0][discounts_charges][0][reason]: desconto comercial // descrição textual do desconto
  lines[0][discounts_charges][0][amount]: 5.00 // refere-se ao valor sem IVA a descontar na linha
  lines[0][quantity]: 2.000 // quantidade de artigos na linha
  lines[0][price]: 10.00000000 // preço unitário do artigo
  lines[0][amount]: 15.00000000 // o total da linha do documento é afectado pelo desconto ( (10 * 2) - 5 = 15)
  lines[0][taxes][0][tax_percent]: 23.000 // taxa de IVA
  lines[0][taxes][0][tax_amount]: 3.45 // valor do IVA da linha (15 * 0.23)
  discount_amount: 0.00 // refere-se ao total de descontos de cabeçalho aplicados ao documento (NÃO inclui descontos nas linhas)

• Desconto no preço do artigo

  lines[0][price_discount][base_amount]: 10.00 // preço unitário original do artigo antes de aplicar o desconto
  lines[0][price_discount][amount]: 5.00 // refere-se ao valor sem IVA a descontar no preço do artigo
  lines[0][quantity]: 2.000 // quantidade de artigos na linha
  lines[0][price]: 5.00000000 // preço do artigo após aplicação do desconto (10 - 5 = 5)
  lines[0][amount]: 10.00000000 // o total da linha do documento é afectado pelo desconto ( (10 - 5) * 2 = 10)
  lines[0][taxes][0][tax_percent]: 23.000 // taxa de IVA
  lines[0][taxes][0][tax_amount]: 2.30 // valor do IVA da linha (10 * 0.23)
  discount_amount: 0.00 // refere-se ao total de descontos de cabeçalho aplicados ao documento (NÃO inclui descontos nas linhas)

• Retenção na fonte

  withholding_tax[0][type]: IRF
  withholding_tax[0][tax_amount]: 10.00 // valor da retenção
  withholding_tax[0][description]: Retenção IRS
  withholding_tax_amount: 10.00 // soma de todas as retenções do documento

  Nota: os totais do documento não são afetados pela retenção

• Isenção de IVA na linha

  lines[0][quantity]: 2.000 // quantidade
  lines[0][price]: 5.00000000 // preço unitário
  lines[0][amount]: 10.00000000 // total da linha sem IVA
  lines[0][taxes][0][tax_percent]: 0.00 // taxa de IVA
  lines[0][taxes][0][tax_amount]: 0.00 // valor do IVA da linha
  lines[0][taxes][0][tax_exemption_reason_code]: M08 // código de motivo da AT
  lines[0][taxes][0][tax_exemption_reason]: IVA - Autoliquidação // descritivo do motivo da AT

• Isenção de IVA no desconto ou encargo de cabeçalho

  discounts_charges[0][type]: false // usar true para encargo
  discounts_charges[0][reason]: desconto comercial // descritivo
  discounts_charges[0][percent]: 0.00 // percentagem (isento)
  discounts_charges[0][tax_code]: ISE // isento
  discounts_charges[0][amount]: 10.00 // valor do desconto
  discounts_charges[0][tax_exemption_reason]: M08 // código de motivo da AT
  discounts_charges[0][tax_exemption_reason_code]: IVA - Autoliquidação // descritivo do motivo da AT

• Envio da fatua por e-mail a um ou mais endereços

  send_by_email: 1,
  customer[email]: endereco1@email.com // enviado sempre para o email especificado no cliente
  additional_emails[0]: endereco2@email.com // também enviado para a lista adicional de endereços
  additional_emails[1]: endereco3@email.com

• Envio de código QR

  qr_code: A:500000000*B:123456789*C:PT*D:GT*E:N*F:20190720*G:GT G234CB/50987*H:GTVX4Y8B-50987*I1:0*N:0.00*O:0.00*Q:5uIg*R:9999

7.2 Criação de documentos por envio do CIUS-PT

• Envio do número de compromisso no cabeçalho do documento

  <Invoice>
  	...
  	<cbc:AccountingCost>2021/156</cbc:AccountingCost>
  </Invoice>

• Envio do Capital Social do fornecedor:

  <Invoice>
  	...
  	<cac:AccountingSupplierParty>
  		<cac:PartyLegalEntity>
  			<cbc:CompanyLegalForm>2.000.000 EUR</cbc:CompanyLegalForm>
  		</cac:PartyLegalEntity>
  	</cac:AccountingSupplierParty>	
  </Invoice>

• Envio do GLN do cliente (usar o schemeID 0088):

  <Invoice>
  	...
  	<cac:AccountingCustomerParty>
  		<cbc:EndpointID schemeID="0088">123456789</cbc:EndpointID>
  	</cac:AccountingCustomerParty>	
  </Invoice>

• Envio de ATCUD e QRCODE:

  <Invoice>
  	...
  	<cac:AdditionalDocumentReference>
  		<cbc:ID schemeID="ANG">AFHOFX-22</cbc:ID> <!-- Valor ATCUD -->
  		<cbc:DocumentDescription>QR_CODE</cbc:DocumentDescription>
  		<cac:Attachment> <!-- Texto do QRCODE, em base64 (da sequência de carateres, NÃO da imagem) -->
  			<cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain" filename="QR_CODE.txt">UVJDT0RF=</cbc:EmbeddedDocumentBinaryObject> 
  		</cac:Attachment>
  	</cac:AdditionalDocumentReference>
  </Invoice>

• Indicar o método de pagamento:

  <Invoice>
  	...
  	<cac:PaymentMeans>
  		<cbc:PaymentMeansCode>NU</cbc:PaymentMeansCode>
  	</cac:PaymentMeans>	
  </Invoice>

  Valores permitidos: CC - Cartão crédito; CD - Cartão débito; CH - Cheque bancário; CI - Crédito documentário internacional; CO - Cheque ou cartão oferta; CS - Compensação de saldos em conta corrente; DE- Dinheiro eletrónico, por exemplo residente em cartões de fidelidade ou de pontos; LC - Letra comercial; MB - Referências de pagamento para Multibanco; NU - Numerário; OU - Outros meios aqui não assinalados; PR - Permuta de bens; TB - Transferência bancária ou débito direto autorizado; TR - Títulos de compensação extrassalarial independentemente do seu suporte, por exemplo, títulos de refeição, educação, etc.

• Indicar informações de pagamento de cartão de débito ou crédito:

  <Invoice>
  	...
  	<cac:PaymentMeans>
  		<cbc:PaymentMeansCode>CC</cbc:PaymentMeansCode>
  		<cac:CardAccount>
  			<cbc:PrimaryAccountNumberID>4211456651233545687</cbc:PrimaryAccountNumberID> <!-- Número da conta -->
  			<cbc:NetworkID>04256</cbc:NetworkID> <!-- Identificador da rede bancária -->
  			<cbc:HolderName>João Ferreira</cbc:HolderName> <!-- Nome do titular -->
  		</cac:CardAccount>
  	</cac:PaymentMeans>
  </Invoice>

• Indicar método de pagamento por transferência bancária:

  <Invoice>
  	...
  	<cac:PaymentMeans>
  		<cbc:PaymentMeansCode>TB</cbc:PaymentMeansCode>
  		<cac:PayeeFinancialAccount>
              <cbc:ID>PT50000700230012345667899</cbc:ID> <!-- IBAN-->
              <cbc:Name>João</cbc:Name> <!-- Nome do titular -->
              <cac:FinancialInstitutionBranch>
  	            <cbc:ID>NBxxxx</cbc:ID> <!--SWIFT -->
              </cac:FinancialInstitutionBranch>
         </cac:PayeeFinancialAccount>
  	</cac:PaymentMeans>
  </Invoice>

• Indicar método de pagamento por referência multibanco:

  <Invoice>
  	...
  	<cac:PaymentMeans>
  		<cbc:PaymentMeansCode name="#DESCRIPTION@ATMPAYMENT#156.22#">#ENTITY@ATMPAYMENT#15652</cbc:PaymentMeansCode> <!-- Entidade e Valor -->
  		<cbc:PaymentID>#REFERENCE@ATMPAYMENT#156555145#</cbc:PaymentID> <!-- Referência -->
  	</cac:PaymentMeans>
  </Invoice>

• Indicar uma segunda referência multibanco:

  <Invoice>
  	...
  	<cbc:Note>#ENTITY@ATMPAYMENT-001#12345#</cbc:Note> <!-- 2ª entidade -->
      <cbc:Note>#REFERENCE@ATMPAYMENT-001#012345678#</cbc:Note> <!-- 2ª referência -->
      <cbc:Note>#AMOUNT@ATMPAYMENT-001#3264.10#</cbc:Note> <!--Valor da 2ª referência -->
      <cbc:Note>#DESCRIPTION@ATMPAYMENT-001#Valor total do documento, mais valores em atraso#</cbc:Note> <!-- Descrição da 2ª referência -->
  </Invoice>

• Indicar as condições de pagamento:

  <Invoice>
      ...
  	<PaymentTerms>
  		<cbc:Note>30 dias</cbc:Note>
  	</PaymentTerms>
  </Invoice>

• Indicar uma nota textual no cabeçalho do documento:

  <Invoice>
  	...
  	<cbc:Note>Nota cabeçalho</cbc:Note>
  </Invoice>

• Indicar uma nota textual numa das linhas do documento:

  <Invoice>
  	...
  	<InvoiceLine>
  		<cbc:Note>Nota linha</cbc:Note>
  	</InvoiceLine>
  </Invoice>

• Indicar uma propriedade adicional no documento:

  <Invoice>
  	...
  	<cbc:Note>#ADDITIONALPROPERTY#VOUCHER#123#</cbc:Note>
  <Invoice>

• Indicar um local de consumo (CPE) numa das linhas do documento:

  <cac:InvoiceLine>
  	...
  	<cac:AdditionalItemProperty>
  		<cbc:Name>CPE</cbc:Name>
  		<cbc:Value>PT1234567890</cbc:Value>
  	</cac:AdditionalItemProperty>
  </cac:InvoiceLine>

• Envio do número de encomenda / número de requisição

  <Invoice>
  	...
  	<cac:OrderReference>
  		<cbc:ID>20159854587</cbc:ID>
  	</cac:OrderReference>
  </Invoice>

• Envio do número de compromisso nas linhas do documento

  <cac:InvoiceLine>
  	<cbc:AccountingCost>2020/123</cbc:AccountingCost> <!-- número do compromisso da linha -->
  	...
  	<cac:Item>
  		<cac:AdditionalItemProperty>
  			<cbc:Name>#LINEID@COMMITMENTLINEREFERENCE#</cbc:Name>
  			<cbc:Value>1</cbc:Value> <!-- número da linha -->
  		</cac:AdditionalItemProperty>
  	</cac:Item>
  </cac:InvoiceLine>

• Envio do PDF anexado (o conteúdo deve estar em base64)

  <Invoice>
  	...
  	<cac:AdditionalDocumentReference>
  		<cbc:ID>1</cbc:ID>
  		<cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
  		<cac:Attachment>
  			<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
  			</cbc:EmbeddedDocumentBinaryObject>
  		</cac:Attachment>
  	</cac:AdditionalDocumentReference>
  </Invoice>

  Ver exemplo

• Envio de múltiplos PDFs anexados

  <Invoice>
  	...
  	<cac:AdditionalDocumentReference>
  		<cbc:ID>1</cbc:ID> <!-- O anexo principal deve ter a descrição INVOICE_REPRESENTATION', ou 'CREDITNOTE_REPRESENTATION' -->
  		<cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
  		<cac:Attachment>
  			<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document.pdf">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
  			</cbc:EmbeddedDocumentBinaryObject>
  		</cac:Attachment>
  	</cac:AdditionalDocumentReference>
   
  	<cac:AdditionalDocumentReference>
  		<cbc:ID>2</cbc:ID> <!-- Os anexos secundários (como a nota de encomenda, guias de pagamento, etc.) devem ter a descrição 'ATTACHMENT'. É possível incluir vários ATTACHMENTs num documento. -->
  		<cbc:DocumentDescription>ATTACHMENT</cbc:DocumentDescription>
  		<cac:Attachment>
  			<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document2.pdf">jUNCiW1tbW1DQoJVBERi0xLjUNCiW1tbW1DQo8PC9UeXBlL0NhUGIvTGF==
  			</cbc:EmbeddedDocumentBinaryObject>
  		</cac:Attachment>
  	</cac:AdditionalDocumentReference>
  </Invoice>

• Envio de outros anexos (QR Code, etc.) (o conteúdo deve estar em base64)

  <Invoice>
  	...
  	<cac:AdditionalDocumentReference>
  		<cbc:ID>2</cbc:ID>
  		<cbc:DocumentDescription>ATTACHMENT</cbc:DocumentDescription> <!-- usar QR_CODE para o código QR -->
  		<cac:Attachment>
  			<cbc:EmbeddedDocumentBinaryObject mimeCode="application/txt" filename="document">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
  			</cbc:EmbeddedDocumentBinaryObject>
  		</cac:Attachment>
  	</cac:AdditionalDocumentReference>
  </Invoice>

• Desconto ou encargo no cabeçalho do documento Ver exemplo

• Desconto ou encargo na linha do documento Ver exemplo

• Desconto ou encargo no preço do artigo Ver exemplo

• Retenção na fonte Ver exemplo

• Isenção de IVA na linha do documento Ver exemplo

• Isenção de IVA no desconto de cabeçalho do documento Ver exemplo

• Múltiplas isenções no documento Ver exemplo

• Vários descontos na linha Ver exemplo

• Ver lista completa de casos de uso CIUS-PT pela eSPap.

8. Fluxos API

A imagem abaixo consolida os fluxos de integração do API do ilink acima descritos:

9. Checklist pré-produção

Antes de passar a integração a produtivo, devem validar os seguintes pontos:

Acordo de interoperabilidade (obrigatório)

• Deverá ser assinado e devolvido

Envio de documentos (no caso da implementação do fluxo de envio)

• Verificar se é possível criar um documento entre ambas as entidades de teste sem erros de validação, contendo os seguintes campos:

  • PDF anexado
  • Número de compromisso
  • Todos os campos da morada do fornecedor (rua, cidade, código postal)
  • Capital social do fornecedor
  • Número de encomenda/requisição
  • GLN do cliente
  • GLN do local de entrega
• No caso do envio de documentos para entidades não públicas (e.g envio de e-mail com PDF anexado), verificar se é enviado um e-mail com a fatura ao destinatário, e se a assinatura do documento XML é desativada (caso seja usada uma assinatura digital qualificada no ilink)
• No caso da consulta de estado de documentos emitidos, deverão testar se o software é capaz de receber e processar a resposta do estado do documento

  • Caso o documento seja rejeitado/regularizado, deverá ser possível enviar o mesmo com informação retificada.

Receção de documentos (no caso da implementação do fluxo de receção)

• Devem verificar se um documento recebido é corretamente integrado no software, e se é comunicada a correta importação e aceitação do mesmo.

Passagem a produção (obrigatório)

1. Configurar o URL de produção
2. Solicitar o token de aplicação e chave(s) da(s) entidade(s) do ambiente de produção à equipa do ilink
3. Assegurar-se que são efetuadas as autenticações necessárias em ambiente produtivo
4. Assegurar-se que o cliente tem todas as ligações configuradas no portal do ilink, bem como as transações necessárias (solicitar ao serviço de apoio)
5. Opcional: assegurar que o cliente tem a assinatura digital configurada no ambiente produtivo.
6. Opcional: assegurar que o cliente tem o template de envio de e-mail de faturação configurado no ambiente produtivo.