Create a Participant

This tutorial explains how to create a new receiver ("Participant" or "Corner 4" in e-invoicing terminology). The Participant is registered in Peppol's test environment (SMK).

This participant can be looked up per the description in the Find Participants tutorial and is later used in the Send Transaction tutorial.

If you prefer importing this tutorial into Postman or Insomnia, download the har archive file and import into your preferred tool.

Prerequisites

Your user must have the orgadmin role in an existing organisation to be able to proceed with this tutorial. Visit the Create an Organisation tutorial if you do not already belong to an organisation.

Step 1. Select the SMP to use

A participant must be registered in an SMP. Arratech maintains two SMP:s, one for test and the other for production. If your organisation is in sandbox/demo mode you only have access to the test SMP while organisations in shared and whitelabel modes have access to both.

To find the reference to Arratech's Test SMP you use the /orgs/:orgId/smps/alltouse endpoint.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/smps/alltouse \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

In the returned list you will find Arratech's Test SMP. Take note of it's id property value.

Step 2. Select the AP to use

The Participant has to be assigned to a C3 Access Point to be able to receive transactions. In this tutorial we will create a participant in Arratech's Test AP.

Start by finding the reference to Arratech's Test AP via the /orgs/:orgId/aps/alltouse endpoint.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/aps/alltouse \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

In the returned list you will find Arratech's test AP. Take note of it's id property value.

Step 3. Select a Participant Peppol-Identifier

The participant you are about to create needs to be assigned a valid Peppol participant id scheme value. These identifiers are generally country specific and based on the ISO 6523 scheme.

We recommend that you create your first participant using your own company registration number as the Peppol id. An example of a Swedish identifier is: 0007:2120000787

To list available participant id schemes, use the /participant_identifiers endpoint. Since there are more than 100 id schemes we suggest that you apply a country filter to limit the number of records. In the example below we use France (FR), filter=country:eq:FR:

curl -X GET https://api.arratech.com/participant_identifiers?filter=country%3Aeq%3AFR \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 4. Create your Participant

The participant is created with the /orgs/:orgId/participants endpoint:

curl -X POST https://api.arratech.com/orgs/YOUR_ORGS_ID/participants \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first participant",
	  "participantIdentifier": "YOUR_PEPPOL_IDENTIFIER",
	  "smpRef": "ARRATECH_TEST_SMP_ID",
	  "apRef": "ARRATECH_TEST_AP_ID",
      "transportProfile": "peppol-transport-as4-v2_0"
}'

Your participant is now created in the Arratech SMP with its participant identifier value.

Take a note of the id property value in the response result, this is the unique identifier (in UUID format) for your participant in the Arratech platform. You will need it later when calling participant specific API endpoints.

Step 5. Request PD publishing on creation (optional)

You can optionally request for your participant to be published in the Peppol Directory upon creation.

For this we use the /orgs/{orgId}/participants/request-pd-publish endpoint.

curl -x POST https://api.arratech.com/orgs/YOUR_ORGS_ID/participants/request-pd-publish \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json' \
  -d '{
    "ids": [
      "YOUR_PARTICIPANTS_ID"
    ]
}'

Step 6. Add a supported document

The newly created participant is now registered to receive documents but it still has not specified which documents it can receive. A participant must explicitly announce which document types it support (can receive).

To do this we use the /orgs/:orgId/participants/:participantId/supported_document_types. Before we assign document types to the participant we need to find one document type to use in the configuration.

6A. Find your Document Type

All available business document types are available via the /document_types endpoint. However, this is a list of hundreds of records so a filter will help.

Peppol business documents are ordered in categories. To understand which categories we have we use the constants endpoint with a category filter: /constants?key=DOCUMENT_TYPE_CATEGORIES

Since the response if fairly small we show it below to spare you from performing this step yourself.

In this tutorial we will add a document type from the Invoice category.

6B. List Invoice Document Types

With the category sorted out we can now call the document type endpoint with a category filter: /document_types?filter=category:eq:Invoice

curl -X GET https://api.arratech.com/document_types?filter=category%3Aeq%3AInvoice \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

In the returned list of invoice types we will find and use the one named Peppol BIS Billing UBL Invoice V3, it has the id at-01e.

Adding a document type is done with two properties, the document type id and the id of the process to use. The available processes for the billing invoice are given in the process-ids property. For our document type we chose the following process:

{
"scheme": "cenbii-procid-ubl",
"value": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
}

With this information in place we are now ready to add the document type to our participant.

6C. Add the Document Type

We now add our chosen document type to our participant. As seen below we use the document id and the process scheme/id in the call.

Note that YOUR_PARTICIPANTS_ID is the UUID participant id, not the peppol-identifier.

Note also that the value added in the processId property is the combination of the scheme and the value properties, on the form scheme::value

curl -X PUT https://api.arratech.com/orgs/YOUR_ORGS_ID/participants/YOUR_PARTICIPANTS_ID/supported_document_types \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "supportedDocumentTypes": [
		{
			"documentId": "at-01e",
			"processId": "cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
		}
		
	]
}'

Congratulations! Your first participant is now registered and ready to receive invoices.