| Variant | Config value | XML namespace |
|---|---|---|
| Peppol SMP 1.x | smp.rest.type = peppol | http://busdox.org/serviceMetadata/publishing/1.0/ |
| OASIS BDXR SMP 1.0 | smp.rest.type = bdxr | http://docs.oasis-open.org/bdxr/ns/SMP/1/ServiceMetadata |
| OASIS BDXR SMP 2.0 | smp.rest.type = bdxr (with BDXR2 path prefix) | http://docs.oasis-open.org/bdxr/ns/SMP/2/ServiceMetadata |
smp.rest.type property in application.properties. Peppol SMP 1.x is the default.
BDXR SMP 2.0 endpoints are served under the
/bdxr-smp-2/ path prefix for GET requests. PUT and DELETE write endpoints use the same paths as Peppol SMP.Base URL
All endpoints are relative to your SMP server’s public URL:Core SMP endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /{ServiceGroupId} | No | Get service group and document type list |
PUT | /{ServiceGroupId} | Yes | Create or update a service group |
DELETE | /{ServiceGroupId} | Yes | Delete a service group and all its metadata |
GET | /{ServiceGroupId}/services/{DocumentTypeId} | No | Get service metadata (endpoints) for a document type |
PUT | /{ServiceGroupId}/services/{DocumentTypeId} | Yes | Create or update service metadata |
DELETE | /{ServiceGroupId}/services/{DocumentTypeId} | Yes | Delete service metadata for a document type |
DELETE | /{ServiceGroupId}/services | Yes | Delete all service metadata for a service group |
GET | /businesscard/{ServiceGroupId} | No | Get business card |
PUT | /businesscard/{ServiceGroupId} | Yes | Create or update business card |
DELETE | /businesscard/{ServiceGroupId} | Yes | Delete business card |
POST | /businesscard/{ServiceGroupId}/push | Yes | Push business card to Peppol Directory |
Custom properties endpoints (since v8.1.0)
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /{ServiceGroupId}/customproperties | Optional | Get all custom properties (public only if unauthenticated) |
GET | /{ServiceGroupId}/customproperties/{PropertyName} | Optional | Get a single custom property |
PUT | /{ServiceGroupId}/customproperties | Yes | Replace all custom properties |
PUT | /{ServiceGroupId}/customproperties/{PropertyType}/{PropertyName} | Yes | Set a single custom property |
DELETE | /{ServiceGroupId}/customproperties | Yes | Delete all custom properties |
DELETE | /{ServiceGroupId}/customproperties/{PropertyName} | Yes | Delete a single custom property |
Utility and administrative endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /complete/{ServiceGroupId} | No | Get complete service group including all service metadata |
GET | /list/{UserId} | Yes | List all service groups owned by a user |
GET | /servicegroupids/all | Yes | List all service group IDs registered on this SMP (since v8.1.0) |
GET | /smp-status/ | No | Health and status information (disabled by default) |
GET | /ping/ | No | Liveness probe |
Remote query API (disabled by default)
The remote query API allows external SMP lookups through this server. It is disabled by default for security. Enable with:smp.rest.remote.queryapi.disabled = false
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /smpquery/{ServiceGroupId} | No | Remote lookup: list document types for a participant |
GET | /smpquery/{ServiceGroupId}/{DocumentTypeId} | No | Remote lookup: get service metadata |
GET | /businesscardquery/{ServiceGroupId} | No | Remote lookup: get business card |
Exchange API (since v5.6.0)
The exchange API provides bulk import/export of SMP data in XML format.| Method | Path | Auth | Description |
|---|---|---|---|
GET | /exchange/export/all/xml/v1 | Yes | Export all data as XML |
GET | /exchange/export/byowner/{UserId}/xml/v1 | Yes | Export all data owned by a user |
GET | /exchange/export/specific/{ServiceGroupId}/xml/v1 | Yes | Export a single service group |
GET | /exchange/export/outboundmigip/xml/v1 | Yes | Export outbound migrations in progress |
PUT | /exchange/import/xml/v1/{UserId} | Yes | Import XML data under the specified user |
Migration API (since v5.6.0)
Participant migration allows transferring a service group from one SMP to another within the Peppol network.| Method | Path | Auth | Description |
|---|---|---|---|
PUT | /migration/outbound/start/{ServiceGroupId} | Yes | Start outbound migration |
PUT | /migration/outbound/cancel/{ServiceGroupId} | Yes | Cancel outbound migration |
PUT | /migration/outbound/finalize/{ServiceGroupId} | Yes | Finalize outbound migration |
PUT | /migration/inbound/{ServiceGroupId}/{MigrationKey} | Yes | Accept inbound migration |
PUT | /migration/inbound | Yes | Accept inbound migration from XML body |
Identifier formats
Participant identifier (ServiceGroupId)
Participant identifiers use the formatscheme::value where scheme and value are separated by a double colon:
:: separator and any / characters within the identifier must be URL-encoded:
Document type identifier (DocumentTypeId)
Document type identifiers also use thescheme::value format:
Content types
All endpoints that accept a request body expectapplication/xml or text/xml. All endpoints that return a body respond with application/xml.
HTTP status codes
| Code | Meaning |
|---|---|
200 OK | Request succeeded |
400 Bad Request | Malformed identifier or inconsistent payload |
401 Unauthorized | Missing or invalid credentials |
403 Forbidden | Authenticated user does not own the service group |
404 Not Found | Service group, document type, or business card not found |
500 Internal Server Error | Unexpected server-side error |
Error responses
Error responses are plain-text HTTP responses with an appropriate status code. The response body contains a human-readable error message. No structured XML error envelope is used.Rate limiting
phoss SMP has no built-in rate limiting. If you need rate limiting, configure it at the reverse proxy layer (for example, nginx or Apache).API variants in depth
Peppol SMP 1.x
Peppol SMP 1.x
The default variant. Uses XML types from the
busdox.org namespace. Responses to GET requests are signed with the SMP’s private key using XML-DSig. This is the variant required for connectivity in the Peppol network.See Peppol service groups and Peppol service metadata for endpoint details.OASIS BDXR SMP 1.0
OASIS BDXR SMP 1.0
The OASIS standardised version of the Peppol SMP specification. Uses the
http://docs.oasis-open.org/bdxr/ns/SMP/1/ServiceMetadata namespace. Responses to GET requests are also signed.See BDXR service groups and BDXR service metadata.OASIS BDXR SMP 2.0
OASIS BDXR SMP 2.0
The newer OASIS version. GET requests for service groups and service metadata use the
/bdxr-smp-2/ path prefix. Uses the http://docs.oasis-open.org/bdxr/ns/SMP/2/ServiceMetadata namespace. Responses are unsigned.See BDXR service groups and BDXR service metadata.