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.

Regardless of what you’re starting with, this post will give you, a modern software developer, a practical crash course in EDI. It will also explain how to build an EDI integration on Stedi that transforms EDI to and from JSON.

• The two most common questions about EDI

• Overview of an EDI integration

• Step 1: Add your trading partner to Stedi

• Step 2: Transform JSON from Stedi to your API shape

• Step 3: Configure a webhook to send transactions to your API

The two most common questions about EDI

This section provides some context. If you want to just start building, skip to Add your trading parter to Stedi.

What is EDI?

You may have heard a lot of jargon or acronyms when researching EDI – things like AS2, VANs, or MFT. Put simply, EDI is a way to get data from one business system into another.

Your customer, vendor, or partner wants to exchange data with you, and 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. Each EDI file can contain one or more transaction types - called transaction sets – each with a unique numeric code and name to identify it. In the EDI world, your customer, vendor, or partner is called a trading partner. This post will use 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 they all require either sending data to a trading partner, receiving data from a trading partner, or both.

Here are a few common examples. EDI spans many industries, so if you don’t see your use case listed, it’s not because it isn’t supported – it’s just because we can’t list out every possible flow here.

Logistics

• 204 Request pickup of a shipment (load tender)

• 990 Accept or reject the shipment (response to a load tender)

• 214 Shipment status update

• 210 Invoicing details for a shipment

Warehousing

• 940 Request shipping from a warehouse

• 945 Communicate fulfillment to a seller

• 944 Indicate receipt of a stock transfer shipment

• 943 Stock transfer shipment notification

Retail

• 850 Send a purchase order to a retailer

• 855 Send a purchase order acknowledgment back to a customer

• 856 Send a ship notice to a retailer

• 810 Send an invoice

Healthcare

• 834 Send benefits enrollments to an insurance provider

• 277 Indicate the status of a healthcare claim

• 276 Request the status of a healthcare claim

• 278 Communicate patient health information

• 835 Make a payment and/or send an Explanation of Benefits (EOB) remittance advice

If it’s just data exchange, can’t we 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 plan to wait around for your trading partner to roll out an API, you’ll likely be waiting a long time.

Overview of an EDI integration

To achieve some business goal, your trading partner wants to either send EDI files to you, receive EDI files from you, or both. 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 business 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 – getting data into your system – because otherwise this post would get too long.

When you build an EDI integration on Stedi, the end-to-end flow for an inbound file (from your trading partner) will look something like this:

1. Receive an EDI file through a configured connection (SFTP/FTPS or AS2).

2. Translate the file to JSON according to your partner’s EDI requirements.

3. Use a Destination webhook to automatically send the JSON to your API. The webhook may be configured to use a Stedi mapping to transform the JSON to a custom shape before sending. You can also just receive raw JSON from Stedi and use other methods to transform it into the shape you need for your API (more on that in step 2).

Step 1: Add your trading partner to Stedi

Adding a trading partner configuration to the Stedi platform takes about 10-15 minutes and doesn’t require any code.

Here’s a video of adding a trading partner that demonstrates each of the following steps in detail.

• Create a partnership: A partnership defines the EDI relationship between you and your trading partner. Within the partnership, you’ll define a connection to exchange files, specify the EDI transactions you plan to send and receive, and configure other settings, such as whether to send automatic acknowledgments.

• Configure a connection: Set up a connection to exchange files with your trading partner. Stedi supports SFTP/FTPS, remote SFTP/FTPS, and AS2.

• Add transaction settings: Create a transaction setting for each EDI transaction you plan to send or receive. For example, an inbound transaction setting to receive 850 Purchase Orders and an outbound transaction setting to send 855 Purchase Order Acknowledgments. This process involves specifying a Stedi guide for the transaction type. Stedi guides are a machine-readable format for trading partner EDI specifications, and Stedi uses them to validate data according to your partner’s requirements.

Stedi automatically translates the EDI files your trading partner sends over the connection into JSON. The next step is to map the JSON fields in Stedi’s output to the JSON shape you need for your API.

Step 2: Transform JSON from Stedi to your API shape

There are three ways you can transform Stedi transaction data (JSON) into a custom format: Stedi Mappings, writing custom code, and using an iPaaS platform. This post demonstrates the Stedi Mappings method, and you can check out our docs for more details about the alternatives.

Guide JSON: Stedi’s JSON EDI format

Stedi converts EDI files into a human-readable JSON format called Guide JSON.

The following EDI example is is an Amazon 850 Purchase Order that follows Amazon’s specific requirements for constructing a Purchase Order transaction (each company has their own requirements for each transaction type). It’s formatted according to the X12 Standard, which is the most popular standard in North America.

You can play around with it by opening the example file in our Inspector tool. On the right, Stedi shows what each data element in the EDI transaction means. Open in Inspector →

ISA*00*          *00*          *ZZ*AMAZON         *ZZ*VENDOR         *221110*0201*U*00401*000012911*0*P*>~
GS*PO*AMAZON*VENDOR*20221110*0201*12911*X*004010~
ST*850*0001~
BEG*00*NE*T82Z63Y5**20221110~
REF*CR*AMZN_VENDORCODE~
FOB*CC~
CSH*N~
DTM*064*20221203~
DTM*063*20221209~
N1*ST**92*RNO1~
PO1*1*8*EA*39*PE*UP*028877454078~
PO1*2*6*EA*40*PE*UP*028877454077~
CTT*2*14~
SE*12*0001~
GE*1*12911~
IEA*1*000012911

The following example shows the Guide JSON shape for the translated Amazon 850 Purchase Order.

{
  "heading": {
    "transaction_set_header_ST": {
      "transaction_set_identifier_code_01": "850",
      "transaction_set_control_number_02": 1
    },
    "beginning_segment_for_purchase_order_BEG": {
      "transaction_set_purpose_code_01": "00",
      "purchase_order_type_code_02": "NE",
      "purchase_order_number_03": "T82Z63Y5",
      "date_05": "2022-11-10"
    },
    "reference_identification_REF_customer_reference": [
      {
        "reference_identification_qualifier_01": "CR",
        "reference_identification_02": "AMZN_VENDORCODE"
      }
    ],
    "fob_related_instructions_FOB": [
      {
        "shipment_method_of_payment_01": "CC"
      }
    ],
    "sales_requirements_CSH": [
      {
        "sales_requirement_code_01": "N"
      }
    ],
    "date_time_reference_DTM_do_not_deliver_before": [
      {
        "date_time_qualifier_01": "064",
        "date_02": "2022-12-03"
      }
    ],
    "date_time_reference_DTM_do_not_deliver_after": [
      {
        "date_time_qualifier_01": "063",
        "date_02": "2022-12-09"
      }
    ],
    "name_N1_loop": [
      {
        "name_N1": {
          "entity_identifier_code_01": "ST",
          "identification_code_qualifier_03": "92",
          "identification_code_04": "RNO1"
        }
      }
    ]
  },
  "detail": {
    "baseline_item_data_PO1_loop": [
      {
        "baseline_item_data_PO1": {
          "assigned_identification_01": "1",
          "quantity_ordered_02": 8,
          "unit_or_basis_for_measurement_code_03": "EA",
          "unit_price_04": 39,
          "basis_of_unit_price_code_05": "PE",
          "product_service_id_qualifier_06": "UP",
          "product_service_id_07": "028877454078"
        }
      },
      {
        "baseline_item_data_PO1": {
          "assigned_identification_01": "2",
          "quantity_ordered_02": 6,
          "unit_or_basis_for_measurement_code_03": "EA",
          "unit_price_04": 40,
          "basis_of_unit_price_code_05": "PE",
          "product_service_id_qualifier_06": "UP",
          "product_service_id_07": "028877454077"
        }
      }
    ]
  },
  "summary": {
    "transaction_totals_CTT_loop": [
      {
        "transaction_totals_CTT": {
          "number_of_line_items_01": 2,
          "hash_total_02": 14
        }
      }
    ],
    "transaction_set_trailer_SE": {
      "number_of_included_segments_01": 12,
      "transaction_set_control_number_02": 1
    }
  }
}

Let’s compare a smaller snippet of the Guide JSON to the original EDI file.

Stedi turns this EDI line:

BEG*00*NE*T82Z63Y5**20221110

into the following object in Guide JSON:

"beginning_segment_for_purchase_order_BEG": {
"transaction_set_purpose_code_01": "00",
"purchase_order_type_code_02": "NE",
"purchase_order_number_03": "T82Z63Y5",
"date_05": "2022-11-10"
},

Notice how Guide JSON makes it easier to understand each data element in the transaction.

Create a Stedi Mapping

Now that you understand Guide JSON, you can map fields from Stedi transactions into a custom shape for your API. If you plan to do this outside of Stedi, you can skip to step 3.

The following example shows a JSON payload for a very simple Orders API endpoint. 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.

The Orders API:

{
  "records": [
    {
      "fields": {
        "purchaseOrderNumber": "PO102388",
        "orderDate": "223-11-24",
        "lineItems": [
          {
            "sku": 123,
            "quantity": 2,
            "unitPrice": 10.0
          },
          {
            "sku": 456,
            "quantity": 2,
            "unitPrice": 12.0
          }
        ]
      }
    }
  ]
}

Assuming that each one of these fields is mandatory, you can extract this data out of the EDI files - in this case, 850 Purchase Orders - by creating a Stedi mapping.

Stedi Mappings is a powerful JSON-to-JSON transformation engine. To transform the Guide JSON from an 850 Purchase Order into the shape for the Orders API, you would create the following Stedi mapping. Note that you don’t need to map every field from the original transaction, only the fields you need for your API.

While is a very simple one-to-one mapping, Stedi Mappings supports the full power of the JSONata language, allowing you to combine fields, split text, and more. Mappings also supports lookup tables that you can use to replace fields from the original transaction with a list of static values (for example, automatically replacing a country code like USA with its full name United States).

For detailed instructions and more examples, check out the Mappings documentation.

Step 3: Configure a webhook to send transactions to your API

Once you create your mapping, you can attach it to a Destination webook to automatically transform JSON transactions from Stedi into a custom shape before automatically sending them to your API.

You can set up an event binding for transaction.processed.v2 events that triggers the webhook every time Stedi successfully processes a 850 Purchase Order.

Get started on Stedi

Now you know how to take an EDI file, translate it into Guide JSON, transform it into your target API shape, and automatically send it to your API. Check out the following resources as you keep building:

• EDI 101 for a deeper dive into EDI standards and format.

• Stedi Network for free access to EDI guides for hundreds of popular trading partners that you can use to configure integrations.

To get started building EDI integrations on Stedi, book a demo with our team.