EDI to JSON API via SFTP

Retailers, 3PLs and carriers still send the documents that run supply chains — purchase orders, invoices, advance ship notices — as EDI over SFTP. Your application, though, wants JSON, not a wall of ISA and UNB segments. The usual options are joining a managed EDI network and paying per document, or standing up your own SFTP server, polling its inbox with cron, and hand-writing an X12 parser. FTPasHTTPS gives you a third path: receive the EDI file over SFTP, transform it to JSON inline, and POST it straight to the endpoint you already run.

How EDI-to-JSON over SFTP works

1. Your trading partner connects over SFTP (SSH key auth) and runs a STOR to upload an X12 or EDIFACT interchange.
2. FTPasHTTPS reads the envelope and segments as they stream in — the edi_to_json transform parses the interchange without ever writing it to disk.
3. Optional schema validation checks the resulting JSON against the contract your API expects, rejecting malformed or out-of-spec interchanges.
4. FTPasHTTPS opens an HTTPS POST to your endpoint, signs it with HMAC-SHA256, and streams the JSON document into the request body.
5. Your API returns 200 and the partner receives 226 Transfer complete; a 5xx maps to 451 Action aborted so the partner resends.

Configuration + example transform

An EDI-to-JSON server is a small JSON config: SFTP in, an inline transform, schema validation, and your endpoint as the target.

# EDI-over-SFTP -> JSON API for a trading partner
{
  "protocol": "sftp",
  "auth": { "type": "ssh-key" },
  "transform": [
    { "type": "edi_to_json", "standard": "x12" },
    { "type": "validate_schema", "schema": "po-850.schema.json" }
  ],
  "forward": {
    "type": "http",
    "url": "https://api.example.com/v1/orders",
    "method": "POST",
    "headers": { "Authorization": "Bearer ${API_TOKEN}" },
    "sign_with": "hmac-sha256"
  }
}

The partner uploads a raw X12 850 purchase order. FTPasHTTPS parses the interchange below…

# Uploaded over SFTP: x12 850 (purchase order), segments shown
ISA*00*          *00*          *ZZ*ACMERETAIL    *ZZ*YOURCO         *260620*0902*U*00401*000004521*0*P*>~
GS*PO*ACMERETAIL*YOURCO*20260620*0902*4521*X*004010~
ST*850*0001~
BEG*00*SA*PO-99182**20260620~
PO1*1*48*EA*12.50**SK*WIDGET-RED~
PO1*2*24*EA*12.50**SK*WIDGET-BLUE~
CTT*2~
SE*7*0001~
GE*1*4521~
IEA*1*000004521~

…and POSTs this JSON to /v1/orders, signed and ready for your API to consume:

# POST https://api.example.com/v1/orders
Content-Type: application/json
X-FTPasHTTPS-Signature: sha256=7b2e91a4c0d8...
X-FTPasHTTPS-Event: file.uploaded

{
  "event": "file.uploaded",
  "standard": "x12",
  "document_type": "850",
  "interchange_control_number": "000004521",
  "sender_id": "ACMERETAIL",
  "receiver_id": "YOURCO",
  "purchase_order": {
    "po_number": "PO-99182",
    "order_date": "2026-06-20",
    "line_items": [
      { "line": 1, "sku": "WIDGET-RED",  "qty": 48, "uom": "EA", "unit_price": 12.50 },
      { "line": 2, "sku": "WIDGET-BLUE", "qty": 24, "uom": "EA", "unit_price": 12.50 }
    ],
    "line_count": 2
  },
  "received_at": "2026-06-20T09:02:33Z"
}

FTPasHTTPS vs. the DIY EDI pipeline

Concern	DIY: SFTP box + cron + EDI parser script	FTPasHTTPS → JSON API
EDI parsing	Hand-written X12/EDIFACT parser you maintain	Built-in edi_to_json transform
Network fees	Per-document VAN charges if you join one	Flat plan, your own endpoint
Files on disk	Interchange written to a volume, then deleted	Never touch disk — streamed
Latency to your API	Up to the cron interval (minutes)	Streams during the upload
Validation	Custom checks bolted on by hand	Schema validation rejects bad interchanges
Retries & auth	Roll your own signing and retry logic	HMAC-SHA256, backoff + dead-letter queue
Audit trail	Scattered across syslog	Full audit log per interchange

When to use it (and the limits)

Reach for EDI-to-JSON over SFTP when partners already send you X12 or EDIFACT but your stack speaks JSON, when you would rather not pay per-document network fees, or when you want a malformed interchange caught before it ever reaches your API. SFTP, inline transforms and schema validation begin on the Professional plan (€49/server/month: 10,000 transfers, 50GB). The Free and Starter tiers are FTP/FTPS only, so you can prototype the JSON contract over FTPS before a partner cuts over to SFTP; if you need PGP or a dedicated IP for an allow-listed partner, Enterprise (€99) adds those.

A few limits to keep in mind: the transform handles the common X12 and EDIFACT document types described here, and you supply a JSON schema per document for validation — this is not full trading-partner relationship management, AS2, or functional-acknowledgement automation. Transformation runs per interchange at upload time, so it is not a batch replay tool for archives you already hold. Throughput is bounded by your plan's monthly transfer and size caps: 10,000 transfers / 50GB on Professional, 50,000 / 250GB on Enterprise.

Control numbers, segment integrity and the audit trail

Every EDI interchange carries control numbers — the ISA interchange control number in X12, the UNB reference in EDIFACT — that let you tie a document back to exactly what the partner sent. FTPasHTTPS surfaces these in the JSON it POSTs, so your API can deduplicate retransmissions and reconcile against the audit log without reparsing the raw interchange. Because parsing happens mid-stream, a truncated or structurally broken interchange is caught as it arrives rather than silently landing half-written on a disk for a cron job to misread later.

Schema validation is your gate for correctness: attach a schema such as po-850.schema.json and any interchange whose parsed JSON does not match — a missing line-item segment, an out-of-range quantity, a document type you did not expect — is rejected before your API sees it. The partner's SFTP client receives 451 Action aborted and knows to resend, while the failure, the control numbers, and the timestamp are written to the audit log. During an incident that single log answers the only questions that matter: did the interchange arrive, was it valid, and exactly when did your API receive it.

Frequently asked questions