Receiving documents

Scope

This feature allows automatic entry of invoicing documents into the recipient's ERP, simplifying integration into accounting systems. It also allows the issuer to be notified of the document's acceptance and integration state (paid, accepted, rejected, etc.).

In this integration workflow, the following points must be implemented:

• Data reading and processing: Extract information from XML or other structured data in the document to record it correctly in the ERP
• Integration state communication: Inform ilink of the outcome of the document integration process
• Acceptance state management: Communicate the acceptance status of the document, including detailed messages in case of error or rejection

Receiving methods

Allows you to view and integrate documents into the system. Receiving can be made in two ways: Manual document viewing or Incoming webhook.

Manual document consultation

In this mode, you must access the endpoint GET /apps/documents. You can specify search parameters to filter the results. The response includes the main data from the documents and pagination information through the properties rows (number of elements per page) and page (page number).

To view the details of a document and access the XML and PDF files, use the GET /apps/documents/{id} method, using one of the ids obtained in the previous list.

The endpoint can be called periodically (background process) or by user action in the system (in real time).

Note: The public key used here corresponds to the entity receiving the documents. The key that identifies who accesses the received documents must be used.

Important: Excessive use of this endpoint should be avoided. Too many calls may result in timeouts or access restrictions, in accordance with the interoperability agreement.

Incoming webhook (recommended)

Neste modo, o ilink notifica o ERP sempre que chega um novo documento, dispensando consultas frequentes ao endpoint GET /apps/documents. Para mais informação, ver a secção Webhooks.

Note: Document data is sent in a structured format, including public URLs for accessing the XML and PDF files.

Import and acceptance

After retrieving the document, the ERP must inform iLink of the processing status, i.e. whether it was successfully integrated or requires corrections. Two steps are required:

• 1. Communicate the document state

  • Done via POST /apps/documents/{id}/accepted, indicating whether the document was accepted or not and, in case of rejection, the reason
  • A rejection reason must be provided if the document is not accepted
  • A rejected document may be resent by the issuer with corrected data

• 2. Communicate the document import (only if accepted)

  • If the previous step indicated acceptance, the method POST /apps/documents/{id} must be called

Note: Rejected documents must not be imported.

Correct communication of accepted/imported documents ensures an audit trail and facilitates API consumption. If manual consultation is being used, documents already rejected or imported will not be returned in future calls. In other words, the endpoint GET /apps/documents does not return documents that have previously been rejected or imported.

The image below shows how the operations performed by the ERP are recorded in the iLink portal:

Proper use of document import also generates queryable information for the document issuer, confirming its integration with the recipient’s system.

Process States (optional)

Note: Optional feature for information purposes only. It does not affect document reception.

ilink allows the creation of custom document states. When enabled, it is possible to consult and modify a document’s state via API. This capability allows external systems (e.g. document management) to update the process state in an integrated way, and is useful for synchronising internal organisational processes across systems. All process state changes are recorded in the document’s history.

Important: The process state is independent of the base state (received, accepted, etc.). It serves only for internal organisation and operational logging.

To view the available states, use GET /apps/processstates, which returns the complete list with the corresponding identification_code. To change a document’s state, use PUT /apps/documents/{id}/processstates, specifying the new identification_code.

Configuration of the process states to be used is carried out by the ilink support team.