Peppol Documents
A 20-minutes tutorial to learn how to send and receive Peppol documents.
Last updated
A 20-minutes tutorial to learn how to send and receive Peppol documents.
Last updated
My Azur API allows you to send and receive digital documents through the Peppol Network.
Peppol (Pan-European Public Procurement OnLine) is an exchange network where governments and companies can exchange documents in .
The first thing you need is a My Azur Account, you can create a free one in the sandbox environment here:
Contact Sita Software and provide the email addresses that you used to create your My Azur account and the information about your company. You will receive the firebase_api_key and your Company ID.
You can now Fork the Postman My Azur API collection by clicking the following button:
In the next section we will setup the Postman environments.
On the top right from the combo box select the Sandbox environment:
Click the Environments section on the left sidebar. You need to set in the Current Value Column the variables value for:
firebase_api_key: provided by Sita Software
test_user_email: your email address linked to your My Azur Account (sandbox or prod)
test_user_password: your password
The current environment is displayed on the top right, always check your current environment before sending an API request. Make sure you select the "Sandbox Env" to complete this tutorial.
You can now fetch a Firebase access token, go back to the Collections section (left sidebar), expand the My Azur API collection and select the api request "Get Token".
Click "Send" to retrieve a new token. The new token will be set automatically as environment variable.
Now you can proceed and send any API request that requires authentication.
SDKs and documentation is provided for several programming languages and platforms, that simplify the integration with your application, here some resources:
Peppol documents are organized in folders. You can handle multi-tenancy by creating one folder for each of your customers. You will create a separate My Azur account for each for your customers and grant permissions to read and write documents from/to a specific folder. As a company administrator you'll have full control over all your customers folders and all the documents sent and received.
In the next sections we'll go through the details on how to build a complete multi-tenancy system that let you manage your customer's Peppol documents through My Azur REST API.
In detail we will see:
How to create a folder for a tenant with a Peppol Identifier
How to create a My Azur account for a tenant and grant permissions to the folder.
How to send a Peppol document
How to fetch the received Peppol documents
A folder is a container of Peppol documents. Each of your tenants will have a separated folder. To create a new folder make sure you fetched a valid firebase token. Send a POST request to /folders and provides your company_id (Please contact Sita Software if you haven't received your company_id)
Peppol documents are exchanged between legal entities. You need to provide the verified information about your tenants in the legal entity section:
It's critically important that you verify your customer before creating a folder on My Azur API (Prod Environment). You are legally responsable for completing the KYC (Know Your Customer) process.
On Postman:
We created our folder and the Peppol legal entity, you can now add the Peppol Identifier, for instance in Luxembourg the Peppol identifier is the TVA number, use "LU:VAT" as scheme.
On Postman:
You'll get a 204 Status code if the operation is successful.
Each of your tentants will have a separated My Azur Account, we will grant the permissions to the new account to read/write documents from/to the folder that we created in the previous section.
On Postman:
We created a folder and an account for our tenant. We are gonna grant the folder permissions to the tenant account in this section. We'll give a folder user role to the tenant account.
Send an HTTP POST request to /folders/<folder_id>/user_roles as the following:
On Postman:
We are ready to send a Peppol document in UBL format via My Azur API.
Expand the Documents folder on the left side panel, and select the endpoint "Create a document in UBL format". On the center panel select the Params tab and set your folder id, make sure you use the correct folder id of your tenant for the environment you are working on (sandbox or production).
Switch to the Body tab, the Peppol document in UBL format must be encoded in base64 format. The routing section will determine who will receive the document. If the customer is a Luxembourg company the scheme must be "LU:VAT", the id is the TVA number.
Click send, if you receive a 200 response status code it means you’ve successfully submitted an invoice for sending via the Peppol network.
Your document is initially in the status "Submitted", you need to monitor the document status using the API. You can find the possible statues here:
You can consider the document as successfully delivered when your document get the status = 5 (Succeded), until then you should display to your user an "in progress" status.
To get the current status of a document use a strategy recommended in the section Incremental Sync Incremental Sync
What if my Customer is not on the Peppol network?
Then we can send an email with an electronic invoice attachment that is appropriate for the country your Customer is in. For instance, in de Germany we would send a ZUFGFeRD attachment, in France Facture-X and in Italy a FatturaPA. For India, the GSTN-signed JSON with a PDF that includes the QR code will be attached. Your receiver will know how to process these!
To test the email scenario, simply include a valid email address in the examples above and leave the "eIdentifiers" array empty, like this:
You can get the list of the Peppol documents received by sending an HTTP GET request to /folders/:folder_id/documents?incoming=true
You can then download each documents by sending a GET request to /folders/:folder_id/documents/:document_id and specify as request Accept header application/xml
Congratulations 🎉 At this point, you have acquired the necessary knowledge to interact with the Peppol network through My Azur API.
We have seen how to create an account for each of your customers (tenants), how to create a folder for each of them, and how each customer will send and receive Peppol documents.
In the upcoming chapters, we will explore how to implement an efficient Peppol document synchronization system based on timestamps. This will allow you to create a high-performance Peppol client that maximizes the capabilities of My Azur API.
Sandbox: is an environment that let you try My Azur API before going in production, documents are exchanged through the Peppol test Network. Base URL is
Production: documents are exchanged through the official Peppol Network in this environment. Base URL is
A convenient approach to try My Azur API is to use . Download it, install it and create a free account.
My Azur API uses Firebase Authentication, you can learn more about how to integrate Firebase Authentication in your app here:
To create a tenant account you can let the tenants create their own account through the website: or you can create a their accounts programmatically through My Azur API by sending an HTTP POST request to /users :
