Skip to main content

EDI Quickstart

Run the gateway

The server refuses to start without EDI_API_TOKEN unless EDI_AUTH_DISABLED=true (development only). It speaks plain HTTP — terminate TLS at a reverse proxy such as nginx, Caddy, or an ALB.
Set EDI_TRUSTED_PROXY_HOPS to the number of proxies in front of the gateway so the rate limiter reads the real client IP from X-Forwarded-For. Left at 0 it ignores the header and keys on the socket peer, so a directly-reachable listener can’t be spoofed.
With Docker:
docker compose up works with a .env (see .env.example). For Kubernetes, deploy/k8s/stateset-edi.hetzner.yaml carries HA API and dashboard deployments, probes, disruption budgets, authenticated Prometheus scraping, alert rules, and Secret-based environment contracts. Interactive API docs are served at /docs, and the OpenAPI 3 document at /api-docs/openapi.json.

Receive a PO, ship it

Starting from a known retailer? Skip step 1 — POST /v1/connectors/{name}/partners/{id} creates a partner from one of the 40+ packaged retailer connectors, prefilling its implementation guide. Browse them with GET /v1/connectors.

Shipping labels (UCC-128 / SSCC-18)

Retailers reject ASNs whose cartons aren’t labelled with a scannable SSCC-18 in a GS1-128 barcode. With EDI_GS1_COMPANY_PREFIX set, POST /v1/labels/856/{partner} takes an 856 ASN and returns a minted SSCC-18 (with GS1 mod-10 check digit) plus a ZPL label — a Code128 subset-C GS1-128 barcode with human-readable (00) SSCC, ship-to, and PO — ready for a Zebra printer. The 856 itself carries a carton (HL*P) level with one MAN*GM SSCC-18 per carton, so the SSCC on each carton label matches the ASN. That is what QVC-style pack compliance requires. Related endpoints:

Authentication

Two credential tiers:
  • The admin token (EDI_API_TOKEN) has full access to all /v1 routes. It selects a tenant with an x-tenant-id header, defaulting to default.
  • Partner API keys are scoped to that partner’s own routes. They are SHA-256-hashed at rest, shown once, and rotated by re-issuing via POST /v1/partners/{id}/api-key. A partner key implies its tenant.
Authorization is checked before request bodies are parsed.

Embedding the codecs

The X12 and EDIFACT codecs are standalone, publishable crates with no transport, HTTP, or database dependencies — embed them in any Rust EDI pipeline:

Next steps

Transaction sets

Every supported set and its direction.

Transports

Move a partner to SFTP, AS2, or AS1.

Operations

Reconciliation, evidence, deductions, alerting.

MCP server

Drive all of this from an agent.