StateSet API Docs

StateSet EDI is a multi-tenant X12 and EDIFACT gateway. It receives trading-partner documents over any common transport, strictly validates and translates them into StateSet VES events, acknowledges every functional group with a 997 (and every malformed interchange with a TA1), generates outbound order-lifecycle documents from StateSet-shaped JSON, and confirms delivery back to the partner — tracked, retried, and reconciled. It is built on the same stack as the Sync Server: Rust, axum, tokio, serde, reqwest (rustls), tracing, and Prometheus.

Every endpoint the engine serves has a generated reference page with a live playground under the EDI API tab — 116 operations, built from the OpenAPI document edi.stateset.com publishes.

Highlights

Five transports

HTTP API, file/VAN directory drop, native SFTP client, AS2 (signed and encrypted, with MDN receipts), and AS1 (EDI over email).

Confirmed delivery

Outbound AS2 is tracked, MDN-confirmed, retried with exponential backoff, and dead-lettered with an alert on failure.

Strict, certifiable

One inbound endpoint auto-detects the syntax — X12 answers with a 997, EDIFACT with a CONTRL. Envelope validation, per-partner implementation guides, exact-decimal money, and replay-proof event IDs.

Retail-ready

40+ packaged retailer connectors and UCC-128 / SSCC-18 label generation.

Additionally:

Multi-tenant, with a WorkOS-SSO operator dashboard.
HA-ready — every coordination store shares through Postgres.
Operational alerting to Slack-compatible webhooks and email.
MCP server exposing 117 agent-callable tools.

Document flow

                  ┌─ HTTP   POST /v1/edi/inbound
 retailer ──850──▶├─ file   EDI_INBOUND_DIR / SFTP mailbox
                  ├─ AS2    POST /v1/as2  (signed/encrypted, returns MDN)
                  └─ AS1    POST /v1/as1/inbound  (EDI over email)
                     │
                     ├─ syntax auto-detected: X12 (ISA) or EDIFACT (UNA/UNB)
                     ├─ dedup on (partner, control ref) — replays collapse to a no-op
                     ├─ strict envelope validation ── invalid ──▶ TA1 rejection
                     ├─ per-partner implementation guide ── violation ──▶ 997 with R
                     ├─ edi.*.received  →  durable outbox
                     └─ 997 (X12) or CONTRL (EDIFACT) acknowledgment

 Stateset ──JSON──▶ POST /v1/edi/outbound/{tx}/:partner        (X12)
                    POST /v1/edifact/outbound/{invoic,desadv}/:partner
                     ├─ enveloped X12 (response body)
                     ├─ file drop (EDI_OUTBOUND_DIR) and/or
                     ├─ AS2 delivery recorded → worker sends, confirms MDN, retries
                     ├─ AS1 email (application/edi-x12 attachment)
                     ├─ tracked for 997 reconciliation (pending → accepted/rejected)
                     └─ edi.{tx}.sent → outbox

 outbox ──flush──▶ Stateset sequencer  /v1/ves/events/ingest   (Ed25519-signed)

The same pipeline — dedup, validate, translate, queue, acknowledge — runs behind every transport, so a partner can move between transports without any code changes. Sending a document is one call. The body is the typed Invoice810 object; the response is the wire-ready X12 interchange itself (Content-Type: application/edi-x12), with the ISA/GS/ST control numbers in its envelope — the same numbers GET /v1/lifecycle/{reference} reconciles against later:

curl --request POST "https://edi.stateset.com/v1/edi/outbound/810/acme-retail" \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"invoice_number": "INV-10428", "invoice_date": "2026-08-31", "po_number": "4500123987", "lines": [], "total_amount": "1284.00"}'

Response (application/edi-x12)

ISA*00*          *00*          *ZZ*STATESET       *ZZ*ACMERETAIL     *260831*1422*U*00401*000004471*0*P*>~
GS*IN*STATESET*ACMERETAIL*20260831*1422*4471*X*004010~
ST*810*0001~
BIG*20260831*INV-10428**4500123987~
…
SE*12*0001~
GE*1*4471~
IEA*1*000004471~

Keep isa_control_number against your own invoice record. It is the only handle that ties a partner’s 997 — and any later chargeback — back to what you sent, and control numbers wrap, so the pairing is only unambiguous if you store it at send time.

Beyond the wire

The gateway does more than move documents. It also covers the operational surface that EDI programs actually run on:

Area	What it does
Reconciliation	Acknowledgment reconciliation (was our document 997’d?) plus business-level reconciliation across PO / ASN / 945 / invoice / payment.
Evidence bundles	Compliance evidence for one document or a whole order chain, exportable for audit.
Deductions	Capture, categorize, dispute, attach evidence, and resolve chargebacks with an exposure/recovery summary.
Monitoring	Per-partner acknowledgment SLA status with alerting through Slack-compatible webhooks and email.
Onboarding	Partner onboarding lifecycle, standard and custom certification, and implementation-guide versioning with diff and rollback.
Labels & artifacts	UCC-128 / SSCC-18 labels, GS1 labels per pack level, packing slips (HTML and native PDF), commercial invoices, postal customs declarations, and Peppol BIS 3.0 UBL e-invoices.
Adapters	A packaged back-end integration catalog (ERP / WMS / TMS / e-commerce / carrier) that can plan and execute the actions a canonical event triggers.
Connector SDK	Validate and certify a connector manifest without persisting it.

Next steps

Quickstart

Run the gateway and process your first 850.

Transaction sets

Every supported X12 set and its direction.

Transports

HTTP, file/VAN, SFTP, AS2, and AS1.

MCP server

Drive EDI flows from Claude with 117 tools.

Last modified on August 31, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

StateSet iCommerce EDI Engine

Highlights

Five transports

Confirmed delivery

Strict, certifiable

Retail-ready

Document flow

Beyond the wire

Next steps

Quickstart

Transaction sets

Transports

MCP server

​Highlights

Five transports

Confirmed delivery

Strict, certifiable

Retail-ready

​Document flow

​Beyond the wire

​Next steps

Quickstart

Transaction sets

Transports

MCP server

Highlights

Document flow

Beyond the wire

Next steps