Peppol API References

Introduction

Peppol (Pan-European Public Procurement On-Line) is an international network designed to facilitate standardized, secure, and efficient electronic document exchange between businesses and governments. It is governed by the OpenPeppol organization and supports the exchange of documents such as invoices, orders, and catalogs in a standardized format.

The Peppol API provides a gateway for businesses to interact with the Peppol network programmatically, enabling them to send and receive electronic documents. It ensures compliance with the Peppol standards and provides tools to integrate seamlessly with enterprise systems like ERPs, invoicing systems, and procurement platforms.

Key Features of Peppol API

Interoperability Peppol ensures that businesses from different countries and systems can exchange documents using the same standards.
Standardized Document Formats Documents are exchanged in Universal Business Language (UBL), ensuring uniformity.
Secure and Reliable Peppol uses Access Points to ensure secure and authenticated data exchange. The network also provides error handling and delivery receipts.
Compliance Peppol meets regulatory requirements for electronic invoicing in various regions, including the EU e-invoicing directive and similar mandates worldwide.
Integration with Existing Systems APIs allow direct integration with ERPs, financial software, and other platforms.

How Peppol API Works

Registration and Configuration

Register with a certified Peppol Access Point provider.
Obtain credentials and configure your system to connect to the Peppol network.

Access Point Interaction

Peppol documents are exchanged through certified Access Points. These serve as intermediaries between senders and receivers.

Document Submission

Use the API to generate and send documents (e.g., invoices, orders) in UBL format.
The document is validated and routed through the network to the intended recipient.

Receiving Documents

The API can receive incoming documents, parse them, and integrate them into your system.

GET/1.0/participant/lookup

Participant LookUp

The Participant Lookup feature in the Peppol API is essential for determining whether a specific participant (e.g., a business or government entity) is registered in the Peppol network. This process allows you to decide whether to route a document through Peppol and identify the target format required for successful document exchange.

Parameters

Name
pid
Type
string
Description
To lookup a participant you need to provide its complete ReceiverId (also known as participant id or Peppol id), such as 0001:5567212047. A Peppol receiver needs to be registered in an SMP and it can only be registered in one (1) SMP. It is identified using a combination of any of the ISO6523 identifiers available and the corresponding identifier value. If you can’t perform a Participant Lookup for the receiver, you are using an incorrect ParticipantID.

Sample Request

GET

test-peppol.flick.network/1.0/participant/lookup

curl 
  --url https://test-peppol.flick.network/1.0/participant/lookup?pid=iso6523-actorid-upis::0230:05019876543 \
  --header 'x-flick-auth-key: {token}

Sample Response

200

Success

{
  "Participants": {
    "xmlns": "urn:com:mdec:peppol:smp:api:2:0",
    "Participant": {
      "Meta": {
        "ParticipantIdentifier": {
          "Scheme": "iso6523-actorid-upis",
          "IdentifierCode": "0230",
          "IdentifierValue": "05019876543"
        },
        "SmlActivation": true,
        "PdActivation": true,
        "PdfFile": "Peppol KYC.pdf",
        "RegistrationDate": "2024-07-11T08:03:00Z"
      },
      "BusinessCard": {
        "BusinessEntity": {
          "Names": {
            "Name": [
              {
                "Name": "Flick Solutions Sdn. Bhd.",
                "Language": "en"
              }
            ]
          },
          "CountryCode": "MY",
          "GeographicalInformation": "Selangor",
          "AdditionalInformation": ""
        }
      },
      "AccessPointConfigurations": {
        "AccessPointConfiguration": {
          "EndpointId": "1",
          "MetadataProfileIds": {
            "ProfileId": [
              "257",
              "261",
              "272",
              "273",
              "274",
              "285",
              "286",
              "287",
              "288"
            ]
          }
        }
      }
    }
  }
}

GET/1.0/participant/lookup

Multiple Participant LookUp

The Multiple Participant Lookup feature in the Peppol API is used to get multiple of them in a singlre request. You need to use & Operators in parameters to add multiple PIDs

Parameters

Name
pid
Type
string
Description
To lookup a participant you need to provide its complete ReceiverId (also known as participant id or Peppol id), such as 0001:5567212047. A Peppol receiver needs to be registered in an SMP and it can only be registered in one (1) SMP. It is identified using a combination of any of the ISO6523 identifiers available and the corresponding identifier value. If you can’t perform a Participant Lookup for the receiver, you are using an incorrect ParticipantID.

Sample Request

GET

test-peppol.flick.network/1.0/participant/lookup

curl 
  --url https://test-peppol.flick.network/1.0/participant/lookup?pid=iso6523-actorid-upis::0230:05019876543 \
  --header 'x-flick-auth-key: {token}

Sample Response

200

Success

{
  "Participants": [{
    "xmlns": "urn:com:mdec:peppol:smp:api:2:0",
    "Participant": {
      "Meta": {
        "ParticipantIdentifier": {
          "Scheme": "iso6523-actorid-upis",
          "IdentifierCode": "0230",
          "IdentifierValue": "05019876543"
        },
        "SmlActivation": true,
        "PdActivation": true,
        "PdfFile": "Peppol KYC.pdf",
        "RegistrationDate": "2024-07-11T08:03:00Z"
      },
      "BusinessCard": {
        "BusinessEntity": {
          "Names": {
            "Name": [
              {
                "Name": "Flick Solutions Sdn. Bhd.",
                "Language": "en"
              }
            ]
          },
          "CountryCode": "MY",
          "GeographicalInformation": "Selangor",
          "AdditionalInformation": ""
        }
      },
      "AccessPointConfigurations": {
        "AccessPointConfiguration": {
          "EndpointId": "1",
          "MetadataProfileIds": {
            "ProfileId": [
              "257",
              "261",
              "272",
              "273",
              "274",
              "285",
              "286",
              "287",
              "288"
            ]
          }
        }
      }
    }
  }]
}

POST/1.0/participant

Create New Participant

This endpoint is used to create a new participant. If the participant requires KYC signing, the accepted KYC methods will be included in the response along with an HTTP status code 202. Otherwise, an HTTP status code 201 will be returned.

Request Body

Name
businessEntity
Type
array of objects: mandatory
Description
A list of entities that represent the participant's business details.
Name
additionalIdentifiers
Type
object: optional
Description
Holds additional identifiers for the participant's business entity.
Name
additionalIdentifier
Type
array of objects: optional
Description
A list of additional identifiers for the business entity.
Name
identifierCode
Type
string: mandatory (limit: 50 chars)
Description
A code representing the type of additional identifier.
Name
identifierValue
Type
string: mandatory (limit: 100 chars)
Description
The value of the additional identifier.
Name
additionalInformation
Type
string: optional
Description
Additional information about the business entity.
Name
contacts
Type
object: optional
Description
Contains contact information for the business entity.
Name
email
Type
string: optional (limit: 100 chars)
Description
The email address of the contact person.
Name
name
Type
string: optional (limit: 50 chars)
Description
The name of the contact person.
Name
phoneNumber
Type
string: optional (limit: 20 chars)
Description
The phone number of the contact person.
Name
type
Type
string: optional
Description
The type of contact (e.g., administrative, technical).
Name
countryCode
Type
string: mandatory (ISO 3166-1 alpha-2)
Description
The country code representing the location of the business entity.
Name
geographicalInformation
Type
string: optional
Description
Additional geographical details about the business entity's location.
Name
names
Type
array of objects: mandatory
Description
A list of names of the business entity.

Sample Request

POST

/my/einvoice/generate/invoice

curl --url https://test-peppol.flick.network/1.0/participant \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "businessEntity": [
        {
          "additionalIdentifiers": {
            "additionalIdentifier": [
              {
                "identifierCode": "string",
                "identifierValue": "string",
                "scheme": "string"
              }
            ]
          },
          "additionalInformation": "string",
          "contacts": {
            "contact": [
              {
                "email": "string",
                "name": "string",
                "phoneNumber": "string",
                "type": "string"
              }
            ]
          },
          "countryCode": "string",
          "geographicalInformation": "string",
          "names": {
            "name": [
              {
                "language": "string",
                "name": "string"
              }
            ]
          }
        }
      ]
    }'

Sample Response

200

Success

{
  "method": [
    "PDF_AUTHORIZATION_DOCUMENT"
  ]
}

PUT/1.0/sml/activate/{pid}

Publish a participant in SML

This endpoint allows you To publish a specific participant in the SML (Service Metadata Locator).

Parameters

Name
pid
Type
string
Description
To lookup a participant you need to provide its complete ReceiverId (also known as participant id or Peppol id), such as 0001:5567212047. A Peppol receiver needs to be registered in an SMP and it can only be registered in one (1) SMP. It is identified using a combination of any of the ISO6523 identifiers available and the corresponding identifier value. If you can’t perform a Participant Lookup for the receiver, you are using an incorrect ParticipantID.

Sample Request

PUT

1.0/sml/activate/{pid}

curl 
  --url https://test-peppol.flick.network/1.0/sml/activate/{pid} \
  --header 'x-flick-auth-key: {token}' \

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "pid": "string",
    "status": "activated"
  }
}

PUT/1.0/sml/deactivate/{pid}

Deactivate a participant in SML

This endpoint allows you To deactivate an already published participant in the SML (Service Metadata Locator).

Parameters

Name
pid
Type
string
Description
To lookup a participant you need to provide its complete ReceiverId (also known as participant id or Peppol id), such as 0001:5567212047. A Peppol receiver needs to be registered in an SMP and it can only be registered in one (1) SMP. It is identified using a combination of any of the ISO6523 identifiers available and the corresponding identifier value. If you can’t perform a Participant Lookup for the receiver, you are using an incorrect ParticipantID.

Sample Request

PUT

1.0/sml/deactivate/{pid}

curl 
  --url https://test-peppol.flick.network/1.0/sml/deactivate/{pid} \
  --header 'x-flick-auth-key: {token}' \

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "pid": "string",
    "status": "deactivated"
  }
}