EDI for developers: turn EDI into JSON

So, you’ve been tasked with “figuring out EDI.” Maybe you’re in the supply chain or logistics world, or maybe you’re building a product in the healthcare or insurance space – chances are that you’re reading this because one of your large customers, vendors, or partners said that if you want to move the relationship forward, you have to do something called EDI: Electronic Data Interchange.

Maybe they sent you a sample file that looks like it came off a dot matrix printer in 1985, or maybe they sent you a PDF “mapping guide” that doesn’t seem to make much sense – or maybe you have nothing to use as a reference at all.

Regardless of what you’re starting with, the goal of this post is to give you, a modern software developer, a practical crash course in EDI: the bare minimum steps necessary to build a basic EDI integration. Alongside this, we’ll provide you the key context about EDI that you need to understand what you're building.

You'll be using a combination of your own tools and Stedi's self-service APIs, which have a free tier that doesn't require a credit card – so there shouldn't be any blockers to getting started.

When your integration is up and running, the end to end flow will look something like this:

1. Receive an EDI file;
2. Send the EDI file to Stedi’s EDI Core API to translate it into JEDI (JSON EDI);
3. Send the JEDI file to Stedi’s Mappings API to transform it into your API’s custom JSON shape;
4. Send the transformed JSON object to your API.

If you get stuck at any point, feel free to drop us a note – we’re here to help. More accurately, we’re here to help and nothing more. We don’t have a quota-driven sales team and we don’t sell contracts or implementations – we build API-driven tools for software developers like you. Everything we do is strictly pay-per-use, with no long term contracts, no setup fees, no monthly minimums, and no professional services to sell.

If you reach out to our support, you’ll get someone who just wants to help you build.

Before we get started: the two most common questions about EDI

This section provides some context – if you want to just start building, you can skip ahead to Part I: Working backwards from your API.

What is EDI?

EDI is a broad topic and this is just a crash course, so we’re going to take some shortcuts in explaining things.

You may have heard a lot of jargon or acronyms when researching EDI – things like AS2, VANs, or MFT – but when you boil it down, 'EDI' just means 'getting data from one business system into another.'

Your customer, vendor, or partner – whoever told you that you needed to do EDI to begin with – wants to exchange data with you. To do so, they need you to work with a very specific file format. The process of exchanging that specific file format is called EDI. The file itself is called an EDI file or EDI document. In the EDI world, your customer, vendor, or partner is called a trading partner. We’ll be using all these terms going forward.

The subject of EDI typically comes up because a company like yours wants to achieve some business goal with your trading partner. Those business goals vary widely, but what they have in common is that they all require either sending data to a trading partner, receiving data from a trading partner, or both.

A few common examples are:

Supply chain

• Receiving purchase orders from a customer;
• Sending e-commerce orders to a fulfillment warehouse;
• Requesting pickup of a shipment by a trucking provider.

Healthcare

• Sending benefits enrollments to an insurance provider;
• Requesting the status of a healthcare claim;
• Communicating patient health information.

EDI spans many industries (finance, government, education, and more) so if you don’t see your use case listed as an example, it’s not because it isn’t supported – it’s just because we can’t list out every possible flow here.

If it’s just data exchange, can’t we just use an API instead?
The short answer is no.

Exactly why your trading partner wants to exchange files instead of integrating with an API is a much longer story (and is out of the scope of this blog post), but EDI has been around since the 1960s and even hypermodern companies like Amazon use it as their primary method for trading partner integration. If you’re hoping to wait around for your trading partner to roll out an API, you’ll likely be waiting a long time.

Getting started

We’ve established that in order to achieve some business goal, your trading partner wants to either send files to you, receive files from you, or both. That process is called EDI, and the files they want to send are generally called EDI files.

But what is it that you are trying to accomplish? In all likelihood, you’re trying to get data into or out of your system.

For the purposes of simplifying this post, we’re going to assume two things: first, that your system has an API, and second, that the API can accept JSON as a format. We’re also going to focus only on receiving EDI files from your trading partner – that is, getting data into your system – because otherwise this post would get too long. We’ll cover that in the next post.

Part I: Working backwards from your API

So far, we know that:

i) You’re trying to receive an EDI file from your trading partner in order to get some important data into your system; and

ii) Your system has a JSON-based API.

The end goal of this exercise, then, is to make a successful call to your API. To do that, we need to create a JSON payload in the format that your API expects. If your trading partner could integrate with your API directly, they would send this payload themselves; since they can only send data via EDI, though, we need to grab the data from the EDI file and turn it into your custom JSON shape.

Let’s start by looking at a simple JSON payload for a fictional orders API endpoint. You can mentally substitute the API you’re working with on your end while you follow along.

The orders API:

{
  "records": [
    {
      "fields": {
        "customerName": "John Doe",
        "customerChannel": "Dropship",
        "purchaseOrderNumber": "PO102388",
        "customerAddress": "20 West 34th Street",
        "customerCity": "New York",
        "customerState": "NY",
        "customerZip": 10001,
        "customerCountry": "US",
        "currency": "USD",
        "lineItems": [
          {
            "sku": 123,
            "quantity": 2,
            "unitPrice": 10.0
          },
          {
            "sku": 456,
            "quantity": 2,
            "unitPrice": 12.0
          }
        ]
      }
    }
  ]
}

Again, this happens to be an API for creating e-commerce orders, but it could just as easily be an API for anything from railroad waybills to health insurance eligibility checks.

Assuming that each one of these fields is mandatory, we need to fill out the values for each of them in order to successfully send a request to your API. To do that, we need to extract some data out of the EDI files that your partner is going to send.

Part II: making sense of EDI files

Your trading partner’s EDI file will look something like this:

ISA*00*          *00*          *ZZ*AMAZONDS       *01*TESTID         *220108*1310*U*00401*000000043*1*T*+~
GS*PO*ATFDS*AMAZONDS*20220108*2001*95*X*004010~
ST*850*0010~
BEG*00*DS*TesT0008596**20220108~
CUR*BT*USD~
REF*OQ*X~
REF*ST*1~
N9*ZZ*01~
MSG*This shipment completes your order.~
N9*ZZ*06~
MSG*For detailed information about your orders, please visit Your Account. You can also print invoices,
change your e-mail address and payment settings, alter your communication preferences, and much more-24
hours a day-athttp://www.amazon.com/your-account.~
N9*ZZ*07~
MSG*Visit http://www.amazon.com/returns to return any item-including gifts-in unopened or original condition
within 30 days for a full refund(other restrictions apply). Please have your order ID ready. Thanks for
shopping at Amazon.com, and please come again!~
N1*BT*Amazon.com.kyde..Inc-*92*KYDC~
N1*SF*WHSE*92*WHSE~
N1*ST*Charlie Dinkins~
N2*Darla Dinkins~
N3*11254 Main St*Suite 112~
N4*Seattle*WA*98104*US*CC*United States~
TD5**92*UPS_GR_RES****ZZ*RES~
N1*LW*Amber Baker~
N3*123 Anderson Avenue~
N4*Seattle*WA*98103*US~
PER*ZZ****TE*206-555-1212~
PO1*1*3*EA*18.04*NT*SK*1617*****BL*1*ZZ*Amazon.com~
CTP**PUR*19.99~
MSG*Wide Tracker Activity Walker~
PO1*2*2*EA*54.42*NT*SK*4927*****BL*1*ZZ*Amazon.com~
CTP**PUR*59.99~
MSG*Deluxe Cozy Convertible~
PO1*3*1*EA*21.9*NT*SK*1682*****BL*1*ZZ*Amazon.com~
CTP**PUR*25.99~
MSG*DiscoverSounds Workshop~
CTT*6*43~
SE*33*0010~
GE*1*43~
IEA*1*000000043~

The file you get might look a bit different. This particular example happens to be formatted according to the X12 Standard, which is the most popular standard in North America. X12 covers 300+ transaction types – which they call transaction sets – each with a unique numeric code and name to identify it. This one is an 850 Purchase Order.

JEDI: Stedi’s JSON EDI format

Stedi’s EDI Core API converts EDI files into a human-readable JSON format called JEDI.

You can play around with it live by opening the example file in our Inspector tool, which uses the EDI Core API under the hood:

Open in Inspector →

If you click over to the Rich view, you will see a rendered view that shows what each data element means. This can be helpful when you’re diving deep to understand the intricacies of EDI, but you should be able to make it pretty far just using the human-readable JEDI format.

For our purposes, we’ll be working with JEDI directly, but you can feel free to explore the Rich view if it’s helpful for getting oriented.

Diving into JEDI

When you’re looking at a JEDI file, you can ignore the interchanges and groups parts to start – this is just enveloping information needed for routing amongst EDI systems. The meat of the transaction starts in transaction_sets.

JEDI turns this EDI line…

BEG*00*DS*TesT0008596**20220108~

…into an easily-understandable object in JEDI:

"beginning_segment_for_purchase_order_BEG": {
  "transaction_set_purpose_code_01": "original_00",
  "purchase_order_type_code_02": "dropship_DS",
  "purchase_order_number_03": "TesT0008596",
  "date_05": "20220108"
},

From the JEDI object, we can glean that:

• this line in the EDI file is the beginning section of the Purchase Order;
• this purpose of this transaction is to send the original (the other possible values can be found here);
• the PO is a ’drop ship’ order, which means it’s getting shipped directly to the customer’s house;
• the PO number is TesT0008596; and
• We also know that the PO date is 20220108, but we can’t be sure how that is formatted; by flipping back to the Rich view and hovering over the date, we can see that the date field is expressed as CCYYMMDD.

If we were to continue walking through the file, we could make sense of every single field. However, the reality is that the vast majority of information in an EDI file isn’t necessary for most integrations – we only have to extract the data needed to populate the target API request; the rest can be ignored.

For our simple orders API, the fields we need to populate are as follows:

• customerName
• customerChannel
• purchaseOrderNumber
• customerAddress
• customerCity
• customerState
• customerZip
• customerCountry
• currency
• lineItems.sku
• lineItems.quantity
• lineItems.unitPrice

By looking at these target values and scanning through our source JEDI file, we can deduce that:

• customerName can be found on line 117;
• customerAddress can be found starting on line 115;
• lineItems can be found starting on line 178.

Part III: Mapping JEDI (JSON EDI) to a custom API shape

So far, you know how to turn an EDI file into JEDI using Stedi’s EDI Core API. The next step is to pull the various pieces of data out of the JEDI file and map it to your orders API object – in other words, we need to map the JSON fields in the JEDI file to the JSON fields in the orders API object.

Mappings allows you to do exactly that: define JSON-to-JSON mappings in a simple, powerful UI – then transform it on-the-fly using the Mappings API.

To keep the length of this exercise manageable, we’ll just be sharing high-level details about Mappings – for detailed instructions on how to use Mappings, check out the API docs or this short video.

At the end of the mapping process, here’s the output we’re expecting:

{
  "records": [
    {
      "fields": {
        "customerName": "Charlie Dinkins",
        "customerChannel": "Dropship",
        "purchaseOrderNumber": "TesT0008596",
        "customerAddress": "11254 Main St, Suite 112",
        "customerCity": "Seattle",
        "customerState": "WA",
        "customerZip": 98104,
        "customerCountry": "US",
        "currency": "USD",
        "lineItems": [
          {
            "sku": 1617,
            "quantity": 3,
            "unitPrice": 18.04
          },
          {
            "sku": 4927,
            "quantity": 2,
            "unitPrice": 54.42
          },
          {
            "sku": 1682,
            "quantity": 1,
            "unitPrice": 21.9
          }
        ]
      }
    }
  ]
}

To achieve that output, the mapping configuration is as follows:

You can deploy this sample mapping code to your Stedi account using this GitHub starter repo.

Wrapping up

By now, you have the ability to take an EDI file, translate it into JEDI, and transform it into your target API shape. This should be enough to unblock you in starting to plan your integration.

To put this into production, you would need to be able to accept live EDI files from your trading partner via SFTP or a special protocol called AS2 (SFTP is typically a better choice, since there are more off-the-shelf tools to facilitate it). You would also need to wire up a pipeline that ties together each of the steps. As with any production service, you’ll want to be thoughtful about things like retries and observability.

If you’d like to keep building, we’ve put together a basic guide for accepting inbound EDI via SFTP.

If you have questions or want some help getting started, drop us a note.
We’d love to help you build.