Skip to main content
2024 and later
Search
Search Indirect Tax Support Help and Support.

This article applies to:

  • Product: ONESOURCE E-Invoicing

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
Tabular form of different AR files
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
Tabular form of different AP files
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-files
     with 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 to
    received
     for 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 to
    sent
     for AR documents and
    received
     for AP documents.
  • Document type
    : Use the
    Invoice
     type 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.