> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StateSet EDI

> A production-grade X12 and EDIFACT gateway for StateSet commerce — strict validation, confirmed delivery, and full acknowledgment reconciliation.

# StateSet EDI

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](/stateset-sync-server-api-basics): Rust,
axum, tokio, serde, reqwest (rustls), tracing, and Prometheus.

## Highlights

<CardGroup cols={2}>
  <Card title="Five transports" icon="arrows-left-right">
    HTTP API, file/VAN directory drop, native SFTP client, AS2 (signed and encrypted, with
    MDN receipts), and AS1 (EDI over email).
  </Card>

  <Card title="Confirmed delivery" icon="circle-check">
    Outbound AS2 is tracked, MDN-confirmed, retried with exponential backoff, and
    dead-lettered with an alert on failure.
  </Card>

  <Card title="Strict, certifiable" icon="shield-check">
    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.
  </Card>

  <Card title="Retail-ready" icon="store">
    40+ packaged retailer connectors and UCC-128 / SSCC-18 label generation.
  </Card>
</CardGroup>

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](/stateset-edi/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.

## 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/stateset-edi/quickstart">
    Run the gateway and process your first 850.
  </Card>

  <Card title="Transaction sets" icon="table-list" href="/stateset-edi/transaction-sets">
    Every supported X12 set and its direction.
  </Card>

  <Card title="Transports" icon="network-wired" href="/stateset-edi/transports">
    HTTP, file/VAN, SFTP, AS2, and AS1.
  </Card>

  <Card title="MCP server" icon="plug" href="/stateset-edi/mcp-server">
    Drive EDI flows from Claude with 117 tools.
  </Card>
</CardGroup>