MES/ERP Data Contract & API Template

Purpose

This template helps teams create clear, versioned data contracts and a minimal API/event envelope for MES–ERP integration. Use it to reduce mapping ambiguity, avoid reconciliation firefights, and enable reliable cross-system decisions for production, inventory, scheduling, and genealogy.

Scope

Contains: canonical field lists for core exchange objects, event/API envelope, sample JSON payloads, versioning rules, error-handling patterns, reconciliation test cases, security and ownership notes, and a stepwise rollout checklist. It is intentionally vendor-neutral and focuses on governance and repeatable patterns rather than vendor-specific APIs.

How to use this template

1. Copy the template into your integration design document or toolkit.
2. Fill in site-specific identifiers, master-of-record decisions, and allowable value lists.
3. Use the sample events as the basis for mock-data tests and reconciliation test cases.
4. Version the contract and publish it to both MES and ERP teams with an agreed rollout plan.

Versioning and Contract Rules

• Semantic versioning: Use MAJOR.MINOR.PATCH (e.g., 1.2.0). MAJOR changes are breaking (rename/remove fields or change data meaning). MINOR adds non-breaking fields. PATCH is bugfix/clarification only.
• Version in header: Every event/API call MUST include contractVersion in the envelope.
• Deprecation window: When changing MAJOR, announce deprecation and maintain previous version for a minimum agreed period (commonly 3 months for pilots, 6–12 months for production) or until consumers confirm readiness.
• Backward compatibility: Producers must avoid removing fields. Consumers should ignore unknown fields.
• Change log and acceptance tests: Each version publishes a short change log and a set of acceptance test cases that must pass in staging before cutover.

API/Event Envelope (recommended minimal model)

Use a consistent envelope around payloads to support routing, idempotency, audit, and reconciliation.

{
  "eventId": "uuid-v4",
  "eventType": "WorkOrder.Created | Material.Reserved | Production.Completed | Genealogy.Event",
  "contractVersion": "1.0.0",
  "sourceSystem": "ERP | MES",
  "sourceSystemId": "system-specific-id",
  "timestamp": "2024-07-10T15:23:45Z",
  "correlationId": "optional-correlation-id",
  "payload": { /* object specific fields */ }
}

• eventId: globally unique idempotency key.
• eventType: canonical string identifying payload structure.
• contractVersion: contract version implementing the payload schema.
• sourceSystem / sourceSystemId: origin for ownership and debugging.
• correlationId: optional for tracing user flows or transactions across systems.

Canonical Field Lists (start)

These are suggested canonical fields and types for common objects. Add site-specific keys and enums as needed; don't rename without a MAJOR version change.

WorkOrder (payload for WorkOrder.Created / Updated)

• workOrderId (string) — unique in enterprise context
• externalRef (string) — customer PO or scheduler reference
• partNumber (string)
• quantityOrdered (number)
• quantityRemaining (number)
• scheduledStart (ISO8601 timestamp)
• scheduledEnd (ISO8601 timestamp)
• status (enum) — Planned | Released | Started | Completed | Cancelled
• routingId (string) — optional routing or process identifier
• revision (string) — BOM/revision reference

MaterialReservation (payload for Material.Reserved / Released)

• reservationId (string)
• workOrderId (string)
• partNumber (string)
• reservedQuantity (number)
• warehouseLocationId (string)
• uom (string) — unit of measure
• status (enum) — Reserved | Released | Consumed | Shortage

ProductionCompletion (payload for Production.Completed)

• completionId (string)
• workOrderId (string)
• partNumber (string)
• completedQuantity (number)
• scrapQuantity (number)
• serialNumbers (array of strings) — if serialized, else omitted
• lotNumber (string) — if lot-tracked
• startTimestamp / endTimestamp (ISO8601)
• operatorId (string) — optional
• resourceId (string) — equipment/machine id

GenealogyEvent (payload for Genealogy.AddEvent)

• eventId (string)
• parentMaterialId (string)
• childMaterialId (string)
• operation (string) — e.g., Assemble | Split | Rework
• timestamp (ISO8601)
• workOrderId (string) — optional
• notes (string) — optional

Sample JSON: Production.Completed

{
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventType": "Production.Completed",
  "contractVersion": "1.0.0",
  "sourceSystem": "MES",
  "sourceSystemId": "mes-plant-01",
  "timestamp": "2024-07-10T15:23:45Z",
  "payload": {
    "completionId": "comp-20240710-001",
    "workOrderId": "WO-1001",
    "partNumber": "PN-12345",
    "completedQuantity": 480,
    "scrapQuantity": 20,
    "lotNumber": "LOT-789",
    "startTimestamp": "2024-07-10T07:00:00Z",
    "endTimestamp": "2024-07-10T11:45:00Z",
    "resourceId": "CELL-A-01"
  }
}

Error Handling and Idempotency

• Idempotency: Use eventId as an idempotency key. The receiver should safely ignore duplicate eventIds (return 200/202 with previously processed outcome) or return a specific 409 with a reference to prior processing.
• Validation errors: For schema/validation failures, return 400 with a clear error payload listing missing/invalid fields and the contractVersion used.
• Processing errors: Return 5xx for transient errors. Producers should implement retry with exponential backoff and a max retry window; include correlationId for tracing.
• Business conflicts: If the payload conflicts with master-of-record, return 409 Conflict with a conflictCode and human-friendly message and guidance for resolution.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "details": [
      {"field": "completedQuantity", "message": "must be a positive number"}
    ],
    "contractVersion": "1.0.0",
    "receivedEventId": "..."
  }
  }

Ownership, Master Data & Governance

Before exchange begins, agree on master-of-record for each business domain:

• ERP is typically master for: Part catalog, BOMs, Routings, Purchase Orders, Sales Orders, Pricing, Master inventory balances (periodic).
• MES is typically master for: Real-time production statuses, equipment runtime data, actual start/stop timestamps, serialized genealogy. MES can be source of truth for completed quantity and time-of-completion events.
• Decide ownership for overlapping data: e.g., who can adjust inventory on receipt of completion events; define reconciliation flows for conflicts.

Define an integration governance board that approves MAJOR version changes, resolves disputes, and holds a published contract and change log.

Security & Compliance Notes

• Always use TLS for transport.
• Use OAuth2 client credential or mutual TLS for system-to-system authentication depending on organizational policy.
• Limit returned data to least privilege—avoid including PII unless absolutely required and authorized.
• Sign or HMAC sensitive event payloads if the environment requires non-repudiation.
• Log events and responses in an auditable way and retain logs consistent with compliance needs.

Reconciliation & Test Cases

Include automated reconciliation tests as part of the contract acceptance tests. Examples:

1. Inventory reconciliation:
   • Test: Send Production.Completed for 100 units. ERP inventory should increase by 100 (or produce a reserved release flow depending on master rules).
   • Acceptance: Inventory delta matches within agreed tolerance; any mismatch triggers a specific reconciliation record in a queue for manual review.
2. Work order lifecycle:
   • Test: ERP creates work order — MES receives WorkOrder.Created and acknowledges within SLA.
   • Acceptance: MES schedules and reports statuses using the same workOrderId. Missing acknowledgment or mismatched partNumber triggers an error event.
3. Genealogy traceability:
   • Test: Produce a child material that references parent lot/serials; attempt a forward trace from child to parents across systems.
   • Acceptance: Trace returns complete lineage within agreed response time.

For each test, include: input fixture, expected output, one or more negative tests (invalid input, duplicate event, delayed arrival), and a pass/fail criterion.

Escalation Path for Mismatches

1. Automated detection: integration layer creates a ReconciliationRecord with mismatch details.
2. Notification: Notify owners (ERP owner, MES owner, integration owner) with correlationId and link to diagnostic payloads.
3. Automated attempts: For transient issues, attempt a configurable automated retry or re-sync operation.
4. Manual resolution: If automated resolution fails, route to a designated SME with documented steps for manual reconciliation and a timeline.
5. Root cause & corrective actions: Track corrective action items in the integration backlog and reflect any contract changes in a new version once approved by governance board.

Rollout & Readiness Checklist

• Mapping complete for all exchanged fields and enumerations.
• Master-of-record decisions documented and signed off.
• Acceptance test suite implemented in staging and green.
• Monitoring and reconciliation dashboards configured (inventory deltas, failed events, processing latency).
• Operational playbooks and escalation contacts published.
• Versioning and change process documented and communicated.
• Pilot scope defined (sites, lines, part families) and rollback plan prepared.

Next steps (practical)

1. Paste this template into your integration design doc and fill site-specific values.
2. Run a small pilot with a narrow scope of part numbers and one work center.
3. Automate acceptance tests and reconciliation checks before scaling.
4. After pilot success, schedule staged rollouts by line or product family with monitoring and a rollback window.

Keep the contract living—treat each rollout as an opportunity to strengthen the contract, add missing tests, and tighten ownership.