Sending a document

To send a document you can choose to build a standard XML UBL 2.1 document or a JSON payload.

In both cases the endpoint is the POST method for that document type. E.g. POST /invoices/outgoing/ubl or POST /orders/outgoing/ubl.

If the platform can not manage the document, you will get a response with a body describing the error in JSON and a status code:

Copy

Copied

- `HTTP 400` if validation will fail
- `HTTP 500` in case of a general error server side.

If everything is fine and the validation passes you will receive an HTTP 202 status and the document resource as the response. E.g. Invoice response or Order response.

The document has been accepted and prepared for the dispatching through the Peppol network Within a short period of time it will be travelling towards the document recipient. Once delivered you will get notified to your configured webhook.

The validation process

The validation is performed real-time during the API HTTP request.

The applied validation rule is chosen by default using the following information extracted from your document:

document typ
customization I
profile ID

Optionally you can send the header X-Validation-Rule: {validation-rule-code} where {validation-rule-code} is one of the available validation rules You can obtain the list of available validation rules with this API

XML UBL 2.1

In this case you must send the HTTP header Content-Type: application/xml and the request body must contains the raw XML.

UBL (Universal Business Language) OASIS (ISO/IEC 19845) is an International Standard UBL defines a royalty-free library of standard electronic XML business documents such as purchase orders and invoices.

Check out the official documentation to get more information about the structure http://docs.oasis-open.org/ubl/os-UBL-2.1/UBL-2.1.html#T-INVOICE

Invoice Example:

Copy

Copied

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
    xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2
    xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    
    <cbc:ID>123</cbc:ID
    <cbc:IssueDate>2011-09-22</cbc:IssueDate>

    <cac:InvoicePeriod
      <cbc:StartDate>2011-08-01</cbc:StartDate
      <cbc:EndDate>2011-08-31</cbc:EndDate
    </cac:InvoicePeriod>

    <cac:AccountingSupplierParty
      <cac:Party
        <cac:PartyName
          <cbc:Name>Custom Cotter Pins</cbc:Name
        </cac:PartyName
      </cac:Party
    </cac:AccountingSupplierParty
    <cac:AccountingCustomerParty
      <cac:Party
        <cac:PartyName
          <cbc:Name>North American Veeblefetzer</cbc:Name
        </cac:PartyName
      </cac:Party
    </cac:AccountingCustomerParty>

    <cac:LegalMonetaryTotal
       <cbc:PayableAmount currencyID="CAD">100.00</cbc:PayableAmount
    </cac:LegalMonetaryTotal>

    <cac:InvoiceLine
      <cbc:ID>1</cbc:ID
      <cbc:LineExtensionAmount currencyID="CAD">100.00</cbc:LineExtensionAmount
      <cac:Item
         <cbc:Description>Cotter pin, MIL-SPEC</cbc:Description
      </cac:Item
    </cac:InvoiceLine>

</Invoice>

JSON UBL 2.1

In case you do not want to manage the XML format, you can define documents in JSON. In this case you must send the HTTP header Content-Type: application/json The structure and the naming is the same of the official XML, except for the case of XML attributes which is a concept that is not applicable to JSON documents We chosen to manage XML attributes within object structures in JSON, so to specify the node value we chosen to use a naming convention, the key is __value.

So if you have this tag with attribute in XML

Copy

Copied

<cbc:PayableAmount currencyID="CAD">100.00</cbc:PayableAmount>

The JSON translation is

Copy

Copied

"PayableAmount": {
    "__value": 100.0,
    "currencyID": "CAD"
    }

Invoice example:

Copy

Copied

{
    "ID": {
      "__value": "123"
    },
    "IssueDate": "2011-09-22",
    "InvoicePeriod": [
        {
          "StartDate": "2011-08-01",
          "EndDate": "2011-08-31"
        }
    ],
    "AccountingSupplierParty": {
        "Party": {
            "PartyName": [
                {
                    "Name": {
                        "__value": "Custom Cotter Pins"
                    }
                }
            ]
        }
    },
    "AccountingCustomerParty": {
        "Party": {
            "PartyName": [
                {
                    "Name": {
                        "__value": "North American Veeblefetzer"
                    }
                }
            ]
        }
    },
    "LegalMonetaryTotal": {
        "PayableAmount": {
          "__value": 100.0,
          "currencyID": "CAD"
        }
    },
    "InvoiceLine": [
        {
            "ID": {
              "__value": "1"
            },
            "LineExtensionAmount": {
              "__value": 100.0,
              "currencyID": "CAD"
            },
            "Item": {
                "Description": [
                    {
                      "__value": "Cotter pin, MIL-SPEC"
                    }
                ]
            }
        }
    ]
}