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:
- Receive an EDI file;
- Send the EDI file to Stedi’s EDI Core API to translate it into JEDI (JSON EDI);
- Send the JEDI file to Stedi’s Mappings API to transform it into your API’s custom JSON shape;
- 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.'
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.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.
The short answer is no.
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.
orders
API endpoint. You can mentally substitute the API you’re working with on your end while you follow along.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~
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
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:
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
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 theRich view
and hovering over the date, we can see that the date field is expressed asCCYYMMDD
.
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.
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
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.{
"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.
We’d love to help you build.
EDI can be tough to look at, so Inspector turns EDI into a format that is readable by humans. Quickly visualize and debug any X12 or EDIFACT document. Share EDI files easily with trading partners.
Get blog posts delivered to your inbox.