EDI 101

Electronic Data Interchange (EDI) is the backbone of freight communication. This guide explains EDI fundamentals and how Flint handles EDI messages.

What is EDI?

EDI is a standardized way for businesses to exchange documents electronically. Instead of emails or PDFs, EDI uses structured formats that systems can automatically process.

Key Benefits

• Automation - No manual data entry
• Speed - Near real-time communication
• Accuracy - Eliminates transcription errors
• Standardization - Common format across partners

EDI Standards

X12 (North America)

Most common in US freight:

• 204 - Motor Carrier Load Tender
• 210 - Motor Carrier Freight Invoice
• 214 - Transportation Carrier Shipment Status
• 990 - Response to Load Tender
• 997 - Functional Acknowledgment

EDIFACT (International)

Used globally, especially in ocean freight:

• IFTMIN - Instruction Message
• IFTMAN - Arrival Notice
• IFTSTA - Status Message
• INVOIC - Invoice Message

EDI Message Structure

Anatomy of an EDI 214 (Status Update)

ISA*00*          *00*          *ZZ*SENDER123     *ZZ*RECEIVER456   *240115*1430*U*00401*000000001*0*P*>~
GS*QM*SENDER123*RECEIVER456*20240115*1430*1*X*004010~
ST*214*0001~
B10*123456*SCAC001*PP~
L11*BOL123456*BM~
L11*PO789012*PO~
AT7*AF*NS***20240115*1400*ET~
MS1*DALLAS*TX*US~
AT8*G*L*350*KG~
SE*9*0001~
GE*1*1~
IEA*1*000000001~

Key Segments Explained

• ISA/IEA - Interchange envelope (outer wrapper)
• GS/GE - Functional group (document type)
• ST/SE - Transaction set (specific message)
• B10 - Shipment identification
• L11 - Reference numbers (BOL, PO, etc.)
• AT7 - Shipment status details
• MS1 - Location information

Trading Partners

Setting Up Trading Partner Connections

1. Exchange EDI IDs

   {
     "partner_name": "ABC Logistics",
     "edi_id": "ABCLOG",
     "qualifier": "ZZ",
     "test_id": "ABCLOG_TEST"
   }

2. Configure Communication

   • AS2 - Direct, secure connection
   • FTP/SFTP - File-based transfer
   • VAN - Value Added Network
   • API - Modern REST/webhook approach

3. Map Data Fields Partner's field → Standard field → Your system

Common Trading Partner Types

• Shippers - Send load tenders (204)
• Carriers - Send status updates (214)
• 3PLs - Exchange various message types
• Customs Brokers - Send entry summaries

Flint's EDI Processing

Automatic Parsing

Flint automatically detects and parses EDI messages:

// Upload EDI file
const result = await client.documents.parse({
  file: ediFileContent,
  documentType: 'edi',
  ediType: '214' // Optional: specify message type
});

// Result includes structured data
{
  "message_type": "214",
  "shipment_id": "123456",
  "status": "delivered",
  "location": {
    "city": "DALLAS",
    "state": "TX"
  },
  "timestamp": "2024-01-15T14:00:00Z"
}

EDI Validation

Flint validates EDI messages against:

• Syntax rules (proper segments and elements)
• Business rules (required fields, valid codes)
• Partner-specific requirements

EDI to Human-Readable

Convert EDI to readable format:

const readable = await client.edi.humanize('edi_doc_123');
// Returns formatted, easy-to-read version

Common EDI Workflows

1. Load Tender Accept/Reject

Shipper → 204 (Load Tender) → Carrier
Carrier → 990 (Accept/Reject) → Shipper
Carrier → 214 (Status Updates) → Shipper
Carrier → 210 (Invoice) → Shipper

2. Shipment Tracking

// Set up workflow for 214 messages
await client.workflows.create({
  name: 'Process Status Updates',
  trigger: {
    type: 'edi_received',
    edi_type: '214'
  },
  actions: [
    {
      type: 'parse_edi'
    },
    {
      type: 'update_shipment',
      field_mapping: {
        'AT7.StatusCode': 'status',
        'MS1.City': 'current_location'
      }
    },
    {
      type: 'notify_if',
      condition: 'status == "delivered"',
      recipients: ['customer@email.com']
    }
  ]
});

EDI Best Practices

1. Always Acknowledge

Send 997 functional acknowledgments for received messages

2. Validate Before Processing

Check for required fields and valid codes

3. Handle Errors Gracefully

• Log rejected messages
• Send clear error responses
• Maintain error queues for review

4. Test Thoroughly

• Use test IDs during setup
• Validate with sample messages
• Run parallel testing before cutover

5. Monitor Continuously

• Track message volumes
• Alert on failures
• Monitor partner compliance

Troubleshooting EDI

Common Issues

1. Missing Segments

   • Error: "Mandatory segment AT7 missing"
   • Fix: Ensure partner includes all required segments

2. Invalid Codes

   • Error: "Invalid status code 'XYZ'"
   • Fix: Use standard EDI code lists

3. Sequence Errors

   • Error: "Segment out of sequence"
   • Fix: Follow proper segment order

Debugging Tools

// Validate EDI message
const validation = await client.edi.validate(ediContent);
console.log(validation.errors);

// View EDI in tree structure
const tree = await client.edi.parse(ediContent, {
  format: 'tree'
});

Next Steps

• Workflows - Build EDI processing workflows
• Integrations - Connect EDI to your systems
• API EDI Endpoints - EDI-specific API calls