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:
- `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 type
- customization ID
- 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:
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:ID>Snippet1</cbc:ID>
<cbc:IssueDate>2017-11-13</cbc:IssueDate>
<cbc:DueDate>2017-12-01</cbc:DueDate>
<cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
<cbc:AccountingCost>4025:123:4343</cbc:AccountingCost>
<cbc:BuyerReference>0150abc</cbc:BuyerReference>
<cac:AccountingSupplierParty>
<cac:Party>
<cbc:EndpointID schemeID="0211">IT01754930384</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID>IT01754930384</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>SupplierTradingName Ltd.</cbc:Name>
</cac:PartyName>
<cac:PostalAddress>
<cbc:StreetName>Main street 1</cbc:StreetName>
<cbc:AdditionalStreetName>Postbox 123</cbc:AdditionalStreetName>
<cbc:CityName>London</cbc:CityName>
<cbc:PostalZone>GB 123 EW</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>GB</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cbc:CompanyID>GB1232434</cbc:CompanyID>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>SupplierOfficialName Ltd</cbc:RegistrationName>
<cbc:CompanyID>GB983294</cbc:CompanyID>
</cac:PartyLegalEntity>
</cac:Party>
</cac:AccountingSupplierParty>
<cac:AccountingCustomerParty>
<cac:Party>
<cbc:EndpointID schemeID="0002">FR23342</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="0002">FR23342</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>BuyerTradingName AS</cbc:Name>
</cac:PartyName>
<cac:PostalAddress>
<cbc:StreetName>Hovedgatan 32</cbc:StreetName>
<cbc:AdditionalStreetName>Po box 878</cbc:AdditionalStreetName>
<cbc:CityName>Stockholm</cbc:CityName>
<cbc:PostalZone>456 34</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>SE</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cbc:CompanyID>SE4598375937</cbc:CompanyID>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Buyer Official Name</cbc:RegistrationName>
<cbc:CompanyID schemeID="0183">39937423947</cbc:CompanyID>
</cac:PartyLegalEntity>
<cac:Contact>
<cbc:Name>Lisa Johnson</cbc:Name>
<cbc:Telephone>23434234</cbc:Telephone>
<cbc:ElectronicMail>lj@buyer.se</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
</cac:AccountingCustomerParty>
<cac:Delivery>
<cbc:ActualDeliveryDate>2017-11-01</cbc:ActualDeliveryDate>
<cac:DeliveryLocation>
<cbc:ID schemeID="0088">9483759475923478</cbc:ID>
<cac:Address>
<cbc:StreetName>Delivery street 2</cbc:StreetName>
<cbc:AdditionalStreetName>Building 56</cbc:AdditionalStreetName>
<cbc:CityName>Stockholm</cbc:CityName>
<cbc:PostalZone>21234</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>SE</cbc:IdentificationCode>
</cac:Country>
</cac:Address>
</cac:DeliveryLocation>
<cac:DeliveryParty>
<cac:PartyName>
<cbc:Name>Delivery party Name</cbc:Name>
</cac:PartyName>
</cac:DeliveryParty>
</cac:Delivery>
<cac:PaymentMeans>
<cbc:PaymentMeansCode name="Credit transfer">30</cbc:PaymentMeansCode>
<cbc:PaymentID>Snippet1</cbc:PaymentID>
<cac:PayeeFinancialAccount>
<cbc:ID>IBAN32423940</cbc:ID>
<cbc:Name>AccountName</cbc:Name>
<cac:FinancialInstitutionBranch>
<cbc:ID>BIC324098</cbc:ID>
</cac:FinancialInstitutionBranch>
</cac:PayeeFinancialAccount>
</cac:PaymentMeans>
<cac:PaymentTerms>
<cbc:Note>Payment within 10 days, 2% discount</cbc:Note>
</cac:PaymentTerms>
<cac:AllowanceCharge>
<cbc:ChargeIndicator>true</cbc:ChargeIndicator>
<cbc:AllowanceChargeReason>Insurance</cbc:AllowanceChargeReason>
<cbc:Amount currencyID="EUR">25</cbc:Amount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:AllowanceCharge>
<cac:TaxTotal>
<cbc:TaxAmount currencyID="EUR">331.25</cbc:TaxAmount>
<cac:TaxSubtotal>
<cbc:TaxableAmount currencyID="EUR">1325</cbc:TaxableAmount>
<cbc:TaxAmount currencyID="EUR">331.25</cbc:TaxAmount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:TaxSubtotal>
</cac:TaxTotal>
<cac:LegalMonetaryTotal>
<cbc:LineExtensionAmount currencyID="EUR">1300</cbc:LineExtensionAmount>
<cbc:TaxExclusiveAmount currencyID="EUR">1325</cbc:TaxExclusiveAmount>
<cbc:TaxInclusiveAmount currencyID="EUR">1656.25</cbc:TaxInclusiveAmount>
<cbc:ChargeTotalAmount currencyID="EUR">25</cbc:ChargeTotalAmount>
<cbc:PayableAmount currencyID="EUR">1656.25</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
<cac:InvoiceLine>
<cbc:ID>1</cbc:ID>
<cbc:InvoicedQuantity unitCode="DAY">7</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount currencyID= "EUR">2800</cbc:LineExtensionAmount>
<cbc:AccountingCost>Konteringsstreng</cbc:AccountingCost>
<cac:OrderLineReference>
<cbc:LineID>123</cbc:LineID>
</cac:OrderLineReference>
<cac:Item>
<cbc:Description>Description of item</cbc:Description>
<cbc:Name>item name</cbc:Name>
<cac:StandardItemIdentification>
<cbc:ID schemeID="0088">21382183120983</cbc:ID>
</cac:StandardItemIdentification>
<cac:OriginCountry>
<cbc:IdentificationCode>NO</cbc:IdentificationCode>
</cac:OriginCountry>
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="SRV">09348023</cbc:ItemClassificationCode>
</cac:CommodityClassification>
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>
</cac:Item>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">400</cbc:PriceAmount>
</cac:Price>
</cac:InvoiceLine>
<cac:InvoiceLine>
<cbc:ID>2</cbc:ID>
<cbc:InvoicedQuantity unitCode="DAY">-3</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount currencyID="EUR">-1500</cbc:LineExtensionAmount>
<cac:OrderLineReference>
<cbc:LineID>123</cbc:LineID>
</cac:OrderLineReference>
<cac:Item>
<cbc:Description>Description 2</cbc:Description>
<cbc:Name>item name 2</cbc:Name>
<cac:StandardItemIdentification>
<cbc:ID schemeID="0088">21382183120983</cbc:ID>
</cac:StandardItemIdentification>
<cac:OriginCountry>
<cbc:IdentificationCode>NO</cbc:IdentificationCode>
</cac:OriginCountry>
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="SRV">09348023</cbc:ItemClassificationCode>
</cac:CommodityClassification>
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>
</cac:Item>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">500</cbc:PriceAmount>
</cac:Price>
</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
<cbc:PayableAmount currencyID="CAD">100.00</cbc:PayableAmount>The JSON translation is
"PayableAmount": {
"__value": 100.0,
"currencyID": "CAD"
}Invoice example:
{
"UBLExtensions": [],
"CustomizationID": {
"__value": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0"
},
"ProfileID": {
"__value": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
},
"ID": {
"__value": "Snippet1"
},
"IssueDate": "2017-11-13",
"DueDate": "2017-12-01",
"InvoiceTypeCode": {
"__value": "380"
},
"Note": [],
"DocumentCurrencyCode": {
"__value": "EUR"
},
"AccountingCost": {
"__value": "4025:123:4343"
},
"BuyerReference": {
"__value": "0150abc"
},
"InvoicePeriod": [],
"BillingReference": [],
"DespatchDocumentReference": [],
"ReceiptDocumentReference": [],
"StatementDocumentReference": [],
"OriginatorDocumentReference": [],
"ContractDocumentReference": [],
"AdditionalDocumentReference": [],
"ProjectReference": [],
"Signature": [],
"AccountingSupplierParty": {
"AdditionalAccountID": [],
"Party": {
"EndpointID": {
"__value": "IT01754930384",
"schemeID": "0211"
},
"PartyIdentification": [
{
"ID": {
"__value": "IT01754930384"
}
}
],
"PartyName": [
{
"Name": {
"__value": "SupplierTradingName Ltd."
}
}
],
"PostalAddress": {
"StreetName": {
"__value": "Main street 1"
},
"AdditionalStreetName": {
"__value": "Postbox 123"
},
"CityName": {
"__value": "London"
},
"PostalZone": {
"__value": "GB 123 EW"
},
"AddressLine": [],
"Country": {
"IdentificationCode": {
"__value": "GB"
}
},
"LocationCoordinate": []
},
"PartyTaxScheme": [
{
"CompanyID": {
"__value": "GB1232434"
},
"ExemptionReason": [],
"TaxScheme": {
"ID": {
"__value": "VAT"
},
"JurisdictionRegionAddress": []
}
}
],
"PartyLegalEntity": [
{
"RegistrationName": {
"__value": "SupplierOfficialName Ltd"
},
"CompanyID": {
"__value": "GB983294"
},
"ShareholderParty": []
}
],
"Person": [],
"ServiceProviderParty": [],
"PowerOfAttorney": []
}
},
"AccountingCustomerParty": {
"AdditionalAccountID": [],
"Party": {
"EndpointID": {
"__value": "FR23342",
"schemeID": "0002"
},
"PartyIdentification": [
{
"ID": {
"__value": "FR23342",
"schemeID": "0002"
}
}
],
"PartyName": [
{
"Name": {
"__value": "BuyerTradingName AS"
}
}
],
"PostalAddress": {
"StreetName": {
"__value": "Hovedgatan 32"
},
"AdditionalStreetName": {
"__value": "Po box 878"
},
"CityName": {
"__value": "Stockholm"
},
"PostalZone": {
"__value": "456 34"
},
"AddressLine": [],
"Country": {
"IdentificationCode": {
"__value": "SE"
}
},
"LocationCoordinate": []
},
"PartyTaxScheme": [
{
"CompanyID": {
"__value": "SE4598375937"
},
"ExemptionReason": [],
"TaxScheme": {
"ID": {
"__value": "VAT"
},
"JurisdictionRegionAddress": []
}
}
],
"PartyLegalEntity": [
{
"RegistrationName": {
"__value": "Buyer Official Name"
},
"CompanyID": {
"__value": "39937423947",
"schemeID": "0183"
},
"ShareholderParty": []
}
],
"Contact": {
"Name": {
"__value": "Lisa Johnson"
},
"Telephone": {
"__value": "23434234"
},
"ElectronicMail": {
"__value": "lj@buyer.se"
},
"Note": [],
"OtherCommunication": []
},
"Person": [],
"ServiceProviderParty": [],
"PowerOfAttorney": []
}
},
"Delivery": [
{
"ActualDeliveryDate": "2017-11-01",
"DeliveryLocation": {
"ID": {
"__value": "9483759475923478",
"schemeID": "0088"
},
"Description": [],
"Conditions": [],
"ValidityPeriod": [],
"Address": {
"StreetName": {
"__value": "Delivery street 2"
},
"AdditionalStreetName": {
"__value": "Building 56"
},
"CityName": {
"__value": "Stockholm"
},
"PostalZone": {
"__value": "21234"
},
"AddressLine": [],
"Country": {
"IdentificationCode": {
"__value": "SE"
}
},
"LocationCoordinate": []
},
"SubsidiaryLocation": [],
"LocationCoordinate": []
},
"DeliveryParty": {
"PartyIdentification": [],
"PartyName": [
{
"Name": {
"__value": "Delivery party Name"
}
}
],
"PartyTaxScheme": [],
"PartyLegalEntity": [],
"Person": [],
"ServiceProviderParty": [],
"PowerOfAttorney": []
},
"NotifyParty": [],
"DeliveryTerms": []
}
],
"PaymentMeans": [
{
"PaymentMeansCode": {
"__value": "30",
"name": "Credit transfer"
},
"InstructionNote": [],
"PaymentID": [
{
"__value": "Snippet1"
}
],
"PayeeFinancialAccount": {
"ID": {
"__value": "IBAN32423940"
},
"Name": {
"__value": "AccountName"
},
"PaymentNote": [],
"FinancialInstitutionBranch": {
"ID": {
"__value": "BIC324098"
}
}
}
}
],
"PaymentTerms": [
{
"PaymentMeansID": [],
"Note": [
{
"__value": "Payment within 10 days, 2% discount"
}
]
}
],
"PrepaidPayment": [],
"AllowanceCharge": [
{
"ChargeIndicator": true,
"AllowanceChargeReason": [
{
"__value": "Insurance"
}
],
"Amount": {
"__value": 25.0,
"currencyID": "EUR"
},
"TaxCategory": [
{
"ID": {
"__value": "S"
},
"Percent": {
"__value": 25.0
},
"TaxExemptionReason": [],
"TaxScheme": {
"ID": {
"__value": "VAT"
},
"JurisdictionRegionAddress": []
}
}
],
"PaymentMeans": []
}
],
"TaxTotal": [
{
"TaxAmount": {
"__value": 331.25,
"currencyID": "EUR"
},
"TaxSubtotal": [
{
"TaxableAmount": {
"__value": 1325.0,
"currencyID": "EUR"
},
"TaxAmount": {
"__value": 331.25,
"currencyID": "EUR"
},
"TaxCategory": {
"ID": {
"__value": "S"
},
"Percent": {
"__value": 25.0
},
"TaxExemptionReason": [],
"TaxScheme": {
"ID": {
"__value": "VAT"
},
"JurisdictionRegionAddress": []
}
}
}
]
}
],
"WithholdingTaxTotal": [],
"LegalMonetaryTotal": {
"LineExtensionAmount": {
"__value": 1300.0,
"currencyID": "EUR"
},
"TaxExclusiveAmount": {
"__value": 1325.0,
"currencyID": "EUR"
},
"TaxInclusiveAmount": {
"__value": 1656.25,
"currencyID": "EUR"
},
"ChargeTotalAmount": {
"__value": 25.0,
"currencyID": "EUR"
},
"PayableAmount": {
"__value": 1656.25,
"currencyID": "EUR"
}
},
"InvoiceLine": [
{
"ID": {
"__value": "1"
},
"Note": [],
"InvoicedQuantity": {
"__value": 7.0,
"unitCode": "DAY"
},
"LineExtensionAmount": {
"__value": 2800.0,
"currencyID": "EUR"
},
"AccountingCost": {
"__value": "Konteringsstreng"
},
"InvoicePeriod": [],
"OrderLineReference": [
{
"LineID": {
"__value": "123"
}
}
],
"DespatchLineReference": [],
"ReceiptLineReference": [],
"BillingReference": [],
"DocumentReference": [],
"Delivery": [],
"PaymentTerms": [],
"AllowanceCharge": [],
"TaxTotal": [],
"WithholdingTaxTotal": [],
"Item": {
"Description": [
{
"__value": "Description of item"
}
],
"Name": {
"__value": "item name"
},
"AdditionalInformation": [],
"Keyword": [],
"BrandName": [],
"ModelName": [],
"ManufacturersItemIdentification": [],
"StandardItemIdentification": {
"ID": {
"__value": "21382183120983",
"schemeID": "0088"
},
"PhysicalAttribute": [],
"MeasurementDimension": []
},
"AdditionalItemIdentification": [],
"ItemSpecificationDocumentReference": [],
"OriginCountry": {
"IdentificationCode": {
"__value": "NO"
}
},
"CommodityClassification": [
{
"ItemClassificationCode": {
"__value": "09348023",
"listID": "SRV"
}
}
],
"TransactionConditions": [],
"HazardousItem": [],
"ClassifiedTaxCategory": [
{
"ID": {
"__value": "S"
},
"Percent": {
"__value": 25.0
},
"TaxExemptionReason": [],
"TaxScheme": {
"ID": {
"__value": "VAT"
},
"JurisdictionRegionAddress": []
}
}
],
"AdditionalItemProperty": [],
"ManufacturerParty": [],
"OriginAddress": [],
"ItemInstance": [],
"Certificate": [],
"Dimension": []
},
"Price": {
"PriceAmount": {
"__value": 400.0,
"currencyID": "EUR"
},
"PriceChangeReason": [],
"ValidityPeriod": [],
"AllowanceCharge": []
},
"SubInvoiceLine": []
},
{
"ID": {
"__value": "2"
},
"Note": [],
"InvoicedQuantity": {
"__value": -3.0,
"unitCode": "DAY"
},
"LineExtensionAmount": {
"__value": -1500.0,
"currencyID": "EUR"
},
"InvoicePeriod": [],
"OrderLineReference": [
{
"LineID": {
"__value": "123"
}
}
],
"DespatchLineReference": [],
"ReceiptLineReference": [],
"BillingReference": [],
"DocumentReference": [],
"Delivery": [],
"PaymentTerms": [],
"AllowanceCharge": [],
"TaxTotal": [],
"WithholdingTaxTotal": [],
"Item": {
"Description": [
{
"__value": "Description 2"
}
],
"Name": {
"__value": "item name 2"
},
"AdditionalInformation": [],
"Keyword": [],
"BrandName": [],
"ModelName": [],
"ManufacturersItemIdentification": [],
"StandardItemIdentification": {
"ID": {
"__value": "21382183120983",
"schemeID": "0088"
},
"PhysicalAttribute": [],
"MeasurementDimension": []
},
"AdditionalItemIdentification": [],
"ItemSpecificationDocumentReference": [],
"OriginCountry": {
"IdentificationCode": {
"__value": "NO"
}
},
"CommodityClassification": [
{
"ItemClassificationCode": {
"__value": "09348023",
"listID": "SRV"
}
}
],
"TransactionConditions": [],
"HazardousItem": [],
"ClassifiedTaxCategory": [
{
"ID": {
"__value": "S"
},
"Percent": {
"__value": 25.0
},
"TaxExemptionReason": [],
"TaxScheme": {
"ID": {
"__value": "VAT"
},
"JurisdictionRegionAddress": []
}
}
],
"AdditionalItemProperty": [],
"ManufacturerParty": [],
"OriginAddress": [],
"ItemInstance": [],
"Certificate": [],
"Dimension": []
},
"Price": {
"PriceAmount": {
"__value": 500.0,
"currencyID": "EUR"
},
"PriceChangeReason": [],
"ValidityPeriod": [],
"AllowanceCharge": []
},
"SubInvoiceLine": []
}
]
}