SMP API
The SMP API allows an organization to seamlessly integrate with Tickstar’s Peppol SMP to manage Peppol receivers instantly from within its own applications.
It contains the full Peppol Directory support and improved error handling.
API
API v.2.1 for Tickstar Peppol SMP
This SMP API allows you to seamlessly integrate with the Tickstar SMP to easily manage all of your Peppol receivers from within your own applications.
Depending on which SMP you use, pick the corresponding API implementation in the table below.
How-to
Please refer to the API documentation and the XML schemas for SMP APIv2.0 and SMP APIv2.1 respectively to get started with SMP API v.2.x.
APIv2.1 deprecates some APIv2.0 controllers and introduces some new ones. All 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.
Authentication
Using your SMP user account, go ahead and 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.
Let´s take you through the steps!
- Login to Tickstar SMP user account or SGNIC SMP user account.
- Click “My Settings”
- Click “Show” and then “Create” in section “API Tokens”
The generated API token should be included in all API requests within an HTTP- header named “Token.”
SMP API host names
| Production | Test | |
|---|---|---|
| Tickstar SMP | https://api.galaxygw.com/ | https://api.test.galaxygw.com/ |
| Singapore SMP | https://api.peppolsmp.sg/ | https://api.test.peppolsmp.sg/ |
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:
- Corppass
- PDF authorisation document
For Tickstar SMP:
- None
Organization shadowing
Organizations can manage their sub-organizations 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 organization 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.
Overriding conflicts
Note! One can choose to ignore the 409 conflict errors by providing the following HTTP header
Ignore-Conflict: true
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 here for detailed information.
FAQ
Congratulations you´ve reach this far! These are the usual suspects of questions when you hit this point. Any other queries, just ping us
• “What is the workflow using the API?”
A four step workflow
- Create access point configuration using the Endpoint- controller (access point configuration will be reused by all participants).
- 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.
- Optional, if not activated in SML/SMK in step 2, use SmlActivation- Controller to activate in SML/SMK.
- 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.
• How can I get the payload for the different controllers?“
It’s possible to create participants/access point configurations using the GUI and then export them with the API to get familiar example data.
Examples
- Participant create example: participant_example.json
- Participant bulk import example: bulk_import_example.ndjson
Commercial details
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.
Change log
| Date | Version | Change |
|---|---|---|
| 2021-11-24 | 2.1 |
|
| 2021-06-17 | 2.0/2.1 |
|
| 2020-07-07 | 2.0 |
|
| 2020-03-19 | 2.0/2.1 |
|
Learn more about Peppol in the Frequently Asked Questions section.
The Peppol Encryption add-on service enables encryption for all documents that you exchange with Peppol Network.
Learn More
Peppol Validator enables easy and fast validation of documents that you send to the Peppol Network. The Validator supports most of the documents for which there are publicly available validation artefacts.
Learn More