EDI Quickstart

Validate approved test wire, process it deliberately, and inspect the recorded document and acknowledgment.

Use an existing test partner and a scoped document-processing key from your workspace. Complete onboarding first if needed. Processing can enqueue external effects; use a fixture without external transport or event destinations for local-only work.

Prerequisites: a test relationship, agreed envelope identifiers, representative X12 or EDIFACT wire, and a scoped key. Outcome: one inspected processing result with its document identity and acknowledgment. Downstream acceptance needs separate evidence.

Configure the connection

Load your scoped key into EDI_API_TOKEN through your secret store.

export EDI_API_BASE=https://api.edi.stateset.com
export EDI_PARTNER_ID=your-test-partner

curl --silent --show-error --fail-with-body \
  "$EDI_API_BASE/v1/partners" \
  --header "Authorization: Bearer ${EDI_API_TOKEN:?Load your workspace key}"

Listing partners needs tenant-level inspection access. Partner-scoped integrations should read their own partner route. Match the interchange’s IDs and test indicator to the saved partner configuration.

Validate before processing

Save approved wire as partner-test-order.edi, preserving its bytes. Validation detects X12 or EDIFACT and checks the current guide without creating an order or queuing delivery.

curl --silent --show-error --fail-with-body \
  "$EDI_API_BASE/v1/edi/validate/$EDI_PARTNER_ID" \
  --header "Authorization: Bearer $EDI_API_TOKEN" \
  --header 'Content-Type: application/edi-x12' \
  --data-binary @partner-test-order.edi \
  --output validation.json

Inspect data.valid, structural errors, and per-document findings. HTTP success does not mean validation passed. For EDIFACT use Content-Type: application/EDIFACT. The separate /v1/edi/parse route is an X12 debugging operation.

Submit the approved interchange once

Confirm configured event, transport, and automatic-855 effects before processing.

curl --silent --show-error --fail-with-body \
  "$EDI_API_BASE/v1/edi/inbound/$EDI_PARTNER_ID" \
  --header "Authorization: Bearer $EDI_API_TOKEN" \
  --header 'Content-Type: application/edi-x12' \
  --data-binary @partner-test-order.edi \
  --dump-header inbound-headers.txt \
  --output inbound-result.json

Keep the original wire and correlation ID. Inspect data.status, every data.documents[] result, events_queued, and acknowledgment fields. HTTP 200 can contain rejected or partial processing. A duplicate interchange commonly returns 409; inspect the original record. After a truncated response or connection loss, inspect the ledger before another submission.

Find the document in Documents and inspect original wire, validation findings, and acknowledgment. For an accepted PO, open Orders using partner and PO identity. Inspect transport and Sync receipts separately before reporting another system’s acceptance.

Respond to the order

Use Orders and recovery to prepare an 855, partial 856, or 810. Persist its frozen overrides, preview revision, and request key before dispatch. Full-payload integrations can use outbound 856 with their own durable key. Generated bytes do not establish partner receipt.

Run locally

From the Rust source checkout:

export EDI_API_TOKEN="$(openssl rand -hex 24)"
cargo run
# Local API: http://127.0.0.1:8480

Use this development token only with the local service. File-backed development can process fixtures, but guarded sends and durable outbound receipts require PostgreSQL. Run cargo run -- migrate with DATABASE_URL before serving, or explicitly enable EDI_MIGRATE_ON_START=true for single-instance development. See configuration.

For codec embedding, use the source crates crates/stateset-edi-x12 and crates/stateset-edi-edifact as path dependencies. Source availability does not establish registry publication.