Content
The solution supports multiple integration options, but it is important to integrate following the below guidance to make sure your integration is behaving correctly and you would be able to get the most benefits of the solution.
There are two integration approaches that can be implemented; callback approach and results polling approach the following sections presents these approaches.
Callback Approach
In this integration approach your ERP/POS system should submit the required documents using one of the submission APIs published and then it should register a callback method to receive the notification of completion for processing of the submitted documents.
Note!
Please note the following key points in the above flow diagram:
• ERP callback should have been registered before the submission occurs. This should have also implemented the server APIs at the ERP side to accept and process the requests on the following endpoints (PUT /notifications/documents, and PUT /notifications/receipts), as described Here
and Here
• Login is performed and access tokens should be cached for the lifetime of the token (this is default to be valid for 60 minutes).
• If login fails, then issue should be investigated and resolved.
• Once documents (invoice documents, or receipts documents) are submitted, then the system should wait asynchronously for callback to be received once processing has been completed.
• Once callback is received then the documents are updated in your internal system.
Polling Approach
Although this is not the recommended approach as it would increase the load on the internal ERP/POS systems and hence it is recommended to follow the callback approach described above.
This is a second priority approach if the first approach had challenges in being implemented.
In this integration approach, the ERP/POS system would submit documents using one of the submission APIs and then continue to check the status of these submitted documents using one of the submission APIs and the reference of the submission that was generated from the system.
Note!
Please note the following key points in the above flow diagram:
• Login is performed and access tokens should be cached for the lifetime of the token (this is default to be valid for 60 minutes).
• If login fails, then issue should be investigated and resolved.
• Once documents (invoice documents, or receipts documents) are submitted, then the ERP/POS system should wait for a period of time depending on the size of your submission before checking with the e-invoicing system if the submission has been completed or not.
All submission APIs listed above returns a submission ID to be used to check the status of the submission as per below.
• Submit documents
• Submit receipt documents
• Checking for the submission status using the returned submission UUID can be performed by one of the following APIs:
Get Submission
Get Receipt Submission
• Once the submission has been completely processed then the documents are updated in your internal ERP/POS system accordingly.
Common Integration Anti-patterns
The following are key practices that should be avoided when implementing the integration with the e-invoicing system as these practices might impact the integrity of the data received and would increase the load over your ERP/POS system.
Also, following some of these patterns might be blocked by the e-invoicing system and hence would impact your systems ability to receive updates on the processing of your documents.
-
Acquiring a new authentication token with every API call to the system.
Received authentication tokens remain valid for a duration that is already specified in the response of the authentication API as per below.
By default, these token are valid for 60 minutes and hence can be used by any system APIs that requires such a token while the token is still valid.
-
Getting the status of the submission by checking the status of each document submitted within the submission by any of the APIs “Get Recent Documents”, “Search Documents”, “Get Document”, “Get Document Details”, “Get Receipt Details”, “Get Receipt”, “Get Receipt Details Anonymously”, “Search Receipts”, or “Get Recent Receipts”. These APIs are designed to be used for documents retrieval after submission and validation and not during the submission operation as per the above workflows.
-
Re-submitting the same submission over and over again without regards to the results received from the submission APIs.
The submission APIs returns results of initial processing of the submission and hence these should be used and checked before the submission is sent again.
In fact, resending the same submission should not be performed in all cases except in case of error received from the submission APIs.
Otherwise, any of the 20x response statuses should be accepted by your system and in this case the submission shouldn’t be resubmitted again as it will be automatically flagged as duplicate submission and in these cases the submission APIs might start to throttling calls being received from your ERP/POS system.
-
The API “Get Document Printout” is not designed for mass PDF generation, but it is used for specific business scenarios.
Mass PDF generation will be throttled and hence your system will start to receive errors due to these practices.
-
The calls to “Get Recent Documents” should be in most cases be fulfilled by the more optimized API “Search Documents”.
Calling the API “Get Recent Documents” is subject to being throttled as well.
-
The calls to “Get Recent Receipts” should be in most cases be fulfilled by the more optimized API “Search Receipts”.
Calling the API “Get Recent Receipts” is subject to being throttled as well.
-
Calling of the authentication API on the path “/connect/token” without supplying the required parameters such as the “client_id”, “grant_type”, or “client_secret”; would not add any value to your system as these calls will be automatically blocked by the system.
These include cases such as sending the “client_id” with wrong (‘0’ or ‘YOUR_CLIENT_ID’) or empty values.