Home /  EDI Translate / 

Translate JSON to X12 EDI

EDI Translate takes a JSON document that’s already structured like EDI and turns it into an X12 EDI document. You need a Stedi guide that describes the structure. If you have a JSON document that’s not structured like EDI, you have to map it first.

  • See also: Create a Stedi guide
  • See also: Map a JSON 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/from-json.

const axios = require("axios");

const apiKey = process.env.STEDI_API_KEY;

async function jsonToX12(guideId, document, envelope) {
  if (typeof document === "string") {
    document = JSON.parse(document);
  }

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

  return response.data;
}

Envelope

EDI documents have envelopes that contain metadata. That metadata is typically not included in the JSON document, so you need to provide it separately.

There are three types of envelopes.

  • The interchange tells you who the message is for on an organization level. It identifies you as the sender and your trading partner as the receiver.
  • The functional group tells you who the message is for on a department level. Invoices go to the Finance department, ship notices go to the Shipping department, that sort of thing.
  • The transaction set represents a single document. An EDI message can contain multiple documents and the transaction set envelope helps keep them apart.

Each envelope has a start segment and an end segment. EDI Translate will generate these segments based on the data you provide.

{
  "interchangeHeader": {
    "senderQualifier": "ZZ",
    "senderId": "ME",
    "receiverQualifier": "ZZ",
    "receiverId": "YOU",
    "date": "2022-08-15",
    "time": "13:20",
    "usageIndicatorCode": "P",
    "controlNumber": "12"
  },
  "groupHeader": {
    "functionalIdentifierCode": "PO",
    "applicationSenderCode": "ME",
    "applicationReceiverCode": "YOUR DEPT",
    "date": "2022-08-15",
    "time": "13:20:52",
    "controlNumber": "1"
  }
}
Interchange fieldDescription
senderIdIdentifies the sender of the message.
senderQualifierIndicates the type of identifier used insenderId. For example, 01 means Duns, 20 means Health Industry Number, ZZ whatever you agree on. The implementation guide should tell you which values are valid. If not, contact your trading partner.
receiverIdIdentifies the receiver of the message.
receiverQualifierIndicates the type of identifier used inreceiverId. For example, 01 means Duns, 20 means Health Industry Number, ZZ whatever you agree on. The implementation guide should tell you which values are valid. If not, contact your trading partner.
dateThe date this message was sent, e.g.2022-08-15.
timeThe time this message was sent, e.g.13:20.
usageIndicatorCodeP if this is a production message, T if it’s a test message, I if the message is informational.
controlNumberA unique identifier for this interchange.
Functional group fieldDescription
functionalIdentifierCodeIndicates the type the message. Must be one of thestandardized functional identifier code.
applicationSenderCodeIndicates where the message came from. There are no standardized codes; you need to agree on valid values with your trading partner. If you can’t find this in the implementation guide, contact your trading partner.
applicationReceiverCodeIndicates where the message should go. There are no standardized codes; you need to agree on valid values with your trading partner. If you can’t find this in the implementation guide, contact your trading partner.
dateThe date this message was sent, e.g.2022-08-15.
timeThe time this message was sent, e.g.13:20:52.
controlNumberA unique identifier for this functional group.

You don’t have to provide data for the transaction set envelope; EDI Translate will take care of it. If you do want to specify the transaction set yourself, you should do so in the JSON document, not in the envelope field.

Calling the APIEnvelope