REST API

This site offers a small REST API to perform arbitrary PEPPOL SMP lookups with a JSON result. The API is proprietary. The result data format is proprietary JSON.

Table of Contents

Base parameters

The base URL for all REST queries is https://peppol.helger.com/api - prepend this to all queries.
If an SML is required, the following SML identifiers are available:
  • digitprod - the production PEPPOL SML
  • digittest - the test PEPPOL SML (aka SMK)
  • smk-toop - the pilot TOOP SML (aka SMK)
  • autodetect - find the matching SML automatically

API: SMP query all document types of a participant

To retrieve all document types from a participant registered in an SMP.

HTTP method: GET
URL layout: /smpquery/SML-ID/participant-ID[?businessCard=false&xmlSchemaValidation=true&verifySignature=true]
SML-ID is the SML identifier mentioned above.
participant-ID is the URL encoded participant identifier to be queried (e.g. iso6523-actorid-upis%3a%3a9915%3atest)
The optional query parameter businessCard can be used to turn on querying of SMP Business Cards
The optional query parameter xmlSchemaValidation can be used to turn off XML Schema validation of SMP responses
The optional query parameter verifySignature can be used to turn off signature verification of SMP responses (not recommended)

Example URL (without Business Card): /smpquery/digittest/iso6523-actorid-upis%3a%3a9915%3atest

Example URL (with Business Card): /smpquery/digittest/iso6523-actorid-upis%3a%3a9915%3atest?businessCard=true

Note: all SMP queries are passed through to the effective SMP server and cause load there.

Example response (with Business Card):

{
  "smptype":"peppol",
  "participantID":"iso6523-actorid-upis::9915:test",
  "urls":[
    {
      "href":"http://test-infra.peppol.at/iso6523-actorid-upis%3A%3A9915%3Atest/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1",
      "documentTypeID":"busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "niceName":"Peppol PEPPOL BIS Billing UBL CreditNote V3",
      "isDeprecated":false
    },
    {
      "href":"http://test-infra.peppol.at/iso6523-actorid-upis%3A%3A9915%3Atest/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Awww.cenbii.eu%3Atransaction%3Abiitrns014%3Aver2.0%3Aextended%3Aurn%3Awww.peppol.eu%3Abis%3Apeppol5a%3Aver2.0%3A%3A2.1",
      "documentTypeID":"busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1",
      "niceName":"Peppol PEPPOL Billing profile CreditNote V2",
      "isDeprecated":false
    },
    {
      "href":"http://test-infra.peppol.at/iso6523-actorid-upis%3A%3A9915%3Atest/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Awww.cenbii.eu%3Atransaction%3Abiitrns014%3Aver2.0%3Aextended%3Aurn%3Awww.peppol.eu%3Abis%3Apeppol5a%3Aver2.0%3Aextended%3Aurn%3Awww.erechnung.gv.at%3Aver1.0%3A%3A2.1",
      "documentTypeID":"busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1"
    },
    {
      "href":"http://test-infra.peppol.at/iso6523-actorid-upis%3A%3A9915%3Atest/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AInvoice-2%3A%3AInvoice%23%23urn%3Awww.cenbii.eu%3Atransaction%3Abiitrns010%3Aver2.0%3Aextended%3Aurn%3Awww.peppol.eu%3Abis%3Apeppol5a%3Aver2.0%3Aextended%3Aurn%3Awww.erechnung.gv.at%3Aver1.0%3A%3A2.1",
      "documentTypeID":"busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1"
    }
  ],
  "businessCard":{
    "participant":{
      "scheme":"iso6523-actorid-upis",
      "value":"9915:test"
    },
    "entity":[
      {
        "name":[
          {
            "name":"Austrian Government"
          }
        ],
        "countrycode":"AT",
        "geoinfo":"Vienna, Austria",
        "additionalinfo":"This is the test endpoint for the whole Austrian Government!"
      }
    ]
  },
  "queryDateTime":"2020-01-10T17:51:15.76Z",
  "queryDurationMillis":878
}

API: SMP query all endpoints of a participant for a certain document type

To retrieve all endpoints of an SMP participant for a single document type. This API gives you AS2 and AS4 endpoints.

HTTP method: GET
URL layout: /smpquery/SML-ID/participant-ID/docType-ID[?xmlSchemaValidation=true&verifySignature=true]
SML-ID is the SML identifier mentioned above.
participant-ID is the URL encoded participant identifier to be queried (e.g. iso6523-actorid-upis%3a%3a9915%3atest)
docType-ID is the URL encoded document type identifier to be queried (e.g. busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AInvoice-2%3A%3AInvoice%23%23urn%3Awww.cenbii.eu%3Atransaction%3Abiitrns010%3Aver2.0%3Aextended%3Aurn%3Awww.peppol.eu%3Abis%3Apeppol5a%3Aver2.0%3A%3A2.1)
The optional query parameter xmlSchemaValidation can be used to turn off XML Schema validation of SMP responses
The optional query parameter verifySignature can be used to turn off signature verification of SMP responses (not recommended)

Example URL: /smpquery/digittest/iso6523-actorid-upis%3a%3a9915%3atest/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AInvoice-2%3A%3AInvoice%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1

Note: all SMP queries are passed through to the effective SMP server and cause load there.

Example response:

{
  "smptype":"peppol",
  "participantID":"iso6523-actorid-upis::9915:test",
  "documentTypeID":"busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1",
  "serviceinfo":{
    "processes":[
      {
        "processID":"cenbii-procid-ubl::urn:www.cenbii.eu:profile:bii05:ver2.0",
        "endpoints":[
          {
            "transportProfile":"busdox-transport-as2-ver1p0",
            "endpointReference":"https://test.erechnung.gv.at/as2",
            "requireBusinessLevelSignature":false,
            "minimumAuthenticationLevel":null,
            "certificate":"MIIFuzCCA6OgAwIBAgIQLc6VuJ1QGhKCNekpRV+3RzANBgkqhkiG9w0BAQsFADBr\nMQswCQYDVQQGEwJCRTEZMBcGA1UEChMQT3BlblBFUFBPTCBBSVNCTDEWMBQGA1UE\nCxMNRk9SIFRFU1QgT05MWTEpMCcGA1UEAxMgUEVQUE9MIEFDQ0VTUyBQT0lOVCBU\nRVNUIENBIC0gRzIwHhcNMTkwMjIyMDAwMDAwWhcNMjEwMjExMjM1OTU5WjBIMRIw\nEAYDVQQDDAlQREswMDAyNzAxFzAVBgNVBAsMDlBFUFBPTCBURVNUIEFQMQwwCgYD\nVQQKDANCUloxCzAJBgNVBAYTAkFUMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEA3/MoOJgIfDzUkSy52GJ0KAmQ8uUFoms+qcZki5xwgeUkEQZqEZfU7uZq\nSuJsQfo1OYNpOSRba4xtBVOMrbS5Q2i4y+rLxUnk89aWZj41GtuEYxlqQ27/F5Bu\nSMTVPzzt439Nj11JljanAhkJ/mHGFXsWoftzuQXajwU1ZCrrSxOv4TighIDBuvrq\n7xHjwi4+mljWOW2jBximWOZmOt0fZGgWduxZgnKwwYAeur7+GnAtPOFeIXyNREiE\nJyMPHxysKhs+a9ZUuSGHXMF+jDYOC1HMozsa10QIctNxpdHkYkORUdXmjh1k6AY/\nEuZwQSeZoAGorE066DdREn+JvIVvQQIDAQABo4IBfDCCAXgwDAYDVR0TAQH/BAIw\nADAOBgNVHQ8BAf8EBAMCA6gwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwHQYDVR0O\nBBYEFEOP+WBp2jknDwIRUt9rhwrSIvgpMF0GA1UdHwRWMFQwUqBQoE6GTGh0dHA6\nLy9wa2ktY3JsLnN5bWF1dGguY29tL2NhXzZhOTM3NzM0YTM5M2EwODA1YmYzM2Nk\nYThiMzMxMDkzL0xhdGVzdENSTC5jcmwwNwYIKwYBBQUHAQEEKzApMCcGCCsGAQUF\nBzABhhtodHRwOi8vcGtpLW9jc3Auc3ltYXV0aC5jb20wHwYDVR0jBBgwFoAUa29L\ntvE3uis8fxjNuiuyuXwqN+swLQYKYIZIAYb4RQEQAwQfMB0GE2CGSAGG+EUBEAEC\nAwEBgamQ4QMWBjk1NzYwODA5BgpghkgBhvhFARAFBCswKQIBABYkYUhSMGNITTZM\neTl3YTJrdGNtRXVjM2x0WVhWMGFDNWpiMjA9MA0GCSqGSIb3DQEBCwUAA4ICAQA6\n56xmXDfQZl3HLKmSpsJN5Fm+Q2MNWj50Q9avI2L7lF2GUS6COih3ECohv6g8t3Pj\ndhzt31ejWPjxuoXtcLesFBL6h9NgLoKel1LWOGnu06y9Q1pBBa4fx0ql2I845AV1\nax/F1Yh5ynQNVtaxyRDZizkL35MOl/WDDL2Oi/wt5d52BwsurU32JTKOlj+TUZt8\ntza1rA5bjGmsnVl48zrxrVSlMY/6y6uT86mub9nrBCMWbdY9BQ73V/jGW8BkhnVq\n+wVzHpDu/X66eErA/HUJk8k5Mb9Cj4uiLBcoSt9vk0cY9Q9S+QMOJdWEkl3veiTj\n1sydTX8MvL5bGBRPo0veNyypSXrA9FQwG6CbCY8UK1h/7oYnnTab04UUqGZBj72t\nXURqTq1updBEnSIFO4si95j0hN1fnkgsB//UtSyHriy4Je8voAzQQmPhms1FL/OS\nINWLSVEnUEodDztNDxD4x4sBZcmIgnsPiF7ygnEQIWVO8J92/GD0NmMcgnW4CFDK\nRgv5Aw4bFKcnS8CO9XvNp6reyZV2Q8kef5lGxxHR7S76CQ0tleUVMQPXkbFxcHN5\n8H2U2yIhorlH1DaOxPOlhSUTfKCBq38I6O4BUW8tvI35Rxo7pSfos5Lt7u/PIVwI\nVMRYrNhdxiS0RgWmZLELqi1QTzliBXJkurhHdG7eVA==",
            "certificateDetails":{
              "parsable":true,
              "subject":{
                "name":"C=AT,O=BRZ,OU=PEPPOL TEST AP,CN=PDK000270",
                "CN":"PDK000270",
                "OU":"PEPPOL TEST AP",
                "O":"BRZ",
                "C":"AT"
              },
              "issuer":{
                "name":"CN=PEPPOL ACCESS POINT TEST CA - G2,OU=FOR TEST ONLY,O=OpenPeppol AISBL,C=BE",
                "C":"BE",
                "O":"OpenPeppol AISBL",
                "OU":"FOR TEST ONLY",
                "CN":"PEPPOL ACCESS POINT TEST CA - G2"
              },
              "serial10":60887909668878219226152841132441057095,
              "serial16":"2dce95b89d501a128235e929455fb747",
              "notBefore":"2019-02-22T01:00:00",
              "notAfter":"2021-02-12T00:59:59",
              "validByDate":true,
              "sigAlgName":"SHA256withRSA"
            },
            "serviceDescription":"BRZ Test AP",
            "technicalContactUrl":"peppol-support@peppol.at",
            "technicalInformationUrl":"http://www.peppol.at",
            "extension":null
          }
        ],
        "extension":null
      }
    ],
    "extension":null
  },
  "queryDateTime":"2020-01-10T17:52:41.949Z",
  "queryDurationMillis":380
}

API: SMP query the Business Card of a participant

To retrieve the Business Card of a participant stored in an SMP.

HTTP method: GET
URL layout: /businesscard/SML-ID/participant-ID
SML-ID is the SML identifier mentioned above.
participant-ID is the URL encoded participant identifier to be queried (e.g. iso6523-actorid-upis%3a%3a9915%3atest)

Example URL: /businesscard/digittest/iso6523-actorid-upis%3a%3a9915%3atest

Note: the layout of the BusinessCard JSON is identical to the one used in querying all document types of a participant.

Note: all SMP queries are passed through to the effective SMP server and cause load there.

Example Response:

{
  "participant":{
    "scheme":"iso6523-actorid-upis",
    "value":"9915:test"
  },
  "entity":[
    {
      "name":[
        {
          "name":"Austrian Government"
        }
      ],
      "countrycode":"AT",
      "geoinfo":"Vienna, Austria",
      "additionalinfo":"This is the test endpoint for the whole Austrian Government!"
    }
  ],
  "queryDateTime":"2020-01-10T18:31:03.548Z",
  "queryDurationMillis":173
}

API: Convert EN 16931 CII to EN 16931 UBL documents

To automatically convert EN 16931 CII D16B documents to EN 16931 UBL 2.1 documents, based on https://github.com/phax/en16931-cii2ubl.

HTTP method: POST
URL layout: /convert/cii2ubl
The CII document to be converted must be the payload of the request.
The optional URL parameter simple-response can be used to "only" return the UBL document and no additional detail. Possible values are true and false. Default is false.
The optional URL parameter xml-beautify can be used to format (indent) the resulting UBL document. Possible values are true and false. Default is true.

Note: the request header Content-Type MUST be set to text/xml or application/xml.

Privacy note: uploaded documents are not persisted and stored by this system. The source document is converted and than discarded.

Example curl call to convert the local file "CII_example2.xml":
curl -X POST "https://peppol.helger.com/api/convert/cii2ubl?simple-response=true&xml-beautify=true" --data @CII_example2.xml --header "Content-Type: application/xml"

Example Response (default layout):

{
  "conversionDateTime":"2020-01-13T08:06:23.224Z",
  "parsingDuractionMillis":6,
  "parsingErrors":[],
  "conversionVersion":"1.3.0",
  "conversionBuildTimestamp":"2021-01-05T20:55:24Z",
  "conversionDuractionMillis":0,
  "coversionErrors":[],
  "ubl":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\" xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\" xmlns:cec=\"urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2\" xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\"><cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID><cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID><cbc:ID>TOSL108</cbc:ID><cbc:IssueDate>2013-06-30</cbc:IssueDate><!-- details omitted for readability --></Invoice>"
}

Example Response (simple response layout):

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cec="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>TOSL108</cbc:ID>
  <cbc:IssueDate>2013-06-30</cbc:IssueDate>
  <!-- details omitted for readability -->
</Invoice>
You must be logged in to post a comment!