Pending Received Documents Management
Our APIs make it possible to manage the Pending Received Documents, which you usually can see in the Acquisti -> Da registrare page of Fatture in Cloud. Here we will explain the available API methods and how to use them to manage the documents.
💡 A little context
The Received Documents can be seen in Fatture in Cloud under the Acquisti (Purchases) section. Here you have two different pages:
- The Spese (expenses) page contains the already registered documents.
- The Da registrare (to be registered) page contains the list of the documents received automatically into Fatture in Cloud, and that must be registered to be moved from this section to the Spese one.
While the Spese section permits to manually insert documents, and can be entirely managed by the standard Received Documents APIs (you can perform the usual List, Get, Create, Modify and Delete operations), the Da Registrare section will contain a special kind of documents received automatically by Fatture in Cloud; these Pending Received Documents require a special set of API methods that can be used to manage them appropriately.
On Fatture in Cloud, it is possible to register the Pending Received Documents in two ways:
- Automatically, in this case, Fatture in Cloud will try to register each electronic document automatically when possible, as soon as it is received.
- Manually from the Da Registrare section if the Automatic Registration is disabled or if it fails for a certain document.
⚡ Webhooks
Our Webhooks make it possible to be notified immediately when something happens; this is also true for the Received Documents. The Automatic Registration affects the notification type that will be triggered when a new document is received, so it is necessary to explain the different cases.
On the Notification Types page, you can find two different Notification Types:
| Notification Type | Triggers |
|---|---|
| it.fattureincloud.webhooks.received_documents.create | When a new Received Document is created, including the documents registered automatically |
| it.fattureincloud.webhooks.received_documents.e_invoices.receive | When a new Pending Received Document is inserted, e.g., the automatic registration is disabled, or an automatic registration fails |
As you can see, when the Automatic Registration is disabled, all the documents received by Fatture in Cloud will be automatically inserted in the Da Registrare section, thus the it.fattureincloud.webhooks.received_documents.e_invoices.receive notification will always be triggered.
If, instead, the Automatic Registration is enabled, the notification type will depend on the outcome of the registration:
- Registration failed: it.fattureincloud.webhooks.received_documents.e_invoices.receive
- Registration succesful: it.fattureincloud.webhooks.received_documents.create
When you receive a notification, you will need to use its type to select the proper API Method to retrieve the related information:
| Notification Type | API Method |
|---|---|
| it.fattureincloud.webhooks.received_documents.create | Get Received Document |
| it.fattureincloud.webhooks.received_documents.e_invoices.receive | Get Pending Received Document |
You can find more info about the API methods dedicated to the Pending Received Documents in the next sections.
🐝 Pending Received Documents API methods
We provide two different API methods to interact with the Pending Received Documents.
The first one is the Get Pending Received Document, which can be used in combination with the Webhooks to retrieve the details of the Pending Document. The method requires knowing the ID of the document, which is contained in the notification body or can be retrieved by other means.
If you don't know the ID of the documents to retrieve, or you want to check if there are any documents to be registered, you can also use the List Pending Issued Documents to get the list of all the Pending Received Documents with the related IDs.
We strongly suggest you avoid using the List method to synchronize your integration using Polling. This approach will rapidly consume your API quotas. Use the webhooks if possible.
Both the API methods provide the usual functionalities typical of the other Get and List methods, such as Filters, Pagination, Sorting, and Response Customization.
❓ And the registrations?
Once a new Document is received, you will be able to use Fatture in Cloud's functionalities to register the documents.
The main possibility is to activate the Automatic Registration, which will trigger registration as soon as a new electronic document is received.
As an alternative, you can also decide not to activate the automatic registration and register each document manually.
You can find more details on our Customer Support page.
It is not possible to register the documents using APIs. The API methods we provided give you the possibility to be notified of the documents received by Fatture in Cloud, but you will be required to use Fatture in Cloud's functionalities to register the Pending Documents as explained above.