# Peppol Documents My Azur API allows you to send and receive digital documents through the Peppol Network. Peppol (**P**an-**E**uropean **P**ublic **P**rocurement **O**n**L**ine) is an exchange network where governments and companies can exchange documents in [UBL format](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl).

Peppol Network https://peppol.eu/what-is-peppol/peppol-transport-infrastructure/

## Environments * **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 [https://api-sandbox.myazur.app](https://api.sitasoftware.lu) * **Production**: documents are exchanged through the official Peppol Network in this environment. Base URL is [https://api.myazur.app](https://api.sitasoftware.lu) ## Preflight The first thing you need is a My Azur Account, you can create a free one in the sandbox environment here: [https://sandbox.myazur.app/signup](https://myazur.app/signup) 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**. ## Postman A convenient approach to try My Azur API is to use [Postman](https://www.postman.com/). Download it, install it and create a free account. You can now Fork the Postman My Azur API collection by clicking the following button: [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/130150-431d6a31-4788-4d02-bc89-8878b1361570?action=collection%2Ffork\&collection-url=entityId%3D130150-431d6a31-4788-4d02-bc89-8878b1361570%26entityType%3Dcollection%26workspaceId%3Ddc078a0f-87b4-4ff2-a458-9745e3e6c017#?env%5BSandbox%20Env%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LnNpdGFzb2Z0d2FyZS5sdSIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiaHR0cHM6Ly9hcGktc2FuZGJveC5zaXRhc29mdHdhcmUubHUiLCJzZXNzaW9uSW5kZXgiOjB9LHsia2V5IjoiZmlyZWJhc2VfYXBpX2tleSIsInZhbHVlIjoiQUl6YVN5QVhtZ1p4MXRjZG9hYTR0UDZMbmJlMnpydnFxc3A2X1RFIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiJBSXphU3lBWG1nWngxdGNkb2FhNHRQNkxuYmUyenJ2cXFzcDZfVEUiLCJzZXNzaW9uSW5kZXgiOjF9LHsia2V5IjoidGVzdF91c2VyX2VtYWlsIiwidmFsdWUiOiJhYmNAdGVzdC5jb20iLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6ImFiY0B0ZXN0LmNvbSIsInNlc3Npb25JbmRleCI6Mn0seyJrZXkiOiJ0ZXN0X3VzZXJfcGFzc3dvcmQiLCJ2YWx1ZSI6ImZpcmViYXNlcGFzc3dvcmRoZXJlIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiJmaXJlYmFzZXBhc3N3b3JkaGVyZSIsInNlc3Npb25JbmRleCI6M30seyJrZXkiOiJzdG9yYWdlX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2F6dXItc2FuZGJveC5zdG9yYWdlLnNpdGFzb2Z0d2FyZS5sdSIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiaHR0cHM6Ly9henVyLXNhbmRib3guc3RvcmFnZS5zaXRhc29mdHdhcmUubHUiLCJzZXNzaW9uSW5kZXgiOjR9LHsia2V5IjoidG9rZW4iLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOmZhbHNlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6NX0seyJrZXkiOiJ0b2tlbiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImFueSIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6Nn1d) 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 {% hint style="danger" %} 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. {% endhint %}
## Authentication 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".

Fetch a new Firebase token

Click "Send" to retrieve a new token. The new token will be set automatically as environment variable. {% hint style="info" %} Firebase access token expires after 1 hour. Repeat the previous step to get a fresh one if the API returns a 401 status code. {% endhint %} Now you can proceed and send any API request that requires authentication. My Azur API uses Firebase Authentication, you can learn more about how to integrate Firebase Authentication in your app here: SDKs and documentation is provided for several programming languages and platforms, that simplify the integration with your application, here some resources: * [Get Started with Firebase Authentication on Websites](https://firebase.google.com/docs/auth/web/start) * [Get Started with Firebase Authentication in C++](https://firebase.google.com/docs/auth/cpp/start) * [Get Started with Firebase Authentication on Apple Platforms](https://firebase.google.com/docs/auth/ios/start) * [Get Started with Firebase Authentication on Android](https://firebase.google.com/docs/auth/android/start) ## Folders and Peppol Documents 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 {% hint style="info" %} If you want to manage your tenants Peppol documents server-side than you don't need to create a separated account for each tenant. You company account can access all your tenants folders. {% endhint %} ## Create a folder for a tenant 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: ```powershell curl --location 'https://api-sandbox.myazur.app/folders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "name" : "Tenant 1", "company_id" : , "legal_entity" : { "party_name": "My Tenant 1", "line1": "220 Rue de la liberte", "city": "Test City", "zip": "Zippy", "country": "LU" } }' ``` {% hint style="danger" %} 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. {% endhint %} On Postman:
## Add the Peppol Identifier 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. ```powershell curl --location 'https://api-sandbox.myazur.app/folders//peppol_identifiers' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "superscheme": "iso6523-actorid-upis", "scheme": "LU:VAT", "identifier": "LU01234567" ``` On Postman:

How to add a peppol identifier to a legal entity

You'll get a 204 Status code if the operation is successful. ## Create a My Azur account for a tenant 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. 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 : ```powershell curl --location 'https://api-sandbox.myazur.app/users' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "admin@tenant1.com", "password": "", "firstname" : "John", "surname" : "Doe" } ``` On Postman:

How to create a My Azur account

## Grant folder permissions to a tenant 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/\/user\_roles as the following: ```powershell curl --location 'https://api-sandbox.myazur.app/folders//user_roles' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data-raw '{ "email" : "john@doe.com", "role" : "folder_admin" } ``` On Postman:

How to add a folder admin

## Send a Peppol document 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).

Send a Peppol Document in UBL format

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.

Send a Peppol Document in UBL format in Luxembourg

{% hint style="info" %} You can send Peppol documents using a Firebase token generated from your account or from the customer account to which you have assigned the folder admin role in the previous section. See the Authentication section above for more details. {% endhint %} 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: {% content-ref url="/pages/4MeitKTJwqSN5DfnVUoa" %} [Document](/models/document.md) {% endcontent-ref %} {% hint style="info" %} In case of a 4XX status code you can inspect the body response to learn more about the cause of the issue. {% endhint %} 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](/peppol/incremental-sync.md) **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: ``` { "routing": { "emails": [ "test@example.com" ], "eIdentifiers": [] } } ``` ## Receive a Peppol Document You can get the list of the Peppol documents received by sending an HTTP GET request to /folders/:folder\_id/documents?incoming=true

Fetch the list of Peppol received documents

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 ```powershell curl --location 'https://api-sandbox.myazur.app/folders//documents/' \ --header 'Accept: application/xml' \ --header 'Authorization: Bearer ```

Download a Peppol Document in UBL format

## Conclusion 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.myazur.app/peppol/peppol-documents.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.