Get started Integration Guide Services and Networks API Specification Tutorials Changelogs
Invoice Response

Invoice Response

What is an Invoice Response?

An Invoice Response is a message between Buyer and a Seller that enables efficient means for communicating about the status of a received Invoice in the Peppol network.

For example Buyer can inform the Seller if the Invoice has been rejected, under query, approved or paid.

More detailed use cases and specifications for invoice response can be found in Peppol documentation.

In this tutorial we dive deeper into how:

How to take invoice responses into use in Maventa?

Before starting:

For a company sending invoices

In the case where a company is sending invoices they are the Seller and therefore the receiver of Invoice Responses from the Buyer. To enable the receiving of Invoice Responses the following steps needs to be taken.

Step 1 - Enable receiving of Invoice Response documents from Peppol

Request to POST /v1/company/profiles:

{
  "profiles": [
    "INVOICE_RESPONSE"
  ],
  "profile_version": "PEPPOLBIS30",
  "network": "PEPPOL"
}

Response:

{
  "id": "3abac0e6-20c1-4172-9e0b-1f882192ca6d",
  "status": "pending",
  "profile": "INVOICE_RESPONSE",
  "profiles": [
    "INVOICE_RESPONSE"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003751734872004",
  "scheme": "0216",
  "network": "PEPPOL"
}

Step 2 - Integrate to API for receiving ordering and other documents

Step 3 - Process the received Invoice Response

Details about the content of Invoice Responses can be found from the Peppol documentation.

For a company receiving invoices

In the case where a company is receiving invoices they are the Buyer and therefore the sender of Invoice Responses to the Seller. To enable the sending of Invoice Responses the following steps needs to be taken.

Step 1 - Integrate to receive invoices. Read more about receiving invoices in the Integration guide for invoice receiving TODO:ADD_LINK.

Step 2 - Check if the Seller has capabilities to handle Invoice Response documents. This can be done doing a Peppol lookup using the GET /v1/lookup/receivers endpoint. The Sellers identifier can be found from the received invoice. For example in a PeppolBIS30 document the information is in the EndpointID element.

<cbc:ID>567</cbc:ID>
  ...
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
      ...
    </cac:Party>
  </cac:AccountingSupplierParty>

The lookup to resolve the receiving capabilities of the Seller requires three parameters.

Request (curl)Response (json) 

curl -X ‘GET’ \
  ‘https://ax-stage.maventa.com/v1/lookup/receivers?network=PEPPOL&amp;eia=0216%3A003751734872004&amp;document_type=INVOICE_RESPONSE’ \
  -H ‘accept: application/json’ \
  -H ‘authorization: Bearer TOKEN’

 

[
  {
    “eia”: “0216:003751734872004”,
    “network”: “PEPPOL”,
    “operator”: “PEPPOL”,
    “document_types”: [
      {
        “document_type”: “INVOICE_RESPONSE”,
        “document_identifier”: “urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1”,
        “process_identifier”: “urn:fdc:peppol.eu:poacc:bis:invoice_response:3”
      },
      …
    ],
    “participant”: {
      “name”: “Seller”,
      “country”: “FI”
    }
  }
]

The endpoint returns entries if the Seller enabled for processing Invoice Responses, otherwise the response will be an empty array.

Step 3 - Generate and send an Invoice Response document

Details about the business content for an Invoice Response check out the Official Peppol documentation

Example of an invoice response payload that acknowledges the receive for an Invoice with the id 567 from Seller 0216:003751734872004.

<?xml version="1.0" encoding="UTF-8"?>

<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <cbc:CustomizationID>urn:fdc:peppol.eu:poacc:trns:invoice_response:3</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:poacc:bis:invoice_response:3</cbc:ProfileID>
  <cbc:ID>1</cbc:ID>
  <cbc:IssueDate>2024-01-01</cbc:IssueDate>
  <cac:SenderParty>
    <cbc:EndpointID schemeID="0216">003751734872001</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Buyer</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:SenderParty>
  <cac:ReceiverParty>
    <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Seller</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:ReceiverParty>
  <cac:DocumentResponse>
    <cac:Response>
      <cbc:ResponseCode listID="UNCL4343OpSubset">AB</cbc:ResponseCode>
    </cac:Response>
    <cac:DocumentReference>
      <!-- Information about the orignal received invoice -->
      <cbc:ID>567</cbc:ID>
      <cbc:DocumentTypeCode listID="UNCL1001">380</cbc:DocumentTypeCode>
    </cac:DocumentReference>
  </cac:DocumentResponse>
</ApplicationResponse>

The Invoice Response payload is handed over for delivery via the POST /v1/documents endpoint.

curl -X 'POST' \
  'https://ax-stage.maventa.com/v1/documents' \
  -H 'accept: application/json' \
  -H 'content-type: multipart/form-data' \
  -F 'file=@response.xml;type=text/xml' \
  -F 'recipient_eia=0126:003751734872004' \
  -F 'recipient_operator=PEPPOL'

Response:

{
  "id": "e6c1e92b-ceba-4155-89fd-072e7ba6148f",
  "type": "INVOICE_RESPONSE"
  ...
}

References

BIS Invoice Response 3.2 specification

Back to top