03-api-reference.md

ECM ERP System - API Reference

Conventions

• Base URL: /api/v1
• Versioning: Path-based (/api/v1/, /api/v2/ when needed)
• Format: JSON request/response bodies
• Auth: Bearer JWT in Authorization header, OR API key in X-API-Key header (for external integrations)
• Tenant: X-Tenant-ID header with tenant slug, derived from JWT claim, or from API key's tenant scope

Standard Response Formats

Single resource:

{
  "data": { /* resource object */ }
}

List (paginated):

{
  "data": [ /* array of resources */ ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 342,
    "totalPages": 14
  }
}

Error:

{
  "error": {
    "message": "Part not found",
    "code": "PART_NOT_FOUND",
    "details": null
  }
}

Pagination Parameters (all list endpoints)

Param	Default	Description
page	1	Page number
limit	25	Items per page (max 100)
sort	created_at	Column to sort by
order	desc	Sort direction (asc or desc)

---

System Administration (no tenant context)

Method	Endpoint	Description
GET	/api/v1/system/tenants	List all tenants
POST	/api/v1/system/tenants	Provision new tenant (creates schema + migrations + seeds)
PUT	/api/v1/system/tenants/:id	Update tenant settings/status
POST	/api/v1/system/tenants/:id/migrate	Run pending migrations for tenant

---

Auth

Method	Endpoint	Description
POST	/api/v1/auth/login	Login → returns access + refresh tokens
POST	/api/v1/auth/refresh	Refresh access token (rotates refresh token)
POST	/api/v1/auth/logout	Revoke refresh token
GET	/api/v1/auth/me	Current user profile + permissions
PUT	/api/v1/auth/change-password	Change own password

---

Users & Roles

Method	Endpoint	Description
GET	/api/v1/users	List users (with role info)
POST	/api/v1/users	Create user + assign roles
GET	/api/v1/users/:id	Get user detail
PUT	/api/v1/users/:id	Update user
DELETE	/api/v1/users/:id	Deactivate user (soft delete)
PUT	/api/v1/users/:id/roles	Set user roles
GET	/api/v1/roles	List roles with permissions
POST	/api/v1/roles	Create custom role
PUT	/api/v1/roles/:id	Update role
DELETE	/api/v1/roles/:id	Delete role (non-system only)
PUT	/api/v1/roles/:id/permissions	Set role permissions
GET	/api/v1/permissions	List all available permissions

---

Parts & BOM Management

Parts

Method	Endpoint	Description
GET	/api/v1/parts	List parts. Filters: search, part_type, category, lifecycle_status
POST	/api/v1/parts	Create part
GET	/api/v1/parts/:id	Get part with AML summary
PUT	/api/v1/parts/:id	Update part
DELETE	/api/v1/parts/:id	Soft delete part
GET	/api/v1/parts/:id/aml	Approved Manufacturer List for this part (MPNs + vendor sources)
POST	/api/v1/parts/:id/aml	Add AML entry (manufacturer MPN + optional vendor source)
PUT	/api/v1/parts/:id/aml/:amlId	Update AML entry
DELETE	/api/v1/parts/:id/aml/:amlId	Remove AML entry
GET	/api/v1/parts/:id/where-used	Find all BOMs containing this part
GET	/api/v1/parts/:id/lifecycle-history	Part lifecycle change history (PLM)

Manufacturers

Method	Endpoint	Description
GET	/api/v1/manufacturers	List manufacturers
POST	/api/v1/manufacturers	Create manufacturer
PUT	/api/v1/manufacturers/:id	Update manufacturer
DELETE	/api/v1/manufacturers/:id	Soft delete manufacturer

BOMs

Method	Endpoint	Description
GET	/api/v1/boms	List BOMs. Filters: part_id, status, search
POST	/api/v1/boms	Create BOM for an assembly part
GET	/api/v1/boms/:id	Get BOM with all lines
PUT	/api/v1/boms/:id	Update BOM header
DELETE	/api/v1/boms/:id	Soft delete BOM
POST	/api/v1/boms/:id/lines	Add line to BOM
PUT	/api/v1/boms/:id/lines/:lineId	Update BOM line
DELETE	/api/v1/boms/:id/lines/:lineId	Remove BOM line
GET	/api/v1/boms/:id/explode	Multi-level BOM explosion (recursive)
POST	/api/v1/boms/:id/clone	Clone BOM as new revision
POST	/api/v1/boms/:id/activate	Set status to active (supersedes previous)
GET	/api/v1/boms/compare	Compare two BOMs. Query: bomA=:id&bomB=:id. Returns { added, removed, changed }

---

PLM (Product Lifecycle Management)

Engineering Change Orders (ECOs)

Method	Endpoint	Description
GET	/api/v1/ecos	List ECOs. Filters: status, priority, search
POST	/api/v1/ecos	Create ECO
GET	/api/v1/ecos/:id	Get ECO with affected items
PUT	/api/v1/ecos/:id	Update ECO
POST	/api/v1/ecos/:id/review	Mark as reviewed
POST	/api/v1/ecos/:id/approve	Approve ECO
POST	/api/v1/ecos/:id/reject	Reject ECO
POST	/api/v1/ecos/:id/implement	Mark as implemented (apply changes)
POST	/api/v1/ecos/:id/close	Close ECO
POST	/api/v1/ecos/:id/affected-items	Add affected item to ECO
DELETE	/api/v1/ecos/:id/affected-items/:itemId	Remove affected item

---

Vendor & Purchasing

Vendors

Method	Endpoint	Description
GET	/api/v1/vendors	List vendors. Filters: search, vendor_type, rating
POST	/api/v1/vendors	Create vendor
GET	/api/v1/vendors/:id	Get vendor with contacts, addresses
PUT	/api/v1/vendors/:id	Update vendor
DELETE	/api/v1/vendors/:id	Soft delete vendor
POST	/api/v1/vendors/:id/contacts	Add contact
PUT	/api/v1/vendors/:id/contacts/:contactId	Update contact
DELETE	/api/v1/vendors/:id/contacts/:contactId	Remove contact
POST	/api/v1/vendors/:id/addresses	Add address
PUT	/api/v1/vendors/:id/addresses/:addrId	Update address

Purchase Orders

Method	Endpoint	Description
GET	/api/v1/purchase-orders	List POs. Filters: status, vendor_id, date_from, date_to
POST	/api/v1/purchase-orders	Create PO
GET	/api/v1/purchase-orders/:id	Get PO with lines + receiving history
PUT	/api/v1/purchase-orders/:id	Update PO
POST	/api/v1/purchase-orders/:id/lines	Add line
PUT	/api/v1/purchase-orders/:id/lines/:lineId	Update line
DELETE	/api/v1/purchase-orders/:id/lines/:lineId	Remove line
POST	/api/v1/purchase-orders/:id/approve	Approve PO
POST	/api/v1/purchase-orders/:id/send	Mark as sent to vendor
POST	/api/v1/purchase-orders/:id/cancel	Cancel PO

Receiving

Method	Endpoint	Description
GET	/api/v1/receiving	List receiving records
POST	/api/v1/receiving	Create receiving record against a PO
GET	/api/v1/receiving/:id	Get receiving with lines
POST	/api/v1/receiving/:id/lines	Add receiving line
POST	/api/v1/receiving/:id/inspect	Record inspection results
POST	/api/v1/receiving/:id/accept	Accept goods into inventory

---

Inventory & Warehousing

Inventory (Serialized)

Method	Endpoint	Description
GET	/api/v1/inventory	List inventory. Filters: part_id, location_id, status, ownership_type, container_type
GET	/api/v1/inventory/:id	Get inventory row by ID
GET	/api/v1/inventory/scan/:serial	Look up inventory by serial number (barcode scan)
GET	/api/v1/inventory/summary	Aggregate stock by part + location (uses inventory_summary view)
GET	/api/v1/inventory/by-part/:partId	All serialized units for a part across locations
GET	/api/v1/inventory/low-stock	Parts below min_stock level (aggregate)
POST	/api/v1/inventory/adjust	Manual stock adjustment on a specific serialized unit
POST	/api/v1/inventory/:id/move	Move serialized unit to a new location
POST	/api/v1/inventory/:id/split	Split a unit (e.g., take 2000 from a 5000 reel → creates new serial)
POST	/api/v1/inventory/merge	Merge units of the same part/lot into one
POST	/api/v1/inventory/:id/quarantine	Put unit in quarantine
GET	/api/v1/inventory/transactions	Transaction history. Filters: part_id, inventory_id, type, date_from, date_to

Warehouses

Method	Endpoint	Description
GET	/api/v1/warehouses	List warehouses
POST	/api/v1/warehouses	Create warehouse
PUT	/api/v1/warehouses/:id	Update warehouse
GET	/api/v1/warehouses/:id/locations	List locations
POST	/api/v1/warehouses/:id/locations	Create location
PUT	/api/v1/warehouses/:id/locations/:locId	Update location

Cycle Counts

Method	Endpoint	Description
GET	/api/v1/cycle-counts	List cycle counts
POST	/api/v1/cycle-counts	Create cycle count
GET	/api/v1/cycle-counts/:id	Get count with lines and variances
POST	/api/v1/cycle-counts/:id/start	Start counting (populate lines from inventory)
PUT	/api/v1/cycle-counts/:id/lines/:lineId	Record counted quantity
POST	/api/v1/cycle-counts/:id/approve	Approve and apply inventory adjustments
POST	/api/v1/cycle-counts/:id/cancel	Cancel count

Consigned Inventory

Method	Endpoint	Description
GET	/api/v1/inventory/consigned	List consigned inventory. Filters: customer_id, part_id
POST	/api/v1/inventory/consigned/receive	Receive customer-consigned parts into inventory
POST	/api/v1/inventory/consigned/return	Return consigned parts to customer

Costing Configuration

Method	Endpoint	Description
GET	/api/v1/admin/costing-config	Get tenant costing configuration
PUT	/api/v1/admin/costing-config	Update costing method and settings

---

Sales & Customers

Customers

Method	Endpoint	Description
GET	/api/v1/customers	List customers
POST	/api/v1/customers	Create customer
GET	/api/v1/customers/:id	Get customer with contacts, addresses
PUT	/api/v1/customers/:id	Update customer
DELETE	/api/v1/customers/:id	Soft delete
POST	/api/v1/customers/:id/contacts	Add contact
POST	/api/v1/customers/:id/addresses	Add address

Sales Orders

Method	Endpoint	Description
GET	/api/v1/sales-orders	List SOs. Filters: status, customer_id
POST	/api/v1/sales-orders	Create SO
GET	/api/v1/sales-orders/:id	Get SO with lines
PUT	/api/v1/sales-orders/:id	Update SO
POST	/api/v1/sales-orders/:id/confirm	Confirm order (also triggers planning action generation for BUY/MAKE inbox items)
POST	/api/v1/sales-orders/:id/cancel	Cancel order

Planning Inbox (Event-Driven, No Cron Required)

Method	Endpoint	Description
GET	/api/v1/planning/actions	List planning actions. Filters: status, action_type (BUY/MAKE), owner_id, source_type, due_date_from, due_date_to
GET	/api/v1/planning/actions/:id	Get planning action detail
POST	/api/v1/planning/actions/:id/approve	Approve action for conversion
POST	/api/v1/planning/actions/:id/reject	Reject/cancel suggested action
POST	/api/v1/planning/actions/:id/convert-to-po	Convert BUY action to draft purchase order/requisition
POST	/api/v1/planning/actions/:id/convert-to-job	Convert MAKE action to draft job/work order
POST	/api/v1/planning/actions/recalculate	Recalculate planning actions for a source document (e.g., sales order)

Invoices

Method	Endpoint	Description
GET	/api/v1/invoices	List invoices. Filters: status, customer_id
POST	/api/v1/invoices	Generate invoice from sales order
GET	/api/v1/invoices/:id	Get invoice detail
POST	/api/v1/invoices/:id/send	Mark as sent
POST	/api/v1/invoices/:id/record-payment	Record payment amount
POST	/api/v1/invoices/:id/void	Void invoice

---

Job/Work Order Management

Jobs

Method	Endpoint	Description
GET	/api/v1/jobs	List jobs. Filters: status, customer_id, priority, date_from, date_to
POST	/api/v1/jobs	Create job (optionally from SO line)
GET	/api/v1/jobs/:id	Get job with materials, operations, labor summary
PUT	/api/v1/jobs/:id	Update job
POST	/api/v1/jobs/:id/explode-bom	Generate job_materials from BOM explosion
POST	/api/v1/jobs/:id/complete	Complete job → receive finished goods into inventory
POST	/api/v1/jobs/:id/cancel	Cancel job
POST	/api/v1/jobs/:id/hold	Put job on hold
POST	/api/v1/jobs/:id/resume	Resume from hold

Job Materials & Kitting

Method	Endpoint	Description
GET	/api/v1/jobs/:id/materials	Get material list with availability status
GET	/api/v1/jobs/:id/shortages	Materials where available qty < required
POST	/api/v1/jobs/:id/kit/allocate	Allocate inventory to job materials
POST	/api/v1/jobs/:id/kit/issue	Issue allocated materials (deducts inventory)
POST	/api/v1/jobs/:id/kit/return	Return unused materials to inventory

Job Operations

Method	Endpoint	Description
GET	/api/v1/jobs/:id/operations	Get operations list
POST	/api/v1/jobs/:id/operations	Add operation
PUT	/api/v1/jobs/:id/operations/:opId	Update operation status/hours
DELETE	/api/v1/jobs/:id/operations/:opId	Remove operation

Job Labor

Method	Endpoint	Description
GET	/api/v1/jobs/:id/labor	Get labor entries for job
POST	/api/v1/jobs/:id/labor	Clock in labor entry
PUT	/api/v1/jobs/:id/labor/:laborId	Clock out / update labor

---

Custom Fields (Form Builder)

Method	Endpoint	Description
GET	/api/v1/admin/custom-fields	List definitions. Filter: entity_type (required)
POST	/api/v1/admin/custom-fields	Create custom field definition
PUT	/api/v1/admin/custom-fields/:id	Update definition
DELETE	/api/v1/admin/custom-fields/:id	Delete definition

Custom field values are included in the regular entity endpoints:

• GET /api/v1/parts/:id → response includes custom_fields: {...}
• POST /api/v1/parts → request body can include custom_fields: {...}
• Filtering: GET /api/v1/parts?custom_field.my_field=value

---

---

General Ledger

Chart of Accounts

Method	Endpoint	Description
GET	/api/v1/gl/accounts	List accounts. Filters: account_type, is_active, search
POST	/api/v1/gl/accounts	Create account
GET	/api/v1/gl/accounts/:id	Get account with current balance
PUT	/api/v1/gl/accounts/:id	Update account
DELETE	/api/v1/gl/accounts/:id	Deactivate account (only if no posted entries)
GET	/api/v1/gl/accounts/:id/ledger	Get all journal entry lines for an account. Filters: period_id, date_from, date_to

Fiscal Periods

Method	Endpoint	Description
GET	/api/v1/gl/fiscal-years	List fiscal years
POST	/api/v1/gl/fiscal-years	Create fiscal year (auto-generates monthly periods)
GET	/api/v1/gl/fiscal-years/:id/periods	List periods for a fiscal year
POST	/api/v1/gl/fiscal-periods/:id/close	Close a period (prevents new postings)
POST	/api/v1/gl/fiscal-periods/:id/reopen	Reopen a closed period (Controller role required)
POST	/api/v1/gl/fiscal-years/:id/year-end-close	Year-end close (close all periods, create retained earnings entry)

Journal Entries

Method	Endpoint	Description
GET	/api/v1/gl/journal-entries	List entries. Filters: status, period_id, source_module, date_from, date_to
POST	/api/v1/gl/journal-entries	Create manual journal entry
GET	/api/v1/gl/journal-entries/:id	Get entry with all lines
PUT	/api/v1/gl/journal-entries/:id	Update draft entry (only while draft)
POST	/api/v1/gl/journal-entries/:id/post	Post entry to GL (validates debits=credits, period is open)
POST	/api/v1/gl/journal-entries/:id/reverse	Create reversing entry

Financial Reports

Method	Endpoint	Description
GET	/api/v1/gl/reports/trial-balance	Trial balance. Query: period_id or as_of_date
GET	/api/v1/gl/reports/balance-sheet	Balance sheet as of date
GET	/api/v1/gl/reports/income-statement	P&L for a period range
GET	/api/v1/gl/reports/cash-flow	Cash flow statement for a period range
GET	/api/v1/gl/reports/general-ledger	Full GL report (all entries, filterable)
GET	/api/v1/gl/reports/account-balances	Account balances by period

---

Accounts Payable

Vendor Bills

Method	Endpoint	Description
GET	/api/v1/ap/bills	List bills. Filters: status, vendor_id, due_date_from, due_date_to, overdue
POST	/api/v1/ap/bills	Create vendor bill (optionally from PO/receiving)
GET	/api/v1/ap/bills/:id	Get bill with lines
PUT	/api/v1/ap/bills/:id	Update draft bill
POST	/api/v1/ap/bills/:id/approve	Approve bill (posts to GL: debit expense/inventory, credit AP)
POST	/api/v1/ap/bills/:id/void	Void bill (creates reversing GL entry)

Vendor Payments

Method	Endpoint	Description
GET	/api/v1/ap/payments	List payments. Filters: vendor_id, date_from, date_to, method
POST	/api/v1/ap/payments	Create payment (select bills to pay, apply amounts)
GET	/api/v1/ap/payments/:id	Get payment with application details
POST	/api/v1/ap/payments/:id/complete	Complete payment (posts to GL: debit AP, credit cash/bank)
POST	/api/v1/ap/payments/:id/void	Void payment

AP Reports

Method	Endpoint	Description
GET	/api/v1/ap/reports/aging	AP aging report (current, 30, 60, 90, 120+ days)
GET	/api/v1/ap/reports/vendor-balance/:vendorId	Balance detail for a vendor
GET	/api/v1/ap/reports/payment-forecast	Upcoming payments due

---

Accounts Receivable

Customer Payments

Method	Endpoint	Description
GET	/api/v1/ar/payments	List payments. Filters: customer_id, date_from, date_to
POST	/api/v1/ar/payments	Receive payment (select invoices to apply against)
GET	/api/v1/ar/payments/:id	Get payment with application details
POST	/api/v1/ar/payments/:id/complete	Complete payment (posts to GL: debit cash/bank, credit AR)
POST	/api/v1/ar/payments/:id/void	Void payment

Credit Memos

Method	Endpoint	Description
GET	/api/v1/ar/credit-memos	List credit memos
POST	/api/v1/ar/credit-memos	Create credit memo
POST	/api/v1/ar/credit-memos/:id/approve	Approve (posts to GL: debit revenue, credit AR)
POST	/api/v1/ar/credit-memos/:id/apply	Apply to an invoice

AR Reports

Method	Endpoint	Description
GET	/api/v1/ar/reports/aging	AR aging report (current, 30, 60, 90, 120+ days)
GET	/api/v1/ar/reports/customer-balance/:customerId	Balance detail for a customer
GET	/api/v1/ar/reports/collections	Overdue invoices requiring follow-up

---

Tax Management

Method	Endpoint	Description
GET	/api/v1/tax/rates	List tax rates
POST	/api/v1/tax/rates	Create tax rate
PUT	/api/v1/tax/rates/:id	Update tax rate
GET	/api/v1/tax/groups	List tax groups
POST	/api/v1/tax/groups	Create tax group (combine multiple rates)
PUT	/api/v1/tax/groups/:id	Update tax group
POST	/api/v1/tax/calculate	Calculate tax for a given amount + tax group

---

Bank & Reconciliation

Method	Endpoint	Description
GET	/api/v1/banking/accounts	List bank accounts
POST	/api/v1/banking/accounts	Create bank account (linked to GL account)
PUT	/api/v1/banking/accounts/:id	Update bank account
GET	/api/v1/banking/accounts/:id/transactions	List transactions for account
POST	/api/v1/banking/accounts/:id/transactions	Record manual bank transaction
POST	/api/v1/banking/reconciliations	Start reconciliation for a bank account
GET	/api/v1/banking/reconciliations/:id	Get reconciliation with unmatched items
PUT	/api/v1/banking/reconciliations/:id/match	Match bank transactions to GL entries
POST	/api/v1/banking/reconciliations/:id/complete	Complete reconciliation

---

Approval Thresholds

Method	Endpoint	Description
GET	/api/v1/admin/approval-thresholds	List thresholds. Filter: document_type
POST	/api/v1/admin/approval-thresholds	Create threshold rule
PUT	/api/v1/admin/approval-thresholds/:id	Update threshold
DELETE	/api/v1/admin/approval-thresholds/:id	Delete threshold

---

Integrations & Webhooks

API Keys

Method	Endpoint	Description
GET	/api/v1/admin/api-keys	List API keys (shows prefix, never full key)
POST	/api/v1/admin/api-keys	Create API key (returns full key ONCE in response)
PUT	/api/v1/admin/api-keys/:id	Update key (name, permissions, active, expiry)
DELETE	/api/v1/admin/api-keys/:id	Revoke API key
GET	/api/v1/admin/api-keys/:id/usage	Usage stats and recent activity log

Webhook Subscriptions

Method	Endpoint	Description
GET	/api/v1/admin/webhooks	List webhook subscriptions
POST	/api/v1/admin/webhooks	Create subscription (URL, events, secret)
PUT	/api/v1/admin/webhooks/:id	Update subscription
DELETE	/api/v1/admin/webhooks/:id	Delete subscription
POST	/api/v1/admin/webhooks/:id/test	Send test event to endpoint
GET	/api/v1/admin/webhooks/:id/deliveries	View delivery history with status
POST	/api/v1/admin/webhooks/:id/deliveries/:deliveryId/retry	Retry a failed delivery
GET	/api/v1/admin/webhooks/events	List all available event types

Integration Connections

Method	Endpoint	Description
GET	/api/v1/admin/integrations	List configured integrations
POST	/api/v1/admin/integrations	Configure new integration (shipping, MES, etc.)
PUT	/api/v1/admin/integrations/:id	Update integration config
DELETE	/api/v1/admin/integrations/:id	Remove integration
POST	/api/v1/admin/integrations/:id/test	Test connection
GET	/api/v1/admin/integrations/:id/logs	View integration activity log

---

Reports

Operational Reports

Method	Endpoint	Description
GET	/api/v1/reports/inventory-valuation	Total inventory value by part/location
GET	/api/v1/reports/bom-cost-rollup/:bomId	Full cost rollup for a BOM
GET	/api/v1/reports/vendor-history/:vendorId	Purchase history for a vendor
GET	/api/v1/reports/job-profitability/:jobId	Material + labor costs vs. sales price
GET	/api/v1/reports/low-stock	Parts below reorder point
GET	/api/v1/reports/on-time-delivery	Delivery performance metrics

Financial Reports

See GL, AP, and AR report endpoints above (/api/v1/gl/reports/*, /api/v1/ap/reports/*, /api/v1/ar/reports/*)