Integrate the B2B Exchange Partner API

Use the Partner API to submit EDIFACT ORDERS to one bound connection and to retrieve outbound ORDRSP, CONTRL, or APERAK messages from its mailbox. Versioning depends on the message type:

Message	Native contract
`ORDERS`, `ORDRSP`, `APERAK`	Directory D.96A or D.25A selected by the active profile revision
`CONTRL`	Service message 2.2 for syntax version 3 or service message 4.1 for syntax version 4

CONTRL is therefore not a D.96A/D.25A directory message. Each payload is limited to 16 MiB.

Read Work with EDIFACT as a developer when you first need to define EDIFACT byte handling, mapping paths, canonical fixtures, and the development test matrix. This page remains the technical reference for the Partner API contract.

The base route for a connection is:

text

/api/v1/b2b-exchange/partner/connections/{connectionID}

A partner may have multiple active api.v1 connections. Treat each concrete connectionID as a separate contract: it binds exactly its own inbox and outbound mailbox, not the mailboxes of other connections owned by the same partner.

Bind the API key and scopes

This path accepts only a fixed-tenant Workspace API key. Send it in the standard bearer format:

http

Authorization: Bearer <api-key-id>:<secret>

The API key must belong to the same identity and tenant as the active api.v1 connection. A session, client credential, wrong tenant, foreign connection, or missing scope is not an alternative.

Method and path	Exact scope
`POST /inbox`	`b2b_exchange_partner_inbox:create`
`GET /mailbox`	`b2b_exchange_partner_mailbox:list`
`POST /mailbox/{deliveryAttemptID}/claim`	`b2b_exchange_partner_mailbox:claim`
`GET /mailbox/{deliveryAttemptID}/payload`	`b2b_exchange_partner_mailbox:payload_read`
`POST /mailbox/{deliveryAttemptID}/acknowledge`	`b2b_exchange_partner_mailbox:acknowledge`

Use separate API keys when a client only uploads or only processes the mailbox. Store the secret in a secret manager, never in source code, a URL, a log, or an error message.

Submit `ORDERS` idempotently

POST/api/v1/b2b-exchange/partner/connections/{connectionID}/inbox

Send exactly one EDIFACT interchange as the unchanged request body:

http

POST /api/v1/b2b-exchange/partner/connections/<connection-id>/inbox HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>
Content-Type: application/edifact
Idempotency-Key: orders-4711-attempt-1

<EDIFACT bytes>

application/octet-stream is also accepted. Workspace stores the payload as application/edifact. Idempotency-Key is mandatory, has a maximum length of 200 characters, and accepts letters, digits, ., _, :, and - only.

Use the same key for every network retry of the same upload. Do not reuse it for a changed payload. The key is bound to the connection and tenant.

Result	HTTP status	Meaning
First complete upload	`202 Accepted`	Workspace stored the payload and accepted it for processing.
Replay of the same completed upload	`200 OK`	The response identifies the same upload and sets `replay` to `true`.
Oversized payload	`413 Payload Too Large`	The payload exceeds 16 MiB.
Invalid contract	`400 Bad Request`	Content type, idempotency key, or request contract is invalid.
Conflicting replay	`409 Conflict`	The key or current upload state does not match the retry.

The response contains uploadId, optional interchangeId, status, and replay. Store uploadId and interchangeId as technical correlations, not as the business order number.

List the mailbox with cursors

GET/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox

List due deliveries that are not currently claimed:

http

GET /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox?limit=50 HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

limit is optional, defaults to 50, and has a maximum of 100. When meta.hasMore is true, pass meta.nextCursor unchanged as the next request's cursor.

Each item contains:

deliveryAttemptId for claim, payload, and acknowledge,
interchangeId for correlation,
messageType,
payloadSize and payloadSha256,
status and createdAt.

Process entries in the returned order. An entry is hidden from the list while its claim is active.

Claim an entry

POST/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox/{deliveryAttemptID}/claim

http

POST /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox/<delivery-attempt-id>/claim HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

The response contains deliveryAttemptId, claimToken, and expiresAt. The claim is valid for five minutes. Workspace stores only the token hash. Keep the token in worker memory only; do not write it to a URL, queue payload, log, or persistent error record.

Use the same token for payload and acknowledge. If a worker lets the lease expire, the entry becomes due again in a controlled way or fails after the attempt budget is exhausted. Do not start a second claim attempt for the same entry while its lease is active.

Read and verify the complete payload

GET/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox/{deliveryAttemptID}/payload

http

GET /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox/<delivery-attempt-id>/payload HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

Also set the X-B2B-Claim-Token HTTP header to the token returned by claim.

The response is an EDIFACT byte stream with Cache-Control: no-store and these integrity fields:

Field	Meaning
`X-B2B-Payload-Size`	Expected byte count.
`X-B2B-Payload-SHA256`	Expected SHA-256 hash in hexadecimal.
Trailer `X-B2B-Payload-Integrity`	`verified` after a complete read; `failed` after interruption or mismatch.

Read the body to EOF. Count bytes and calculate SHA-256 while reading. Process the message only when size and hash match and the HTTP client sees the verified trailer after EOF. A successful status before EOF is insufficient.

Workspace audits both opening the stream and its verified or failed completion, without copying payload bytes or their hash into the audit log. A stream closed before EOF remains a failed read completion.

Acknowledge delivery

POST/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox/{deliveryAttemptID}/acknowledge

Acknowledge only after durable local storage and successful integrity checks:

http

POST /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox/<delivery-attempt-id>/acknowledge HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

Set the X-B2B-Claim-Token HTTP header to the same token here as well.

The response contains deliveryAttemptId, receiptId, acknowledgedAt, and replay. Retry acknowledge after an uncertain network failure with the same token. An already completed acknowledgement returns the same receipt contract with replay: true.

Do not acknowledge when download, EOF, size, hash, trailer, or local storage fails. Let the lease expire or follow the agreed operating procedure instead.

Handle errors without disclosure

Partner responses use stable codes and expose no internal database details, table names, file paths, host details, or raw driver errors.

HTTP status	Stable code	Client action
`400`	`ERR_B2B_EXCHANGE_INVALID_REQUEST`	Correct the request locally; do not retry it unchanged.
`404`	`ERR_B2B_EXCHANGE_NOT_FOUND`	Check the local connection ID, key binding, scope, claim, and lease; do not probe foreign IDs.
`409`	`ERR_B2B_EXCHANGE_CONFLICT`	Check idempotency or state transition and list again.
`413`	`ERR_B2B_EXCHANGE_PAYLOAD_TOO_LARGE`	Limit the payload to 16 MiB.
`503`	`ERR_B2B_EXCHANGE_UNAVAILABLE`	Retry with backoff and record correlation and time.
`500`	`ERR_B2B_EXCHANGE_INTERNAL`	Do not infer internals from the message; notify the operator with correlation.

Log only the HTTP status, stable code, your correlation, connectionID, deliveryAttemptID, and time. Never log the API key, claim token, or EDIFACT payload.

Implement the worker sequence

A robust mailbox worker always follows the same order:

List the mailbox with its cursor.
Claim one entry.
Read the payload to EOF with the claim token.
Verify byte count, SHA-256, and the integrity trailer.
Store and process the payload locally and idempotently.
Acknowledge with the same claim token.
Only then claim the next entry.

See Operate B2B Exchange for the administration and operations contract.