Integração via AS2

1. Âmbito

A comunicação via AS2 é destinada principalmente a brokers EDI, e facilita a comunicação em tempo real de documentos e mensagens de estado. Para iniciar esta interligação, deverá pedir as nossas credenciais AS2 à equipa de apoio.

2. Detalhes técnicos

Assinatura MDN ativa
Algoritmo de encriptação 3DES
Algoritmo de assinatura SHA1
MDN asíncrono
Formatos suportados: CIUS-PT

3. Fase de testes

Após configuração de credenciais e certificados, normalmente é feito um teste simples de ligação entre os parceiros com um ficheiro de texto.

Após essa fase, procede-se ao envio de documentos reais no ambiente de testes, passando a produção após a validação dos documentos e mensagens de estado. Caso o broker já esteja integrado com diversos clientes, cada novo cliente pode passar a produção de imediato após o pedido de ligação.

4. Formatos e estados

Todos os documentos recebidos pelo ilink são sujeitos à validação CIUS-PT (ver validador online).

Nota: Para incluir um ficheiro PDF na fatura, este deverá ser inserido em base64 encode dentro do elemento AdditionalDocumentReference > Attachment > EmbeddedDocumentBinaryObject. Ver exemplo

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

4.1 Mensagem de Estado

As respostas serão enviadas via XML CIUS MessageStatus versão 2.1, em que:

O nome do ficheiro enviado pelo ilink segue a estrutura Response_<UUID_MESSAGE_STATUS>
O elemento DocumentResponse>DocumentReference>ID inclui o número de documento que se refere
O elemento DocumentResponse>DocumentReference>UUID inclui o AdditionalDocumentReference>ID[schemeID=AIM] do documento que se refere. Caso não exista, o elemento não é enviado.

Nota: Caso o documento recebido não consiga ser interpretado (ficheiro corrupto, XML inválido), o ilink irá enviar uma mensagem .txt de volta ao emissor com o título igual ao AS2_MESSAGE_ID do documento a que se refere a indicar que o ficheiro recebido não foi lido.

Nota: Caso falhe o envio do MessageStatus, o ilink irá tentar novamente no final do dia, e assim sucessivamente até o ficheiro ser recebido pelo destinatário.

Abaixo pode consultar um exemplo de um ficheiro de estados:

<?xml version="1.0" encoding="UTF-8"?>
<ubl:DocumentStatus xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" 
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:DocumentStatus-2">
	<cbc:CustomizationID>urn:feap.gov.pt:MSGSTS_CIUS-PT:2.1</cbc:CustomizationID>
	<cbc:ID>Response_f02866d2-feeb-4f96-9320-d00507c0018a_6e098568-dfde-4835-87e9-28f6ca1b139d</cbc:ID>
	<cbc:IssueDate>2021-04-13</cbc:IssueDate>
	<cbc:IssueTime>09:06:41.0000000+01:00</cbc:IssueTime>
	<cac:SenderParty>
		<cac:PartyName>
			<cbc:Name>ENTIDADE PÚBLICA Nº 156</cbc:Name>
		</cac:PartyName>
		<cac:PostalAddress>
			<cac:Country>
				<cbc:IdentificationCode>PT</cbc:IdentificationCode>
			</cac:Country>
		</cac:PostalAddress>
		<cac:PartyTaxScheme>
			<cbc:CompanyID>PT614054128</cbc:CompanyID>
			<cac:TaxScheme>
				<cbc:ID>VAT</cbc:ID>
			</cac:TaxScheme>
		</cac:PartyTaxScheme>
		<cac:PartyLegalEntity>
			<cbc:RegistrationName>ENTIDADE PÚBLICA Nº 156</cbc:RegistrationName>
		</cac:PartyLegalEntity>
	</cac:SenderParty>
	<cac:ReceiverParty>
		<cac:PartyName>
			<cbc:Name>Serviços de Consultoria, Lda.</cbc:Name>
		</cac:PartyName>
		<cac:PostalAddress>
			<cac:Country>
				<cbc:IdentificationCode>PT</cbc:IdentificationCode>
			</cac:Country>
		</cac:PostalAddress>
		<cac:PartyTaxScheme>
			<cbc:CompanyID>PT547570692</cbc:CompanyID>
			<cac:TaxScheme>
				<cbc:ID>VAT</cbc:ID>
			</cac:TaxScheme>
		</cac:PartyTaxScheme>
		<cac:PartyLegalEntity>
			<cbc:RegistrationName>Serviços de Consultoria, Lda.</cbc:RegistrationName>
		</cac:PartyLegalEntity>
	</cac:ReceiverParty>
	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ResponseCode>11</cbc:ResponseCode>
		</cac:Response>
		<cac:DocumentReference>
			<cbc:ID>ZM 02/7000009232102</cbc:ID>
			<cbc:UUID>f02866d2-feeb-4f96-9320-d00507c0018a</cbc:UUID>
			<cbc:IssueDate>2021-03-10</cbc:IssueDate>
			<cbc:DocumentTypeCode>380</cbc:DocumentTypeCode>
		</cac:DocumentReference>
	</cac:DocumentResponse>
</ubl:DocumentStatus>

4.2 Lista de estados

Os MessageStatus do ilink incluem os estados EDI definidos pela eSPap no elemento DocumentResponse>Response>ResponseCode:

ACCEPTED - documento passou pela validação de XML e regras de qualidade, e foi integrado no sistema, e foi enviado ao receptor
ERROR - documento não passou pela validação inicial de qualidade (XML com erros, não cumpre os campos obrigatórios especificados pelo receptor, etc)
14 - documento foi recusado pelo receptor e aguarda regularização (deve ser retificado e reenviado, ou alternativamente submetida uma nota de crédito/débito)
22 - documento foi devolvido pelo receptor e deverá ser anulado. Deve ser emitido novo documento
33 - documento foi colocado a pagamento
29 - documento pago
11 - documento processado pelo receptor (documento foi aceite)
30 - nota de crédito aceite pelo receptor

Nota: Os estados ERROR, 14 e 22 incluem a descrição do erro em DocumentResponse>Response>Description.

Nota: Embora os estados 33 e 29 não sejam enviados pelo ilink, estes podem ser recebidos e interpretados correctamente pelo nosso sistema.

4.3. Fluxo de Estados EDI

Tendo em conta os estados descritos acima, estes são os diversos fluxos que um documento pode seguir:

Descrição	Caminho
O documento chegou ao ilink e não passou a validação das regras semânticas do XML ou controlo de qualidade (erro CIUS-PT, campos obrigatórios em falta, ligação não existente)	ERROR
O documento chegou ao ilink e passou na validação XML, e foi enviado ao receptor	ACCEPTED
O documento chegou ao ilink, validou correctamente e chegou ao destinatário, mas o destinatário não integrou o mesmo no seu sistema e pediu um documento de regularização (emissão de NC ou re-envio do documento retificado)	ACCEPTED >> 14
O documento chegou ao ilink, validou correctamente e chegou ao destinatário, mas o destinatário devolveu o mesmo e obriga à emissão de um novo documento	ACCEPTED >> 22
O documento chegou ao ilink, validou correctamente e chegou ao destinatário, foi integrado no sistema contabilístico.	ACCEPTED >> 11
A Nota de Crédito chegou ao ilink, validou correctamente e chegou ao destinatário, e o destinatário integrou o mesmo no seu sistema contabilístico, para depois proceder ao ajuste de contas	ACCEPTED >> 30

4.4 Reenvio de documentos

É possível reenviar um documento após retificação do mesmo. Um documento apenas pode ser reenviado se o seu último estado for:

ERROR (Erro de validação ou ligação)
14 (Regularização por parte do cliente)

Para os restantes estados, não é possível reenviar um documento e este será rejeitado pelo sistema.

5. Assinatura digital

O protocolo AS2 requer o uso de uma assinatura especifica a aplicar ao nível do protocolo de transporte, recorrendo-se para tal a S/MIME e usando certificados X.509. A autenticação é feita através da comparação das chaves públicas e privadas tanto do emissor como do recetor.

A assinatura ao nível do documento é obrigatória para comunicações via web services, sendo que passa a facultativa no caso de comunicações via AS2, dado que, no caso deste último canal, a assinatura já é usada ao nível do S/MIME.

Fonte: Guia de Transmissão de documentos eletrónicos FE-AP v1.4, ESPAP-IP

É também verificada a validade da assinatura de todos os documentos recebidos pelo ilink. O seguinte validador pode ser utilizado para verificar a validade da assinatura dos documentos. Os formatos de assinatura reconhecidos pelo ilink são PADES (PDF), ou XMLDSig e XADES-BES enveloped (XML).

6. Pedidos de ligação

Deve ser enviado um pedido de ligação à equipa do ilink (apoio@ilink.pt) quando um cliente do broker externo se pretende ligar a um cliente do ilink, e vice-versa. Este processo é feito por cada par de clientes a ligar.

Quando a equipa do ilink configura um pedido de ligação de outro broker, irá ser indicado na nossa resposta as validações adicionais que o nosso cliente exige nos ficheiros recebidos (e.g PDF anexado, número de compromisso associado, etc), caso existam.

7. Casos de uso

Podem consultar como implementar várias situações na geração do XML CIUS-PT aqui.