Translate between JSON and EDI with modern, machine-readable EDI specifications

Developers building EDI integrations often find that receiving EDI documents is relatively straightforward compared to the difficulty of sending EDI documents. What makes these use cases so different?

Imagine you’ve switched cell phone providers and you receive your first bill. Though you’ve never seen an invoice from this cell phone provider before, you can quickly ‘parse’ out the relevant details – the total, the due date, your address, how many units of data you’ve consumed, and so on.

But what if you had to create an invoice in this exact format – from scratch? How would you know which fields were required, what order to put them in, and details like whether to use the full name of states or just the abbreviation?

What’s needed is a template, and a way to validate an input against it – which is precisely what we’ve launched with EDI Translate, a new API for creating and validating EDI files that conform to precise trading partner specifications. EDI Translate accepts user-defined JSON payloads and translates them into valid EDI files, and vice versa.

EDI Translate works in conjunction with recently-launched Stedi Guides, which enables users to quickly and accurately define EDI specifications using a no-code visual interface. Once a guide has been defined, users can use the EDI Translate API to create outbound EDI files that conform to the guide. Users can also use EDI Translate API to validate that inbound EDI files meet the defined specification, as well as parse these EDI files into JSON for further processing.

Stedi Guides uses the popular, open-source JSON Schema format, giving developers a familiar way to ensure that their JSON payloads have all the information required to create a valid EDI file.

Features of EDI Translate

• Read and write any X12 EDI transaction.

• Validate EDI documents automatically against trading partner specifications.

• Seamlessly integrate with your own tech stack – or build your end-to-end EDI workflow on Stedi.

How EDI Translate works

EDI Translate makes EDI integrations a lot simpler, taking the EDI format out of the equation and enabling you to work with JSON. Behind the scenes, the nuances of EDI are handled for you to ensure every transaction meets your or your trading partners’ requirements.

For outbound EDI: Once you map your internal payload to the JSON Schema generated by your Stedi guide, you can use EDI Translate to create an EDI document that conforms to the guide’s specifications.

For inbound EDI: When you receive an EDI file from a trading partner, you can use EDI Translate to convert it to JSON. You can use this output JSON directly, or map the output to your own data schema for additional processing (e.g. posting data to an ERP system).

Using EDI Translate

Generating EDI: The following example generates EDI using a custom JSON payload. For a detailed walkthrough, see the demo for writing EDI.

You need three pieces of data to generate EDI:

1. A Stedi guideId that refers to the trading partner specification. For more information, see Creating a Stedi Guide.

2. A JSON payload that conforms to the JSON Schema of your guide. If you need help creating this payload, you can use Stedi Mappings to map your internal format to the guide’s JSON Schema.

3. The X12 envelope data, including interchange control header and functional group headers. Here is an example:

const envelope = {
  interchangeHeader: {
    senderQualifier: "ZZ",
    senderId,
    receiverQualifier: "14",
    receiverId,
    date: format(documentDate, "yyyy-MM-dd"),
    time: format(documentDate, "HH:mm"),
    controlNumber,
    usageIndicatorCode,
  },
  groupHeader: {
    functionalIdentifierCode,
    applicationSenderCode: "WRITEDEMO",
    applicationReceiverCode: "072271711TMS",
    date: format(documentDate, "yyyy-MM-dd"),
    time: format(documentDate, "HH:mm:ss"),
    controlNumber,
  },
};

Once you have these three inputs, you can call the EDI Translate API.

// Translate the Guide schema-based JSON to X12 EDI
const translation = await translateJsonToEdi(mapResult.content, guideId, envelope);

The output of the API call is an EDI payload that you can send to your trading partner using Stedi SFTP or another file transfer mechanism. The sample output below is for the X12-5010-850 transaction set.

{
    "output": "ISA*00*          *00*          *ZZ*AMERCHANT      *14*ANOTHERMERCH   *220915*0218*U*00501*000000001*0*T*>~GS*OW*WRITEDEMO*072271711TMS*20220915*021828*000000001*X*005010~ST*850*000000001~BEG*00*DS*365465413**20220830~REF*CO*ACME-4567~REF*ZZ*Thank you for your business~PER*OC*Marvin Acme*TE*973-555-1212*EM*marvin@acme.com~TD5****ZZ*FHD~N1*ST*Wile E Coyote*92*123~N3*111 Canyon Court~N4*Phoenix*AZ*85001*US~PO1*item-1*0008*EA*400**VC*VND1234567*SK*ACM/8900-400~PID*F****400 pound anvil~PO1*item-2*0004*EA*125**VC*VND000111222*SK*ACM/1100-001~PID*F****Detonator~CTT*2~AMT*TT*3700~SE*16*000000001~GE*1*000000001~IEA*1*000000001~"
}

Parsing EDI: To parse an EDI file, you only need the raw EDI payload (file contents) and the relevant Stedi guideId.

{
    "input": "ISA*00*          *00*          *ZZ*ANOTHERMERCH   *14*AMERCHANT      *220914*2022*U*00501*000001746*0*T*>~\nGS*PR*072271711TMS*READDEMO*20220914*202222*000001746*X*005010~\nST*855*0001~\nBAK*00*AD*365465413*20220914*****20220913~\nREF*CO*ACME-4567~\nN1*SE*Marvin Acme*92*DROPSHIP CUSTOMER~\nN3*123 Main Street~\nN4*Fairfield*NJ*07004*US~\nN1*ST*Wile E Coyote*92*DROPSHIP CUSTOMER~\nN3*111 Canyon Court~\nN4*Phoenix*AZ*85001*US~\nPO1*item-1*8*EA*400**VC*VND1234567*SK*ACM/8900-400~\nPID*F****400 pound anvil~\nACK*IA*8*EA~\nPO1*item-2*4*EA*125**VC*VND000111222*SK*ACM/1100-001~\nPID*F****Detonator~\nACK*IA*4*EA~\nCTT*2~\nSE*17*0001~\nGE*1*000001746~\nIEA*1*000001746~",
    "guideId": "01GEJBYTQCHWK59PKANTKKGJXM"
}

EDI Translate API is now generally available

EDI Translate is the core of any modern EDI system. Backed by Stedi Guides, EDI Translate enables you to convert data between JSON and EDI while conforming to your trading partners’ specifications. Use EDI Translate regardless of whether you are building an EDI system from scratch or simplifying your existing architecture. You can build your end-to-end flow entirely on Stedi, or integrate EDI Translate into your existing tech stack.

Try it for yourself – start by creating a Stedi guide using the guide builder UI. Use the guide with EDI Translate to parse and generate EDI files. We have a generous free tier for API calls, so there is no need to worry about costs when you are experimenting (see pricing). Creating guides and sharing them within your organization is entirely free.

For more details, check out EDI Translate’s API reference and user guide.

Start building today.

Did you know? You can build an end-to-end EDI integration on Stedi. Capture EDI specifications from your trading partner in a Stedi Guide, convert data between JSON and EDI using EDI Translate, transform data between schemas using Stedi Mappings, handle transmission of EDI files with your trading partners using Stedi SFTP (backed by Stedi Buckets), and orchestrate API calls and business logic with Stedi Functions. Use Stash as a reliable key-value store to keep track of transactions, reference lookup tables, and more.