Sending an EDI file: the request, the response and the errors

Summary

EDI files come in through the same web service as the API, at POST /api/wms/edi, with the same access key. The file goes in whole, exactly as the partner's system generates it, from ISA to IEA. The response says on the spot whether it was processed or set aside, and why.

The request

The file can go as the raw request body:

POST /api/wms/edi
Authorization: Bearer 7|...
X-Warehouse-Code: DAL-01
Content-Type: text/plain
Accept: application/json

ISA*00*          *00*          *ZZ*NORTHERN       *ZZ*WAREHOUSE      *261006*0930*U*00401*000000123*0*P*>~GS*AR*NORTHERN*WAREHOUSE*20261006*0930*123*X*004010~ST*943*0001~W06*N*PO-7781~N1*CA*Southern Logistics~W04*120*CS**VN*NT-1001~W04*40*EA**VN*NT-2040~W03*160~SE*7*0001~GE*1*123~IEA*1*000000123~

Or inside JSON, in the raw field:

{ "raw": "ISA*00*          *00*    ... ~IEA*1*000000123~" }

The file must start with ISA. The element separator and segment terminator are taken from the ISA itself, so whatever the partner uses is accepted.
The warehouse code works just like in the API: see The key, the warehouse and error responses.
Send Accept: application/json to get errors back as JSON.

The response

Processed (the document was created):

HTTP/1.1 201 Created
{
  "id": 88,
  "transaction_type": "943",
  "status": "processed",
  "isa_control": "000000123",
  "st_control": "0001",
  "source_type": "Asn",
  "source_id": 413,
  "error_detail": null
}

Set aside (nothing was created):

HTTP/1.1 200 OK
{
  "id": 89,
  "transaction_type": "943",
  "status": "quarantined",
  "isa_control": "000000124",
  "st_control": "0001",
  "source_type": null,
  "source_id": null,
  "error_detail": "Unknown SKU: NT-9999"
}

What each field says

Field	What it is
`id`	The message number at the warehouse. Give it to us if it needs checking.
`transaction_type`	The type read from ST01: 943, 940, 856…
`status`	`processed` (the document was created) or `quarantined` (set aside).
`isa_control`, `st_control`	The interchange (ISA13) and transaction (ST02) control numbers.
`source_type`, `source_id`	What was created: `Asn` (advance ship notice) or `Shipment`, and its internal id. You can look it up through the API with it.
`error_detail`	The reason, if it was set aside.

Tip: watch the response code: 201 means something was created; 200 means it was set aside, or it is a resend of something already set aside.

Resends and control numbers

Each message is stored with the partner, the interchange control number (ISA13) and the transaction control number (ST02). If another one arrives with all three equal, it is not processed again: the response returns the original message, with its original result.

A resend after a network drop is safe: it does not duplicate.
A corrected file must carry new control numbers, or it is ignored.

Errors

Response	Meaning	What to do
404	The warehouse does not have the EDI (or API) module on.	Check it with us.
422 `empty_payload`	The request arrived without a file.	Send the file in the body or in `raw`.
422 `No trading partner profile matches the sender for this client.`	The ISA sender id does not match any active partner of that customer in that warehouse.	Check the file's ISA06; if it is right, set it up with us.
401 / 403	Key or warehouse problems, same as the API.	See The key, the warehouse and error responses.
500	A server failure. Today it also happens if the body is not an X12 file (it does not start with ISA or is cut short).	Check that the whole file is sent; if it is, send us the reference in the response.

Troubleshooting

The partner gets 200 with processed but the document is not there.

It is a resend of a file that had already been processed: look the document up by its source_id or by the order reference.
Check that you are in the right warehouse.

Every file from the partner is rejected with 422.

The sender id changed (it happens when they switch EDI providers) or their profile was deactivated. Write to us with a sample file.

A 500 when sending the file.

Almost always the body is not the complete X12 file (for example, a JSON with a different field name, or a truncated file).

Frequently asked questions

My partner can only send over SFTP

Today there is no SFTP or AS2 inbound. Many EDI providers can forward files to a web service; if the partner's cannot, write to us before committing to dates.