Set up an EDIFACT trading partner

This quickstart takes administrators and project owners from an agreed partner contract to an accepted ORDERS/ORDRSP connection. When complete, the partner can submit a test order through the selected connection and receive the expected responses in a verifiable way.

Use this quickstart only for the native contract: ORDERS, ORDRSP, and optional CONTRL/APERAK in D.96A or D.25A over the Partner API or SFTP. Read Understand and introduce EDI/EDIFACT first when the directory, syntax version, or acknowledgement type is not settled.

Check the prerequisites

You need:

a reachable Workspace server and a fixed tenant,
administration permissions for B2B Exchange partners, identifiers, connections, profiles, Commerce bindings, and messages,
a company, customer account, sales channel, and Commerce profile for the partner,
approved buyer, seller, and item identifiers,
at least one valid and one intentionally invalid test message,
for API, a fixed-tenant Partner API key,
for SFTP, a dedicated inbound store and verified credentials, plus the partner's independently verified host key fingerprint for outbound.

Check the administration context:

bash

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

See numin for the strict offline/online tool boundary. nucli remains the tenant-bound HTTP client; the server enforces permissions, tenancy, and business contracts.

1. Record the partner agreement

Create a versioned data sheet before configuring Workspace. Record the full contract, not only the word “EDIFACT”:

Topic	Example	What must be agreed
Business process	Purchase order and complete order response	Who sends which message and when?
Inbound message	`ORDERS:D:96A:UN`	Type, version, release, and controlling agency.
Outbound message	`ORDRSP:D:96A:UN`	Acceptance/rejection semantics and deadline.
Syntax	`UNOC`, syntax version 3	Character set, service characters, decimal mark, and release character.
Partner identifiers	GLN with qualifier `14`	Exact values and sender/recipient roles.
Document references	Buyer order number from `BGM`	Uniqueness, length, and reuse policy.
Item identifiers	GTIN, supplier SKU, or customer item number	Priority, qualifier, and fallback.
Quantities and units	Ordered quantity, `PCE`	Permitted codes, decimal places, and conversion.
Date and time	Document date and requested date	Qualifier, representation, and timezone rule.
Currency and prices	`EUR`, external reference price	Required status and mismatch handling. Workspace remains the price and tax authority.
Acknowledgements	Positive/negative `CONTRL`, `APERAK`	Which message is generated or expected?
Transport	Partner API or SFTP	Endpoints, owners, time windows, and retry rules.
Contacts	Business and technical	Escalation path for mapping, transport, and business failures.

Keep approved sample files byte-for-byte unchanged. Calculate SHA-256 for each file and record the partner-profile version it represents.

2. Select the transport

Decision	Partner API	SFTP
Choose it when	The partner can implement HTTPS, bearer key, idempotency, and a mailbox worker.	The partner uses file workflows and can operate an SFTP endpoint.
Inbound	Streaming upload for one connection ID.	Upload into a specifically bound Workspace store.
Outbound	Claim, integrity-checked download, and acknowledge.	Atomic publication on the destination server.
Security binding	Fixed-tenant API key with minimal partner scopes.	Inbound: store, identity, ACL, and API key; outbound: secret, host key pin, and destination policy.
Retry	Reuse the same idempotency key for identical bytes.	Reuse the same business message under the agreed file and retry policy.

Select one transport as the canonical acceptance path. A second transport needs a separate connection and transport acceptance; it does not create a new mapping automatically.

3. Prepare master data and identifiers

Before sending the first message, verify that:

stable identifiers distinguish buyer and seller,
every expected item reference resolves to exactly one active item in the agreed Commerce context,
units and currency match the Commerce profile,
delivery and billing context are understood, and
prices and taxes are not copied from EDIFACT without validation.

Do not use production identifiers in public samples. Use dedicated demo identifiers that are inactive in every other partner contract.

4. Create the Workspace contract as a draft

Create the objects in this order and keep them inactive or in draft:

The complete fields, permissions, and connection contracts are documented in Operate B2B Exchange. In particular:

the ORDERS profile is inbound; the ORDRSP profile is outbound,
the Commerce binding references the inbound ORDERS profile,
D.96A uses syntax version 3 and D.25A uses syntax version 4 in the native contract,
activated revisions are immutable; create a new revision for a change, and
an active connection binds exactly the intended partner and transport context.

5. Verify mapping fixtures

Create reproducible evidence for each profile revision:

Revision	Input	Expected result
Inbound `ORDERS`	Unchanged EDIFACT file	Valid canonical `SalesOrderRequestV1` JSON.
Outbound `ORDRSP`	Canonical `OrderResponseV1` JSON	Unchanged expected EDIFACT file.
Negative syntax case	Intentionally invalid EDIFACT file	`ERR_B2B_EXCHANGE_FIXTURE_SYNTAX`.
Negative mapping case	Syntactically valid file that lacks the mapping contract	`ERR_B2B_EXCHANGE_FIXTURE_MAPPING`.

Store input and expected results as authorized Storage objects and submit their actual SHA-256 hashes. Start verification through the revision fixture endpoint. A valid case must reach verificationStatus: "succeeded". A negative case succeeds only when the observed stable error code exactly matches the expected code.

A fixture proves mapping and output for that revision. It does not prove the transport, product master data, or Commerce application.

6. Activate and run the pilot

After all fixture checks succeed, activate:

the partner,
the current ORDERS and ORDRSP revisions, which activates their profiles,
the exact connection, and
the Commerce binding.

Run at least these cases over the real acceptance transport:

Pilot case	Expected result
Valid order	Exactly one Commerce order and one business decision.
Identical network retry	No second order and no second business response.
Same idempotency key with different bytes	Controlled conflict and no business effect.
Syntax failure	No Commerce effect; syntax status and, when configured, `CONTRL` show rejection.
Mapping failure	No Commerce effect; mapping status and, when configured, `APERAK` show rejection.
Unknown item or business difference	Behaviour follows `automatic`, `review_on_difference`, or `manual`.
Outbound response	Recipient verifies complete bytes, references, and control numbers.
Unauthorized request	No payload and no disclosure about foreign partner or connection IDs.

For API tests, follow Integrate the B2B Exchange Partner API. For SFTP, also verify the host key, destination path, atomic publication, and the agreed inbound filename handling.

7. Record acceptance

For each test case, record:

partner-profile and Workspace profile-revision numbers,
transport and connection ID,
your own test-case reference,
SHA-256 and size of sent or received bytes,
interchange and message reference,
transport, syntax, mapping, application, and acknowledgement status,
business result and approval by both partners.

Do not put API keys, passwords, claim tokens, or complete production messages into the acceptance record.

Recognize success

The setup is complete when:

all active objects belong to the correct tenant and partner,
every active revision has successful positive and negative fixture evidence,
the pilot used the real transport,
a retry creates no second Commerce effect,
CONTRL, APERAK, and ORDRSP follow the agreed policy,
both partners accepted bytes, references, statuses, and escalation path, and
an owner has accepted monitoring and operations.

Continue with Operate B2B Exchange to monitor status, review, retries, and failure handling.