StediDOCS

EDI Core

EDI Core translates X12 EDI documents to JSON and vice versa. Stedi has its own JSON representation of EDI, called JEDI. JEDI is easier to work with than X12 EDI because most modern programming languages and tools have built-in support for JSON.

EDI Core also validates the documents during translation. You can choose to check against one of the following.

  • The standard X12 specifications.
  • A popular spec, such as Walmart's 855 Purchase Order Acknowledgment.
  • A custom mapping guide of your own.

A quick demonstration

EDI Core is fully accessible via API, but if you want to take it for a quick spin, you can also see the functionality in action via the Stedi console. Just paste an EDI document into the input box and it will be translated to JEDI. If you don't have an EDI file handy, you can click use our sample file.

Any validation error will show up in red in the input document. Hover over the offending element to get more information.

Using the API

The EDI Core API allows you to do translation and validation programmatically. Make sure you have set up an API key and that you include the key in the Authorization header when you make a request.

Translation

To translate a document, you need three pieces of information.

  • The document you want to translate.
  • The format of that document.
  • The output format that you want to get back.

You have two options when it comes to document format: edi and jedi@2.0-beta.

POST https://edi-core.stedi.com/2021-06-05/translate
Authorization: Key $STEDI_API_KEY
Content-Type: application/json

{
  "input": "ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*U*00401*123456789*1*T*:~GS*IN*00*00*20210902*1200*987654321*X*004010~ST*810*0000~BIG*20210902*AB01010101~TDS*999~SE*4*0000~GE*1*987654321~IEA*1*123456789~",
  "input_format": "edi",
  "output_format": "jedi@2.0-beta"
}
curl --location --request POST "https://edi-core.stedi.com/2021-06-05/translate" --header "Content-Type: application/json" --data-raw '{"input": "ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*U*00401*123456789*1*T*:~GS*IN*00*00*20210902*1200*987654321*X*004010~ST*810*0000~BIG*20210902*AB01010101~TDS*999~SE*4*0000~GE*1*987654321~IEA*1*123456789~","input_format": "edi", "output_format": "jedi@2.0-beta"}' --header "Authorization: Key $STEDI_API_KEY"

The API will return a JSON object, which has a field output that contains the translated document.

{
  "code": "valid",
  "output": {
    "interchanges": [
      {
        "groups": [
          {
            "transaction_sets": [
              {
                "heading": {
                  "transaction_set_header_ST": {
                    "transaction_set_identifier_code_01": "810",
                    "transaction_set_control_number_02": "0000"
                  },
                  "beginning_segment_for_invoice_BIG": {
                    "date_01": "20210902",
                    "invoice_number_02": "AB01010101"
                  }
                },
                "summary": {
                  "total_monetary_value_summary_TDS": {
                    "amount_01": "999"
                  },
                  "transaction_set_trailer_SE": {
                    "number_of_included_segments_01": "4",
                    "transaction_set_control_number_02": "0000"
                  }
                }
              }
            ],
            "functional_group_header_GS": {
              "functional_identifier_code_01": "invoice_information_810819",
              "application_senders_code_02": "00",
              "application_receivers_code_03": "00",
              "date_04": "20210902",
              "time_05": "1200",
              "group_control_number_06": "987654321",
              "responsible_agency_code_07": "accredited_standards_committee_x12",
              "version_release_industry_identifier_code_08": "004010"
            },
            "functional_group_trailer_GE": {
              "number_of_transaction_sets_included_01": "1",
              "group_control_number_02": "987654321"
            }
          }
        ],
        "delimiters": {
          "element": "*",
          "segment": "~",
          "sub_element": ":"
        },
        "interchange_control_header_ISA": {
          "authorization_information_qualifier_01": "no_authorization_information_present_no_meaningful_information_in_i02",
          "authorization_information_02": "",
          "security_information_qualifier_03": "no_security_information_present_no_meaningful_information_in_i04",
          "security_information_04": "",
          "interchange_id_qualifier_05": "mutually_defined",
          "interchange_sender_id_06": "",
          "interchange_id_qualifier_07": "mutually_defined",
          "interchange_receiver_id_08": "",
          "interchange_date_09": "210902",
          "interchange_time_10": "1200",
          "interchange_control_standards_identifier_11": "us_edi_community_of_asc_x12_tdcc_and_ucs",
          "interchange_control_version_number_code_12": "00401",
          "interchange_control_number_13": "123456789",
          "acknowledgment_requested_code_14": "interchange_acknowledgment_requested",
          "interchange_usage_indicator_code_15": "test_data",
          "component_element_separator_16": ":"
        },
        "interchange_control_trailer_IEA": {
          "number_of_included_functional_groups_01": "1",
          "interchange_control_number_02": "123456789"
        }
      }
    ],
    "__version": "jedi@2.0-beta"
  }
}

Note that EDI is always represented as a string and JEDI is always represented as JSON; that's why the output in the example above is a JSON object. It's also true when you translate the other way around, so if you translate from JEDI to EDI, you need to provide the input as a JSON object, not as a string.

Validation

The response from the API will include validation information. To know if validation succeeded, you can look at the code field.

CodeDescription
validThe document passed validation.
invalidThe document violates the X12 specification.

If the document fails validation, the response will also include an errors field that gives you more information about what went wrong.

Even if a document is invalid, the translation is still included in the response. Only if the document is malformed, and therefore can't be parsed, will the translation be absent.

Validate using a custom mapping guide

By default, EDI Core validates your documents using the standard X12 transaction sets. However, you can also use a mapping guide published by your trading partner, or create a guide of your own. All you need is the ID of the guide.

  • If you want to validate against a published mapping guide:

    1. Select your trading partner.
    2. Click on the guide you want.
    3. Select the version from the dropdown list next to the search box.
    4. Copy the ID of that version.
  • If you want to validate against your own guide, you can get the ID by going to EDI Guides in the Stedi console.

    1. Click on the guide you want to use.
    2. From the list of versions, copy the ID.

You can send that ID to the API as part of the validation_options field.

POST https://edi-core.stedi.com/2021-06-05/translate
Authorization: Key $STEDI_API_KEY
Content-Type: application/json

{
  "input": "ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*U*00401*123456789*1*T*:~GS*IN*00*00*20210902*1200*987654321*X*004010~ST*810*0000~BIG*20210902*AB01010101~TDS*999~SE*4*0000~GE*1*987654321~IEA*1*123456789~",
  "input_format": "edi",
  "output_format": "jedi@2.0-beta",
  "validation_options": {
    "validation_type": "specification",
    "validation_id": "01FAJW8S4NSWGZ96VMSED25BRF"
  }
}
curl --location --request POST "https://edi-core.stedi.com/2021-06-05/translate" --header "Content-Type: application/json" --data-raw '{"input": "ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*U*00401*123456789*1*T*:~GS*IN*00*00*20210902*1200*987654321*X*004010~ST*810*0000~BIG*20210902*AB01010101~TDS*999~SE*4*0000~GE*1*987654321~IEA*1*123456789~","input_format": "edi","output_format": "jedi@2.0-beta","validation_options": { "validation_type": "base", "validation_id": "01FAJW8S4NSWGZ96VMSED25BRF" }}' --header "Authorization: Key $STEDI_API_KEY"

Override EDI delimiters

A JEDI document contains information on which delimiters to use when converting it to EDI. If you want, you can override these delimiters when you call the API.

POST https://edi-core.stedi.com/2021-06-05/translate
Authorization: Key $STEDI_API_KEY
Content-Type: application/json

{
  "input": {"interchanges":[{"groups":[{"transaction_sets":[{"heading":{"transaction_set_header_ST":{"transaction_set_identifier_code_01":"326","transaction_set_control_number_02":"0000"},"vessel_identification_V1_loop":[{"vessel_identification_V1":{"vessel_code_01":"12"},"port_or_terminal_R4_loop":[{"port_or_terminal_R4":{"port_or_terminal_function_code_01":"final_port_of_discharge_operational"}}]}],"transaction_set_trailer_SE":{"number_of_included_segments_01":"2","transaction_set_control_number_02":"0000"}}}],"functional_group_header_GS":{"functional_identifier_code_01":"ocean_shipment_information_304_311_317_319_322_323_324_325_326_361","application_senders_code_02":"00","application_receivers_code_03":"00","date_04":"20210902","time_05":"1200","group_control_number_06":"987654321","responsible_agency_code_07":"accredited_standards_committee_x12","version_release_industry_identifier_code_08":"008010"},"functional_group_trailer_GE":{"number_of_transaction_sets_included_01":"1","group_control_number_02":"987654321"}}],"delimiters":{"element":"*","segment":"~","sub_element":":","repetition":"\/"},"interchange_control_header_ISA":{"authorization_information_qualifier_01":"no_authorization_information_present_no_meaningful_information_in_i02","authorization_information_02":"","security_information_qualifier_03":"no_security_information_present_no_meaningful_information_in_i04","security_information_04":"","interchange_id_qualifier_05":"mutually_defined","interchange_sender_id_06":"","interchange_id_qualifier_07":"mutually_defined","interchange_receiver_id_08":"","interchange_date_09":"210902","interchange_time_10":"1200","repetition_separator_11":"\/","interchange_control_version_number_code_12":"00801","interchange_control_number_13":"123456789","acknowledgment_requested_code_14":"interchange_acknowledgment_requested_ta1","interchange_usage_indicator_code_15":"test_data","component_element_separator_16":":"},"interchange_control_trailer_IEA":{"number_of_included_functional_groups_01":"1","interchange_control_number_02":"123456789"}}]},
  "input_format": "jedi@2.0-beta",
  "output_format": "edi",
  "output_options": {
    "delimiters": {
      "element": "+",
      "segment": "`",
      "repetition": "=",
      "sub_element": ":"
    }
  }
}
curl --location --request POST "https://edi-core.stedi.com/2021-06-05/translate" --header "Content-Type: application/json" --data-raw '{"input": {"interchanges":[{"groups":[{"transaction_sets":[{"heading":{"transaction_set_header_ST":{"transaction_set_identifier_code_01":"326","transaction_set_control_number_02":"0000"},"vessel_identification_V1_loop":[{"vessel_identification_V1":{"vessel_code_01":"12"},"port_or_terminal_R4_loop":[{"port_or_terminal_R4":{"port_or_terminal_function_code_01":"final_port_of_discharge_operational"}}]}],"transaction_set_trailer_SE":{"number_of_included_segments_01":"2","transaction_set_control_number_02":"0000"}}}],"functional_group_header_GS":{"functional_identifier_code_01":"ocean_shipment_information_304_311_317_319_322_323_324_325_326_361","application_senders_code_02":"00","application_receivers_code_03":"00","date_04":"20210902","time_05":"1200","group_control_number_06":"987654321","responsible_agency_code_07":"accredited_standards_committee_x12","version_release_industry_identifier_code_08":"008010"},"functional_group_trailer_GE":{"number_of_transaction_sets_included_01":"1","group_control_number_02":"987654321"}}],"delimiters":{"element":"*","segment":"~","sub_element":":","repetition":"\/"},"interchange_control_header_ISA":{"authorization_information_qualifier_01":"no_authorization_information_present_no_meaningful_information_in_i02","authorization_information_02":"","security_information_qualifier_03":"no_security_information_present_no_meaningful_information_in_i04","security_information_04":"","interchange_id_qualifier_05":"mutually_defined","interchange_sender_id_06":"","interchange_id_qualifier_07":"mutually_defined","interchange_receiver_id_08":"","interchange_date_09":"210902","interchange_time_10":"1200","repetition_separator_11":"\/","interchange_control_version_number_code_12":"00801","interchange_control_number_13":"123456789","acknowledgment_requested_code_14":"interchange_acknowledgment_requested_ta1","interchange_usage_indicator_code_15":"test_data","component_element_separator_16":":"},"interchange_control_trailer_IEA":{"number_of_included_functional_groups_01":"1","interchange_control_number_02":"123456789"}}]},"input_format": "jedi@2.0-beta","output_format": "edi","output_options": {"delimiters": {"element": "+","segment": "`","repetition": "=","sub_element": ":"}}}' --header "Authorization: Key $STEDI_API_KEY"

Generating Control Numbers

X12 documents contain several control numbers:

  • a 9-digit number in ISA-13
  • a 1 to 9 digit number in GS-06
  • a 4 to 9 digit number in ST-02

When translating JEDI to EDI, you can request that the ISA and GS control numbers be generated for you. Stedi will fill in ISA-13 and GS-06 with sequential numbers that are unique for the sender + receiver pair specified in the ISA. More specifically, the combination of the following fields determines the sequence to use to generate the numbers:

  • ISA-05 and 06 - The sender qualifier and ID
  • ISA-07 and 08 - The receiver qualifier and ID
  • ISA-15 - The usage indicator (test vs. production)
POST https://edi-core.stedi.com/2021-06-05/translate
Authorization: Key $STEDI_API_KEY
Content-Type: application/json

{
  "input": {"interchanges":[{"groups":[{"transaction_sets":[{"heading":{"transaction_set_header_ST":{"transaction_set_identifier_code_01":"326","transaction_set_control_number_02":"0001"},"vessel_identification_V1_loop":[{"vessel_identification_V1":{"vessel_code_01":"12"},"port_or_terminal_R4_loop":[{"port_or_terminal_R4":{"port_or_terminal_function_code_01":"final_port_of_discharge_operational"}}]}],"transaction_set_trailer_SE":{"number_of_included_segments_01":"2","transaction_set_control_number_02":"0001"}}}],"functional_group_header_GS":{"functional_identifier_code_01":"ocean_shipment_information_304_311_317_319_322_323_324_325_326_361","application_senders_code_02":"00","application_receivers_code_03":"00","date_04":"20210902","time_05":"1200","group_control_number_06":"","responsible_agency_code_07":"accredited_standards_committee_x12","version_release_industry_identifier_code_08":"008010"}}],"delimiters":{"element":"*","segment":"~","sub_element":":","repetition":"\/"},"interchange_control_header_ISA":{"authorization_information_qualifier_01":"no_authorization_information_present_no_meaningful_information_in_i02","authorization_information_02":"","security_information_qualifier_03":"no_security_information_present_no_meaningful_information_in_i04","security_information_04":"","interchange_id_qualifier_05":"mutually_defined","interchange_sender_id_06":"SENDER","interchange_id_qualifier_07":"mutually_defined","interchange_receiver_id_08":"RECEIVER","interchange_date_09":"210902","interchange_time_10":"1200","repetition_separator_11":"\/","interchange_control_version_number_code_12":"00801","interchange_control_number_13":"","acknowledgment_requested_code_14":"interchange_acknowledgment_requested_ta1","interchange_usage_indicator_code_15":"test_data","component_element_separator_16":":"}}]},
  "input_format": "jedi@2.0-beta",
  "output_format": "edi",
  "output_options": {
    "generate_control_numbers": true
  }
}
curl --location --request POST "https://edi-core.stedi.com/2021-06-05/translate" --header "Content-Type: application/json" --data-raw '{"input": {"interchanges":[{"groups":[{"transaction_sets":[{"heading":{"transaction_set_header_ST":{"transaction_set_identifier_code_01":"326","transaction_set_control_number_02":"0001"},"vessel_identification_V1_loop":[{"vessel_identification_V1":{"vessel_code_01":"12"},"port_or_terminal_R4_loop":[{"port_or_terminal_R4":{"port_or_terminal_function_code_01":"final_port_of_discharge_operational"}}]}],"transaction_set_trailer_SE":{"number_of_included_segments_01":"2","transaction_set_control_number_02":"0001"}}}],"functional_group_header_GS":{"functional_identifier_code_01":"ocean_shipment_information_304_311_317_319_322_323_324_325_326_361","application_senders_code_02":"00","application_receivers_code_03":"00","date_04":"20210902","time_05":"1200","group_control_number_06":"","responsible_agency_code_07":"accredited_standards_committee_x12","version_release_industry_identifier_code_08":"008010"}}],"delimiters":{"element":"*","segment":"~","sub_element":":","repetition":"\/"},"interchange_control_header_ISA":{"authorization_information_qualifier_01":"no_authorization_information_present_no_meaningful_information_in_i02","authorization_information_02":"","security_information_qualifier_03":"no_security_information_present_no_meaningful_information_in_i04","security_information_04":"","interchange_id_qualifier_05":"mutually_defined","interchange_sender_id_06":"SENDER","interchange_id_qualifier_07":"mutually_defined","interchange_receiver_id_08":"RECEIVER","interchange_date_09":"210902","interchange_time_10":"1200","repetition_separator_11":"\/","interchange_control_version_number_code_12":"00801","interchange_control_number_13":"","acknowledgment_requested_code_14":"interchange_acknowledgment_requested_ta1","interchange_usage_indicator_code_15":"test_data","component_element_separator_16":":"}}]}, "input_format": "jedi@2.0-beta", "output_format": "edi", "output_options": {"generate_control_numbers": true}}' --header "Authorization: Key $STEDI_API_KEY"

Stedi will not generate the same control number twice, unless:

  • the sequence wraps back to 1, which happens if it exceeds 9 digits (i.e. upon reaching 1 billion), or
  • you explicitly set the sequence's value back to a number that has previously been generated (see below)

Setting Control Number Values

If you need a control number sequence to start at a number other than 1, you can set the current value via an API call, specifying the values for the specific ISA fields listed above.

POST https://edi-core.stedi.com/2021-06-05/control_numbers/set
Authorization: Key $STEDI_API_KEY
Content-Type: application/json

{
  "sequence": {
    "sender": {
      "id": "SENDER",
      "qualifier": "ZZ"
    },
    "receiver": {
      "id": "RECEIVER",
      "qualifier": "ZZ"
    },
    "usage": "T"
  },
  "value": 1000
}
curl --location --request POST "https://edi-core.stedi.com/2021-06-05/control_numbers/set" --header "Content-Type: application/json" --data-raw '{"sequence": {"sender": {"id": "SENDER", "qualifier": "ZZ"}, "receiver": {"id": "RECEIVER", "qualifier": "ZZ"}, "usage": "T"}, "value": 1000}' --header "Authorization: Key $STEDI_API_KEY"

In the example above, we set the value of the given sequence to 1000. The next generated control number from this sequence will be 1001.

API Reference