API v.2.1 for Tickstar Peppol SMP (updated 2021-11-24)
Depending on which SMP you use, you should pick the corresponding API implementation in the table below.
See change log of the bottom of this page for most recent changes of the API.
Please note that APIv2.1 deprecates some APIv2.0 controllers and introduces some new ones. Controllers that have been deprecated are indicated in the API documentation. A mix of APIv2.0 and APIv2.1 should be used. Not all controllers have been changed between the versions and the unchanged controllers are not duplicated between the versions.
To be able to use the API, you need an SMP user account.
Using your SMP user account you can log in and create an API- token which will be used for authentication. Select the token type that fits you best, either the regular token or the HMAC.
- Login to Tickstar SMP user account or SGNIC SMP user account.
- Click “Settings”
- Click “Show” and then “Create” in section “API Tokens”
The generated API- token should be added to all API- requests in an HTTP- header named Token.
SMP API host names
Know your customer (KYC)
Know your customer (“KYC”)- support has been added to the Tickstar SMP, meaning that adding a participant to the SMP will require the participants approval before publishing it on the Peppol network. The API has been updated accordingly to accommodate this.
Some APIv2.0 endpoints have been deprecated and replaced with v2.1 where KYC support is added. Even if you’re in a region that currently does not require KYC to publish participants you can still use v2.1 and prepare for potential upcoming KYC requirements.
When a participant is created in a region where no KYC requirement exist, API v2.1 will behave in the same way as API v.2.0.
KYC requirements depends on the region you’re operating in.
For Singapore SMP:
- PDF authorisation document
For Galaxy Gateway SMP:
Organisations can manage their sub- organisation’s entities using the API by providing an HTTP- header named OrganizationId together with the id of the sub- organisation to act upon. The id of the organisation can be set and viewed in the SMP GUI Admin- section. All existing endpoints in the API can be shadowed into using this method.
Using the APIv2.0 endpoint- controller after 2020-03-19
The APIv.2.0 endpoint- controller, which has an interface that does not support multiple transport profiles, has been deprecated. Even though it’s recommended to use APIv2.1 for this specific controller the old controller from APIv2.0 can still be used. However, since the underlying data model has been changed to allow an endpoint to have several supported transports already persisted data can now be incompatible with APIv.2.0 interface.
To handle this the APIv.2.0 will now respond with HTTP error code 409 (conflict) for following cases:
- When endpoint information can’t be listed (GET) since it contains one or several endpoints which has more than one supported transport profile.
- When updating an endpoint (PUT) with one supported transport profile where the already persisted data has more than one supported transport.
Note! One can chose to ignore the 409 conflict errors by providing following HTTP header
By doing so:
- listing access points (GET) with more than one supported transport profile will only return the first one.
- updating access points (PUT) with one supported transport profile where already existing data has several, it will just overwrite existing data.
API error codes
Please visit https://www.tickstar.com/support/smp-api-error-codes for detailed information.
- “What is the workflow using the API?”
1. Create access point configuration using the Endpoint- controller (access point configuration will be reused by all participants).
2. Create participant using the Participant-controller referring to the created access point configuration (see 1.). Participant can be created with or without PD- (Peppol Directory) and SMK/SML- activation.
3. Optional, if not activated in SML/SMK in step 2, use SmlActivation- Controller to activate in SML/SMK.
4. Optional, if not activated in PD in step 2, use PdActivation- controller to activate in PD.
- “When creating participants, what is the expected content of accessPointConfigurations -> endpointId and accessPointConfigurations -> metadataProfileIds -> profileIds?“
These ids refers to your configured access point id and corresponding document ids.
The id of your access point instance/instances can either be found in the SMP GUI under “Access Point” or you can use the endpoint- controller to retrieve it. Using the endpoint- controller the the access point id is called “endpointId”.
Available profileIds for you organization can be found using the “Metadata profile”- controller.
- “I’m a little bit lazy, can’t you provide me with payload for the different controllers?“
See example section for examples. It’s also possible to create participants / access point configurations using the GUI and then export them with the API to get familiar example data.
- Participant create example: participant_example.json
- Participant bulk import example: bulk_import_example.ndjson
The API is an add-on service and is priced separately. You can test the API by creating a token from within your account. Please be reminded that we might remove your token without prior notice if you use the API in production scenarios without letting us know about it.
- Learn more about PEPPOL in the Frequently Asked Questions section.