Transaction Hierarchy

Transactions have several header and trailer segments that define the sender, the receiver and the transaction traded:

Interchange Control Header (ISA) - Optional in JSON and Mandatory in X12
Group Control Header (GS) - Optional in JSON and Mandatory in X12
Transaction Set Header (ST) - Optional in JSON and Mandatory in X12
Transaction Set Trailer (SE) - Optional in JSON and Mandatory in X12
Group Control Trailer (GE) - Mandatory in X12 only
Interchange Control Trailer (IEA) - Mandatory in X12 only

📘
Note on headers In JSON
Each header in JSON has the same meaning as in its equivalent in X12.
When posting or uploading a JSON to Orderful, we recommend that you don't include any headers within the transaction. All the required information are already in the payload of the POST /transactions endpoint or in the upload file (sender, receiver, transaction type, stream), so the headers don't provide any additional information.
Orderful will then auto-generate this header if required (when converting JSON to X12 for example.

ISA Interchange Control Header

In X12, this header is a segment that starts any EDI file. It identifies the sender and receiver of the transaction as well as the X12 version used. Between the ISA segment and the IEA segment, an EDI files can have several functional groups (GS segments).

{
  "interchangeControlHeader": [
    {
      "authorizationInformationQualifier": "00",
      "authorizationInformation": "          ",
      "securityInformationQualifier": "00",
      "securityInformation": "          ",
      "interchangeIDQualifier": "12",
      "interchangeSenderID": "ODF_BUYER      ",
      "interchangeIDQualifier1": "ZZ",
      "interchangeReceiverID": "ODF_SUPPLIER   ",
      "interchangeDate": "200828",
      "interchangeTime": "0932",
      "repetitionSeparator": "^",
      "interchangeControlStandardsIdentifier": "U",
      "interchangeControlVersionNumberCode": "00401",
      "interchangeControlNumber": "001234321",
      "acknowledgmentRequestedCode": "0",
      "interchangeUsageIndicatorCode": "T",
      "componentElementSeparator": ">"
    }
  ]

ISA*00*          *00*          *ZZ*ODF_BUYER      *ZZ*ODF_SUPPLIER   *200828*0932*U*00401*001234321*0*T*>~

Element of the Interchange Control Header segment:

JSON Element	X12 Element	Value	Description
authorizationInformationQualifier	I01	00	This qualifier defines the type of data transmitted between partners. 00 means Authorization Information Present (No Meaningful Information in I02). It's the most common qualifier used but other qualifiers exist, such as 08 (Ocean Communications ID) or 05 (Department of Defense (DoD)).
authorizationInformation	I02		Information used for additional identification or authorization of the interchange sender or the data in the interchange; the type of information is set by the Authorization Information Qualifier (I01)
securityInformationQualifier	I03	00
securityInformation	I04
interchangeIDQualifier	I05	ZZ	This qualifier describes the type of ISA ID given in the element `interchangeSenderID` (ISA06). ZZ means Mutually Defined. Other qualifiers can be used, such as 12 (Phone (Telephone Companies)) or 01 (Duns (Dun & Bradstreet)).
interchangeSenderID	I06	ODF_BUYER	ODF_BUYER is the ISA ID of the sender of all the transactions included in this functional group.
interchangeIDQualifier1	I05	ZZ	This qualifier describes the type of ISA ID given in the element `interchangeReceiverID` (ISA08). ZZ means Mutually Defined. Other qualifiers can be used, such as 12 (Phone (Telephone Companies)) or 01 (Duns (Dun & Bradstreet)).
interchangeReceiverID	I07	ODF_SUPPLIER	ODF_SUPPLIER is the ISA ID of the receiver of all the transactions included in this functional group.
interchangeDate	I08	200828	This EDI file has been sent on Aug 28th 2020.
interchangeTime	I09	0932	This EDI file has been sent on Aug 28th 2020 at 09:32.
repetitionSeparator	I65	^	This is a delimiter used to separate repeated occurrences of a data element or a composite data structure. This element isn't used in all X12 version
interchangeControlStandardsIdentifier	I10	U	This identifier defines the agency responsible for the standard used. U means U.S. EDI Community of ASC X12, TDCC, and UCS. This identifier isn't available on all the X12 version.
interchangeControlVersionNumberCode	I11	00401	This code is the X12 version number used for this functional group. 00401 means Standards Approved for Publication by ASC X12 Procedures Review Board through October 1997. Other codes can be used such as 00705 (Standards Approved for Publication by ASC X12 Procedures Review Board through December 2017).
interchangeControlNumber	I12	001234321	The EDI file is referenced by this control number 001234321. This number would be useful if you need to find a transaction when you troubleshoot an error with your partner.
acknowledgmentRequestedCode	I13	0	This code informs the receiver of the transactions if an acknowledgment is needed. 0 = No Acknowledgment Requested 1 = Interchange Acknowledgment Requested
interchangeUsageIndicatorCode	ISA14	T	This code defines if the EDI contains test or production data. T means Test. P means Production.
componentElementSeparator	ISA15	>	This is a delimiter used to separate separate component data elements within a composite data structure.

GS Group Control Header

The functional group gathers one or several transaction set (ST segment).
All the transaction sets included inside one functional group are from the same transaction type.

"functionalGroupHeader": [
    {
      "functionalIdentifierCode": "PO",
      "applicationSendersCode": "ODF_BUYER",
      "applicationReceiversCode": "ODF_SUPPLIER",
      "date": "20200828",
      "time": "0932",
      "groupControlNumber": "1234321",
      "responsibleAgencyCode": "X",
      "versionReleaseIndustryIdentifierCode": "004010"
    }
  ],

GS*PO*ODF_BUYER*ODF_SUPPLIER*20200828*0932*123432*X*004010~

JSON Element	X12 Element	Value	Description
functionalIdentifierCode	GS01	PO	This 3 digit code is unique per transaction type. PO = Purchase order (850) IN = Invoice Information (810) SM = Motor Carrier Load Tender (204) GF = Response to a Load Tender (990) QM = Transportation Carrier Shipment Status Message (214) OW = Warehouse Shipping Order (940) SW = Warehouse Shipping Advice (945) RE = Warehouse Stock Receipt Advice (944) AR = Warehouse Stock Transfer Shipment Advice (943)
applicationSendersCode	GS02	ODF_BUYER	ODF_BUYER is the ISA ID of the sender of all the transactions included in this functional group.
applicationReceiversCode	GS03	ODF_SUPPLIER	ODF_SUPPLIER is the ISA ID of the receiver of all the transactions included in this functional group.
date	GS04	20200828	This functional group has been sent on Aug 28th 2020.
time	GS05	0932	This functional group has been sent on Aug 28th 2020 at 09:32.
groupControlNumber	GS06	1234321	This is the control number of the functional group. This control number can be useful to reference a single transaction along with the control numbers from the ISA and ST segments when troubleshooting a production error on a specific transaction with your partner.
responsibleAgencyCode	GS07	X	This code defines which agency standards the functional group is respecting. X = Accredited Standards Committee X12 T = Transportation Data Coordinating Committee (TDCC)
versionReleaseIndustryIdentifierCode	GS08	004010	This is the X12 version number used for this functional group.

ST Transaction Set Header

"transactionSetHeader": [
        {
          "transactionSetIdentifierCode": "850",
          "transactionSetControlNumber": "0001"
        }
      ]

ST*850*001~

JSON Element	X12 Element	Value	Description
transactionSetIdentifierCode	ST01	850	This 3 digit code is unique per transaction type. 850 = Purchase order. 810 = Invoice 204 = Motor Carrier Load Tender 990 = Response to a Load Tender 214 = Transportation Carrier Shipment Status Message 940 = Warehouse Shipping Order 945 = Warehouse Shipping Advice 944 = Warehouse Stock Transfer Receipt Advice 943 = Warehouse Stock Transfer Shipment Advice
transactionSetControlNumber	ST02	0001	This is the control number of the transaction set. This control number can be useful to reference a single transaction along with the control numbers from the ISA and GS segments when troubleshooting a production error on a specific transaction with your partner.

SE Transaction Set Trailer

"transactionSetTrailer": [
        {
          "numberOfIncludedSegments": "16",
          "transactionSetControlNumber": "001"
        }

SE*16*0001~

JSON Element	X12 Element	Value	Description
numberOfIncludedSegments	SE01	16	16 is the number of segments included between the previous ST segment and the SE segment (ST and SE segments included).
transactionSetControlNumber	SE02	0001	This control number must match the previous control number of the ST segment.

GE Group Control Trailer

No JSON equivalent

GE*1*1234321~

JSON Element	X12 Element	Value	Description
N/A	GE01	1	1 is the number of ST segments included between the previous GS segment and the GE segment.
N/A	GE02	1234321	This control number must match the previous control number of the GS segment.

IEA Interchange Control Trailer

No JSON equivalent

IEA*1*001234321~

Element	X12 Element	Value	Description
N/A	IEA01	1	1 is the number of GE segments included between the previous ISA segment and the IEA segment.
N/A	IEA02	001234321	This control number must match the previous control number of the ISA segment.

Transaction headers example

{
  "interchangeControlHeader": [
    {
      "authorizationInformationQualifier": "00",
      "authorizationInformation": "          ",
      "securityInformationQualifier": "00",
      "securityInformation": "          ",
      "interchangeIDQualifier": "12",
      "interchangeSenderID": "ODF_BUYER      ",
      "interchangeIDQualifier1": "ZZ",
      "interchangeReceiverID": "ODF_SUPPLIER   ",
      "interchangeDate": "200828",
      "interchangeTime": "0932",
      "repetitionSeparator": "^",
      "interchangeControlStandardsIdentifier": "U",
      "interchangeControlVersionNumberCode": "00401",
      "interchangeControlNumber": "001234321",
      "acknowledgmentRequestedCode": "0",
      "interchangeUsageIndicatorCode": "T",
      "componentElementSeparator": ">"
    }
  ],
  "functionalGroupHeader": [
    {
      "functionalIdentifierCode": "PO",
      "applicationSendersCode": "ODF_BUYER",
      "applicationReceiversCode": "ODF_SUPPLIER",
      "date": "20200828",
      "time": "0932",
      "groupControlNumber": "1234321",
      "responsibleAgencyCode": "X",
      "versionReleaseIndustryIdentifierCode": "004010"
    }
  ],
  "transactionSets": [
    {
      "transactionSetHeader": [
        {
          "transactionSetIdentifierCode": "850",
          "transactionSetControlNumber": "001"
        }
      ],
/*   
      [...] Transaction loops, segments and elements
*/    
      "transactionSetTrailer": [
        {
          "numberOfIncludedSegments": "16",
          "transactionSetControlNumber": "001"
        }
      ]
    }
  ]
}

ISA*00*          *00*          *ZZ*ODF_BUYER      *ZZ*ODF_SUPPLIER   *200828*0932*U*00401*001234321*0*T*>~
GS*PO*ODF_BUYER*ODF_SUPPLIER*20200828*0932*123432*X*004010~
ST*850*001~
/*
[...] Transaction loops, segments and elements
*/
SE*16*001~
GE*1*1234321~
IEA*1*001234321~