Home /  Legacy products /  EDI Translate / 
This is a legacy product

Translate X12 EDI to JSON

EDI Translate takes X12 EDI and turns it into a JSON document. You may use a Stedi guide to describes the structure of the document. Guides ensure that EDI exchanged between trading partners meets their needs. The shape of the JSON document resembles the original X12 EDI, but you can map it into any shape you need.

You may also translate X12 EDI without a guide for more flexibility. Review calling the API without a guide for more details.

Envelopes

The interchange envelope (ISA) and functional group envelope (GS) are optional, but if you provide either, you should provide both. The input EDI can optionally contain the transaction set envelope (ST).

At the moment, it isn’t possible to translate EDI documents with multiple functional groups. Multiple transaction sets within the same functional group works fine, though.

Delimiters

The delimiters used during translation depend on the type of EDI document you submit.

  • EDI document with ISA envelope. The delimiters specified in the ISA segment are used for parsing purposes. Delimiters specified in the guide or as request input options are ignore in this case.
  • EDI document without ISA and GS envelopes. If EDI Translate is called with a guide, the delimiters specified in the guide will be used. If EDI Translate is called without a guide, the delimiters specified in guidelessInputOptions will be used.
The response of the to-json endpoint includes the delimiters used during processing of the EDI document.

Calling the API

You translate a document by calling the API. First you need an API key and then you can call the EDI Translate endpoint: https://edi-translate.us.stedi.com/2022-01-01/x12/to-json.

With a Guide

const axios = require("axios");

const apiKey = process.env.STEDI_API_KEY;

async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      guideId: guideId,
      input: document,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}

Without a Guide

Using EDI Translate without a Stedi guide lets you receive X12 EDI that might not conform to strict, partner-specific EDI requirements. Translation flexibility is useful for the following use cases:

  • Developing and testing a new trading partner integration
  • Troubleshooting EDI that doesn't meet your expectations
  • Developing a guide to make sure EDI you receive meets your requirements

When you translate EDI without a Stedi guide, EDI Translate validates the incoming EDI with the generic X12 release specification and uses a default structure definition for the resulting JSON document. For example, the output will use default names for all properties.

Therefore, we do not recommend translating without a Stedi guide in production scenarios that require accurately processing partner-specific data. For example, updating an ERP system in response to incoming EDI may require specific fields for data consistency. In this case, you should use a guide to ensure these fields are present before the data is passed to the ERP system.

To translate without a guide, simply omit the guideId argument from the API call.
async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      input: document,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}

If your X12 EDI document does not have an ISA or GS envelope you will need to specify an X12 release to use.

async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      input: document,
      inputOptions: {
        guidelessInputOptions: {
          x12Release: "004010",
        },
      },
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
EnvelopesDelimitersCalling the API

Feedback

Have an idea for something we could improve? Page not clear? We love feedback - send us a message.

Stedi

Build EDI integrations fast, without being an EDI expert

Start building
About
ProductPricingCareersContactBlog
Follow
  1. Twitter
  2. GitHub
Backed by
AdditionBloomberg BetaFirst RoundStripeUSV
Customer AgreementService TermsPrivacy Notice

Stedi is a registered trademark of Stedi, Inc. All names, logos, and brands of third parties listed on our site are trademarks of their respective owners (including “X12”, which is a trademark of X12 Incorporated). Stedi, Inc. and its products and services are not endorsed by, sponsored by, or affiliated with these third parties. Our use of these names, logos, and brands is for identification purposes only, and does not imply any such endorsement, sponsorship, or affiliation.