Integration Paths at a Glance

Path	Best For	Complexity	Recommended
Mosaic	New integrations, ERP systems	⭐ Low	✅ Yes
Orderful JSON	Existing EDI expertise, custom mappings	⭐⭐ Medium	For specific needs
X12 Passthrough	Existing EDI infrastructure	⭐⭐⭐ Higher	Legacy systems

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

Get Started

👉 Mosaic Integration Guide

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~

Communicaiton 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

Feature	Mosaic	Orderful JSON	X12 Passthrough
Schema complexity	Simple	Medium	Complex
EDI knowledge required	None	Some	Extensive
Partner-specific mapping	Automatic	Manual	Manual
Payload size	Smallest	Medium	Largest
Real-time validation	✅ Full	✅ Full	⚠️ Basic
Error messages	Business-friendly	Technical	Raw EDI
Time to integrate	Days	Weeks	Weeks+

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.