Skip to main content

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​

This integration allows you to view and integrate documents into the system. Receiving can be done in two ways: Manual document consultation 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.

In this mode, ilink notifies the ERP whenever a new document arrives, eliminating the need for frequent polling of the GET /apps/documents endpoint. For more information, see the Webhooks section.

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 actions are required:

  • Communicate the document import

    • The document import confirms that the document was effectively received in the client's system, using the method POST /apps/documents/{id}

  • Communicate the document state

    • Via POST /apps/documents/{id}/accepted, indicate 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

Note: Although the order of the above actions is flexible, 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:

img info

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 this feature is 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.