EDI for developers: turn EDI into JSON

This post mentions Stedi’s EDI Core API. Converting EDI into JSON remains a key Stedi offering, however EDI Core API has been superseded by Stedi Core, an event-driven EDI system that allows you to configure integrations without being an EDI or development expert.

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.

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 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

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.'

A few common examples are:

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

• 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.

Getting started

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.

{
  "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~

JEDI: Stedi’s JSON EDI format

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:

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

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.

• 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

{
  "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
          }
        ]
      }
    }
  ]
}

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.