InboxOutbox API v3

This guide documents the v3 Inbox and Outbox API. This will be available in Link in the first version after 3.0.9741.18968.

Authorization

Partner selection has additional rules. A user associated with a Link partner is restricted to that partner. A user without an associated partner needs permision AllowSendFromMultiplePartners to specify an Inbox sender, or AllowGetFromMultiplePartners to select Outbox receiver. For Outbox, a user with the latter permission can leave receiver identifications empty to retrieve data matching any receiver (subject to other request filters).

Inbox

Send a message

To send metadata with a message, first request a configuration token, then submit the message payload with that token in the Inbox-Config-Token header. The token request is JSON; the push request body is the message itself and may be any supported content type. The token can be omitted when the caller is permitted to send based on message content.

POST /api/transport/inbox/v3/get-inbox-token
Content-Type: application/json

{
    "fileName": "order.xml",
    "documentType": "Order",
    "receiverPartnerIdentifications": [
        { "qualifier": "GLN", "value": "5790000000000" }
    ]
}

The response is the token as plain text.

Send the payload using the token returned above:

POST /api/transport/inbox/v3/push-to-inbox
Content-Type: application/xml
Inbox-Config-Token: <token>

<Order>...</Order>

Inbox routes

The token endpoint requires API_Transport_SendInterchange and returns text/plain. The push endpoint requires the same permission and returns the Inbox response as JSON. Inbox-Config-Token is optional; without it, the user must have AllowSendFromMultiplePartners. The additional-file endpoint accepts the file bytes as its body and optional file-name, content-type, file-type, and note headers.

Outbox

V3 separates selecting work from downloading payloads. Reserve first, download each reserved interchange, then confirm its state. A reservation prevents other clients from retrieving those interchanges until it expires or is confirmed. Its duration is configured by the server; the status documentation reports the current value. Persist the downloaded payload before confirming it as received, because that confirmation removes it from the outbox.

POST /api/transport/outbox/v3/reserve-from-outbox
Content-Type: application/json

{
    "transportTypeName": "Sftp",
    "transportLocationName": "Partner SFTP",
    "documentTypeName": "Order",
    "maxNumberOfFiles": 10
}

transportTypeName is required. transportLocationName, documentTypeName, receiverPartnerIdentifications, senderPartnerIdentifications, and maxNumberOfFiles are optional. If omitted, maxNumberOfFiles defaults to one. Each identification has qualifier and value. The response contains an interchanges array; each entry includes meta-data about the interchange. But most importantly is the interchangeId.

Download each reserved payload using its ID. The response body is the payload itself and may be JSON, XML, or another format; it is not necessarily a JSON response.

GET /api/transport/outbox/v3/get-from-outbox/{interchangeId}

Persist the payload before confirming receipt. confirm-received removes it from the Outbox, so clients must be able to resume processing from their persisted copy.

After persisting the payload, confirm receipt. Once processing finishes, confirm delivery or failure. If processing should be retried later, mark the interchange for redelivery instead. The confirmation request bodies are optional. Received and delivered confirmations may include technicalStatuses; failed confirmations may also include errorMessage and errorCode. Each technical status has a required statusName and optional comment. Include custom statuses only when agreed upon. Server-reserved status names are rejected.

POST /api/transport/outbox/v3/confirm-received/{interchangeId}
Content-Type: application/json

{
    "technicalStatuses": [
        { "statusName": "Persisted", "comment": "Stored in the receiving system" }
    ]
}

For successful processing, call POST /api/transport/outbox/v3/confirm-delivered/{interchangeId}. For an unsuccessful processing result, call POST /api/transport/outbox/v3/confirm-failed/{interchangeId} with an optional body such as:

{
    "errorMessage": "The document failed validation",
    "errorCode": "DU58D",
}

To return an interchange to the queue, call POST /api/transport/outbox/v3/mark-for-redelivery/{interchangeId}. The confirmation and redelivery endpoints return a JSON object with a message property.

Outbox routes

The Outbox additional-file endpoint accepts file bytes as its body and optional file-name, content-type, file-type, and note headers. It returns a JSON object with a message property. All Outbox operations require API_Transport_GetFromOutbox permission.