Procurement Service Bus

# Peppol v1

The Peppol endpoints are used to look for recipients in Peppol, or to edit your Peppol configurations. To learn more about Peppol visit "What is Peppol".

Search for Peppol participants using this simple discovery tool.

Search for a partyId that uses a scheme from the Peppol Participant Schemes list.

# Delivery options

The peppol/deliveryOption endpoint offers advanced options when looking for recipients in OpenPeppol. The queryRecipientParty endpoint should be efficient enough for most users. But if you are an advanced user, you could use this endpoint.

When sending documents it is good to know the partyId that will guarantee the best delivery. The peppol/deliveryOption endpoint lets you request the best partyId to use with the salesInvoice/send endpoint. An organisation can have more than one partyId registered in the SMP to receive documents. The deliveryOption API will return the partyId that best fits the sending request.

To call the deliveryOptions API use the GET /api/v1/peppol/deliveryOption endpoint. Use these parameters to limit the returned values:

Name Type Description
partyIds array[string] (query) All possible partyIds of the recipient party.
preferredDocumentTypeId srting (query) The source or preferred documentTypeId to match with and to determine the partyId format.
documentTypeIds array[string] (query) Filter on document formats.
documentFamily string (query) Filter on a family.
isCredit boolean (query) Example: Set it to true, to search only for CreditNotes or to false if you don’t want to include CreditNotes in our result set.

Example: GET https://accp-psb.econnect.eu/api/v1/peppol/deliveryOption?partyIds=0106%3A54441587&partyIds=9944%3ANL12345678B01&documentFamily=Invoice

This will give a response containing a list of data to be used for sending, sorted on best value first. If there is no match the response will be empty.

# Returned elements

Name Type Description
partyId string
documentTypeId string The document format type id
processId string
protocol string AS2, AS4. (Enum: Array 2 )
url string Ap url
certificate string AP cert (Only valid OpenPeppol PKI)

# Response example

[
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:www.cenbii.eu:transaction:biitrns071:ver2.0:extended:urn:www.peppol.eu:bis:peppol36a:ver1.0::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii36:ver2.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF .... AT00kF4Xw=="
    },
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.simplerinvoicing.org:si:si-ubl:ver1.2::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii04:ver1.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF0 ... GItkAT00kF4Xw=="
    },
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.simplerinvoicing.org:si:si-ubl:ver1.2::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii04:ver2.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF0 ... GItkAT00kF4Xw=="
    },
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii04:ver2.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF0z ... GItkAT00kF4Xw=="
    }
]

# Peppol registration

Users with the ApManager role can use the Peppol endpoints to manage their parties in the eConnect SMP and Peppol SML. When adding new parties to the Peppol network, please make sure these parties are assigned to users who have sending and/or receiving capabilities and make sure there are hooks registered for the partyId. To do this all in one go, you can use the Enrollment endpoint.

# Register in Peppol

ApManagers can register a party in Peppol by calling the PUT method on the /api/v1/peppol/config/party/{partyId} endpoint. The given partyId is registered in the PEPPOL SML and in the eConnect SMP, using the configuration provided in the payload. Using the PUT method in combination with a partyId that is already registered will update the registration and configuration. Calling the GET method on the same endpoint will show you the current Peppol configuration for the provided partyId. Invoking the GET method on endpoint api/v1/peppol/config/party shows you all parties that are already registered in the eConnect SMP for your organization.

# Verification

The Peppol service configuration object includes verification, businessCard and capabilities. Verification is used to prove you are in compliance with the 'Know Your Customer policy' of the 'Peppol compliance policy'. It contains a 'verifiedOn' field with the date the customer has been verified and a 'notes' field where you can refer to the verification you have done (for example, a contract number).

"verification": {
    "notes": "Contract agreement C21345",
    "verifiedOn": "2020-02-03T14:11:17.2750853+00:00"
  }

# Capabilities

Capabilities are the services you want to register in the SMP. We separated the services into document families. The families are 'invoices', 'invoices_bisv2', 'reviews', 'invoiceResponse', 'orders', 'orderResponse', 'orderOnly', 'orderAdvanced' and 'orderResponseAdvanced'. The 'state' field is used to turn these families on or off. Using the 'inherited' value will use the default configuration for your organization. The endpoint api/v1/peppol/config is used to get, add or update the default Peppol configuration for your organization. Use the GET method to get your configuration and the PUT method to add or update a configuration.

"capabilities": {
    "invoices": {
      "state": "on",
      "description": "SI 2.0, SI 2.0 CreditNote, BIS Billing V3, BIS Billing V3 CreditNote, BIS Billing V3 CII"
    },
    "invoice_bisv2": {
      "state": "off",
      "description": "BIS5a Invoice, BIS4a Invoice, BIS5a CreditNote"
    },
    "reviews": {
      "state": "off",
      "description": "PEPPOL MLR 3.0"
    },
    "invoiceResponse": {
      "state": "off",
      "description": "PEPPOL Invoice Response transaction 3.0"
    },
    "orders": {
      "state": "off",
      "description": "PEPPOL Order transaction 3.0"
    },
    "orderResponse": {
      "state": "inherited => off",
      "description": "PEPPOL Order response transaction 3.3"
    },
    "orderOnly": {
      "state": "inherited => off",
      "description": "PEPPOL Order only transaction 3.3"
    },
    "orderAdvanced": {
      "state": "inherited => off",
      "description": "PEPPOL Order transaction 3.3, PEPPOL Order change transaction 3.3, PEPPOL Order cancellation transaction 3.3"
    },
    "orderResponseAdvanced": {
      "state": "inherited => off",
      "description": "PEPPOL Order response advanced transaction 3.3"
  },
  "createdOn": "2020-01-17T08:05:03.3845085+00:00",
  "changedOn": "2020-03-21T04:57:05.6917681+00:00"
}

# Peppol Directory

The businessCard object contains information that will be published in the Peppol Directory (opens new window). The Peppol Directory contains information about entities participating in the Peppol network. The Peppol Directory aggregates public information from SMPs and provides them centrally in a structured way. It enables an accessible way of searching for other participants in Peppol, for example by searching for a company's name. For now only receiving capabilities are listed in the Peppol Directory.

The Peppol Directory registration can be activated or deactivated with the 'state' field. Individual values can also be turned on or off with their own 'state' field. Note that atleast one name and a country code are necessary to create a valid business card. The country code should be a part of the address's 'value', separated by a comma. Multiple business names should also be separated by a comma.

Using the 'inherited' value will use the default configuration for your organization. The endpoint api/v1/peppol/config is used to get, add or update the default Peppol configuration for your organization. Use the GET method to get your configuration and the PUT method to add or update a configuration.

"businessCard": {
    "names": {
      "value": "eVerbinding, eConnect",
      "state": "on",
      "description": "Business names."
    },
    "address": {
      "value": "Pelmolenlaan 16A, 3447 GW, Woerden, NL",
      "state": "on",
      "description": "Geographic information."
    },
    "emailAddress": {
      "value": "techsupport@econnect.eu",
      "state": "on",
      "description": "Technical contact"
    },
    "state": "on"
  },

This businessCard translates to the following entry in the SMP:

<BusinessCard xmlns="http://www.peppol.eu/schema/pd/businesscard/20180621/">
    <ParticipantIdentifier scheme="iso6523-actorid-upis">0106:12345</ParticipantIdentifier>
    <BusinessEntity>
        <Name>eVerbinding</Name>
        <Name>eConnect</Name>
        <CountryCode>NL</CountryCode>
        <GeographicalInformation>Pelmolenlaan 16A, 3447 GW, Woerden, NL</GeographicalInformation>
        <Contact>
            <Email>techsupport@econnect.eu</Email>
        </Contact>
    </BusinessEntity>
</BusinessCard>

# Unregister from Peppol

To unregister, or delete, a party from the Peppol network you can use the DELETE method on the /api/v1/peppol/config/party/{partyId} endpoint. Doing so will remove the partyId from the eConnect SMP and the Peppol SML.

← User →

© 2024 eConnect International B.V.