R1.4.0.1 October 11, 2024 release notes
ONESOURCE E-Invoicing API updates
Hotfix updates for OEI APIs
We’ve marked the
Due Date
and Postal Zone
fields as optional in ONESOURCE E-Invoicing APIs for accounts receivable (AR) and accounts payable (AP) transactions. New document file APIs for AR and AP transactions (version 1.4.0.1)
The new document file APIs offer an efficient solution for accessing and storing digital copies of 9 AR and 6 AP documents per transaction. These APIs enable you to download and manage key transactional documents within your systems, enhancing compliance, accessibility, and long-term record-keeping capabilities.
API features
- Document access for AR and AP- Multiple document files, including invoices, clearance documents, business responses, and source/target files, are now accessible through these APIs.
- Compliance support- The APIs facilitate access to transactional records such as clearance responses, supporting various country-specific tax regulations.
- Seamless integration- Designed for efficient integration with client systems for streamlined document storage and management.
Accounts receivable document APIs
- Invoice PDF: Retrieve the PDF of the invoice shared with the buyer.
- API: /document-files/{id}/presentation
- Invoice source: Access the original invoice received by Pagero from OEI (PUF XML).
- API: /document-files/{id}/source
- Invoice target: Download the invoice as sent to the buyer (XML or PDF).
- API: /document-files/{id}/target
- Clearance PDF: Get the PDF version of the clearance response from tax authorities.
- API: /document-files/{id}/presentation
- Clearance source: Retrieve the source file received from the tax authority.
- API: /document-files/{id}/source
- Clearance target: Download the clearance document issued by Pagero to OEI.
- API: /document-files/{id}/target
- Business PDF: Access the PDF version of the business response.
- API: /document-files/{id}/presentation
- Business source: Retrieve the source file received from the buyer.
- API: /document-files/{id}/source
- Business target: Download the business response issued by Pagero to OEI.
- API: /document-files/{id}/target
AR | Notes | API |
|---|---|---|
Invoice PDF | PDF of the invoice shared with the buyer | /document-files/{id}/presentation |
Invoice source | Pagero receives from OEI (PUF XML) | /document-files/{id}/source |
Invoice target | Pagero sends to buyer (XML or PDF) | /document-files/{id}/target |
Clearance PDF | PDF version of clearance response | /document-files/{id}/presentation |
Clearance source | Pagero receives from Tax Authority | /document-files/{id}/source |
Clearance taget | Pagero issues to OEI after receiving clearance | /document-files/{id}/target |
Business PDF | PDF version of business response | /document-files/{id}/presentation |
Business source | Pagero receives from buyer | /document-files/{id}/source |
Business target | Pagero issues to OEI after receiving from buyer | /document-files/{id}/target |
Accounts payable document APIs
- Invoice PDF (with Clearance ID): Download the PDF version of the target invoice, including the Clearance ID for supported countries.
- API: /document-files/{id}/presentation
- Source XML: Access the source XML received by Pagero from the seller or tax authority.
- API: /document-files/{id}/source
- Target XML: Retrieve the XML sent to OEI (PEPPOL XML), including local formats (Italy only).
- API: /document-files/{id}/target
- Business PDF: Get the PDF version of the business response.
- API: /document-files/{id}/presentation
- Business source: Access the business response sent from OEI to Pagero.
- API: /document-files/{id}/source
- Business target: Download the business response shared with the supplier.
- API: /document-files/{id}/target
AP | Notes | API |
|---|---|---|
Invoice PDF including Clearance ID | PDF version of Target XML (Clearance ID available only for supported countries) | /document-files/{id}/presentation |
Source XML | Pagero receives from seller/Tax Authority | /document-files/{id}/source |
Target XML | Pagero sends PEPPOL XML to OEI. This will also include the local format as attachment (Italy only) | /document-files/{id}/target |
Business PDF | PDF version of business response | /document-files/{id}/presentation |
Business source | Business response sent from OEI to Pagero | /document-files/{id}/source |
Business target | Business response shared with the supplier | /document-files/{id}/target |
Retrieve document IDs
To fetch a document, you'll need a unique document ID. Use the
GET /document-files
API to retrieve a list of available document IDs for a company.
- AR documents: The API/document-fileswith relevant parameters retrieves invoices, credit notes, debit notes, and prepayment invoices sent by the supplier, along with associated application responses.
- AP documents: Like AR, but you must set the the direction parameter toreceivedfor AP documents. Clearance responses don't support AP.
note
- Company ID: Obtain the Company ID by logging into the OEI UI. Access the Company ID from the UI since no API is available to retrieve a list of Company IDs.
- Direction: Set the direction parameter tosentfor AR documents andreceivedfor AP documents.
- Document type: Use theInvoicetype to retrieve AR documents such as invoices, debit notes, credit notes, or prepayment invoices. When you pull AR documents, they’ll include invoices, credit notes, debit notes, and prepayment invoices sent by the supplier, along with their associated application responses. Each one represents a separate document.
Country-specific variations
- Italy: For Italian invoices, you may retrieve multiple clearance responses. Documents remain accessible even if a clearance ends in error or rejection.
- Malaysia, Romania, and Centralized Clearance Countries: Documents won’t be available for download if the transaction ends in a clearance rejected state, except for clearance-related documents.
Country-specific use cases
- Italy:
- The document handling process through the API differs slightly due to the country’s tax compliance requirements.
- Customers may receive multiple clearance responses for a single transaction. The document file APIs provide access to each of these clearance responses.
- For a single AR document (such as an invoice), you can retrieve and access multiple clearance responses through the API, ensuring compliance with Italian tax laws.
- For example, if an invoice goes through multiple stages of clearance with the Italian tax authorities, you can download each response (whether approval, rejection, or further action) using the API endpoint.
- Malaysia, Romania, and other centralized clearance countries:
- In countries like Malaysia and Romania, or any country operating under a centralized clearance model, certain conditions may prevent documents from being available for download.
- If the clearance process rejects a document, such as an AR invoice, or it ends up in an error state, you won't be able to download some associated documents, like the invoice PDF, source, and target files.
- In such cases, only clearance-related documents will remain accessible. This includes:
- Clearance PDF: The PDF version of the clearance response from the tax authority (API: /document-files/{id}/presentation).
- Clearance source: The source document Pagero received from the tax authority (API: /document-files/{id}/source).
- Clearance target: The target document Pagero issued to OEI after receiving the clearance response (API: /document-files/{id}/target).
- For example, if an issue occurs and Romania rejects an AR invoice sent for clearance, you won't be able to download the following documents:
- Invoice PDF: The buyer receives the PDF version of the invoice.
- Invoice Source: The source file received from OEI (PUF XML).
- Invoice Target: The target file sent to the buyer (XML or PDF).
In these cases, only clearance-related documents will be available, providing a record of the clearance attempt and the subsequent rejection or error.
New API parameter: isFetched
We've introduced a new parameter called
isFetched
to optimize document retrieval.
- True: Returns documents that the client has already fetched.
- False (default): Returns documents that the client hasn’t yet fetched.
Once the system fetches a document using its ID, it marks the document as
fetched = true
, reducing the document list for future API calls. These APIs offer a flexible and efficient solution for document management, supporting compliance requirements and improving document handling. For additional details, refer to the API documentation or contact the support team.