Data mapping¶

The contract uses a small set of shared envelope types — document references, movement records, exception records, and window keys — that recur across endpoint families. This page is the reference for those envelopes.

Document reference (`document_ref`)¶

Every event tied to a planner document carries a document_ref:

{
  "type": "SHIPPER",
  "id": "SH-2026-000183",
  "line_no": 10
}

Field	Required	Meaning
`type`	yes	One of `PR`, `PO`, `SO`, `RECEIVER`, `SHIPPER`, `WORKORDER`, `TRANSFER_ORDER`, `VASORDER`, `REFURBISH_ORDER`, `CYCLE_COUNT`, `OTHER`.
`id`	yes	The planner’s natural document identifier. Treat as opaque.
`line_no`	no	Line number on the document. Required when the event is line-scoped (e.g. a `PICK` for a specific shipper line).

The executor must echo document_ref exactly as received in dispatch when reporting realtime work against the document.

Movement record¶

{
  "correlation_id": "01J7Y6K1NQ3W2C0X4V0R5T6E7N",
  "kind": "PICK",
  "warehouse_id": "WH-Tokyo-01",
  "sku": "SKU-WIDGET-RED-LG",
  "qty": 12,
  "uom": "EA",
  "from_location": "A.12.3.1",
  "to_location": "STAGING-OUT-3",
  "lot": "LOT-2026-04-15",
  "serial": null,
  "document_ref": { "type": "SHIPPER", "id": "SH-2026-000183", "line_no": 10 },
  "occurred_at": "2026-05-24T03:14:01.123Z",
  "actor": { "kind": "HUMAN", "id": "user-abc" }
}

Field	Required	Notes
`correlation_id`	yes	Idempotency key. UUID v4 / v7.
`kind`	yes	See movement kinds.
`warehouse_id`	yes	Must match the credential’s allowed warehouse.
`sku`	yes	Must exist in planner master data.
`qty`	yes	Numeric; positive for kinds other than `ADJUST`. `ADJUST` may be negative.
`uom`	yes	Must match the SKU’s base UoM in planner master data.
`from_location`	conditional	Required for `PICK`, `MOVE`, `CONSUME`, `SHIP`.
`to_location`	conditional	Required for `PUT`, `MOVE`, `PRODUCE`, `RECEIVE`.
`lot`	conditional	Required when the SKU is lot-tracked.
`serial`	conditional	Required when the SKU is serial-tracked. Single serial per record.
`document_ref`	conditional	Required for document-tied movements; absent for free-floating `MOVE` or `ADJUST`.
`occurred_at`	yes	RFC 3339 timestamp at second or millisecond precision.
`actor`	no	`kind ∈ {HUMAN, ROBOT, AUTOMATION}`; `id` is opaque.

The planner remains authoritative for SKU, UoM, and location validation. A movement referencing an unknown SKU, an unknown location, or the wrong UoM for the SKU is rejected with 422 Unprocessable Entity.

Exception record¶

{
  "correlation_id": "01J7Y6K1NQ3W2C0X4V0R5T6E7P",
  "severity": "HIGH",
  "code": "SHORT_PICK",
  "warehouse_id": "WH-Tokyo-01",
  "document_ref": { "type": "SHIPPER", "id": "SH-2026-000183", "line_no": 10 },
  "context": {
    "expected_qty": 12,
    "actual_qty": 9,
    "location": "A.12.3.1"
  },
  "occurred_at": "2026-05-24T03:14:01.123Z",
  "actor": { "kind": "HUMAN", "id": "user-abc" }
}

Field	Notes
`severity`	`LOW` / `MEDIUM` / `HIGH` / `URGENT`. Drives the planner’s notification severity.
`code`	One of a registered set — `SHORT_PICK`, `DAMAGE`, `WRONG_SKU`, `ROBOT_STUCK`, `LOCATION_EMPTY`, `WORKER_UNAVAILABLE`, `DEVICE_FAULT`, `SUBSYSTEM_OFFLINE`, `OTHER`. New codes are negotiated through the contract change process, not extended ad-hoc.
`context`	Free-form object scoped to the code. Schemas per code are in the OpenAPI.

Unknown code values are rejected with 422. Always send a known code with OTHER plus a context.detail string as the last-resort fallback.

Work-status record¶

{
  "correlation_id": "01J7Y6K1NQ3W2C0X4V0R5T6E7Q",
  "task_id": "task-abc",
  "state": "IN_PROGRESS",
  "warehouse_id": "WH-Tokyo-01",
  "document_ref": { "type": "SHIPPER", "id": "SH-2026-000183", "line_no": 10 },
  "actor": { "kind": "ROBOT", "id": "robot-12" },
  "occurred_at": "2026-05-24T03:14:01.123Z"
}

state is one of ASSIGNED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED, FAILED. task_id is the executor’s internal task identifier; the planner does not interpret it but stores it for traceability.

Confirmation window key¶

Every confirmation payload is keyed by:

{
  "partner_id": "WH-Tokyo-01/AcmeWES",
  "warehouse_id": "WH-Tokyo-01",
  "window_start": "2026-05-24T06:00:00Z",
  "window_end":   "2026-05-24T14:00:00Z",
  "correlation_id": "01J7Y6K1NQ3W2C0X4V0R5T6E7R"
}

window_start is inclusive; window_end is exclusive. The window key is the deduplication key for confirmation — see Confirmation.

Identifiers and locations¶

Identifier	Format	Source of truth
`warehouse_id`	Planner-defined opaque code (e.g. `WH-Tokyo-01`).	Planner.
`sku`	Planner-defined SKU code.	Planner.
`location`	Dot-separated path of the planner’s choosing (e.g. `A.12.3.1`).	Planner.
`lot`	Planner-defined lot code.	Planner.
`serial`	Planner-defined serial code.	Planner.

The contract does not mandate a format for these identifiers beyond string-typing. The planner chooses; the executor echoes. The recommended convention is the planner side documents these in its master-data section so executors can validate during onboarding.