Operate B2B Exchange

B2B Exchange receives EDIFACT orders from a trading partner in Workspace and returns the corresponding order response. This operating contract has no administration UI. Configure it through authorized server APIs and use nucli as the tenant-bound HTTP client when needed.

The current scope is deliberately narrow:

Read Understand and introduce EDI/EDIFACT when you first need to separate the standard, directory, and partner profile. For a new partner onboarding, Set up an EDIFACT trading partner provides a compact acceptance sequence before you use this detailed operations contract.

Understand the processing path

Workspace tracks transport, syntax, mapping, application, and acknowledgement status separately. A successful upload therefore does not prove that the order was applied or that the response was delivered.

Prepare permissions

Grant administrators only the required actions on these permission families:

• b2b_exchange_partners
• b2b_exchange_identifiers
• b2b_exchange_connections
• b2b_exchange_commerce_bindings
• b2b_exchange_profiles, including activate
• b2b_exchange_messages for list, read, review, retry, cancel, and payload access

The action follows the colon, for example b2b_exchange_connections:create. Verify the active tenant and scopes before making a change:

nucli --tenant <tenant> whoami
nucli --tenant <tenant> scopes
nucli --tenant <tenant> api GET /api/v1/b2b-exchange/partners --summary

Pass mutation bodies to nucli api with --input <file> or --input -.

Create the configuration in a stable order

Create the partner and commerce binding as inactive and create connections and profiles as drafts. Do not run live or transport tests against these states. Activate the complete contract first, then start testing and acceptance.

An activated revision is immutable. Create and activate a new revision when a mapping or acknowledgement policy changes. Use inbound for ORDERS and outbound for ORDRSP. The current W2 contract supports automatic, review_on_difference, and manual as application policies.

Verify fixture evidence

Create at least one fixture evidence record for each revision at /api/v1/b2b-exchange/profiles/{profileID}/revisions/{revisionID}/fixtures/. Reference existing authorized, tenant-bound Storage objects and provide their SHA-256 hashes. The fixture endpoint neither accepts nor returns payload bytes.

• For inbound ORDERS, inputStorageObjectId contains EDIFACT and expectedStorageObjectId contains the expected canonical JSON order.
• For outbound ORDRSP, inputStorageObjectId contains the canonical JSON response and expectedStorageObjectId contains the expected EDIFACT document.
• For expectedOutcome: "valid", provide the expected object and its hash. Leave expectedErrorCode empty.
• For expectedOutcome: "rejected", do not provide an expected object. Use only ERR_B2B_EXCHANGE_FIXTURE_SYNTAX or ERR_B2B_EXCHANGE_FIXTURE_MAPPING as expectedErrorCode.

New evidence has verificationStatus: "pending". Start deterministic verification with POST .../fixtures/{fixtureID}/verify. The result is terminal:

• succeeded without observedErrorCode confirms a valid fixture case.
• succeeded with an observedErrorCode equal to the expected code confirms an expected rejection case.
• failed permanently records the stable error code actually observed and verifiedAt. Delete the evidence and create a corrected record; you cannot verify the same evidence again.

Activation remains blocked when evidence is absent, has not succeeded, or its expected and observed results differ. After activation, you cannot change or delete the revision or its fixture evidence. Fixture verification proves only the mapping contract; run transport and live acceptance separately afterwards.

Verify unambiguous cardinality before activation

Each active partner must have exactly this active topology:

A second active profile binding remains invalid. Multiple API connections and multiple SFTP inbound connections with different tuples are valid. The transport contract becomes ambiguous only with a duplicate active SFTP inbound tuple or more than one active SFTP outbound connection for the same partner.

Configure a Partner API connection

A Partner API connection uses these fixed values:

A partner may have multiple active API connections. Every request addresses a concrete connection ID; that exact connection binds both its inbox and its outbound mailbox.

The API connection does not accept credential, signing, or encryption secret IDs. Issue a fixed-tenant API key for the bound partner identity with only the required partner scopes. See Integrate the B2B Exchange Partner API for the integration contract.

Configure SFTP inbound

SFTP inbound uses the existing storage-bound SFTP listener. The connection resolves a successful upload through its identity and store:

Activate exactly one SFTP inbound connection for each (Tenant, PartnerIdentityID, InboundStoreID) tuple. Multiple active inbound connections with different tuples are permitted. Prepare the storage account completely:

1. Create a tenant-bound store and enable its sftp.enabled setting.
2. Grant the identity bound by partnerIdentityId an Editor ACL on the StorageStore resource for that exact store.
3. Issue an active fixed-tenant API key for the same identity. Both its requested scopes and its effective role scopes must contain storage_object:create.
4. Use the same store as inboundStoreId and activate exactly one SFTP inbound connection for this identity/store binding.

The SFTP listener uses these canonical credentials:

Other identity, tenant, store, or scope combinations do not resolve to a B2B connection. Other SSH login methods are outside this inbound contract. The username/password rule above is the canonical SFTP login contract for B2B Exchange.

Secure SFTP outbound

SFTP outbound uses transport: "sftp" and adapterKey: "sftp.outbound.v1". Keep only public connection metadata in configuration:

{
  "host": "sftp.partner.example",
  "port": 22,
  "remoteDirectory": "/outbound/orders",
  "hostKeySHA256": "SHA256:<verified-fingerprint>",
  "connectTimeoutSeconds": 10,
  "operationTimeoutSeconds": 45
}

The following constraints apply:

• port is fixed at 22.
• hostKeySHA256 is mandatory. Verify the SHA-256 fingerprint through a separate trusted channel.
• connectTimeoutSeconds must not exceed 30, and operationTimeoutSeconds must not exceed 120.
• remoteDirectory must be an absolute normalized path without traversal segments.
• The destination server must provide the SFTP extension posix-rename@openssh.com. Delivery fails when it is unavailable.
• The adapter writes an exclusive temporary file, publishes it only through posix-rename@openssh.com, and then verifies the final size and SHA-256 hash.

credentialSecretId must reference a closed JSON object in the tenant-bound secret store. Only these two forms are accepted:

Unknown fields or data appended after the JSON object cause an error. The complete JSON must not exceed 256 KiB. username is required, contains 1 to 128 UTF-8 bytes, and must contain no leading or trailing spaces, null bytes, or line breaks. For type password, the field with the same name is required, non-empty, and limited to 4096 UTF-8 bytes. For type private_key, privateKey must contain non-empty SSH credential material. Never place the username, a password, SSH credential material, or a passphrase in configuration, logs, tickets, or nucli command lines.

Private destinations are blocked by default. Only an operator with global configuration permission can allow selected private CIDR ranges through the locked b2b_exchange.sftp.outbound.allowed_private_cidrs setting. A tenant or connection cannot broaden this allowlist. Special-purpose destinations and mixed public/private DNS answers stay blocked, and the adapter pins the validated destination address for the connection.

Monitor and operate messages

Use the messages API for the operational lifecycle:

nucli --tenant <tenant> api GET '/api/v1/b2b-exchange/messages?limit=50' --summary
nucli --tenant <tenant> api GET /api/v1/b2b-exchange/messages/<interchange-id> --summary

Inspect every status axis independently:

Use operations deliberately:

• POST /api/v1/b2b-exchange/messages/{interchangeID}/retry schedules a new controlled attempt for a failed process.
• POST /api/v1/b2b-exchange/messages/{interchangeID}/cancel stops a process that can still be cancelled.
• POST /api/v1/b2b-exchange/messages/{interchangeID}/review approves or rejects a message that requires business review. Send its messageId, use approve without a reason code, or reject with a stable reason code.
• GET /api/v1/b2b-exchange/messages/{interchangeID}/payload requires the separate payload-read scope and creates audit records.

Do not retry blindly. Inspect the stable error code, status axes, profile revision, partner binding, and destination connection first. A retry preserves the business identity of the process; it does not replace corrected configuration.

Diagnose failures safely

The API returns stable ERR_B2B_EXCHANGE_* codes and deliberately excludes raw SQL, storage, network, and cryptographic errors. Treat this reduction as a security contract.

Never copy a raw server error into a partner response. Share only the stable code, your own correlation, and the next safe action.

Accept the operation

The contract is ready for operation when:

• partner, identifier, exactly assigned connections, commerce binding, and the active ORDERS and ORDRSP profile revisions belong to the correct tenant,
• one test interchange for each active directory and syntax configuration passes through the expected states only after the complete activation,
• duplicates create neither a second commerce order nor a second business ORDRSP,
• CONTRL and APERAK follow the active acknowledgement policy,
• the Partner API verifies payload size, hash, and completion or SFTP confirms the atomically published file, and
• unauthorized requests disclose no foreign partner, connection, or payload information.

Developers can continue with Work with EDIFACT as a developer for mapping, fixture, and test conventions or Integrate the B2B Exchange Partner API for the complete Partner API contract.