Reference based on OpenAPI Specification¶
Generated from OpenAPI Specification
The following reference documentation of the sedex Messaging REST API is automatically generated from the OpenAPI specification file. It therefore contains the same content as the SwaggerUI tool provided by the sedex client to interactively explore the REST API (see section Technical Aspects - SwaggerUI/OpenAPI specification for details).
Note: The underlying OpenAPI specification file can also serve as input for the developer to generate his REST client.
sedex Messaging API V1¶
About the sedex Messaging REST API¶
You are reading the OpenAPI Specification of the sedex messaging REST API.
The main functionality of the sedex platform is secure, reliable and traceable data exchange between business applications related to e-Government.
The sedex Messaging REST API is a machine interface provided by the sedex client. It allows the business applications of a sedex participant to send sedex messages and receive sedex messages using the https protocol. In other words, the sedex Messaging REST API allows a business application to exchange data with other business applications connected to the sedex platform.
sedex message¶
A sedex message is used for the data exchange between the participants of the sedex platform.
A sedex message consists of two components:
-
a sedex envelope
-
a payload file
The sedex envelope is a document that contains the metadata of a message. These are among others fields like * the sender of the message (i.e. the sedex ID of the sender) * the recipient(s) of the message (i.e. the sedex ID(s) of the addressees) * the message type (a number describing the business case or the meaning of the data) * the message-id (a reference ID assigned by the sender for this message) * the message-date (a creation date of the message defined by the sender) * the event-date (a business date defined by the sender for the payload)
The payload file is containing the actual business data to be transmitted. In principle sedex can transfer files of any type as payload, but very common are the file types XML, JSON, ZIP. In particular, ZIP files are always chosen when several related files are to be transferred at once with one sedex message.
Operations offered by the REST API¶
Basically, the operations offered by the REST API are divided into two groups:
-
[ Send ]: Operations for sending sedex messages
-
[ Receive ]: Operations for receiving sedex messages
Servers¶
| Description | URL |
|---|---|
| Generated server url | https://localhost:8443 |
[ Send ]¶
POST /api/sedex/messaging/v1/send/messages/pre-check¶
Optional send step 0: Preliminary check whether registering a sedex message will succeed or not. (Purely informative without leaving traces.)
Description
Description¶
This operation allows an optional preliminary check, to find out if a sedex message could be sent with the sedex platform. It takes the envelope of the message to be sent as an input. The response of the operation contains an authorisation result indicating whether the message may be sent.
The sedex envelope contains the metadata for a sedex message. The following fields are part of the sedex envelope: * sender-id: sedex participant ID of the sender (ex: 1-123-1). * recipient-ids: one or more sedex participant IDs of the addressees (ex: 1-123-1) * message-type: number of the message type (business case specific and specified by authorities) * message-class: number of the class of message, in most cases 0 * message-id: a unique reference message ID assigned by the sender (must be unique across all its messages) * message-date: creation date of the sedex message (the maximum lifetime of the message is this date +30 days) * event-date*: a business case specific date assigned by the sending application
Within this operation, the message is checked for authorization based on the data in the envelope. As part of this check, the following criteria, among others, are checked: * validity of participant certificates * message type exists * sender exists and is authorized * recipient(s) exist and are authorized
Considerations¶
- This operation allows a sender to determine whether it will reach a particular recipient via sedex.
- For most message exchanges, a preliminary check with this operation is not necessary, since the same checks are also performed during a normal registration.
- This operation is purely informative and does not register any data in sedex yet.
- This functionality corresponds to the SOAP-webservice "checkSedex" offered by the sedex webservice proxy.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
Request body
{
"document-type": "envelope",
"document-version": "1.0",
"sender-id": "1-123-1",
"recipient-ids": [
"1-123-1"
],
"message-type": 4711,
"message-class": 0,
"message-id": "08989cf0-d239-47a9-8cb0-54cd8be5e62d",
"reference-message-id": "string",
"message-date": "2022-04-13T15:42:05.901Z",
"event-date": "2022-04-13T15:42:05.901Z",
"loopback": false,
"test-data": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
Schema of the request body
{
"required": [
"document-type",
"document-version",
"event-date",
"message-class",
"message-date",
"message-id",
"message-type",
"recipient-ids",
"sender-id"
],
"type": "object",
"properties": {
"document-type": {
"pattern": "envelope",
"type": "string",
"example": "envelope"
},
"document-version": {
"pattern": "\\d+\\.\\d+",
"type": "string",
"description": "Version of the document.",
"example": "1.0"
},
"sender-id": {
"type": "string",
"description": "sedexID of the sender of the message.",
"example": "1-123-1"
},
"recipient-ids": {
"type": "array",
"description": "List of sedexIDs of the recipients of the message.",
"example": [
"1-123-1"
],
"items": {
"type": "string",
"description": "List of sedexIDs of the recipients of the message.",
"example": "[\"1-123-1\"]"
}
},
"message-type": {
"maximum": 2699999,
"minimum": 0,
"type": "integer",
"description": "The message type specifies what the semantics of the message data is and to which business process it belongs.",
"format": "int64",
"example": 4711
},
"message-class": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer",
"description": "Defines the meaning of the message within a message type in the context of the business process. The following values are predefined:\n0 = Message. Indicates the initial message.\n1 = Response. Indicates the response to a message.\n2 = Receipt. Indicates an application acknowledgement (receipt) that a receiving application sends to the sending application. Such an acknowledgement may be sent if a longer period of time can elapse before a response is delivered, or if the recipient will not send a response at all.\n3 = Error. Indicates an error message that a receiving application sends to the sending application.",
"format": "int64",
"example": 0
},
"message-id": {
"pattern": "([a-zA-Z]|[0-9]|-){1,36}",
"type": "string",
"description": "Unique ID of the message. This ID is assigned by the sending application. The messageId must be unique in the context of the application.",
"example": "08989cf0-d239-47a9-8cb0-54cd8be5e62d"
},
"reference-message-id": {
"pattern": "([a-zA-Z]|[0-9]|-){1,36}",
"type": "string",
"description": "This element is set by an application when it sends a response or an error message to another application in response to a message. The element contains the message ID of the original message sent."
},
"message-date": {
"type": "string",
"description": "The creation date of the sedex message (the maximum lifetime of the message is this date +30 days).",
"format": "date-time"
},
"event-date": {
"type": "string",
"description": "A business case specific date assigned by the sending application.",
"format": "date-time"
},
"loopback": {
"type": "boolean",
"description": "If the sender marks a message as loopback=true, the message is only used for an end-to-end reachability test including authorization. However, the message is not delivered to the receiver.",
"example": false
},
"test-data": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Test data allows the transport of optional customer-specific metadata in the form of key/value pairs in a map. Usually not used.",
"example": "{\"Optional test data key 1\":\"test-value 1 (normally test-data is not used)\",\"Optional test data key 2\":\"test-value 2\"}"
},
"description": "Test data allows the transport of optional customer-specific metadata in the form of key/value pairs in a map. Usually not used.",
"example": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
},
"description": "The envelope contains the relevant metadata for a sedex message such as sender, recipient etc."
}
Response 503 Service Unavailable
{
"timestamp": "2022-04-13T15:42:05.901Z",
"status": 100,
"error": "string",
"message": "string",
"developer-message": "string",
"path": "string"
}
Schema of the response body
{
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "integer",
"description": "The http status code.",
"format": "int32"
},
"error": {
"type": "string",
"description": "The http status error title."
},
"message": {
"type": "string",
"description": "A message decribing the error."
},
"developer-message": {
"type": "string",
"description": "An extended explenation of the problem for developers and hints to possible solutions."
},
"path": {
"type": "string",
"description": "The called path where the error occurred."
}
},
"description": "Data structure used to return an error back to the caller of the API."
}
Response 400 Bad Request
Response 200 OK
{
"document-type": "pre-check-response",
"document-version": "1.0",
"allowed-to-send": true,
"message-authorisation-result": {
"overall": {
"is-authorized": true,
"authorization-code": 100,
"authorization-info": "Not allowed to send."
},
"per-recipient": {}
}
}
Schema of the response body
{
"type": "object",
"properties": {
"document-type": {
"type": "string",
"example": "pre-check-response"
},
"document-version": {
"type": "string",
"example": "1.0"
},
"allowed-to-send": {
"type": "boolean",
"description": "Only if allowedToSend=true a message can be transmitted.",
"example": true
},
"message-authorisation-result": {
"$ref": "#/components/schemas/MessageAuthorisationResult"
}
},
"description": "Data structure with the result of an optional preliminary check that shows whether a sedex message could be sent or not."
}
POST /api/sedex/messaging/v1/send/messages/register¶
Send step 1: Register a sedex message for sending by providing its envelope.
Description
Introduction: Sending a sedex message¶
A sedex message consists of an envelope with message metadata (such as sender, receiver, etc.) and a payload file containing the actual data to be transmitted.
Sending a sedex message via the REST API is done in two steps:
-
Register envelope: In the first step, the envelope of the message must be registered. The result of the registration is a unique-sedex-message-id generated by sedex, which is used to uniquely identify this message.
-
Upload Payload: Once the envelope of a message has been registered, the payload of the message can be uploaded in a second step. The unique-sedex-message-id serves as a correlation feature between the envelope and the payload.
Description¶
This operation registers a sedex message to be sent with the sedex platform. It takes the envelope of the message to be sent as an input. The response of the operation contains an authorisation result indicating whether the message may be sent and the unique-sedex-message-id under which it is registered on the platform sedex. Using this unique ID, the message can be referenced and tracked from now on.
The sedex envelope contains the metadata for a sedex message. The following fields are part of the sedex envelope: * sender-id: sedex participant ID of the sender (ex: 1-123-1). * recipient-ids: one or more sedex participant IDs of the addressees (ex: 1-123-1) * message-type: number of the message type (business case specific and specified by authorities) * message-class: number of the class of message, in most cases 0 * message-id: a unique reference message ID assigned by the sender (must be unique across all its messages) * message-date: creation date of the sedex message (the maximum lifetime of the message is this date +30 days) * event-date*: a business case specific date assigned by the sending application
Within this operation, the message is checked for authorization based on the data in the envelope. As part of this check, the following criteria, among others, are checked: * validity of participant certificates * message type exists * sender exists and is authorized * recipient(s) exist and are authorized
Considerations¶
- Part of the response is the
unique-sedex-message-idwith which the message has been registered. - If the registration is successful (result contains
allowed-to-send = true), the next step is to upload the message payload under theunique-sedex-message-id.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
Request body
{
"document-type": "envelope",
"document-version": "1.0",
"sender-id": "1-123-1",
"recipient-ids": [
"1-123-1"
],
"message-type": 4711,
"message-class": 0,
"message-id": "08989cf0-d239-47a9-8cb0-54cd8be5e62d",
"reference-message-id": "string",
"message-date": "2022-04-13T15:42:05.901Z",
"event-date": "2022-04-13T15:42:05.901Z",
"loopback": false,
"test-data": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
Schema of the request body
{
"required": [
"document-type",
"document-version",
"event-date",
"message-class",
"message-date",
"message-id",
"message-type",
"recipient-ids",
"sender-id"
],
"type": "object",
"properties": {
"document-type": {
"pattern": "envelope",
"type": "string",
"example": "envelope"
},
"document-version": {
"pattern": "\\d+\\.\\d+",
"type": "string",
"description": "Version of the document.",
"example": "1.0"
},
"sender-id": {
"type": "string",
"description": "sedexID of the sender of the message.",
"example": "1-123-1"
},
"recipient-ids": {
"type": "array",
"description": "List of sedexIDs of the recipients of the message.",
"example": [
"1-123-1"
],
"items": {
"type": "string",
"description": "List of sedexIDs of the recipients of the message.",
"example": "[\"1-123-1\"]"
}
},
"message-type": {
"maximum": 2699999,
"minimum": 0,
"type": "integer",
"description": "The message type specifies what the semantics of the message data is and to which business process it belongs.",
"format": "int64",
"example": 4711
},
"message-class": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer",
"description": "Defines the meaning of the message within a message type in the context of the business process. The following values are predefined:\n0 = Message. Indicates the initial message.\n1 = Response. Indicates the response to a message.\n2 = Receipt. Indicates an application acknowledgement (receipt) that a receiving application sends to the sending application. Such an acknowledgement may be sent if a longer period of time can elapse before a response is delivered, or if the recipient will not send a response at all.\n3 = Error. Indicates an error message that a receiving application sends to the sending application.",
"format": "int64",
"example": 0
},
"message-id": {
"pattern": "([a-zA-Z]|[0-9]|-){1,36}",
"type": "string",
"description": "Unique ID of the message. This ID is assigned by the sending application. The messageId must be unique in the context of the application.",
"example": "08989cf0-d239-47a9-8cb0-54cd8be5e62d"
},
"reference-message-id": {
"pattern": "([a-zA-Z]|[0-9]|-){1,36}",
"type": "string",
"description": "This element is set by an application when it sends a response or an error message to another application in response to a message. The element contains the message ID of the original message sent."
},
"message-date": {
"type": "string",
"description": "The creation date of the sedex message (the maximum lifetime of the message is this date +30 days).",
"format": "date-time"
},
"event-date": {
"type": "string",
"description": "A business case specific date assigned by the sending application.",
"format": "date-time"
},
"loopback": {
"type": "boolean",
"description": "If the sender marks a message as loopback=true, the message is only used for an end-to-end reachability test including authorization. However, the message is not delivered to the receiver.",
"example": false
},
"test-data": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Test data allows the transport of optional customer-specific metadata in the form of key/value pairs in a map. Usually not used.",
"example": "{\"Optional test data key 1\":\"test-value 1 (normally test-data is not used)\",\"Optional test data key 2\":\"test-value 2\"}"
},
"description": "Test data allows the transport of optional customer-specific metadata in the form of key/value pairs in a map. Usually not used.",
"example": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
},
"description": "The envelope contains the relevant metadata for a sedex message such as sender, recipient etc."
}
Response 503 Service Unavailable
Response 200 OK
{
"document-type": "registration-response",
"document-version": "1.0",
"allowed-to-send": true,
"unique-sedex-message-id": 2036412,
"message-authorisation-result": {
"overall": {
"is-authorized": true,
"authorization-code": 100,
"authorization-info": "Not allowed to send."
},
"per-recipient": {}
}
}
Schema of the response body
{
"type": "object",
"properties": {
"document-type": {
"type": "string",
"example": "registration-response"
},
"document-version": {
"type": "string",
"example": "1.0"
},
"allowed-to-send": {
"type": "boolean",
"description": "Only if allowedToSend=true a message can be transmitted.",
"example": true
},
"unique-sedex-message-id": {
"type": "integer",
"description": "The *Unique sedex Message Id*. A system-wide unique MessageID, which is assigned by sedex for each message. With the help of this ID, a message can be uniquely referenced and tracked.",
"format": "int64",
"example": 2036412
},
"message-authorisation-result": {
"$ref": "#/components/schemas/MessageAuthorisationResult"
}
},
"description": "Data structure with the registration result of a new sedex message to be transmitted."
}
Response 400 Bad Request
POST /api/sedex/messaging/v1/send/messages/{unique-sedex-message-id}/payload¶
Send step 2: Upload a payload for a registered sedex message.
Description
Description¶
Uploads the payload of a sedex message that has been registered before.
The sedex payload contains the actual payload data of a sedex message. It is exactly one file of any type. Frequently used file types are xml, json, cvs, zip. The file type zip is used in particular when several files should be transmitted at once. Which file types are allowed for a particular message type is up to the responsible domain administrators and business use cases.
Considerations¶
- The
unique-sedex-message-idhas been provided as part of the result during the registration step. - The payload file is expected as the first multipart element of the body.
- The client (i.e. the sending business application) can track the status
of the message by using the status operation on the
unique-sedex-message- id.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
unique-sedex-message-id |
path | integer | No | The unique-sedex-message-id of the message to which the payload should belong. This message ID was provided during the registration of a sedex message. (*Example:* 2036412) |
Request body
{
"payloadFile": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
}
Schema of the request body
{
"type": "object",
"properties": {
"payloadFile": {
"type": "string",
"description": "payload file",
"format": "binary"
}
},
"description": "Data structure with the file name of the payload file to be transmitted with a sedex message."
}
Response 423 Locked
Response 503 Service Unavailable
Response 404 Not Found
Response 200 OK
{
"message": "string"
}
Schema of the response body
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A message decribing the success."
}
},
"description": "Data structure used to return information about a successful execution back to the caller of the API."
}
Response 400 Bad Request
{
"message": "string"
}
Schema of the response body
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A message decribing the success."
}
},
"description": "Data structure used to return information about a successful execution back to the caller of the API."
}
GET /api/sedex/messaging/v1/send/messages/{unique-sedex-message-id}/status¶
Optional send step 3: Check the status of a sent message.
Description
Description¶
The sender (i.e. the sending business application) can get the detailed status of a sent sedex message to check whether it could be delivered to all addressed recipients.
Considerations¶
- Typically, this operation is called several times at defined intervals
(e.g. every few minutes) until a final state is reached (
current- status.overall.status = completed). - Once a message has reached a final status, it no longer undergoes any changes. The status of such a message should therefore no longer be queried regularly in order not to create an unnecessary load on the system.
- In most cases, it is easier and more efficient for the sending business application to evaluate only the receipts and not to use this operation to check the status of each sent message for potential changes.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
unique-sedex-message-id |
path | integer | No | Unique sedex message ID of the message to check the status. (*Example:* 2036412) |
Response 404 Not Found
Response 429 Too Many Requests
Response 503 Service Unavailable
Response 200 OK
{
"document-type": "string",
"document-version": "string",
"unique-sedex-message-id": 265,
"envelope": {
"document-type": "envelope",
"document-version": "1.0",
"sender-id": "1-123-1",
"recipient-ids": [
"1-123-1"
],
"message-type": 4711,
"message-class": 0,
"message-id": "08989cf0-d239-47a9-8cb0-54cd8be5e62d",
"reference-message-id": "string",
"message-date": "2022-04-13T15:42:05.901Z",
"event-date": "2022-04-13T15:42:05.901Z",
"loopback": false,
"test-data": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
},
"payload": {
"size-in-bytes": 220
},
"current-status": {
"overall": {
"status": "string",
"last-status-change": "2022-04-13T15:42:05.901Z",
"registered-at": "2022-04-13T15:42:05.901Z",
"completed-at": "2022-04-13T15:42:05.901Z",
"delivery": "string"
},
"status-per-recipient": [
{
"recipient-id": "string",
"status": "string",
"last-status-change": "2022-04-13T15:42:05.901Z",
"delivered-at": "2022-04-13T15:42:05.901Z",
"final-state-code": 281,
"final-state-information": "string"
}
]
}
}
Schema of the response body
{
"type": "object",
"properties": {
"document-type": {
"type": "string"
},
"document-version": {
"type": "string"
},
"unique-sedex-message-id": {
"type": "integer",
"format": "int64"
},
"envelope": {
"$ref": "#/components/schemas/Envelope"
},
"payload": {
"$ref": "#/components/schemas/Payload"
},
"current-status": {
"$ref": "#/components/schemas/CurrentStatus"
}
}
}
GET /api/sedex/messaging/v1/send/receipts¶
Send step 4: Get unacknowledged receipts for all sedex messages sent by the calling participant.
Description
Introduction¶
For each sedex message, the sender receives a (technical) receipt from sedex as soon as the message has reached a final state. Normally, this should be a success receipt indicating that the message was successfully delivered to the recipient. However, if errors have occurred that have made the delivery of a message impossible, an error receipt will indicate the problem.
Since a sedex message can be addressed to several recipients, the sender will receive a separate receipt for each addressee. For example, a message addressed to three recipients will result in three receipts, each indicating the final state for one recipient.
Important: Receipts must be processed and acknowledged! Robust message exchange can only be achieved if the receipts are evaluated. The application that sends a sedex message must also process and evaluate the corresponding receipts. Otherwise, it will not have the chance to detect if messages do not reach one or more recipients and act accordingly.
Description¶
This operation returns the (unacknowledged) receipts for sent sedex messages which are in a final state and were sent by the calling participant. The result contains at most the 200 oldest receipts. If there are more unprocessed receipts waiting, the newer ones will become visible only after the older ones are acknowledged.
Considerations¶
- The result contains at most the 200 oldest receipts. * Receipts must be read and processed by the sender.
- If a sending business application has processed a receipt, it must acknowledge it.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
for-all-messaging-interfaces |
query | boolean | No | Optional: Include receipts for messages sent using any interface (file system outbox and REST-API). By default only messages sent via the REST-API are included. (*Example:* true) | |
message-type |
query | integer | No | Optional: The message type to which to limit the response. (*Example:* 4711) | |
sender-id |
query | string | No | Optional: The sedex ID of the sending participant to which to limit the response. (*Example:* 1-123-1) |
Response 200 OK
{
"receipt-list": [
{
"event-date": "2022-04-13T15:42:05.901Z",
"status-code": 290,
"status-info": "string",
"unique-sedex-message-id": 129,
"message-id": "string",
"message-type": 74,
"message-class": 197,
"messaging-interface": "string",
"sender-id": "string",
"recipient-id": "string"
}
]
}
Schema of the response body
{
"type": "object",
"properties": {
"receipt-list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Receipt"
}
}
}
}
Response 429 Too Many Requests
Response 404 Not Found
Response 503 Service Unavailable
PUT /api/sedex/messaging/v1/send/receipts/acknowledge¶
Send step 5: Acknowledge that a receipt has been processed by the sending business application.
Description
Description¶
Acknowledges one or more receipts that have been processed by the sending business application. Once a receipt has been acknowledged, it no longer appears in the list of receipts.
Considerations¶
- If a sending business application has processed a receipt, it must acknowledge it.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
Request body
[
{
"unique-sedex-message-id": 2036412,
"recipient-id": "1-123-1"
},
{
"unique-sedex-message-id": 2036639,
"recipient-id": "1-123-1"
}
]
Schema of the request body
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceiptAcknowledgmentRequest"
}
}
Response 200 OK
{
"succeeded": 135,
"failed": 163,
"acknowledgment-recording-result-per-recipient": [
{
"unique-sedex-message-id": 139,
"recipient-id": "string",
"status": "SUCCESSFUL",
"status-message": "string"
}
]
}
Schema of the response body
{
"type": "object",
"properties": {
"succeeded": {
"type": "integer",
"format": "int64"
},
"failed": {
"type": "integer",
"format": "int64"
},
"acknowledgment-recording-result-per-recipient": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReceiptAcknowledgmentResult"
}
}
}
}
Response 400 Bad Request
Response 503 Service Unavailable
[ Receive ]¶
GET /api/sedex/messaging/v1/receive/messages¶
Receive step 1: Get a (filtered, paginated) list of unique-sedex-message-ids referencing unprocessed incoming messages.
Description
Description¶
Get a (filtered and paginated) list of unique-sedex-message-id
referencing sedex messages that have not yet been finally processed by the
receiving client (i.e. business application).
Pagination¶
The result is automatically paginated (i.e. the result can extend over more than one page if it contains a lot of elements).
Pagination prevents the technical problems that can occur when transferring results that are too large. In addition, pagination allows the client application to process the data chunk by chunk.
Pagination can be explicitly controlled by the client using the page-
number and page-size parameters (see parameter description for
details). If these request parameters are not explicitly set by the client,
the first page of the result is delivered (see parameter description for the
default page-size).
The pagination values actually applied to a result can be taken from the
result's meta-data.pagination subfields.
Filter¶
Optionally, the list can be filtered by setting the following query
parameters:
* sender-id
* recipient-id
* message-type
Considerations¶
- Depending on the processing strategy of the receiving business application, you can also consider requesting a list of envelopes of the incoming messages right from the start with the alternative operation.
- Important security note: In a next step, the receiving business application should fetch and check the corresponding envelope for each unique-sedex-message-id to be processed. Only after successful validation of the envelope should a payload be downloaded and processed at all.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
message-type |
query | integer | No | Optional: The message type to which to limit the response. (*Example:* 4711) | |
page-number |
query | integer | 1 | No | Optional: Selects a specific page of the paginated result. (*Example:* 2) |
page-size |
query | integer | 1000 | No | Optional: Defines the page size of the paginated result. (*Example:* 20) |
recipient-id |
query | string | No | Optional: The sedex ID of the recipient to which to limit the response. (*Example:* 1-123-1) | |
sender-id |
query | string | No | Optional: The sedex ID of the sender to which to limit the response. (*Example:* 1-123-1) |
Response 200 OK
{
"documentType": "message-ids-response",
"document-version": "1.0",
"meta-data": {
"has-more-pages": true,
"page-number": 144,
"min-page-number": 79,
"max-page-number": 104,
"page-size": 149,
"min-page-size": 273,
"max-page-size": 71,
"page-element-count": 239,
"total-element-count": 7,
"applied-filter-criteria": {
"recipient-id": "1-123-1"
}
},
"unique-sedex-message-ids": "{ 202114852, 202114853 }"
}
Schema of the response body
{
"required": [
"document-version",
"documentType"
],
"type": "object",
"properties": {
"documentType": {
"type": "string",
"example": "message-ids-response"
},
"document-version": {
"type": "string",
"example": "1.0"
},
"meta-data": {
"$ref": "#/components/schemas/FilteredListMetaData"
},
"unique-sedex-message-ids": {
"type": "array",
"description": "List of ExtendedEnvelopes (envelopes supplemented by the MessageID).",
"example": "{ 202114852, 202114853 }",
"items": {
"type": "integer",
"description": "List of ExtendedEnvelopes (envelopes supplemented by the MessageID).",
"format": "int64"
}
}
},
"description": "Data structure with the result of a query for the message Ids of incoming messages."
}
GET /api/sedex/messaging/v1/receive/messages/envelopes¶
Alternative receive step 1: Get a (filtered, paginated) list of envelopes of unprocessed incoming messages.
Description
Description¶
Get a (filtered and paginated) list of envelopes of sedex messages that have not yet been finally processed by the receiving client (i.e. business application).
The sedex envelope contains the metadata for a sedex message. The following fields are part of the sedex envelope: * sender-id: sedex participant ID of the sender (ex: 1-123-1). * recipient-ids: one or more sedex participant IDs of the addressees (ex: 1-123-1) * message-type: number of the message type (business case specific and specified by authorities) * message-class: number of the class of message, in most cases 0 * message-id: a unique reference message ID assigned by the sender (must be unique across all its messages) * message-date: creation date of the sedex message (the maximum lifetime of the message is this date +30 days) * event-date*: a business case specific date assigned by the sending application
Pagination¶
The result is automatically paginated (i.e. the result can extend over more than one page if it contains a lot of elements).
Pagination prevents the technical problems that can occur when transferring results that are too large. In addition, pagination allows the client application to process the data chunk by chunk.
Pagination can be explicitly controlled by the client using the page-
number and page-size parameters (see parameter description for
details). If these request parameters are not explicitly set by the client,
the first page of the result is delivered (see parameter description for the
default page-size).
The pagination values actually applied to a result can be taken from the
result's meta-data.pagination subfields.
Filter¶
Optionally, the list can be filtered by setting the following query
parameters:
* sender-id
* recipient-id
* message-type
Considerations¶
- Important security note: In a next step, the receiving business application should check the corresponding envelope for each unique-sedex- message-id to be processed. Only after successful validation of the envelope should a payload be downloaded and processed at all.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
message-type |
query | integer | No | Optional: The message type to which to limit the response. (*Example:* 4711) | |
page-number |
query | integer | 1 | No | Optional: Selects a specific page of the paginated result. (*Example:* 2) |
page-size |
query | integer | 200 | No | Optional: Defines the page size of the paginated result. (*Example:* 20) |
recipient-id |
query | string | No | Optional: The sedex ID of the recipient to which to limit the response. (*Example:* 1-123-1) | |
sender-id |
query | string | No | Optional: The sedex ID of the sender to which to limit the response. (*Example:* 1-123-1) |
Response 200 OK
{
"document-type": "envelopes-response",
"document-version": "1.0",
"meta-data": {
"has-more-pages": true,
"page-number": 178,
"min-page-number": 274,
"max-page-number": 183,
"page-size": 50,
"min-page-size": 112,
"max-page-size": 101,
"page-element-count": 298,
"total-element-count": 249,
"applied-filter-criteria": {
"recipient-id": "1-123-1"
}
},
"envelopes": [
{
"unique-sedex-message-id": 2036412,
"envelope": {
"document-type": "envelope",
"document-version": "1.0",
"sender-id": "1-123-1",
"recipient-ids": [
"1-123-1"
],
"message-type": 4711,
"message-class": 0,
"message-id": "08989cf0-d239-47a9-8cb0-54cd8be5e62d",
"reference-message-id": "string",
"message-date": "2022-04-13T15:42:05.901Z",
"event-date": "2022-04-13T15:42:05.901Z",
"loopback": false,
"test-data": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
}
]
}
Schema of the response body
{
"required": [
"document-type",
"document-version"
],
"type": "object",
"properties": {
"document-type": {
"type": "string",
"example": "envelopes-response"
},
"document-version": {
"type": "string",
"example": "1.0"
},
"meta-data": {
"$ref": "#/components/schemas/FilteredListMetaData"
},
"envelopes": {
"type": "array",
"description": "List of ExtendedEnvelopes (envelopes supplemented by the MessageID).",
"items": {
"$ref": "#/components/schemas/ExtendedEnvelope"
}
}
},
"description": "Data structure with the result of a query for the envelopes of incoming messages."
}
GET /api/sedex/messaging/v1/receive/message/{unique-sedex-message-id}/envelope¶
Optional receive step 2: Receive the envelope of a specific message.
Description
Description¶
Returns the envelope of the sedex message with the given unique-sedex-
message-id.
The sedex envelope contains the metadata for a sedex message. The following fields are part of the sedex envelope: * sender-id: sedex participant ID of the sender (ex: 1-123-1). * recipient-ids: one or more sedex participant IDs of the addressees (ex: 1-123-1) * message-type: number of the message type (business case specific and specified by authorities) * message-class: number of the class of message, in most cases 0 * message-id: a unique reference message ID assigned by the sender (must be unique across all its messages) * message-date: creation date of the sedex message (the maximum lifetime of the message is this date +30 days) * event-date*: a business case specific date assigned by the sending application
Considerations¶
- If the alternative step 1 was used, a list with the complete envelopes is already available. In this case, retrieving the individual envelopes again using this operation is normally not necessary.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
unique-sedex-message-id |
path | integer | No | The unique-sedex-message-id of the message for which the envelope is requested. (*Example:* 2036412) |
Response 404 Not Found
Response 200 OK
{
"document-type": "envelope",
"document-version": "1.0",
"sender-id": "1-123-1",
"recipient-ids": [
"1-123-1"
],
"message-type": 4711,
"message-class": 0,
"message-id": "08989cf0-d239-47a9-8cb0-54cd8be5e62d",
"reference-message-id": "string",
"message-date": "2022-04-13T15:42:05.901Z",
"event-date": "2022-04-13T15:42:05.901Z",
"loopback": false,
"test-data": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
Schema of the response body
{
"required": [
"document-type",
"document-version",
"event-date",
"message-class",
"message-date",
"message-id",
"message-type",
"recipient-ids",
"sender-id"
],
"type": "object",
"properties": {
"document-type": {
"pattern": "envelope",
"type": "string",
"example": "envelope"
},
"document-version": {
"pattern": "\\d+\\.\\d+",
"type": "string",
"description": "Version of the document.",
"example": "1.0"
},
"sender-id": {
"type": "string",
"description": "sedexID of the sender of the message.",
"example": "1-123-1"
},
"recipient-ids": {
"type": "array",
"description": "List of sedexIDs of the recipients of the message.",
"example": [
"1-123-1"
],
"items": {
"type": "string",
"description": "List of sedexIDs of the recipients of the message.",
"example": "[\"1-123-1\"]"
}
},
"message-type": {
"maximum": 2699999,
"minimum": 0,
"type": "integer",
"description": "The message type specifies what the semantics of the message data is and to which business process it belongs.",
"format": "int64",
"example": 4711
},
"message-class": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer",
"description": "Defines the meaning of the message within a message type in the context of the business process. The following values are predefined:\n0 = Message. Indicates the initial message.\n1 = Response. Indicates the response to a message.\n2 = Receipt. Indicates an application acknowledgement (receipt) that a receiving application sends to the sending application. Such an acknowledgement may be sent if a longer period of time can elapse before a response is delivered, or if the recipient will not send a response at all.\n3 = Error. Indicates an error message that a receiving application sends to the sending application.",
"format": "int64",
"example": 0
},
"message-id": {
"pattern": "([a-zA-Z]|[0-9]|-){1,36}",
"type": "string",
"description": "Unique ID of the message. This ID is assigned by the sending application. The messageId must be unique in the context of the application.",
"example": "08989cf0-d239-47a9-8cb0-54cd8be5e62d"
},
"reference-message-id": {
"pattern": "([a-zA-Z]|[0-9]|-){1,36}",
"type": "string",
"description": "This element is set by an application when it sends a response or an error message to another application in response to a message. The element contains the message ID of the original message sent."
},
"message-date": {
"type": "string",
"description": "The creation date of the sedex message (the maximum lifetime of the message is this date +30 days).",
"format": "date-time"
},
"event-date": {
"type": "string",
"description": "A business case specific date assigned by the sending application.",
"format": "date-time"
},
"loopback": {
"type": "boolean",
"description": "If the sender marks a message as loopback=true, the message is only used for an end-to-end reachability test including authorization. However, the message is not delivered to the receiver.",
"example": false
},
"test-data": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Test data allows the transport of optional customer-specific metadata in the form of key/value pairs in a map. Usually not used.",
"example": "{\"Optional test data key 1\":\"test-value 1 (normally test-data is not used)\",\"Optional test data key 2\":\"test-value 2\"}"
},
"description": "Test data allows the transport of optional customer-specific metadata in the form of key/value pairs in a map. Usually not used.",
"example": {
"Optional test data key 1": "test-value 1 (normally test-data is not used)",
"Optional test data key 2": "test-value 2"
}
}
},
"description": "The envelope contains the relevant metadata for a sedex message such as sender, recipient etc."
}
GET /api/sedex/messaging/v1/receive/message/{unique-sedex-message-id}/payload¶
Receive step 3: Receive the payload of a specific message.
Description
Description¶
Returns the payload of the sedex message with the given unique-sedex-
message-id.
If the original file name of the payload is relevant for its processing
(e.g. to determine the file extension), it can be taken from the HTTP header
field X-payload-name.
Considerations¶
- Important security note: Before the receiving client (i.e. receiving business application) downloads or processes the payload data, it should check the metadata in the associated envelope. In particular, it should ensure that the sender as well as the message type of the message match the expected values. And only then the receiver should download and process the payload.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
unique-sedex-message-id |
path | integer | No | The unique-sedex-message-id of the message for which the payload is requested. |
Response 404 Not Found
Response 200 OK
"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
Schema of the response body
{
"type": "string",
"description": "chunked",
"format": "byte"
}
DELETE /api/sedex/messaging/v1/receive/message/{unique-sedex-message-id}¶
Receive step 4: Delete a processed message.
Description
Description¶
Deletes an incoming sedex message with the given unique-sedex-message-
id.
Considerations¶
- The receiving client (i.e. receiving business application) should delete a sedex message as soon as it has read and processed the incoming message completely.
- Deleting a message causes the message to disappear from the list of sedex messages that still need to be processed.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
basicAuth |
header | string | N/A | No | Basic authentication |
unique-sedex-message-id |
path | integer | No | The unique-sedex-message-id of the message to be deleted. (*Example:* 2036412) |
Response 404 Not Found
{
"message": "string"
}
Schema of the response body
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A message decribing the success."
}
},
"description": "Data structure used to return information about a successful execution back to the caller of the API."
}
Response 200 OK
{
"message": "string"
}
Schema of the response body
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A message decribing the success."
}
},
"description": "Data structure used to return information about a successful execution back to the caller of the API."
}
Schemas¶
AggregateStatusDetails¶
| Name | Type |
|---|---|
completed-at |
string(date-time) |
delivery |
string |
last-status-change |
string(date-time) |
registered-at |
string(date-time) |
status |
string |
ApiError¶
| Name | Type |
|---|---|
developer-message |
string |
error |
string |
message |
string |
path |
string |
status |
integer(int32) |
timestamp |
string(date-time) |
ApiSuccess¶
| Name | Type |
|---|---|
message |
string |
AuthorisationResult¶
| Name | Type |
|---|---|
authorization-code |
integer(int64) |
authorization-info |
string |
is-authorized |
boolean |
CurrentStatus¶
| Name | Type |
|---|---|
overall |
AggregateStatusDetails |
status-per-recipient |
Array<StatusDetailsPerRecipient> |
Envelope¶
| Name | Type |
|---|---|
document-type |
string |
document-version |
string |
event-date |
string(date-time) |
loopback |
boolean |
message-class |
integer(int64) |
message-date |
string(date-time) |
message-id |
string |
message-type |
integer(int64) |
recipient-ids |
Array<string> |
reference-message-id |
string |
sender-id |
string |
test-data |
Example: {'Optional test data key 1': 'test-value 1 (normally test-data is not used)', 'Optional test data key 2': 'test-value 2'} |
EnvelopesResponse¶
| Name | Type |
|---|---|
document-type |
string |
document-version |
string |
envelopes |
Array<ExtendedEnvelope> |
meta-data |
FilteredListMetaData |
ExtendedEnvelope¶
| Name | Type |
|---|---|
envelope |
Envelope |
unique-sedex-message-id |
integer(int64) |
FilteredListMetaData¶
| Name | Type |
|---|---|
applied-filter-criteria |
Example: {'recipient-id': '1-123-1'} |
has-more-pages |
boolean |
max-page-number |
integer(int64) |
max-page-size |
integer(int64) |
min-page-number |
integer(int64) |
min-page-size |
integer(int64) |
page-element-count |
integer(int64) |
page-number |
integer(int64) |
page-size |
integer(int64) |
total-element-count |
integer(int64) |
MessageAuthorisationResult¶
| Name | Type |
|---|---|
overall |
AuthorisationResult |
per-recipient |
MessageIdsResponse¶
| Name | Type |
|---|---|
document-version |
string |
documentType |
string |
meta-data |
FilteredListMetaData |
unique-sedex-message-ids |
Array<integer(int64)> |
Payload¶
| Name | Type |
|---|---|
size-in-bytes |
integer(int64) |
PayloadUploadRequest¶
| Name | Type |
|---|---|
payloadFile |
string(binary) |
PreCheckResponse¶
| Name | Type |
|---|---|
allowed-to-send |
boolean |
document-type |
string |
document-version |
string |
message-authorisation-result |
MessageAuthorisationResult |
Receipt¶
| Name | Type |
|---|---|
event-date |
string(date-time) |
message-class |
integer(int64) |
message-id |
string |
message-type |
integer(int64) |
messaging-interface |
string |
recipient-id |
string |
sender-id |
string |
status-code |
integer(int64) |
status-info |
string |
unique-sedex-message-id |
integer(int64) |
ReceiptAcknowledgmentRequest¶
| Name | Type |
|---|---|
recipient-id |
string |
unique-sedex-message-id |
integer(int64) |
ReceiptAcknowledgmentResponse¶
| Name | Type |
|---|---|
acknowledgment-recording-result-per-recipient |
Array<ReceiptAcknowledgmentResult> |
failed |
integer(int64) |
succeeded |
integer(int64) |
ReceiptAcknowledgmentResult¶
| Name | Type |
|---|---|
recipient-id |
string |
status |
string |
status-message |
string |
unique-sedex-message-id |
integer(int64) |
ReceiptInformation¶
| Name | Type |
|---|---|
receipt-list |
Array<Receipt> |
RegistrationResponse¶
| Name | Type |
|---|---|
allowed-to-send |
boolean |
document-type |
string |
document-version |
string |
message-authorisation-result |
MessageAuthorisationResult |
unique-sedex-message-id |
integer(int64) |
StatusDetailsPerRecipient¶
| Name | Type |
|---|---|
delivered-at |
string(date-time) |
final-state-code |
integer(int64) |
final-state-information |
string |
last-status-change |
string(date-time) |
recipient-id |
string |
status |
string |
TrackingInformation¶
| Name | Type |
|---|---|
current-status |
CurrentStatus |
document-type |
string |
document-version |
string |
envelope |
Envelope |
payload |
Payload |
unique-sedex-message-id |
integer(int64) |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| basicAuth | http | basic |
Tags¶
| Name | Description |
|---|---|
| [ Send ] | #### Operations for the sender of a sedex message |
Sending a sedex message via the REST API is done in two steps:
-
Register envelope: In the first step, the envelope of the message must be registered. The result of the registration is a unique-sedex-message-id generated by sedex, which is used to uniquely identify this message.
-
Upload Payload: Once the envelope of a message has been registered, the payload of the message can be uploaded in a second step. The unique-sedex-message-id serves as a correlation feature between the envelope and the payload.
Evaluating receipts of sent messages¶
The sedex platform provides receipt(s) for each sedex message sent. The receipt informs the sending business application about the final status of a sedex message: Could it be successfully delivered to the recipient or did an error prevent delivery to the recipient?
It is mandatory that the sending business application regularly checks whether new receipts for sent messages are available. Unprocessed receipts must be processed by it and once processed receipts must be acknowledged. | | [ Receive ] | #### Operations for the receiver of a sedex message
Receiving a sedex message via the REST API is basically done in three steps:
-
Receive Envelope: The envelope of an incoming message must be read and evaluated by the receiving business application.
-
Receive Payload File: The associated payload file must be downloaded and processed by the receiving business application.
-
Delete message: Once the message has been processed, it must be deleted by the receiving business application. |