Issuing documents

Scope

The ilink platform allows integrator systems to issue documents that are automatically sent to their respective recipients. ilink manages the entire sending process for the ERPs and EDIs configured for each customer, making this process transparent for the API. These configurations are carried out by the ilink support team before before deployment to production.

The ilink platform supports the sending of electronic invoices in two different scenarios:

• Sending signed PDFs via e-mail to end consumers or private companies
  • In this scenario, it is not necessary to create connections with other EDIs. Simply indicate the destination e-mail address(es) in the document creation endpoint. For more information, see the section Sending methods.
• Sending CIUS-PT XML to public entities (mandatory in public contracts)
  • In this scenario, it is necessary to configure the connections between TINs in advance and, possibly, between other external EDI brokers.

How are documents sent to other EDI brokers? During the production deployment phase, a survey of all entities that will receive documents via EDI, as well as their respective EDI brokers, must be carried out. Subsequently, the support team (apoio@ilink.pt) will configure the necessary connections to ensure that the documents are automatically integrated into each recipient’s system. Before sending documents to the FE-AP solution of eSPap, each issuer must also complete the FE-AP supplier enrolment process.

All documents issued are available on the ilink portal, both for the issuing entity and for the receiving entity.

Note: In the test environment, you should only issue documents between the two entities that have been granted access. If you wish to verify the functioning of document sending to an end consumer (arbitrary TIN), you should always issue the document through one of the entities that have been granted access.

IMPORTANT: When sending documents to public entities, we strongly recommend implementing the following aspects, otherwise you may not be able to integrate the documents with certain systems:

• Commitment number
• Original PDF file of the invoice
• Order or requisition number (if applicable)
• Supplier's share capital
• Customer's e-mail address (only for the offices of the Regional Government of Madeira)
• All supplier address details (street, postal code, city, etc.)
• Customer GLN (if applicable)
• Possibility of resending the document based on the state obtained (useful for correcting and resending a previously rejected document)

Digital signature

Ilink allows you to automatically sign attachments to issued documents (XML and PDF), provided that the issuing entity has purchased and configured a seal from one of the qualified digital signature providers. Currently, only GTS - Global Trusted Sign is supported, but there are plans to support the remaining providers in Portugal.

This means that the ERP is not required to integrate with a signature provider and can (optionally) delegate the certification process to ilink. Alternatively, the ERP itself can perform the certification process and send the signed documents to ilink.

Note: In the ilink signature scenario, by default, all resulting files are signed upon entry (xml and pdf) and subsequently sent to the customer. This behaviour can be changed, allowing you to define which files are signed. For more information, see the section on signature consumption.

In the case of signing via ERP, the digital signature of the document is always cryptographically validated for all documents entering the system. A document with an invalid signature, both in XML and PDF, will not integrate and will always return an error via API as follows:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "document": {
      "code": "e217",
      "msg": "The signature on the document is not valid."
    }
  }
}

The previous error indicates that the document has been altered since it was signed, or that the signature was generated incorrectly. The following validator can be used to verify the validity of document signatures. The signature formats recognised by ilink are PADES and PKCS7-B (PDF), or XMLDSig and XADES-BES (XML).

Note: The legal requirements for the signature of electronic invoices are available in Decree-Law 28/2019, section II, article 12.

Note: Ilink signs PDF documents in PADES and XML documents in XADES-BES enveloped.

Sending methods

Once authentication has been successfully completed, we are ready to start sending documents. The ilink API provides two approaches for sending documents:

Sending XML in UBL 2.1 CIUS-PT format (or UBL 2.1 PEPPOLBIS3 - Orders)

In this method, the integrator system must correctly generate the XML file before sending it to ilink. eSPap provides the technical specification for the CIUS-PT format here.

All XML files sent using this method are validated according to the official eSPap validator, version 2.1.2, and the API will return an error if syntactic inconsistencies are found. eSPap provides a Schematron validator that implements all the validations of European Standard EN16931 CIUS and the additional validations of CIUS-PT, available online at this link. If the files validate syntactically in the online validator, then they should validate in ilink, with the exception of any additional validations defined by the document recipient.

Note: To add a PDF file to your electronic invoice and view other use cases, see the [use cases] section(usecases#criação-de-documentos-por-envio-do-cius-pt).

Note: eSPap also provides several CIUS-PT examples.

Some examples of errors in the XML validation process:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "document": {
      "code": "e217",
      "msg": "[BR-CO-25]-If the amount payable (BT-115) is positive, you must indicate the due date (BT-9) or the payment terms note(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)."
    }
  }
}

The method to be used for sending the XML is POST /apps/documentsUBL. In this context, the public key identifies the issuer of the document and must correspond to the key associated with the issuer's TIN specified in the XML (AccountingSupplierParty>Party>PartyTaxScheme>CompanyID for invoices/credit notes, or AccountingCustomerParty>Party>PartyTaxScheme>CompanyID for orders). If this does not occur, the API will return the following error:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "supplier": {
      "code": "e199",
      "msg": "The entity creating the document must be a customer or supplier of the new document."
    }
  }
}

If the XML is valid and complies with all the standard validations, as well as all additional business rules of the recipient, the API returns a successful response, along with the main data from the created document:

HTTP status: 201 Created

{
  "success": true,
  "message": {
    "code": "s011",
    "msg": "Document successfully created"
  },
  "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": "Invoice"
      },
      "type_document": {
        "alias": "issued",
        "description": "Issued"
      },
      "state_document": {
        "id": "5c9cb878745b16.4225687",
        "alias": "sent",
        "description": "Sent to customer."
      }
    }
  }
}

Note: A document is successfully sent to the recipient via EDI when the state_document.alias field has the value sent or accepted. If you only want the document to be sent by email, the document state should be ignored. Instead, you should consult the record of e-mails sent via state consultation.

Sending structured document data

When using this option, the ERP does not need to generate the entire XML file, as ilink is responsible for generating the final XML file. Thus, the ERP only needs to send all data related to the document to ilink. The endpoint to use here is POST /apps/documents

The specification for this method is extensive, as it covers all possible fields in an invoice/order, which are duly documented in the specification. All documents created by this endpoint are subject to the same validations as documents sent by the method POST /apps/documentsUBL, in other words, the XML resulting from the data entered will be validated according to the official eSPap validator, which can be consulted online at this link, and according to the additional business rules of the document recipient, if any.

Note: To add a PDF file to an electronic invoice and other common situations, see the [use cases] section(usecases#criação-de-documentos-por-envio-de-dados).

Note: It is possible to send multiple attachments in a document using the files[] field (see specification above). However, the visual representation of the document (i.e. the original PDF of the invoice used for printing) must always be sent in the file field, with the files[] field reserved for additional files (order notes, dispatch notices, transport guides, etc.). **If the document issuer has an active digital signature on ilink, all attachments will be signed by default, and transaction consumption will take into account the total size of all attachments sent (1 transaction is debited for every 1MB of attachments sent).

Sending the document

Sending via EDI

A document, after being successfully created by any of the methods described (XML sending or data sending), will be automatically sent to the recipient by EDI. However, in specific cases, it may not be sent immediately via EDI due to missing configurations and/or other anomalies in the ilink platform or the recipient's system. If this occurs, a to_send_status field will be returned in the document response to detail the situation:

HTTP status: 201 OK

{
  "success": true,
  "message": {
    "code": "s011",
    "msg": "Document successfully created"
  },
  "response": {
    "data": {
      "id":"60796c3c2a6fa2.53909016",
      "state_document": {
        "id": "5c9cb870f34b16.42025494",
        "alias": "tosend",
        "description": "To be sent to the customer."
      },
      "to_send_status": {
        "code": "sent_connection",
        "title": "Await acceptance of connection with the recipient of the document."
      }
    }
  }
}

Note: You can verify that the document was NOT delivered via EDI because the state_document.alias field assumes the value tosend and the reason for the error is described in the to_send_state field. In this situation, you must first complete the EDI connection with the recipient and then resend the document.

The possible reasons (code) for a document not being sent are:

• sent_connection, no_connection: Missing connection with recipient
• registered_entity: The recipient is not registered with ilink
• received_pay_transactions: The recipient bears the costs of the documents received but does not have sufficient transactions to send the document

After rectifying the error, you will be able to resend the document (see section on [resending documents])(issued#criareditar-documento)).

Note: The document state (state_document) only applies to EDI sendings. If the document is only sent to an arbitrary customer via e-mail (PDF), the sending state does not reflect the sending of the e-mail. See the following section for more information.

Sending via email

After a document has been successfully created (HTTP status 201) using any of the methods described (sending XML or sending data), it will be sent via email to the recipient if the send_by_email field is specified with the value 1. The address(es) of the recipient(s) of the document can be specified in three ways:

• in the additional_emails[] field (in both sending methods)
• in the customer[email] field (only in the sending data method)
• in the cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail XML element (only in the sending XML method).

To check the sending of emails and their reading by the customer, see the section on checking the state of issued documents.

Creation of documents and use of qualified digital signatures

Note: This section is only relevant for customers who use ilink to digitally sign issued documents. See details.

If a qualified digital signature is configured in ilink, all documents will be signed at the time of creation, including all files resulting from the electronic invoice (xml and pdf). Given that document signature is not required by law in all usage scenarios, it is possible to individually control the signature of xml and pdf files at the time of document creation using the disable_xml_sign and disable_pdf_sign fields, available in both document creation methods ( XML or data). This reduces the consumption of digital signatures and optimises the document creation process.

In other words:

• When sending a digital invoice via signed PDF to an end consumer or private customer, it will not be mandatory to sign the resulting XML file, so we recommend using the field disable_xml_sign: 1.
• When sending electronic invoices to the Public Administration via EDI (e.g. eSPap), it is not mandatory to sign the document; however, it is always possible to sign both files for additional security and integrity reasons. If, for example, you wish to disable the digital signature on the PDF attachment, simply use the option disable_pdf_sign: 1.
• The fields described above only take effect when the document issuer uses a qualified digital signature in ilink.

Additional validations

The invoice recipient can configure additional requirements for certain fields (business rules) in ilink, even when these are not mandatory in the CIUS-PT specification. For example, a customer may specify that he or she only accepts invoices with a PDF file attached or with a specific commitment number. It is essential that these requirements are agreed in advance with the customer/recipient before going into production, in order to avoid integration errors.

If the document recipient requires the presence of a field not specified in the XML, the API will return an error as shown below and the document will not be generated:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "commitment_number": {
      "code": "e048",
      "msg": "The commitment number is mandatory."
    }
  }
}

Please note that errors are only returned in this format when the document recipient is an ilink customer and has the appropriate business rules configured on the platform. When a document is sent to an external EDI system, any failure in the validation process is normally communicated at a later time via a state change to Rejected, with the appropriate error message. It is important to note that not all EDI systems support the sending of state messages.

Create/edit document

A document can be edited and resent to the recipient:

• if it has not yet been sent to the end customer
• or if it has already been sent to the customer and the customer has requested a correction

In practical terms, the possibility of resending can be checked using the following response field in the document:

"state_edi_document": {
  "alias": <state> // possible resend states: 'regularization' ou 'reception' ou 'error'
}

To check the state of a document, see the section on checking the state of issued documents.

To edit an existing document, simply repeat the request POST /apps/documentsUBL or POST /apps/documents with the corrected data, keeping the number, type and date of issue of the previous document:

HTTP status: 200 OK

{
  "success": true,
  "message": {
    "code": "s012",
    "msg": "Document successfully created"
  },
  "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": "Invoice"
      },
      "type_document": {
        "alias": "issued",
        "description": "Issued"
      },
      "state_document": {
        "id": "5c9cb870f34b16.42025494",
        "alias": "tosend",
        "description": "To be sent to the customer."
      }
    }
  }
}

If the document is not eligible for editing (i.e. it has already been sent or accepted by the end customer), an error will be displayed when attempting to resend it:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "number": {
      "code": "e200",
      "msg": "Document already exists."
    }
  }
}

Access to issued documents

When a document is successfully registered, an id will always be returned in the responses, which identifies it to ilink. It is useful to save this identifier for future queries to the document.

HTTP status: 201 Created

{
  "success": true,
  "message": {
    "code": "s011",
    "msg": "Document successfully created"
  },
  "response": {
    "data": {
      "id": "60796c3c2a6fa2.53909016"
    }
  }
}

The API also allows you to access all data (including generated XML and PDF) from all previously issued documents. To do so, use the GET /apps/documents/{id} method. The id received when creating the document must be used as a parameter here to access the corresponding document.

All data returned by this method is available in the specification.

Note: If the entity issuing the document has configured automatic document signature in ilink, the URLs for accessing the XML and PDF files will already return the signed files.

Consultation of documents issued on the portal (optional)

The documents can also be consulted on the ilink test portal using the credentials provided by the entities. Here you can visually validate whether the information presented is consistent with the data sent via API:

To access the attachments of a document, you must access the document in the table and click on the magnifying glass icon:

Note: The documents must be present both at the issuing entity (issued documents section) and at the receiving entity (received documents section).

Consultation of state of issued documents

It is also possible to access the current state of previously issued documents. This operation allows the issuer of the document to check whether the document has been accepted by the customer, or whether it is pending resending/regularisation, as well as the reasons that led to this.

Consultation of the state of documents sent via EDI

Ilink provides four simplified document states in the state_document property:

State	alias	Description
To be sent	tosend	the document has not been sent to the customer. This probably means that some configuration is missing in ilink, the sender/recipient does not authorise a connection between them, or that some of the entities in the document do not have sufficient transactions to proceed with the sending. If you only want the document to be sent via email, this state should be ignored.
Sent	sent	The document has been sent to the customer and is awaiting acceptance. Please note that not all recipient systems support state communication, so some documents may never leave this state.
Accepted	accepted	The document has been sent and the customer has approved it. Final state.
Rejected	rejected	The document was sent and the customer rejected it due to an inconsistency. The reason for rejection is provided in the response in the reasons field. The document can be sent again if a regularisation is requested.

Note: Ilink also returns the EDI processing state of the document (state_edi_document), which is independent of the above states. For more information, see the FE-AP Document Transmission Guide, page 7. However, reading the EDI state is not always relevant for invoicing software.

There are 3 approaches to accessing the state of a previously issued document: Individual state consultation, State change webhook, and State report.

• In Individual state consultation, simply make the call GET /apps/documents/{id}. The id received when creating the document must be used as a parameter to access the document in question. The state is returned in the state_document field (see specification). This method only allows you to check the state of one document at a time, and as such is not recommended for customers who process a high volume of documents.

• In the State change webhook, ilink takes the initiative to inform the document issuer whenever the document changes state. This is the recommended option in terms of performance and speed, but it may not be feasible if the system to be integrated belongs to a network that is not publicly exposed to ilink. For more information, see the Webhooks section.

• In State report, the integrator application takes the initiative to consult the various events that led to changes in the state of the documents issued. To do so, simply make the call GET /apps/states-report/documents. Each event identifies the document and the changed state. It is possible to filter the returned events by document id, document number, date ranges, among others (see specification). This method allows the application to check the state of several documents simultaneously.

  In order to facilitate the use of state reporting, an event read endpoint is also available POST /apps/states-report/documents/read, which allows one or more previously obtained event ids to be marked as read. Events marked as read are not returned again in the state reporting endpoint, facilitating future queries of the previous method. This option is a scalable alternative for systems that cannot implement Webhooks.

Consultation of the state of documents sent via e-mail

When sending documents by email, it is possible to consult the record of e-mails sent to the customer and their read state. Please note that the state of the returned document (state_document) is not applicable in this scenario, as these documents are not normally sent via EDI, and as such, their sending state will usually be to_send. This state should be ignored in favour of the approaches described below:

• In Individual state consultation, simply make the call GET /apps/documents/{id}. The id received when creating the document must be used as a parameter to access the document in question. In the response, you must access the emails property, which returns a list of sent messages and their reception and reading state. This method only allows you to query the state of one document at a time and has the same limitations as the individual document query in the previous section:

HTTP status: 200 OK

{
  "success": true,
  "response": {
    "data": {
      "id": "60796c3c2a6fa2.53909016",
      ...
      "emails": [
        {
          "id": "634672bab0f3b8.40302642",
          "b_open": true, // true if the e-mail has been read by the recipient
          "b_sent": true, // true if the e-mail was successfully sent
          "created_at": "2022-10-12 08:54:34", // date and time of e-mail sending
          "opened_at": "2022-10-12 09:14:16", // date and time of email reading
          "address": {
            "emails": ["joao.freitas@email.com"], // sending address
          }
        }
      ]
    }
  }
}

Note: Some email clients (Outlook, etc.) may block the reading of emails, leaving b_open as false even if the email has been opened in some situations. Ilink also has the ability to detect if an email has been returned by the e-mail server, taking responsibility for successive attempts to resend it over time.

• In Document history consultation, you can consult all procedural changes to a given document. This history will list all state changes that have occurred in the document in chronological order, as well as records of e-mails sent to the recipient, allowing for complete audit tracking. It can be accessed via GET /apps/documents/{id}/history.