Peppol Documents

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 UBL format.

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

• Production: documents are exchanged through the official Peppol Network in this environment. Base URL is https://api.myazur.app

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

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. Download it, install it and create a free account.

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

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".

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.

My Azur API uses Firebase Authentication, you can learn more about how to integrate Firebase Authentication in your app here: https://firebase.google.com/docs/auth

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

• Get Started with Firebase Authentication in C++

• Get Started with Firebase Authentication on Apple Platforms

• Get Started with Firebase Authentication on Android

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

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:

curl --location 'https://api-sandbox.myazur.app/folders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Firebase Access Token>' \
--data '{
    "name" : "Tenant 1",
    "company_id" : <Your company id>,
    "legal_entity" : {
        "party_name": "My Tenant 1",
        "line1": "220 Rue de la liberte",
        "city": "Test City",
        "zip": "Zippy",
        "country": "LU"
    }
}'

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.

curl --location 'https://api-sandbox.myazur.app/folders/<folder_id>/peppol_identifiers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <firebase token>' \
--data '{
	"superscheme": "iso6523-actorid-upis",
	"scheme": "LU:VAT",
	"identifier": "LU01234567"

On Postman:

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: https://myazur.app/signup or you can create a their accounts programmatically through My Azur API by sending an HTTP POST request to /users :

curl --location 'https://api-sandbox.myazur.app/users' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "password": "<tenant password>",
    "firstname" : "John",
    "surname" : "Doe"
}

On Postman:

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/<folder_id>/user_roles as the following:

curl --location 'https://api-sandbox.myazur.app/folders/<folder_id>/user_roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <firebase_token>' \
--data-raw '{
    "email" : "[email protected]",
    "role" : "folder_admin" 
}  

On Postman:

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).

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:

{
  "routing":  {
    "emails": [
      "[email protected]"
    ],
    "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

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

curl --location 'https://api-sandbox.myazur.app/folders/<folder_id>/documents/<document_id>' \
--header 'Accept: application/xml' \
--header 'Authorization: Bearer <Bearer Token>

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.