Integration Overview

Integration Paths at a Glance

Path 1: Mosaic Integration (Recommended)

Mosaic is Orderful's next-generation API, designed to make EDI integration as simple as working with any modern REST API.

Why Choose Mosaic?

• Simple Schema: Logical, human-readable field names (no EDI jargon)
• ERP-Oriented: Data structures match how your business systems work
• No Partner Mapping: Build once - Orderful handles partner-specific requirements
• Shorter Payloads: Contextual data inheritance means less repetition
• Real-Time Validation: Clear error messages during development

Example: Sending a Purchase Order Acknowledgment

{
  "type": "855_PURCHASE_ORDER_ACKNOWLEDGMENT",
  "stream": "test",
  "senderId": "SELLERISA",
  "receiverId": "BUYERISA",
  "message": {
    "purchaseOrderNumber": "PO-2024-001234",
    "status": "accepted",
    "parties": {
      "shipFrom": {
        "name": "Best Products Inc",
        "identificationCode": "VENDOR123"
      },
      "supplier": {
        "name": "Best Products Inc",
        "identificationCode": "VENDOR123"
      }
    },
    "lineItems": [
      {
        "purchaseOrderLineId": "1",
        "productIds": {
          "buyerItemNumber": "SKU-12345",
          "vendorItemNumber": "VPN-98765"
        },
        "actions": [
          {
            "status": "accepted",
            "quantity": {
              "value": "100",
              "unitOfMeasure": "each"
            },
            "scheduledShipDate": "2024-01-23",
            "estimatedDeliveryDate": "2024-01-25"
          }
        ]
      }
    ]
  }
}

API Versions Used

• v4: Create transactions, manage inbox, approve deliveries
• v3: List transactions, get transaction content

Path 2: Orderful JSON

Orderful JSON gives you full control over EDI document structure while still using JSON instead of raw X12.

Why Choose Orderful JSON?

• Full EDI Control: Access to all EDI segments and elements
• Partner-Specific Mapping: Create custom mappings when needed
• Existing EDI Knowledge: Leverage your team's EDI expertise
• Gradual Migration: Easier transition from legacy EDI systems

Example: Purchase Order in Orderful JSON

{
  "transactionType": "850",
  "sender": { "isaId": "YOUR_ISA_ID", "qualifier": "ZZ" },
  "receiver": { "isaId": "PARTNER_ISA_ID", "qualifier": "ZZ" },
  "message": {
    "heading": {
      "transactionSetHeader_ST": {
        "transactionSetIdentifierCode_01": "850",
        "transactionSetControlNumber_02": "0001"
      },
      "beginningSegmentForPurchaseOrder_BEG": {
        "transactionSetPurposeCode_01": "00",
        "purchaseOrderTypeCode_02": "SA",
        "purchaseOrderNumber_03": "PO-12345",
        "date_05": "20260115"
      }
    },
    "detail": {
      "purchaseOrderLineItems": [...]
    }
  }
}

API Versions Used

• v3: Create and manage transactions

When to Use

• You need precise control over EDI segment structure
• Your trading partners have complex, non-standard requirements
• Your team has existing EDI expertise
• You're migrating from a legacy EDI system

📘

Note: For most use cases, Mosaic is simpler and handles partner-specific requirements automatically. You may need ot use v3 for some transaciton types that are not supported by Mosaic.

Path 3: X12 Passthrough

X12 Passthrough allows you to send and receive raw EDI documents directly.

Why Choose X12 Passthrough?

• Existing Infrastructure: Connect your current EDI translator
• Full EDI Fidelity: No transformation or mapping by Orderful
• Legacy Integration: Bridge legacy systems to modern partners

Example: Raw X12 850

ISA*00*          *00*          *ZZ*YOURISAID      *ZZ*PARTNERISAID   *260115*1200*U*00401*000000001*0*T*>~
GS*PO*YOURISAID*PARTNERISAID*20260115*1200*1*X*004010~
ST*850*0001~
BEG*00*SA*PO-12345**20260115~
PO1*1*100*EA*25.00**VP*SKU-001~
CTT*1~
SE*5*0001~
GE*1*1~
IEA*1*000000001~

Communication Method

When using X12 passthrough, you will typically use an inbound and outbound communicaiton channel like AS2, VAN, or SFTP to connect to your existing EDI-capable system of record.

When to Use

• You have an existing EDI translator (Sterling, Gentran, etc.)
• You need to maintain exact EDI format control
• You're integrating legacy systems that only speak X12

Comparison Matrix

Making Your Decision

Choose Mosaic if:

• ✅ You're building a new integration
• ✅ You want the fastest path to production
• ✅ Your team doesn't have deep EDI expertise
• ✅ You're integrating with an ERP or modern system

Choose Orderful JSON if:

• ✅ You need precise control over EDI structure
• ✅ Your team has EDI expertise
• ✅ You have complex partner requirements

Choose X12 Passthrough if:

• ✅ You have an existing EDI translator
• ✅ You need to maintain raw EDI format
• ✅ You're bridging legacy systems

Next Steps

Ready to start building? Choose your path:

• 🚀 Mosaic Integration Guide - Recommended
• 📋 Orderful JSON Guide - Full EDI control
• 🔧 X12 Passthrough Guide - Raw EDI handling

Not sure? Start with Mosaic - you can always access the underlying data structures if needed.