Request-Idrequest correlation id returned in contract errors
requiredIntegration
API Contracts
ERP API endpoints, write headers, and live-stock safety gates
Contract Gates
live-stock trust stays disabled until the gate is complete
- Live stock trust
- disabled until an enabled cutover cohort has proof, rollback, and approver
- Write safety
- all mutation routes require Request-Id, Idempotency-Key, Actor-Id, Actor-Type, and Source-System
- Publisher
- worker-run-once drains local outbox rows; external publish stays configurable
- Runtime
- systemd promotion requires final ERP_DATABASE_URL outside source control
Write Headers
all ERP writes are traceable and retry-safe
Idempotency-Keyretry key for every write and workflow transition
requiredActor-Idhuman or service actor id stored on workflow rows
requiredActor-Typemust be user, service, or worker
requiredSource-Systemallowed source such as commerce, erp, workbench, inventory-worker, or vendor-feed
required| Resource | Method | Path | Purpose | Status |
|---|---|---|---|---|
| Inventory | GET | /api/v1/inventory/availability | read available, reserved, held, and owned inventory | implemented |
| Reservations | POST | /api/v1/inventory/reservations | create idempotent order reservations | implemented |
| Reservations | POST | /api/v1/inventory/reservations/{id}/release | release active reserved stock | implemented |
| Reservations | POST | /api/v1/inventory/reservations/{id}/consume | consume reserved stock after shipment proof | implemented |
| Work items | GET | /api/v1/inventory/work-items | list purchasing, receiving, warehouse, vendor, scan, and report work | implemented |
| Work items | POST | /api/v1/inventory/work-items | create an operational workflow item | implemented |
| Work items | POST | /api/v1/inventory/work-items/{id}/transition | move a workflow item between draft, open, in progress, blocked, completed, or cancelled | implemented |
| Operations | GET | /api/v1/inventory/operations/{module} | list concrete workflow records for receiving, purchasing, putaway, picking, transfers, counts, adjustments, returns, vendors, RFQs, invoices, forecasts, landed cost, and kits | implemented |
| Operations | POST | /api/v1/inventory/operations/{module} | create a module workflow record and linked operational work item | implemented |
| Operations | POST | /api/v1/inventory/operations/{module}/{record_id}/transition | transition module records through open, approved, ordered, receiving, in progress, posted, closed, blocked, or cancelled states | implemented |
| Operations | POST | /api/v1/inventory/operations/{module}/{record_id}/post-stock | post receiving, putaway, transfer, pick, pack, ship, count, adjustment, and return stock movements to balances and ledger | guarded |
| Purchasing | POST | /api/v1/inventory/operations/purchase-recommendations/generate | generate reorder recommendations from stockable product settings where available stock is below reorder point or safety stock | implemented |
| Purchasing | POST | /api/v1/inventory/operations/purchase-recommendations/{record_id}/create-rfq | create an ERP-owned RFQ workflow record from a recommendation without touching Commerce | implemented |
| Purchasing | POST | /api/v1/inventory/operations/purchase-recommendations/{record_id}/create-purchase-order | create an ERP-owned purchase order workflow record from a recommendation without touching Commerce | implemented |
| Receiving | POST | /api/v1/inventory/operations/purchase-orders/{record_id}/create-receiving-session | create a receiving session from an ERP-owned purchase order record | implemented |
| Receiving | POST | /api/v1/inventory/operations/receiving-sessions/{record_id}/generate-putaway | create putaway work from a receiving session | implemented |
| Fulfillment | POST | /api/v1/inventory/operations/pick-tasks/generate-from-reservations | create ERP pick tasks from active ERP reservation rows | implemented |
| Fulfillment | POST | /api/v1/inventory/operations/pick-tasks/{record_id}/generate-pack-session | create a pack session from an ERP pick task | implemented |
| Fulfillment | POST | /api/v1/inventory/operations/pack-sessions/{record_id}/generate-ship-confirmation | create a ship confirmation from an ERP pack session | implemented |
| Advanced | POST | /api/v1/inventory/operations/vendor-scorecards/generate | create vendor scorecard records from ERP vendor snapshots | implemented |
| Advanced | POST | /api/v1/inventory/operations/forecasts/generate | create standalone demand forecast records from ERP balances and stock rules | implemented |
| Advanced | POST | /api/v1/inventory/operations/kit-assemblies/{record_id}/post-assembly | consume component stock and create finished kit stock through ERP ledger movements | guarded |
| Barcode | POST | /api/v1/inventory/barcode-scans | capture scanner events and mark them captured, matched, or rejected from expected scan context | implemented |
| Analytics | POST | /api/v1/inventory/analytics/snapshots | persist workflow/report snapshots from live ERP summary metrics or caller-supplied analytics rows | implemented |
| Cutover | POST | /api/v1/inventory/cutover-cohorts/{key}/transition | gate live-stock trust behind stock proof, restore proof, rollback, and approval | guarded |
| Reports | GET | /api/v1/inventory/reports/summary | summarize work backlog, outbox status, reservations, and cutover state | implemented |