{"openapi":"3.1.0","info":{"title":"Apus Platform API","version":"0.1.0-draft.3","description":"REST API for the Apus Platform business operation platform. Read and write products, inventory, orders, production, finance, people, quality, assets and documents over one data layer."},"servers":[{"url":"https://api.apusplatform.com"}],"security":[{"oauth2":[]}],"tags":[{"name":"Products","description":"The product catalog — items you buy, make, stock or sell — plus categories, units of measure and price lists. Master data shared by inventory, sales, purchasing and finance. Keep an external PIM or POS in sync with these endpoints."},{"name":"Partners","description":"Business partners — the customers, suppliers and other counterparties your organization trades with — plus their contacts and addresses. Master data shared by sales, purchasing, distribution, finance and CRM. Sync a CRM, an e-invoice provider or an external directory against these endpoints."},{"name":"Inventory","description":"Real-time stock — on-hand, reserved and available quantities by SKU and warehouse — plus the warehouses, bins, lots, serials, adjustments, transfers and reservations that move it. The operational balance-sheet inventory that sales, purchasing and manufacturing draw down and replenish. Every mutation is an auditable event."},{"name":"Purchasing","description":"Procure-to-pay: requisitions, RFQs, purchase orders, goods receipts and supplier invoices. Orders you place with suppliers and the receiving status against them. Drive procurement from an external system, or read receiving and matching status for AP automation."},{"name":"Manufacturing (MES)","description":"Shop-floor execution — production orders, work centers with live OEE, bills of materials, routings, completion and scrap reporting. The MES endpoints drive and observe what happens on the line: release an order, report finished quantity, log downtime, and read equipment effectiveness in real time."},{"name":"Finance & Accounting","description":"Accounts receivable and payable, payments, the general ledger and the closing cycle — invoices, journal entries, the chart of accounts, cost centers, fiscal periods, tax codes and exchange rates. The system of record for money owed and money owing. Feed an e-invoice provider, a bank reconciliation tool or an external BI warehouse from these endpoints."},{"name":"Sales & CRM","description":"The sell side, end to end — sales orders and their fulfilment plus the CRM pipeline that feeds them: leads, opportunities and quotations. A confirmed order reserves stock and hands off to distribution and finance; a converted quotation or lead flows straight into an order. Sync a CRM, an e-commerce front end or an order-management system against these endpoints."},{"name":"Distribution (DMS)","description":"Channel distribution (DMS) — distributors and their territories, delivery routes and drivers, deliveries to the trade, field-sales visits and trade promotions. Use these endpoints to sync a mobile field-force app, plan daily routes and push orders down the channel."},{"name":"HRM","description":"Human resources — the employee master, org structure, attendance, leave and payroll runs. People data shared by projects, timesheets, expenses and finance. Sync an HRIS, a time clock or a payroll provider against these endpoints."},{"name":"BI & Analytics","description":"Read-only analytics over your ERP data — datasets, ad-hoc queries, KPIs, dashboards, reports and exports. Query modelled facts and dimensions, pull KPI values for an external scorecard, or schedule a data export to a warehouse. Every endpoint reads data; none mutates it, so they all require the bi:read scope."},{"name":"QMS – Quality","description":"Quality management — inspections, non-conformances (NCR), corrective and preventive actions (CAPA), checklists, standards and certificates. Records that gate incoming goods, in-process work and finished output, and prove compliance to auditors and customers. Feed a LIMS, an SPC tool or a supplier scorecard from these endpoints."},{"name":"Maintenance (EAM)","description":"Enterprise asset management: the equipment register, corrective and preventive work orders, meter readings, spare parts and recurring maintenance schedules. The physical assets you run and the maintenance history against them. Feed readings from IoT/SCADA, or drive work orders from an external CMMS."},{"name":"EDM – Documents","description":"Electronic document management — files, folders, versions and approval workflows. Store contracts, drawings, SOPs and certificates against a folder tree, route them for sign-off, and keep an auditable version history. Reference documents from any business object (an order, a work order, a supplier) via the reference field, and control access with per-document permissions."},{"name":"Webhooks","description":"Subscribe to events and Apus POSTs a signed JSON payload to your endpoint as things happen — no polling. Every request carries an X-Apus-Signature header: the HMAC-SHA256 of the raw request body keyed with your endpoint's signing_secret (returned once when you create the webhook). Recompute it and compare in constant time to verify the delivery is genuine and untampered. Subscribable events include product.updated, inventory.changed, sales_order.created, production_order.completed and invoice.paid. Deliveries are retried with exponential backoff, and you can inspect or replay them from the deliveries endpoints."}],"paths":{"/v1/products":{"get":{"tags":["Products"],"operationId":"listProducts","summary":"List products","description":"Returns a cursor-paginated list of products. Use updated_since for incremental sync.\n\nRequires scope `products:read`.","responses":{"200":{"description":"List products","content":{"application/json":{"example":{"data":[{"id":"prd_1a2b","sku":"STEEL-BRKT-08","name":"Steel bracket 8mm","unit":"pcs","category":"raw-material","price":{"amount":12500,"currency":"VND"},"active":true,"updated_at":"2026-07-12T04:20:11Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"RFC 3339 timestamp; return items changed after it.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Filter by category code.","schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"Filter by active status.","schema":{"type":"boolean"}}],"security":[{"oauth2":["products:read"]}]},"post":{"tags":["Products"],"operationId":"createProduct","summary":"Create a product","description":"Creates a product. sku must be unique.\n\nRequires scope `products:write`.","responses":{"201":{"description":"Create a product","content":{"application/json":{"example":{"id":"prd_1a2b","sku":"STEEL-BRKT-08","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","description":"Unique stock-keeping unit."},"name":{"type":"string","description":"Display name."},"unit":{"type":"string","description":"Unit of measure, e.g. pcs, kg."},"category":{"type":"string","description":"Category code."},"price":{"type":"object","description":"{ amount (minor units), currency }."}},"required":["sku","name","unit"]},"example":{"sku":"STEEL-BRKT-08","name":"Steel bracket 8mm","unit":"pcs","category":"raw-material","price":{"amount":12500,"currency":"VND"}}}}},"security":[{"oauth2":["products:write"]}]}},"/v1/products/{id}":{"get":{"tags":["Products"],"operationId":"getProduct","summary":"Retrieve a product","description":"Returns a single product by its id, or by sku (prefix the value with sku_).\n\nRequires scope `products:read`.","responses":{"200":{"description":"Retrieve a product","content":{"application/json":{"example":{"id":"prd_1a2b","sku":"STEEL-BRKT-08","name":"Steel bracket 8mm","unit":"pcs","category":"raw-material","price":{"amount":12500,"currency":"VND"},"active":true,"updated_at":"2026-07-12T04:20:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}}],"security":[{"oauth2":["products:read"]}]},"patch":{"tags":["Products"],"operationId":"updateProduct","summary":"Update a product","description":"Updates mutable fields of a product. Only supplied fields change.\n\nRequires scope `products:write`.","responses":{"200":{"description":"Update a product","content":{"application/json":{"example":{"id":"prd_1a2b","sku":"STEEL-BRKT-08","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name."},"category":{"type":"string","description":"Category code."},"price":{"type":"object","description":"{ amount (minor units), currency }."},"active":{"type":"boolean","description":"Activate or archive the product."}}},"example":{"price":{"amount":13000,"currency":"VND"}}}}},"security":[{"oauth2":["products:write"]}]},"delete":{"tags":["Products"],"operationId":"deleteProduct","summary":"Archive a product","description":"Archives a product (soft delete). It stays referenced by historical documents.\n\nRequires scope `products:write`.","responses":{"204":{"description":"Archive a product"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}}],"security":[{"oauth2":["products:write"]}]}},"/v1/products/product-categories":{"get":{"tags":["Products"],"operationId":"listCategories","summary":"List categories","description":"Returns the product category tree.\n\nRequires scope `products:read`.","responses":{"200":{"description":"List categories","content":{"application/json":{"example":{"data":[{"code":"raw-material","name":"Raw material","parent":null},{"code":"finished-good","name":"Finished good","parent":null}]}}}}},"security":[{"oauth2":["products:read"]}]},"post":{"tags":["Products"],"operationId":"createCategory","summary":"Create a category","description":"Creates a product category, optionally nested under a parent.\n\nRequires scope `products:write`.","responses":{"201":{"description":"Create a category","content":{"application/json":{"example":{"code":"fasteners","name":"Fasteners","parent":"raw-material"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Unique category code."},"name":{"type":"string","description":"Display name."},"parent":{"type":"string","description":"Parent category code."}},"required":["code","name"]},"example":{"code":"fasteners","name":"Fasteners","parent":"raw-material"}}}},"security":[{"oauth2":["products:write"]}]}},"/v1/products/units":{"get":{"tags":["Products"],"operationId":"listUoms","summary":"List units of measure","description":"Returns configured units of measure and their conversion factors.\n\nRequires scope `products:read`.","responses":{"200":{"description":"List units of measure","content":{"application/json":{"example":{"data":[{"code":"pcs","name":"Pieces","base":"pcs","factor":1},{"code":"box","name":"Box (12)","base":"pcs","factor":12}]}}}}},"security":[{"oauth2":["products:read"]}]}},"/v1/products/price-lists":{"get":{"tags":["Products"],"operationId":"listPriceLists","summary":"List price lists","description":"Returns price lists (e.g. retail, wholesale, per-customer).\n\nRequires scope `products:read`.","responses":{"200":{"description":"List price lists","content":{"application/json":{"example":{"data":[{"id":"pl_retail","name":"Retail","currency":"VND","active":true}]}}}}},"parameters":[{"name":"currency","in":"query","required":false,"description":"Filter by currency.","schema":{"type":"string"}}],"security":[{"oauth2":["products:read"]}]}},"/v1/products/price-lists/{id}":{"get":{"tags":["Products"],"operationId":"getPriceList","summary":"Retrieve a price list","description":"Returns a price list with its per-SKU prices.\n\nRequires scope `products:read`.","responses":{"200":{"description":"Retrieve a price list","content":{"application/json":{"example":{"id":"pl_retail","name":"Retail","currency":"VND","items":[{"sku":"STEEL-BRKT-08","price":{"amount":15000,"currency":"VND"}}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Price list id.","schema":{"type":"string"}}],"security":[{"oauth2":["products:read"]}]}},"/v1/partners":{"get":{"tags":["Partners"],"operationId":"listPartners","summary":"List partners","description":"Returns a cursor-paginated list of partners. Filter by type or search by name and tax code.\n\nRequires scope `partners:read`.","responses":{"200":{"description":"List partners","content":{"application/json":{"example":{"data":[{"id":"prt_1a2b","code":"CUST-000142","name":"Cong ty TNHH Thanh Long","type":["customer"],"tax_code":"0312345678","email":"ketoan@thanhlong.vn","currency":"VND","active":true,"updated_at":"2026-07-12T04:20:11Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Filter by role: customer or supplier.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Match against name and tax code.","schema":{"type":"string"}}],"security":[{"oauth2":["partners:read"]}]},"post":{"tags":["Partners"],"operationId":"createPartner","summary":"Create a partner","description":"Creates a partner. tax_code, when supplied, must be unique.\n\nRequires scope `partners:write`.","responses":{"201":{"description":"Create a partner","content":{"application/json":{"example":{"id":"prt_1a2b","code":"CUST-000142","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Legal or trading name."},"type":{"type":"string","description":"One or more roles: customer, supplier."},"tax_code":{"type":"string","description":"Tax identification number (unique)."},"email":{"type":"string","description":"Primary contact email."}},"required":["name","type"]},"example":{"name":"Cong ty TNHH Thanh Long","type":["customer"],"tax_code":"0312345678","email":"ketoan@thanhlong.vn"}}}},"security":[{"oauth2":["partners:write"]}]}},"/v1/partners/{id}":{"get":{"tags":["Partners"],"operationId":"getPartner","summary":"Retrieve a partner","description":"Returns a single partner by its id, or by tax code (prefix the value with tax_).\n\nRequires scope `partners:read`.","responses":{"200":{"description":"Retrieve a partner","content":{"application/json":{"example":{"id":"prt_1a2b","code":"CUST-000142","name":"Cong ty TNHH Thanh Long","type":["customer"],"tax_code":"0312345678","email":"ketoan@thanhlong.vn","currency":"VND","active":true,"updated_at":"2026-07-12T04:20:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"security":[{"oauth2":["partners:read"]}]},"patch":{"tags":["Partners"],"operationId":"updatePartner","summary":"Update a partner","description":"Updates mutable fields of a partner. Only supplied fields change.\n\nRequires scope `partners:write`.","responses":{"200":{"description":"Update a partner","content":{"application/json":{"example":{"id":"prt_1a2b","code":"CUST-000142","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Legal or trading name."},"type":{"type":"string","description":"One or more roles: customer, supplier."},"email":{"type":"string","description":"Primary contact email."},"active":{"type":"boolean","description":"Activate or archive the partner."}}},"example":{"type":["customer","supplier"],"email":"muahang@thanhlong.vn"}}}},"security":[{"oauth2":["partners:write"]}]},"delete":{"tags":["Partners"],"operationId":"archivePartner","summary":"Archive a partner","description":"Archives a partner (soft delete). It stays referenced by historical documents.\n\nRequires scope `partners:write`.","responses":{"204":{"description":"Archive a partner"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"security":[{"oauth2":["partners:write"]}]}},"/v1/partners/{id}/contacts":{"get":{"tags":["Partners"],"operationId":"listContacts","summary":"List partner contacts","description":"Returns the people recorded against a partner.\n\nRequires scope `partners:read`.","responses":{"200":{"description":"List partner contacts","content":{"application/json":{"example":{"data":[{"id":"con_5f6g","name":"Nguyen Thi Mai","email":"mai@thanhlong.vn","phone":"+84 28 3822 1234","role":"Accountant"}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"security":[{"oauth2":["partners:read"]}]},"post":{"tags":["Partners"],"operationId":"addContact","summary":"Add a contact","description":"Adds a contact person to a partner.\n\nRequires scope `partners:write`.","responses":{"201":{"description":"Add a contact","content":{"application/json":{"example":{"id":"con_5f6g","name":"Nguyen Thi Mai","created_at":"2026-07-20T02:14:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Full name."},"email":{"type":"string","description":"Contact email."},"phone":{"type":"string","description":"Contact phone number."},"role":{"type":"string","description":"Job title or role, e.g. Accountant."}},"required":["name"]},"example":{"name":"Nguyen Thi Mai","email":"mai@thanhlong.vn","phone":"+84 28 3822 1234","role":"Accountant"}}}},"security":[{"oauth2":["partners:write"]}]}},"/v1/partners/{id}/addresses":{"get":{"tags":["Partners"],"operationId":"listAddresses","summary":"List partner addresses","description":"Returns the billing and shipping addresses recorded against a partner.\n\nRequires scope `partners:read`.","responses":{"200":{"description":"List partner addresses","content":{"application/json":{"example":{"data":[{"id":"adr_7h8i","type":"billing","line1":"128 Nguyen Hue","city":"Ho Chi Minh City","country":"VN"}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"security":[{"oauth2":["partners:read"]}]},"post":{"tags":["Partners"],"operationId":"addAddress","summary":"Add an address","description":"Adds a billing or shipping address to a partner.\n\nRequires scope `partners:write`.","responses":{"201":{"description":"Add an address","content":{"application/json":{"example":{"id":"adr_7h8i","type":"billing","created_at":"2026-07-20T02:16:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Partner id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line1":{"type":"string","description":"Street address line."},"city":{"type":"string","description":"City or province."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code."},"type":{"type":"string","description":"Address role: billing or shipping."}},"required":["line1"]},"example":{"line1":"128 Nguyen Hue","city":"Ho Chi Minh City","country":"VN","type":"billing"}}}},"security":[{"oauth2":["partners:write"]}]}},"/v1/inventory":{"get":{"tags":["Inventory"],"operationId":"listInventory","summary":"List stock levels","description":"Returns on-hand, reserved and available quantities per SKU per warehouse. Filter to items at or below their reorder point to drive replenishment.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"List stock levels","content":{"application/json":{"example":{"data":[{"sku":"STEEL-BRKT-08","warehouse_id":"wh_hcm","on_hand":1840,"reserved":320,"available":1520,"reorder_point":500,"below_reorder":false,"updated_at":"2026-07-20T03:14:52Z"}],"has_more":true,"next_cursor":"crsr_inv_2f"}}}}},"parameters":[{"name":"sku","in":"query","required":false,"description":"Filter by stock-keeping unit.","schema":{"type":"string"}},{"name":"warehouse_id","in":"query","required":false,"description":"Filter by warehouse id.","schema":{"type":"string"}},{"name":"below_reorder","in":"query","required":false,"description":"Only SKUs at or below their reorder point.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/{sku}":{"get":{"tags":["Inventory"],"operationId":"getInventorySku","summary":"Retrieve stock for a SKU","description":"Returns aggregated stock for one SKU across every warehouse, plus a per-warehouse breakdown.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"Retrieve stock for a SKU","content":{"application/json":{"example":{"sku":"STEEL-BRKT-08","unit":"pcs","totals":{"on_hand":2650,"reserved":320,"available":2330},"warehouses":[{"warehouse_id":"wh_hcm","on_hand":1840,"reserved":320,"available":1520},{"warehouse_id":"wh_hanoi","on_hand":810,"reserved":0,"available":810}],"updated_at":"2026-07-20T03:14:52Z"}}}}},"parameters":[{"name":"sku","in":"path","required":true,"description":"Stock-keeping unit.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/adjustments":{"post":{"tags":["Inventory"],"operationId":"adjustInventory","summary":"Adjust stock","description":"Records a signed stock adjustment against a SKU at a warehouse. Use a positive quantity_delta to add, a negative one to remove. Every adjustment is an auditable event with a reason.\n\nRequires scope `inventory:write`.","responses":{"201":{"description":"Adjust stock","content":{"application/json":{"example":{"id":"adj_7d21","sku":"STEEL-BRKT-08","warehouse_id":"wh_hcm","quantity_delta":-12,"reason":"damage","on_hand":1828,"created_at":"2026-07-20T03:20:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","description":"Stock-keeping unit."},"warehouse_id":{"type":"string","description":"Warehouse the adjustment applies to."},"quantity_delta":{"type":"integer","description":"Signed quantity change (negative removes stock)."},"reason":{"type":"string","description":"One of cycle_count, damage, correction."},"note":{"type":"string","description":"Free-text memo kept on the audit trail."}},"required":["sku","warehouse_id","quantity_delta","reason"]},"example":{"sku":"STEEL-BRKT-08","warehouse_id":"wh_hcm","quantity_delta":-12,"reason":"damage","note":"Water damage during monsoon transit"}}}},"security":[{"oauth2":["inventory:write"]}]}},"/v1/inventory/transfers":{"post":{"tags":["Inventory"],"operationId":"transferInventory","summary":"Transfer stock","description":"Moves stock of a SKU from one warehouse to another. The quantity is deducted from the source on creation and received at the destination when the transfer completes.\n\nRequires scope `inventory:write`.","responses":{"201":{"description":"Transfer stock","content":{"application/json":{"example":{"id":"trf_5c90","sku":"STEEL-BRKT-08","from_warehouse_id":"wh_hcm","to_warehouse_id":"wh_hanoi","quantity":200,"status":"in_transit","created_at":"2026-07-20T03:25:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","description":"Stock-keeping unit."},"from_warehouse_id":{"type":"string","description":"Source warehouse id."},"to_warehouse_id":{"type":"string","description":"Destination warehouse id."},"quantity":{"type":"integer","description":"Quantity to move (positive)."}},"required":["sku","from_warehouse_id","to_warehouse_id","quantity"]},"example":{"sku":"STEEL-BRKT-08","from_warehouse_id":"wh_hcm","to_warehouse_id":"wh_hanoi","quantity":200}}}},"security":[{"oauth2":["inventory:write"]}]}},"/v1/inventory/warehouses":{"get":{"tags":["Inventory"],"operationId":"listWarehouses","summary":"List warehouses","description":"Returns the warehouses (and distribution centers) stock is held in.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"List warehouses","content":{"application/json":{"example":{"data":[{"id":"wh_hcm","code":"HCM-01","name":"Ho Chi Minh DC","type":"distribution","active":true},{"id":"wh_hanoi","code":"HN-01","name":"Hanoi warehouse","type":"storage","active":true}]}}}}},"security":[{"oauth2":["inventory:read"]}]},"post":{"tags":["Inventory"],"operationId":"createWarehouse","summary":"Create a warehouse","description":"Creates a warehouse. code must be unique.\n\nRequires scope `inventory:write`.","responses":{"201":{"description":"Create a warehouse","content":{"application/json":{"example":{"id":"wh_danang","code":"DN-01","name":"Da Nang warehouse","created_at":"2026-07-20T03:30:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Unique warehouse code."},"name":{"type":"string","description":"Display name."},"address":{"type":"string","description":"Physical address."}},"required":["code","name"]},"example":{"code":"DN-01","name":"Da Nang warehouse","address":"48 Bach Dang, Hai Chau, Da Nang"}}}},"security":[{"oauth2":["inventory:write"]}]}},"/v1/inventory/warehouses/{id}":{"get":{"tags":["Inventory"],"operationId":"getWarehouse","summary":"Retrieve a warehouse","description":"Returns a single warehouse by its id.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"Retrieve a warehouse","content":{"application/json":{"example":{"id":"wh_hcm","code":"HCM-01","name":"Ho Chi Minh DC","type":"distribution","address":"12 Nguyen Van Linh, District 7, Ho Chi Minh City","bins_count":240,"active":true,"created_at":"2025-01-08T09:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Warehouse id.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/warehouses/{id}/bins":{"get":{"tags":["Inventory"],"operationId":"listBins","summary":"List bins","description":"Returns the storage bins (locations) within a warehouse.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"List bins","content":{"application/json":{"example":{"data":[{"id":"bin_a1","code":"A-01-01","zone":"A","type":"pick","occupied":true},{"id":"bin_a2","code":"A-01-02","zone":"A","type":"bulk","occupied":false}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Warehouse id.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/lots":{"get":{"tags":["Inventory"],"operationId":"listLots","summary":"List lots","description":"Returns tracked lots/batches with their quantities and expiry dates. Filter by SKU or warehouse.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"List lots","content":{"application/json":{"example":{"data":[{"id":"lot_88f2","sku":"PAINT-WHT-5L","lot_number":"L2026-0142","warehouse_id":"wh_hcm","quantity":340,"expires_at":"2027-03-31","unit_cost":{"amount":210000,"currency":"VND"}}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"sku","in":"query","required":false,"description":"Filter by stock-keeping unit.","schema":{"type":"string"}},{"name":"warehouse_id","in":"query","required":false,"description":"Filter by warehouse id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/lots/{id}":{"get":{"tags":["Inventory"],"operationId":"getLot","summary":"Retrieve a lot","description":"Returns a single lot/batch by its id.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"Retrieve a lot","content":{"application/json":{"example":{"id":"lot_88f2","sku":"PAINT-WHT-5L","lot_number":"L2026-0142","warehouse_id":"wh_hcm","quantity":340,"manufactured_at":"2026-04-02","expires_at":"2027-03-31","unit_cost":{"amount":210000,"currency":"VND"},"status":"available"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Lot id.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/serials":{"get":{"tags":["Inventory"],"operationId":"listSerials","summary":"List serial numbers","description":"Returns serial-tracked units and their current status. Filter by SKU or status.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"List serial numbers","content":{"application/json":{"example":{"data":[{"id":"srl_4410","sku":"LAPTOP-14-PRO","serial_number":"SN-2026-004410","warehouse_id":"wh_hcm","status":"in_stock"},{"id":"srl_4411","sku":"LAPTOP-14-PRO","serial_number":"SN-2026-004411","status":"shipped"}],"has_more":true,"next_cursor":"crsr_srl_7a"}}}}},"parameters":[{"name":"sku","in":"query","required":false,"description":"Filter by stock-keeping unit.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: in_stock, reserved, shipped, returned.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]}},"/v1/inventory/reservations":{"get":{"tags":["Inventory"],"operationId":"listReservations","summary":"List reservations","description":"Returns active stock reservations. Filter by SKU or by the order they back.\n\nRequires scope `inventory:read`.","responses":{"200":{"description":"List reservations","content":{"application/json":{"example":{"data":[{"id":"rsv_2c81","sku":"STEEL-BRKT-08","warehouse_id":"wh_hcm","quantity":320,"order_id":"so_9f30","status":"active","created_at":"2026-07-19T10:02:00Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"sku","in":"query","required":false,"description":"Filter by stock-keeping unit.","schema":{"type":"string"}},{"name":"order_id","in":"query","required":false,"description":"Filter by the order the reservation backs.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"security":[{"oauth2":["inventory:read"]}]},"post":{"tags":["Inventory"],"operationId":"createReservation","summary":"Reserve stock","description":"Reserves available stock of a SKU at a warehouse, moving it from available to reserved. Optionally tie the reservation to a sales order.\n\nRequires scope `inventory:write`.","responses":{"201":{"description":"Reserve stock","content":{"application/json":{"example":{"id":"rsv_2c82","sku":"STEEL-BRKT-08","warehouse_id":"wh_hcm","quantity":50,"order_id":"so_9f30","status":"active","expires_at":"2026-07-27T03:35:00Z","created_at":"2026-07-20T03:35:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","description":"Stock-keeping unit."},"warehouse_id":{"type":"string","description":"Warehouse to reserve from."},"quantity":{"type":"integer","description":"Quantity to reserve (positive)."},"order_id":{"type":"string","description":"Sales order the reservation backs."}},"required":["sku","warehouse_id","quantity"]},"example":{"sku":"STEEL-BRKT-08","warehouse_id":"wh_hcm","quantity":50,"order_id":"so_9f30"}}}},"security":[{"oauth2":["inventory:write"]}]}},"/v1/inventory/stock-counts":{"post":{"tags":["Inventory"],"operationId":"createStockCount","summary":"Open a stock count","description":"Opens a physical stock-count (cycle count or full inventory) for a warehouse. Counted quantities are reconciled against the system on close.\n\nRequires scope `inventory:write`.","responses":{"201":{"description":"Open a stock count","content":{"application/json":{"example":{"id":"cnt_6712","warehouse_id":"wh_hcm","scope":"partial","status":"open","created_at":"2026-07-20T03:40:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_id":{"type":"string","description":"Warehouse to count."},"scope":{"type":"string","description":"One of full, partial (default full)."}},"required":["warehouse_id"]},"example":{"warehouse_id":"wh_hcm","scope":"partial"}}}},"security":[{"oauth2":["inventory:write"]}]}},"/v1/purchasing/purchase-orders":{"get":{"tags":["Purchasing"],"operationId":"listPurchaseOrders","summary":"List purchase orders","description":"Returns a cursor-paginated list of purchase orders. Use updated_since for incremental sync.\n\nRequires scope `purchasing:read`.","responses":{"200":{"description":"List purchase orders","content":{"application/json":{"example":{"data":[{"id":"po_3310","number":"PO-2026-3310","supplier_id":"prt_501","status":"sent","expected_at":"2026-07-28","total":{"amount":92000000,"currency":"VND"},"updated_at":"2026-07-18T09:12:04Z"}],"has_more":true,"next_cursor":"crsr_po44"}}}}},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status: draft | sent | received | closed.","schema":{"type":"string"}},{"name":"supplier_id","in":"query","required":false,"description":"Filter by supplier (partner id).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"RFC 3339 timestamp; return orders changed after it.","schema":{"type":"string"}}],"security":[{"oauth2":["purchasing:read"]}]},"post":{"tags":["Purchasing"],"operationId":"createPurchaseOrder","summary":"Create a purchase order","description":"Creates a purchase order for a supplier. lines must not be empty.\n\nRequires scope `purchasing:write`.","responses":{"201":{"description":"Create a purchase order","content":{"application/json":{"example":{"id":"po_3311","number":"PO-2026-3311","status":"sent","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string","description":"Partner id of the supplier."},"lines":{"type":"array","items":{},"description":"[{ sku, quantity, unit_price }]."},"expected_at":{"type":"string","description":"Expected delivery date (RFC 3339)."}},"required":["supplier_id","lines"]},"example":{"supplier_id":"prt_501","lines":[{"sku":"STEEL-COIL-2MM","quantity":40,"unit_price":{"amount":2300000,"currency":"VND"}}],"expected_at":"2026-07-28"}}}},"security":[{"oauth2":["purchasing:write"]}]}},"/v1/purchasing/purchase-orders/{id}":{"get":{"tags":["Purchasing"],"operationId":"getPurchaseOrder","summary":"Retrieve a purchase order","description":"Returns a single purchase order by its id, including its lines.\n\nRequires scope `purchasing:read`.","responses":{"200":{"description":"Retrieve a purchase order","content":{"application/json":{"example":{"id":"po_3310","number":"PO-2026-3310","supplier_id":"prt_501","status":"sent","expected_at":"2026-07-28","lines":[{"sku":"STEEL-COIL-2MM","quantity":40,"unit_price":{"amount":2300000,"currency":"VND"}}],"total":{"amount":92000000,"currency":"VND"},"updated_at":"2026-07-18T09:12:04Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order id.","schema":{"type":"string"}}],"security":[{"oauth2":["purchasing:read"]}]},"patch":{"tags":["Purchasing"],"operationId":"updatePurchaseOrder","summary":"Update a purchase order","description":"Updates mutable fields of a draft or sent purchase order. Only supplied fields change.\n\nRequires scope `purchasing:write`.","responses":{"200":{"description":"Update a purchase order","content":{"application/json":{"example":{"id":"po_3311","number":"PO-2026-3311","status":"sent","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_at":{"type":"string","description":"Expected delivery date (RFC 3339)."},"lines":{"type":"array","items":{},"description":"Replace the order lines: [{ sku, quantity, unit_price }]."},"status":{"type":"string","description":"Advance the status, e.g. draft → sent."}}},"example":{"expected_at":"2026-07-30"}}}},"security":[{"oauth2":["purchasing:write"]}]}},"/v1/purchasing/purchase-orders/{id}/cancel":{"post":{"tags":["Purchasing"],"operationId":"cancelPurchaseOrder","summary":"Cancel a purchase order","description":"Cancels a purchase order. Only orders with no goods received can be cancelled.\n\nRequires scope `purchasing:write`.","responses":{"201":{"description":"Cancel a purchase order","content":{"application/json":{"example":{"id":"po_3311","status":"cancelled","cancelled_at":"2026-07-20T02:30:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Optional cancellation reason (stored on the audit trail)."}}},"example":{"reason":"Supplier out of stock."}}}},"security":[{"oauth2":["purchasing:write"]}]}},"/v1/purchasing/purchase-orders/{id}/receipts":{"post":{"tags":["Purchasing"],"operationId":"receiveGoods","summary":"Receive goods","description":"Records a goods receipt against a purchase order. Increases inventory in real time.\n\nRequires scope `purchasing:write`.","responses":{"201":{"description":"Receive goods","content":{"application/json":{"example":{"id":"rcpt_88a1","purchase_order_id":"po_3311","status":"received","received_at":"2026-07-20T03:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_id":{"type":"string","description":"Receiving warehouse."},"lines":{"type":"array","items":{},"description":"[{ sku, quantity_received }]."}},"required":["warehouse_id","lines"]},"example":{"warehouse_id":"wh_north","lines":[{"sku":"STEEL-COIL-2MM","quantity_received":40}]}}}},"security":[{"oauth2":["purchasing:write"]}]}},"/v1/purchasing/goods-receipts":{"get":{"tags":["Purchasing"],"operationId":"listGoodsReceipts","summary":"List goods receipts","description":"Returns goods receipts, filterable by purchase order or warehouse.\n\nRequires scope `purchasing:read`.","responses":{"200":{"description":"List goods receipts","content":{"application/json":{"example":{"data":[{"id":"rcpt_88a1","purchase_order_id":"po_3311","warehouse_id":"wh_north","status":"received","received_at":"2026-07-20T03:00:00Z"}]}}}}},"parameters":[{"name":"purchase_order_id","in":"query","required":false,"description":"Filter by source purchase order.","schema":{"type":"string"}},{"name":"warehouse_id","in":"query","required":false,"description":"Filter by receiving warehouse.","schema":{"type":"string"}}],"security":[{"oauth2":["purchasing:read"]}]}},"/v1/purchasing/purchase-requisitions":{"get":{"tags":["Purchasing"],"operationId":"listPurchaseRequisitions","summary":"List purchase requisitions","description":"Returns internal purchase requisitions awaiting sourcing or approval.\n\nRequires scope `purchasing:read`.","responses":{"200":{"description":"List purchase requisitions","content":{"application/json":{"example":{"data":[{"id":"req_7011","number":"PR-2026-7011","department":"maintenance","status":"pending","created_at":"2026-07-19T06:40:00Z"}]}}}}},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status: pending | approved | rejected | ordered.","schema":{"type":"string"}}],"security":[{"oauth2":["purchasing:read"]}]},"post":{"tags":["Purchasing"],"operationId":"createPurchaseRequisition","summary":"Create a purchase requisition","description":"Raises an internal purchase requisition. lines must not be empty.\n\nRequires scope `purchasing:write`.","responses":{"201":{"description":"Create a purchase requisition","content":{"application/json":{"example":{"id":"req_7012","number":"PR-2026-7012","status":"pending","created_at":"2026-07-20T02:15:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"department":{"type":"string","description":"Requesting department code."},"lines":{"type":"array","items":{},"description":"[{ sku, quantity }]."},"needed_by":{"type":"string","description":"Date the goods are needed (RFC 3339)."}},"required":["department","lines"]},"example":{"department":"maintenance","lines":[{"sku":"BEARING-6204","quantity":12}],"needed_by":"2026-08-05"}}}},"security":[{"oauth2":["purchasing:write"]}]}},"/v1/purchasing/purchase-requisitions/{id}/approvals":{"post":{"tags":["Purchasing"],"operationId":"approvePurchaseRequisition","summary":"Approve a requisition","description":"Records an approval decision (approve or reject) on a purchase requisition.\n\nRequires scope `purchasing:write`.","responses":{"201":{"description":"Approve a requisition","content":{"application/json":{"example":{"id":"req_7012","status":"approved","approved_at":"2026-07-20T02:50:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase requisition id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","description":"approve | reject."},"comment":{"type":"string","description":"Optional reviewer note."}},"required":["decision"]},"example":{"decision":"approve","comment":"Within budget."}}}},"security":[{"oauth2":["purchasing:write"]}]}},"/v1/purchasing/rfqs":{"get":{"tags":["Purchasing"],"operationId":"listRfqs","summary":"List requests for quotation","description":"Returns requests for quotation sent to suppliers, filterable by status.\n\nRequires scope `purchasing:read`.","responses":{"200":{"description":"List requests for quotation","content":{"application/json":{"example":{"data":[{"id":"rfq_402","number":"RFQ-2026-402","status":"open","supplier_ids":["prt_501","prt_530"],"due_at":"2026-07-25T00:00:00Z"}]}}}}},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status: open | quoted | awarded | closed.","schema":{"type":"string"}}],"security":[{"oauth2":["purchasing:read"]}]}},"/v1/purchasing/supplier-invoices":{"get":{"tags":["Purchasing"],"operationId":"listSupplierInvoices","summary":"List supplier invoices","description":"Returns supplier (AP) invoices, filterable by supplier and status. Use for three-way matching.\n\nRequires scope `purchasing:read`.","responses":{"200":{"description":"List supplier invoices","content":{"application/json":{"example":{"data":[{"id":"sinv_9120","number":"SINV-2026-9120","supplier_id":"prt_501","purchase_order_id":"po_3310","status":"matched","total":{"amount":92000000,"currency":"VND"},"due_at":"2026-08-17"}]}}}}},"parameters":[{"name":"supplier_id","in":"query","required":false,"description":"Filter by supplier (partner id).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: draft | matched | approved | paid.","schema":{"type":"string"}}],"security":[{"oauth2":["purchasing:read"]}]}},"/v1/mes/production-orders":{"get":{"tags":["Manufacturing (MES)"],"operationId":"listProductionOrders","summary":"List production orders","description":"Returns a cursor-paginated list of production orders. Filter by status or work center; use updated_since for incremental sync.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"List production orders","content":{"application/json":{"example":{"data":[{"id":"pro_7f3a","product_sku":"PUMP-A200","quantity":500,"quantity_done":180,"scrap":4,"status":"in_progress","work_center_id":"wc_assembly_1","due_date":"2026-08-01","updated_at":"2026-07-19T08:14:00Z"}],"has_more":true,"next_cursor":"crsr_2b71"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"RFC 3339 timestamp; return orders changed after it.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: planned, released, in_progress or done.","schema":{"type":"string"}},{"name":"work_center_id","in":"query","required":false,"description":"Filter by the assigned work center.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]},"post":{"tags":["Manufacturing (MES)"],"operationId":"createProductionOrder","summary":"Create a production order","description":"Creates a production order in planned status. Release it separately to schedule work on the floor.\n\nRequires scope `mes:write`.","responses":{"201":{"description":"Create a production order","content":{"application/json":{"example":{"id":"pro_7f3a","product_sku":"PUMP-A200","status":"planned","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_sku":{"type":"string","description":"SKU of the finished good to produce."},"quantity":{"type":"integer","description":"Quantity to produce (positive integer)."},"due_date":{"type":"string","description":"Target completion date (YYYY-MM-DD)."},"work_center_id":{"type":"string","description":"Work center to assign the order to."}},"required":["product_sku","quantity"]},"example":{"product_sku":"PUMP-A200","quantity":500,"due_date":"2026-08-01","work_center_id":"wc_assembly_1"}}}},"security":[{"oauth2":["mes:write"]}]}},"/v1/mes/production-orders/{id}":{"get":{"tags":["Manufacturing (MES)"],"operationId":"getProductionOrder","summary":"Retrieve a production order","description":"Returns a single production order by its id, including progress and scrap counters.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"Retrieve a production order","content":{"application/json":{"example":{"id":"pro_7f3a","product_sku":"PUMP-A200","quantity":500,"quantity_done":180,"scrap":4,"status":"in_progress","work_center_id":"wc_assembly_1","due_date":"2026-08-01","released_at":"2026-07-16T01:00:00Z","updated_at":"2026-07-19T08:14:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Production order id.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]}},"/v1/mes/production-orders/{id}/release":{"post":{"tags":["Manufacturing (MES)"],"operationId":"releaseProductionOrder","summary":"Release a production order","description":"Moves a planned order to released so it can be dispatched to the work center. Consumes component reservations from the BOM.\n\nRequires scope `mes:write`.","responses":{"201":{"description":"Release a production order","content":{"application/json":{"example":{"id":"pro_7f3a","status":"released","released_at":"2026-07-16T01:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Production order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"released_by":{"type":"string","description":"User id recording the release."}}},"example":{"released_by":"usr_ops_12"}}}},"security":[{"oauth2":["mes:write"]}]}},"/v1/mes/production-orders/{id}/completions":{"post":{"tags":["Manufacturing (MES)"],"operationId":"reportCompletion","summary":"Report a completion","description":"Records a quantity of good (and optionally scrap) finished against a production order. Advances quantity_done; closes the order when it reaches the target.\n\nRequires scope `mes:write`.","responses":{"201":{"description":"Report a completion","content":{"application/json":{"example":{"id":"cmp_4d81","production_order_id":"pro_7f3a","quantity":120,"scrap":3,"quantity_done":180,"created_at":"2026-07-19T08:14:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Production order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","description":"Good quantity completed (positive integer)."},"scrap":{"type":"integer","description":"Scrapped quantity in this report."},"work_center_id":{"type":"string","description":"Work center where the work was done."}},"required":["quantity"]},"example":{"quantity":120,"scrap":3,"work_center_id":"wc_assembly_1"}}}},"security":[{"oauth2":["mes:write"]}]}},"/v1/mes/work-centers":{"get":{"tags":["Manufacturing (MES)"],"operationId":"listWorkCenters","summary":"List work centers","description":"Returns work centers with their current status and live OEE (availability × performance × quality).\n\nRequires scope `mes:read`.","responses":{"200":{"description":"List work centers","content":{"application/json":{"example":{"data":[{"id":"wc_assembly_1","name":"Assembly line 1","status":"running","oee":{"availability":0.92,"performance":0.88,"quality":0.97,"oee":0.785},"updated_at":"2026-07-20T03:00:00Z"}]}}}}},"security":[{"oauth2":["mes:read"]}]}},"/v1/mes/work-centers/{id}":{"get":{"tags":["Manufacturing (MES)"],"operationId":"getWorkCenter","summary":"Retrieve a work center","description":"Returns a single work center by its id, including its live OEE breakdown.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"Retrieve a work center","content":{"application/json":{"example":{"id":"wc_assembly_1","name":"Assembly line 1","status":"running","oee":{"availability":0.92,"performance":0.88,"quality":0.97,"oee":0.785},"updated_at":"2026-07-20T03:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Work center id.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]}},"/v1/mes/boms":{"get":{"tags":["Manufacturing (MES)"],"operationId":"listBoms","summary":"List bills of materials","description":"Returns bills of materials. Filter by the finished-good SKU they build.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"List bills of materials","content":{"application/json":{"example":{"data":[{"id":"bom_3c9f","product_sku":"PUMP-A200","components":[{"sku":"MOTOR-1KW","quantity":1},{"sku":"STEEL-BRKT-08","quantity":4}]}]}}}}},"parameters":[{"name":"product_sku","in":"query","required":false,"description":"Filter by the finished-good SKU.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]},"post":{"tags":["Manufacturing (MES)"],"operationId":"createBom","summary":"Create a bill of materials","description":"Creates a bill of materials for a finished good. Each component references a stocked SKU and a per-unit quantity.\n\nRequires scope `mes:write`.","responses":{"201":{"description":"Create a bill of materials","content":{"application/json":{"example":{"id":"bom_3c9f","product_sku":"PUMP-A200","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_sku":{"type":"string","description":"SKU of the finished good this BOM builds."},"components":{"type":"array","items":{},"description":"Component lines, each { sku, quantity }."}},"required":["product_sku","components"]},"example":{"product_sku":"PUMP-A200","components":[{"sku":"MOTOR-1KW","quantity":1},{"sku":"STEEL-BRKT-08","quantity":4}]}}}},"security":[{"oauth2":["mes:write"]}]}},"/v1/mes/boms/{id}":{"get":{"tags":["Manufacturing (MES)"],"operationId":"getBom","summary":"Retrieve a bill of materials","description":"Returns a single bill of materials by its id, with its component lines.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"Retrieve a bill of materials","content":{"application/json":{"example":{"id":"bom_3c9f","product_sku":"PUMP-A200","components":[{"sku":"MOTOR-1KW","quantity":1},{"sku":"STEEL-BRKT-08","quantity":4}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"BOM id.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]}},"/v1/mes/routings":{"get":{"tags":["Manufacturing (MES)"],"operationId":"listRoutings","summary":"List routings","description":"Returns routings — the ordered operations (with standard times) a finished good passes through.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"List routings","content":{"application/json":{"example":{"data":[{"id":"rtg_a12b","product_sku":"PUMP-A200","operations":[{"seq":10,"name":"Machining","work_center_id":"wc_machining_2","std_minutes":12},{"seq":20,"name":"Assembly","work_center_id":"wc_assembly_1","std_minutes":8}]}]}}}}},"parameters":[{"name":"product_sku","in":"query","required":false,"description":"Filter by the finished-good SKU.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]}},"/v1/mes/work-centers/{id}/downtime":{"post":{"tags":["Manufacturing (MES)"],"operationId":"logDowntime","summary":"Log downtime","description":"Records a downtime event against a work center. Downtime lowers the availability factor of the work center's live OEE.\n\nRequires scope `mes:write`.","responses":{"201":{"description":"Log downtime","content":{"application/json":{"example":{"id":"dtm_9a27","work_center_id":"wc_assembly_1","reason":"tooling-change","minutes":25,"logged_at":"2026-07-20T03:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Work center id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Downtime reason code, e.g. tooling-change, breakdown."},"minutes":{"type":"integer","description":"Duration of the downtime in minutes (positive integer)."}},"required":["reason","minutes"]},"example":{"reason":"tooling-change","minutes":25}}}},"security":[{"oauth2":["mes:write"]}]}},"/v1/mes/scrap":{"get":{"tags":["Manufacturing (MES)"],"operationId":"listScrap","summary":"List scrap records","description":"Returns scrap records reported on the floor. Filter by work center and a start timestamp.\n\nRequires scope `mes:read`.","responses":{"200":{"description":"List scrap records","content":{"application/json":{"example":{"data":[{"id":"scr_5b19","production_order_id":"pro_7f3a","work_center_id":"wc_assembly_1","quantity":3,"reason":"misaligned-weld","logged_at":"2026-07-19T08:14:00Z"}]}}}}},"parameters":[{"name":"work_center_id","in":"query","required":false,"description":"Filter by the work center that reported the scrap.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"RFC 3339 timestamp; return scrap logged on or after it.","schema":{"type":"string"}}],"security":[{"oauth2":["mes:read"]}]}},"/v1/fin/invoices":{"get":{"tags":["Finance & Accounting"],"operationId":"listInvoices","summary":"List invoices","description":"Returns a cursor-paginated list of invoices. Filter by lifecycle status, partner or direction (receivable vs payable).\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List invoices","content":{"application/json":{"example":{"data":[{"id":"inv_1a2b","number":"INV-2026-000142","direction":"receivable","partner_id":"prt_1a2b","status":"open","issue_date":"2026-07-20","due_date":"2026-08-19","total":{"amount":13750000,"currency":"VND"},"balance":{"amount":13750000,"currency":"VND"},"updated_at":"2026-07-20T04:20:11Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: open, paid, overdue or void.","schema":{"type":"string"}},{"name":"partner_id","in":"query","required":false,"description":"Filter by partner (customer or supplier).","schema":{"type":"string"}},{"name":"direction","in":"query","required":false,"description":"receivable (sales) or payable (purchase).","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]},"post":{"tags":["Finance & Accounting"],"operationId":"createInvoice","summary":"Create an invoice","description":"Creates a draft invoice. Totals and tax are computed from the lines; the number is assigned on posting.\n\nRequires scope `finance:write`.","responses":{"201":{"description":"Create an invoice","content":{"application/json":{"example":{"id":"inv_1a2b","number":"INV-2026-000142","status":"open","total":{"amount":13750000,"currency":"VND"},"created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"partner_id":{"type":"string","description":"Customer (receivable) or supplier (payable)."},"direction":{"type":"string","description":"receivable or payable."},"lines":{"type":"string","description":"Line items: { description, quantity, unit_price, tax_code }."},"due_date":{"type":"string","description":"Payment due date (YYYY-MM-DD)."}},"required":["partner_id","direction","lines"]},"example":{"partner_id":"prt_1a2b","direction":"receivable","due_date":"2026-08-19","lines":[{"description":"Steel bracket 8mm","quantity":100,"unit_price":{"amount":125000,"currency":"VND"},"tax_code":"VAT10"}]}}}},"security":[{"oauth2":["finance:write"]}]}},"/v1/fin/invoices/{id}":{"get":{"tags":["Finance & Accounting"],"operationId":"getInvoice","summary":"Retrieve an invoice","description":"Returns a single invoice with its lines and running balance.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"Retrieve an invoice","content":{"application/json":{"example":{"id":"inv_1a2b","number":"INV-2026-000142","direction":"receivable","partner_id":"prt_1a2b","status":"open","issue_date":"2026-07-20","due_date":"2026-08-19","lines":[{"description":"Steel bracket 8mm","quantity":100,"unit_price":{"amount":125000,"currency":"VND"},"tax_code":"VAT10","subtotal":{"amount":12500000,"currency":"VND"}}],"subtotal":{"amount":12500000,"currency":"VND"},"tax":{"amount":1250000,"currency":"VND"},"total":{"amount":13750000,"currency":"VND"},"balance":{"amount":13750000,"currency":"VND"},"updated_at":"2026-07-20T04:20:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Invoice id.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]},"patch":{"tags":["Finance & Accounting"],"operationId":"updateInvoice","summary":"Update an invoice","description":"Updates mutable fields of an invoice while it is still open. Only supplied fields change; a paid or void invoice is read-only.\n\nRequires scope `finance:write`.","responses":{"200":{"description":"Update an invoice","content":{"application/json":{"example":{"id":"inv_1a2b","number":"INV-2026-000142","status":"open","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Invoice id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"due_date":{"type":"string","description":"Payment due date (YYYY-MM-DD)."},"lines":{"type":"string","description":"Replacement line items: { description, quantity, unit_price, tax_code }."},"memo":{"type":"string","description":"Internal note shown on the document."}}},"example":{"due_date":"2026-09-03"}}}},"security":[{"oauth2":["finance:write"]}]}},"/v1/fin/invoices/{id}/void":{"post":{"tags":["Finance & Accounting"],"operationId":"voidInvoice","summary":"Void an invoice","description":"Voids an invoice, reversing its ledger impact. Only an invoice with no settled payments can be voided.\n\nRequires scope `finance:write`.","responses":{"201":{"description":"Void an invoice","content":{"application/json":{"example":{"id":"inv_1a2b","number":"INV-2026-000142","status":"void","voided_at":"2026-07-20T02:18:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Invoice id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Reason recorded in the audit trail."}}},"example":{"reason":"Issued to the wrong partner"}}}},"security":[{"oauth2":["finance:write"]}]}},"/v1/fin/payments":{"get":{"tags":["Finance & Accounting"],"operationId":"listPayments","summary":"List payments","description":"Returns a cursor-paginated list of payments and receipts. Filter by the invoice they settle or by method.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List payments","content":{"application/json":{"example":{"data":[{"id":"pay_6h7i","invoice_id":"inv_1a2b","amount":{"amount":13750000,"currency":"VND"},"method":"bank_transfer","paid_at":"2026-07-22T03:00:00Z","reference":"FT26073300142"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"invoice_id","in":"query","required":false,"description":"Return only payments applied to this invoice.","schema":{"type":"string"}},{"name":"method","in":"query","required":false,"description":"Filter by method: bank_transfer, cash or card.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]},"post":{"tags":["Finance & Accounting"],"operationId":"createPayment","summary":"Record a payment","description":"Records a payment or receipt against an invoice and applies it to the outstanding balance. Marks the invoice paid once fully settled.\n\nRequires scope `finance:write`.","responses":{"201":{"description":"Record a payment","content":{"application/json":{"example":{"id":"pay_6h7i","invoice_id":"inv_1a2b","invoice_status":"paid","created_at":"2026-07-22T03:00:05Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice being settled."},"amount":{"type":"object","description":"{ amount (minor units), currency }."},"method":{"type":"string","description":"bank_transfer, cash or card."},"paid_at":{"type":"string","description":"RFC 3339 timestamp of settlement (defaults to now)."}},"required":["invoice_id","amount","method"]},"example":{"invoice_id":"inv_1a2b","amount":{"amount":13750000,"currency":"VND"},"method":"bank_transfer","paid_at":"2026-07-22T03:00:00Z"}}}},"security":[{"oauth2":["finance:write"]}]}},"/v1/fin/journal-entries":{"get":{"tags":["Finance & Accounting"],"operationId":"listJournalEntries","summary":"List journal entries","description":"Returns a cursor-paginated list of general-ledger journal entries. Filter by the account they touch or by fiscal period.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List journal entries","content":{"application/json":{"example":{"data":[{"id":"je_3k4l","date":"2026-07-20","memo":"Sales invoice INV-2026-000142","source":"inv_1a2b","period":"2026-07","posted":true}],"has_more":true,"next_cursor":"crsr_7d8e"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"account","in":"query","required":false,"description":"Return entries that post to this account code.","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Fiscal period, e.g. 2026-07.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]},"post":{"tags":["Finance & Accounting"],"operationId":"createJournalEntry","summary":"Create a journal entry","description":"Posts a manual journal entry. Total debits must equal total credits and the target period must be open.\n\nRequires scope `finance:write`.","responses":{"201":{"description":"Create a journal entry","content":{"application/json":{"example":{"id":"je_3k4l","date":"2026-07-20","period":"2026-07","posted":true,"created_at":"2026-07-20T02:20:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","description":"Accounting date (YYYY-MM-DD)."},"lines":{"type":"string","description":"Balanced lines: { account, debit, credit }."},"memo":{"type":"string","description":"Description shown on the entry."}},"required":["date","lines"]},"example":{"date":"2026-07-20","memo":"Cash sale receipt","lines":[{"account":"111","debit":{"amount":13750000,"currency":"VND"},"credit":{"amount":0,"currency":"VND"}},{"account":"511","debit":{"amount":0,"currency":"VND"},"credit":{"amount":12500000,"currency":"VND"}},{"account":"3331","debit":{"amount":0,"currency":"VND"},"credit":{"amount":1250000,"currency":"VND"}}]}}}},"security":[{"oauth2":["finance:write"]}]}},"/v1/fin/journal-entries/{id}":{"get":{"tags":["Finance & Accounting"],"operationId":"getJournalEntry","summary":"Retrieve a journal entry","description":"Returns a single journal entry with its debit and credit lines.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"Retrieve a journal entry","content":{"application/json":{"example":{"id":"je_3k4l","date":"2026-07-20","memo":"Sales invoice INV-2026-000142","source":"inv_1a2b","period":"2026-07","posted":true,"lines":[{"account":"131","debit":{"amount":13750000,"currency":"VND"},"credit":{"amount":0,"currency":"VND"}},{"account":"511","debit":{"amount":0,"currency":"VND"},"credit":{"amount":12500000,"currency":"VND"}},{"account":"3331","debit":{"amount":0,"currency":"VND"},"credit":{"amount":1250000,"currency":"VND"}}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Journal entry id.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]}},"/v1/fin/accounts":{"get":{"tags":["Finance & Accounting"],"operationId":"listAccounts","summary":"List accounts","description":"Returns the chart of accounts. Filter by account type.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List accounts","content":{"application/json":{"example":{"data":[{"code":"111","name":"Cash on hand","type":"asset","parent":null},{"code":"112","name":"Cash in banks","type":"asset","parent":null},{"code":"131","name":"Trade receivables","type":"asset","parent":null}]}}}}},"parameters":[{"name":"type","in":"query","required":false,"description":"Filter by type: asset, liability, equity, revenue or expense.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]}},"/v1/fin/cost-centers":{"get":{"tags":["Finance & Accounting"],"operationId":"listCostCenters","summary":"List cost centers","description":"Returns the cost centers used to tag expenses and revenue for management reporting.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List cost centers","content":{"application/json":{"example":{"data":[{"id":"cc_prod","code":"PROD","name":"Production","active":true},{"id":"cc_sales","code":"SALES","name":"Sales & Marketing","active":true}]}}}}},"security":[{"oauth2":["finance:read"]}]}},"/v1/fin/fiscal-periods":{"get":{"tags":["Finance & Accounting"],"operationId":"listFiscalPeriods","summary":"List fiscal periods","description":"Returns the accounting calendar with each period's open or closed status.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List fiscal periods","content":{"application/json":{"example":{"data":[{"id":"fp_2026_06","period":"2026-06","status":"closed","closed_at":"2026-07-05T09:00:00Z"},{"id":"fp_2026_07","period":"2026-07","status":"open","closed_at":null}]}}}}},"security":[{"oauth2":["finance:read"]}]}},"/v1/fin/fiscal-periods/{id}/close":{"post":{"tags":["Finance & Accounting"],"operationId":"closePeriod","summary":"Close a fiscal period","description":"Closes a fiscal period so no further entries can post to it. Fails if earlier periods are still open or unbalanced entries remain.\n\nRequires scope `finance:write`.","responses":{"201":{"description":"Close a fiscal period","content":{"application/json":{"example":{"id":"fp_2026_07","period":"2026-07","status":"closed","closed_at":"2026-08-05T09:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Fiscal period id.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:write"]}]}},"/v1/fin/tax-codes":{"get":{"tags":["Finance & Accounting"],"operationId":"listTaxCodes","summary":"List tax codes","description":"Returns the configured VAT and withholding tax codes with their rates and posting accounts.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List tax codes","content":{"application/json":{"example":{"data":[{"code":"VAT10","name":"VAT 10%","rate":0.1,"account":"3331","active":true},{"code":"VAT8","name":"VAT 8%","rate":0.08,"account":"3331","active":true},{"code":"VAT0","name":"VAT 0%","rate":0,"account":"3331","active":true}]}}}}},"security":[{"oauth2":["finance:read"]}]}},"/v1/fin/exchange-rates":{"get":{"tags":["Finance & Accounting"],"operationId":"listExchangeRates","summary":"List exchange rates","description":"Returns exchange rates against the base currency for a given date, used to translate foreign-currency documents.\n\nRequires scope `finance:read`.","responses":{"200":{"description":"List exchange rates","content":{"application/json":{"example":{"base":"VND","date":"2026-07-20","rates":[{"currency":"USD","rate":25450},{"currency":"EUR","rate":27680},{"currency":"JPY","rate":162}]}}}}},"parameters":[{"name":"base","in":"query","required":false,"description":"Base currency (default VND).","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Rate date (YYYY-MM-DD); defaults to today.","schema":{"type":"string"}}],"security":[{"oauth2":["finance:read"]}]}},"/v1/orders/sales-orders":{"get":{"tags":["Sales & CRM"],"operationId":"listSalesOrders","summary":"List sales orders","description":"Returns a cursor-paginated list of sales orders. Filter by status or customer.\n\nRequires scope `orders:read`.","responses":{"200":{"description":"List sales orders","content":{"application/json":{"example":{"data":[{"id":"so_1a2b","number":"SO-2026-000142","customer_id":"prt_1a2b","status":"confirmed","warehouse_id":"wh_hn1","total":{"amount":1250000,"currency":"VND"},"created_at":"2026-07-18T03:14:00Z"}],"has_more":true,"next_cursor":"crsr_5f6g"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: draft, confirmed, fulfilled or cancelled.","schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"description":"Filter by customer (partner id).","schema":{"type":"string"}}],"security":[{"oauth2":["orders:read"]}]},"post":{"tags":["Sales & CRM"],"operationId":"createSalesOrder","summary":"Create a sales order","description":"Creates a sales order in draft status. Prices default from the customer's price list when unit_price is omitted.\n\nRequires scope `orders:write`.","responses":{"201":{"description":"Create a sales order","content":{"application/json":{"example":{"id":"so_1a2b","number":"SO-2026-000142","status":"draft","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer (partner id)."},"lines":{"type":"array","items":{},"description":"Order lines: array of { sku, quantity, unit_price? }."},"warehouse_id":{"type":"string","description":"Warehouse fulfilling the order."}},"required":["customer_id","lines"]},"example":{"customer_id":"prt_1a2b","warehouse_id":"wh_hn1","lines":[{"sku":"STEEL-BRKT-08","quantity":100,"unit_price":{"amount":12500,"currency":"VND"}}]}}}},"security":[{"oauth2":["orders:write"]}]}},"/v1/orders/sales-orders/{id}":{"get":{"tags":["Sales & CRM"],"operationId":"getSalesOrder","summary":"Retrieve a sales order","description":"Returns a single sales order with its lines and totals.\n\nRequires scope `orders:read`.","responses":{"200":{"description":"Retrieve a sales order","content":{"application/json":{"example":{"id":"so_1a2b","number":"SO-2026-000142","customer_id":"prt_1a2b","status":"confirmed","warehouse_id":"wh_hn1","currency":"VND","lines":[{"sku":"STEEL-BRKT-08","quantity":100,"unit_price":{"amount":12500,"currency":"VND"},"line_total":{"amount":1250000,"currency":"VND"}}],"total":{"amount":1250000,"currency":"VND"},"created_at":"2026-07-18T03:14:00Z","updated_at":"2026-07-18T06:20:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Sales order id.","schema":{"type":"string"}}],"security":[{"oauth2":["orders:read"]}]}},"/v1/orders/sales-orders/{id}/confirm":{"post":{"tags":["Sales & CRM"],"operationId":"confirmSalesOrder","summary":"Confirm a sales order","description":"Confirms a draft order. Reserves stock and makes the order visible to distribution and finance.\n\nRequires scope `orders:write`.","responses":{"201":{"description":"Confirm a sales order","content":{"application/json":{"example":{"id":"so_1a2b","number":"SO-2026-000142","status":"confirmed","confirmed_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Sales order id.","schema":{"type":"string"}}],"security":[{"oauth2":["orders:write"]}]}},"/v1/orders/sales-orders/{id}/cancel":{"post":{"tags":["Sales & CRM"],"operationId":"cancelSalesOrder","summary":"Cancel a sales order","description":"Cancels an order and releases any reserved stock. A cancelled order cannot be confirmed again.\n\nRequires scope `orders:write`.","responses":{"201":{"description":"Cancel a sales order","content":{"application/json":{"example":{"id":"so_1a2b","status":"cancelled","cancel_reason":"Customer withdrew the purchase order.","cancelled_at":"2026-07-20T02:15:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Sales order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Free-text cancellation reason (stored on the order)."}}},"example":{"reason":"Customer withdrew the purchase order."}}}},"security":[{"oauth2":["orders:write"]}]}},"/v1/crm/quotations":{"get":{"tags":["Sales & CRM"],"operationId":"listQuotations","summary":"List quotations","description":"Returns a cursor-paginated list of quotations. Filter by status or customer.\n\nRequires scope `crm:read`.","responses":{"200":{"description":"List quotations","content":{"application/json":{"example":{"data":[{"id":"qtn_3c4d","number":"QT-2026-000087","customer_id":"prt_1a2b","status":"sent","total":{"amount":1250000,"currency":"VND"},"valid_until":"2026-08-15","created_at":"2026-07-16T08:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: draft, sent, accepted, declined or expired.","schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"description":"Filter by customer (partner id).","schema":{"type":"string"}}],"security":[{"oauth2":["crm:read"]}]},"post":{"tags":["Sales & CRM"],"operationId":"createQuotation","summary":"Create a quotation","description":"Creates a quotation in draft status. Convert it to a sales order once the customer accepts.\n\nRequires scope `crm:write`.","responses":{"201":{"description":"Create a quotation","content":{"application/json":{"example":{"id":"qtn_3c4d","number":"QT-2026-000087","status":"draft","created_at":"2026-07-20T02:20:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer (partner id)."},"lines":{"type":"array","items":{},"description":"Quote lines: array of { sku, quantity, unit_price? }."},"valid_until":{"type":"string","description":"Expiry date (YYYY-MM-DD)."}},"required":["customer_id","lines"]},"example":{"customer_id":"prt_1a2b","valid_until":"2026-08-15","lines":[{"sku":"STEEL-BRKT-08","quantity":100,"unit_price":{"amount":12500,"currency":"VND"}}]}}}},"security":[{"oauth2":["crm:write"]}]}},"/v1/crm/quotations/{id}/convert":{"post":{"tags":["Sales & CRM"],"operationId":"convertQuotation","summary":"Convert a quotation","description":"Converts an accepted quotation into a draft sales order, carrying over its lines and prices.\n\nRequires scope `crm:write`.","responses":{"201":{"description":"Convert a quotation","content":{"application/json":{"example":{"id":"qtn_3c4d","status":"accepted","sales_order_id":"so_1a2b","converted_at":"2026-07-20T02:22:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Quotation id.","schema":{"type":"string"}}],"security":[{"oauth2":["crm:write"]}]}},"/v1/crm/leads":{"get":{"tags":["Sales & CRM"],"operationId":"listLeads","summary":"List leads","description":"Returns a cursor-paginated list of leads. Filter by pipeline stage or acquisition source.\n\nRequires scope `crm:read`.","responses":{"200":{"description":"List leads","content":{"application/json":{"example":{"data":[{"id":"lead_5e6f","name":"Nguyen Van An","email":"an.nguyen@example.com","company":"Cong ty CP Dai Phat","stage":"new","source":"website","owner_id":"usr_7a","created_at":"2026-07-19T09:30:00Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"stage","in":"query","required":false,"description":"Filter by stage: new, contacted, qualified or unqualified.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"Filter by source: website, referral, event or import.","schema":{"type":"string"}}],"security":[{"oauth2":["crm:read"]}]},"post":{"tags":["Sales & CRM"],"operationId":"createLead","summary":"Create a lead","description":"Creates a lead in the new stage. Convert a qualified lead into an opportunity later.\n\nRequires scope `crm:write`.","responses":{"201":{"description":"Create a lead","content":{"application/json":{"example":{"id":"lead_5e6f","stage":"new","created_at":"2026-07-20T02:25:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Contact's full name."},"email":{"type":"string","description":"Contact email address."},"company":{"type":"string","description":"Company or organization name."},"source":{"type":"string","description":"Acquisition source: website, referral, event or import."}},"required":["name"]},"example":{"name":"Nguyen Van An","email":"an.nguyen@example.com","company":"Cong ty CP Dai Phat","source":"website"}}}},"security":[{"oauth2":["crm:write"]}]}},"/v1/crm/leads/{id}/convert":{"post":{"tags":["Sales & CRM"],"operationId":"convertLead","summary":"Convert a lead","description":"Converts a qualified lead into an opportunity and, when company details are present, a customer partner.\n\nRequires scope `crm:write`.","responses":{"201":{"description":"Convert a lead","content":{"application/json":{"example":{"id":"lead_5e6f","stage":"qualified","opportunity_id":"opp_9a10","partner_id":"prt_2b3c","converted_at":"2026-07-20T02:28:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Lead id.","schema":{"type":"string"}}],"security":[{"oauth2":["crm:write"]}]}},"/v1/crm/opportunities":{"get":{"tags":["Sales & CRM"],"operationId":"listOpportunities","summary":"List opportunities","description":"Returns a cursor-paginated list of opportunities. Filter by pipeline stage or owner.\n\nRequires scope `crm:read`.","responses":{"200":{"description":"List opportunities","content":{"application/json":{"example":{"data":[{"id":"opp_9a10","name":"Dai Phat — ERP rollout","customer_id":"prt_2b3c","stage":"proposal","amount":{"amount":480000000,"currency":"VND"},"owner_id":"usr_7a","expected_close":"2026-09-30","created_at":"2026-07-19T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"stage","in":"query","required":false,"description":"Filter by stage: prospecting, qualification, proposal, negotiation, won or lost.","schema":{"type":"string"}},{"name":"owner_id","in":"query","required":false,"description":"Filter by the sales rep who owns the opportunity.","schema":{"type":"string"}}],"security":[{"oauth2":["crm:read"]}]}},"/v1/crm/opportunities/{id}":{"patch":{"tags":["Sales & CRM"],"operationId":"updateOpportunity","summary":"Update an opportunity","description":"Updates mutable fields of an opportunity — typically to advance its stage or revise the deal amount. Only supplied fields change.\n\nRequires scope `crm:write`.","responses":{"200":{"description":"Update an opportunity","content":{"application/json":{"example":{"id":"opp_9a10","stage":"negotiation","amount":{"amount":520000000,"currency":"VND"},"updated_at":"2026-07-20T02:30:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Opportunity id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"type":"string","description":"Pipeline stage: prospecting, qualification, proposal, negotiation, won or lost."},"amount":{"type":"object","description":"{ amount (minor units), currency }."}}},"example":{"stage":"negotiation","amount":{"amount":520000000,"currency":"VND"}}}}},"security":[{"oauth2":["crm:write"]}]}},"/v1/orders/shipments":{"get":{"tags":["Sales & CRM"],"operationId":"listShipments","summary":"List shipments","description":"Returns a cursor-paginated list of shipments. Filter by order or delivery status.\n\nRequires scope `orders:read`.","responses":{"200":{"description":"List shipments","content":{"application/json":{"example":{"data":[{"id":"shp_1x2y","order_id":"so_1a2b","status":"in_transit","carrier":"GHN","tracking_number":"GHN-4457821","shipped_at":"2026-07-19T01:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"order_id","in":"query","required":false,"description":"Filter by sales order id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: pending, packed, in_transit, delivered or returned.","schema":{"type":"string"}}],"security":[{"oauth2":["orders:read"]}]}},"/v1/orders/returns":{"post":{"tags":["Sales & CRM"],"operationId":"createReturn","summary":"Create a return","description":"Opens a return (RMA) against a fulfilled order. Approving it restocks the items and credits the customer.\n\nRequires scope `orders:write`.","responses":{"201":{"description":"Create a return","content":{"application/json":{"example":{"id":"rtn_8k9l","order_id":"so_1a2b","status":"requested","created_at":"2026-07-20T02:35:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","description":"Sales order the return is raised against."},"lines":{"type":"array","items":{},"description":"Returned lines: array of { sku, quantity }."},"reason":{"type":"string","description":"Return reason, e.g. damaged, wrong-item, surplus."}},"required":["order_id","lines"]},"example":{"order_id":"so_1a2b","reason":"damaged","lines":[{"sku":"STEEL-BRKT-08","quantity":5}]}}}},"security":[{"oauth2":["orders:write"]}]}},"/v1/dms/distributors":{"get":{"tags":["Distribution (DMS)"],"operationId":"listDistributors","summary":"List distributors","description":"Returns a cursor-paginated list of distributors. Filter by sales territory.\n\nRequires scope `dms:read`.","responses":{"200":{"description":"List distributors","content":{"application/json":{"example":{"data":[{"id":"dst_4f21","code":"DIST-HN-07","name":"Hoan Kiem Trading Co.","territory":"north","credit_limit":{"amount":500000000,"currency":"VND"},"credit_used":{"amount":128000000,"currency":"VND"},"active":true,"updated_at":"2026-07-14T03:11:52Z"}],"has_more":true,"next_cursor":"crsr_2b7f"}}}}},"parameters":[{"name":"territory","in":"query","required":false,"description":"Filter by territory code.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}}],"security":[{"oauth2":["dms:read"]}]},"post":{"tags":["Distribution (DMS)"],"operationId":"createDistributor","summary":"Create a distributor","description":"Onboards a distributor into a territory. credit_limit defaults to zero (cash only).\n\nRequires scope `dms:write`.","responses":{"201":{"description":"Create a distributor","content":{"application/json":{"example":{"id":"dst_4f21","code":"DIST-HN-07","created_at":"2026-07-20T02:20:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Legal or trading name."},"territory":{"type":"string","description":"Territory code the distributor belongs to."},"credit_limit":{"type":"object","description":"{ amount (minor units), currency } — revolving credit ceiling."}},"required":["name","territory"]},"example":{"name":"Hoan Kiem Trading Co.","territory":"north","credit_limit":{"amount":500000000,"currency":"VND"}}}}},"security":[{"oauth2":["dms:write"]}]}},"/v1/dms/distributors/{id}":{"get":{"tags":["Distribution (DMS)"],"operationId":"getDistributor","summary":"Retrieve a distributor","description":"Returns a single distributor by its id, or by code (prefix the value with code_).\n\nRequires scope `dms:read`.","responses":{"200":{"description":"Retrieve a distributor","content":{"application/json":{"example":{"id":"dst_4f21","code":"DIST-HN-07","name":"Hoan Kiem Trading Co.","territory":"north","credit_limit":{"amount":500000000,"currency":"VND"},"credit_used":{"amount":128000000,"currency":"VND"},"contact":{"name":"Le Van Minh","phone":"+84 24 3825 1090"},"active":true,"updated_at":"2026-07-14T03:11:52Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Distributor id.","schema":{"type":"string"}}],"security":[{"oauth2":["dms:read"]}]},"patch":{"tags":["Distribution (DMS)"],"operationId":"updateDistributor","summary":"Update a distributor","description":"Updates mutable fields of a distributor. Only supplied fields change.\n\nRequires scope `dms:write`.","responses":{"200":{"description":"Update a distributor","content":{"application/json":{"example":{"id":"dst_4f21","code":"DIST-HN-07","updated_at":"2026-07-20T02:22:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Distributor id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Legal or trading name."},"territory":{"type":"string","description":"Territory code."},"credit_limit":{"type":"object","description":"{ amount (minor units), currency }."},"active":{"type":"boolean","description":"Activate or suspend the distributor."}}},"example":{"credit_limit":{"amount":650000000,"currency":"VND"}}}}},"security":[{"oauth2":["dms:write"]}]}},"/v1/dms/delivery-routes":{"get":{"tags":["Distribution (DMS)"],"operationId":"listRoutes","summary":"List delivery routes","description":"Returns delivery routes, filterable by date and assigned driver.\n\nRequires scope `dms:read`.","responses":{"200":{"description":"List delivery routes","content":{"application/json":{"example":{"data":[{"id":"rte_9c30","date":"2026-07-21","driver_id":"drv_71a2","vehicle":"29H-114.02","stops":12,"status":"planned"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"date","in":"query","required":false,"description":"Route date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"driver_id","in":"query","required":false,"description":"Filter by assigned driver id.","schema":{"type":"string"}}],"security":[{"oauth2":["dms:read"]}]},"post":{"tags":["Distribution (DMS)"],"operationId":"createRoute","summary":"Create a delivery route","description":"Plans a delivery route for a driver on a given date.\n\nRequires scope `dms:write`.","responses":{"201":{"description":"Create a delivery route","content":{"application/json":{"example":{"id":"rte_9c31","date":"2026-07-22","created_at":"2026-07-20T02:24:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","description":"Route date (YYYY-MM-DD)."},"driver_id":{"type":"string","description":"Driver assigned to the route."},"stops":{"type":"integer","description":"Planned number of stops (informational)."}},"required":["date","driver_id"]},"example":{"date":"2026-07-22","driver_id":"drv_71a2","stops":10}}}},"security":[{"oauth2":["dms:write"]}]}},"/v1/dms/delivery-routes/{id}":{"get":{"tags":["Distribution (DMS)"],"operationId":"getRoute","summary":"Retrieve a delivery route","description":"Returns a single route with its ordered list of stops.\n\nRequires scope `dms:read`.","responses":{"200":{"description":"Retrieve a delivery route","content":{"application/json":{"example":{"id":"rte_9c30","date":"2026-07-21","driver_id":"drv_71a2","vehicle":"29H-114.02","status":"planned","stops":[{"seq":1,"distributor_id":"dst_4f21","delivery_id":"dlv_a801"},{"seq":2,"distributor_id":"dst_5b88","delivery_id":"dlv_a802"}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Route id.","schema":{"type":"string"}}],"security":[{"oauth2":["dms:read"]}]}},"/v1/dms/deliveries":{"get":{"tags":["Distribution (DMS)"],"operationId":"listDeliveries","summary":"List deliveries","description":"Returns deliveries to distributors, filterable by distributor and status.\n\nRequires scope `dms:read`.","responses":{"200":{"description":"List deliveries","content":{"application/json":{"example":{"data":[{"id":"dlv_a801","distributor_id":"dst_4f21","route_id":"rte_9c30","status":"pending","total":{"amount":24600000,"currency":"VND"},"created_at":"2026-07-20T01:40:00Z"}],"has_more":true,"next_cursor":"crsr_7d21"}}}}},"parameters":[{"name":"distributor_id","in":"query","required":false,"description":"Filter by distributor id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"One of pending, confirmed, delivered, cancelled.","schema":{"type":"string"}}],"security":[{"oauth2":["dms:read"]}]},"post":{"tags":["Distribution (DMS)"],"operationId":"createDelivery","summary":"Create a delivery","description":"Creates a delivery order for a distributor. Attach it to a route now or later.\n\nRequires scope `dms:write`.","responses":{"201":{"description":"Create a delivery","content":{"application/json":{"example":{"id":"dlv_a801","status":"pending","created_at":"2026-07-20T02:26:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"distributor_id":{"type":"string","description":"Distributor receiving the goods."},"route_id":{"type":"string","description":"Route this delivery is assigned to."},"lines":{"type":"array","items":{},"description":"Order lines — array of { sku, quantity }."}},"required":["distributor_id","lines"]},"example":{"distributor_id":"dst_4f21","route_id":"rte_9c30","lines":[{"sku":"BEV-COLA-330","quantity":240},{"sku":"BEV-WATER-500","quantity":120}]}}}},"security":[{"oauth2":["dms:write"]}]}},"/v1/dms/deliveries/{id}/confirm":{"post":{"tags":["Distribution (DMS)"],"operationId":"confirmDelivery","summary":"Confirm a delivery","description":"Confirms a pending delivery, reserving stock and locking the order lines.\n\nRequires scope `dms:write`.","responses":{"201":{"description":"Confirm a delivery","content":{"application/json":{"example":{"id":"dlv_a801","status":"confirmed","confirmed_at":"2026-07-20T02:30:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Delivery id.","schema":{"type":"string"}}],"security":[{"oauth2":["dms:write"]}]}},"/v1/dms/visits":{"get":{"tags":["Distribution (DMS)"],"operationId":"listVisits","summary":"List field-sales visits","description":"Returns field-sales visits, filterable by sales rep and date.\n\nRequires scope `dms:read`.","responses":{"200":{"description":"List field-sales visits","content":{"application/json":{"example":{"data":[{"id":"vst_e004","distributor_id":"dst_4f21","rep_id":"rep_2210","checked_in_at":"2026-07-21T02:05:00Z","notes":"Restocked cooler, collected aging invoice."}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"rep_id","in":"query","required":false,"description":"Filter by sales rep id.","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Visit date (YYYY-MM-DD).","schema":{"type":"string"}}],"security":[{"oauth2":["dms:read"]}]},"post":{"tags":["Distribution (DMS)"],"operationId":"logVisit","summary":"Log a field-sales visit","description":"Records a rep's visit to a distributor. Typically posted from a mobile field-force app.\n\nRequires scope `dms:write`.","responses":{"201":{"description":"Log a field-sales visit","content":{"application/json":{"example":{"id":"vst_e004","created_at":"2026-07-21T02:05:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"distributor_id":{"type":"string","description":"Distributor visited."},"rep_id":{"type":"string","description":"Sales rep who made the visit."},"notes":{"type":"string","description":"Free-text visit notes."}},"required":["distributor_id","rep_id"]},"example":{"distributor_id":"dst_4f21","rep_id":"rep_2210","notes":"Restocked cooler, collected aging invoice."}}}},"security":[{"oauth2":["dms:write"]}]}},"/v1/dms/promotions":{"get":{"tags":["Distribution (DMS)"],"operationId":"listPromotions","summary":"List trade promotions","description":"Returns trade promotions. Pass active=true to return only currently running ones.\n\nRequires scope `dms:read`.","responses":{"200":{"description":"List trade promotions","content":{"application/json":{"example":{"data":[{"id":"promo_31aa","code":"Q3-BUY10-GET1","name":"Buy 10 get 1 — beverages","starts_on":"2026-07-01","ends_on":"2026-09-30","active":true}]}}}}},"parameters":[{"name":"active","in":"query","required":false,"description":"Return only promotions active today.","schema":{"type":"boolean"}}],"security":[{"oauth2":["dms:read"]}]}},"/v1/hrm/employees":{"get":{"tags":["HRM"],"operationId":"listEmployees","summary":"List employees","description":"Returns a cursor-paginated list of employees. Filter by department or employment status.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"List employees","content":{"application/json":{"example":{"data":[{"id":"emp_1a2b","code":"EMP-000142","name":"Nguyen Van An","department":"production","title":"Line supervisor","email":"an.nv@apusplatform.com","status":"active","hired_at":"2024-03-01","updated_at":"2026-07-12T04:20:11Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"department","in":"query","required":false,"description":"Filter by department code.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: active, on_leave or terminated.","schema":{"type":"string"}}],"security":[{"oauth2":["hrm:read"]}]},"post":{"tags":["HRM"],"operationId":"createEmployee","summary":"Create an employee","description":"Creates an employee record. name and department are required.\n\nRequires scope `hrm:write`.","responses":{"201":{"description":"Create an employee","content":{"application/json":{"example":{"id":"emp_1a2b","code":"EMP-000142","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Full name."},"department":{"type":"string","description":"Department code."},"title":{"type":"string","description":"Job title."},"email":{"type":"string","description":"Work email."}},"required":["name","department"]},"example":{"name":"Nguyen Van An","department":"production","title":"Line supervisor","email":"an.nv@apusplatform.com"}}}},"security":[{"oauth2":["hrm:write"]}]}},"/v1/hrm/employees/{id}":{"get":{"tags":["HRM"],"operationId":"getEmployee","summary":"Retrieve an employee","description":"Returns a single employee by its id, or by code (prefix the value with code_).\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"Retrieve an employee","content":{"application/json":{"example":{"id":"emp_1a2b","code":"EMP-000142","name":"Nguyen Van An","department":"production","title":"Line supervisor","email":"an.nv@apusplatform.com","status":"active","hired_at":"2024-03-01","updated_at":"2026-07-12T04:20:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Employee id.","schema":{"type":"string"}}],"security":[{"oauth2":["hrm:read"]}]},"patch":{"tags":["HRM"],"operationId":"updateEmployee","summary":"Update an employee","description":"Updates mutable fields of an employee. Only supplied fields change.\n\nRequires scope `hrm:write`.","responses":{"200":{"description":"Update an employee","content":{"application/json":{"example":{"id":"emp_1a2b","code":"EMP-000142","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Employee id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Full name."},"department":{"type":"string","description":"Department code."},"title":{"type":"string","description":"Job title."},"email":{"type":"string","description":"Work email."}}},"example":{"department":"quality","title":"QA lead"}}}},"security":[{"oauth2":["hrm:write"]}]}},"/v1/hrm/employees/{id}/terminate":{"post":{"tags":["HRM"],"operationId":"terminateEmployee","summary":"Terminate an employee","description":"Ends employment on the effective date and moves the employee to status terminated.\n\nRequires scope `hrm:write`.","responses":{"201":{"description":"Terminate an employee","content":{"application/json":{"example":{"id":"emp_1a2b","status":"terminated","effective_date":"2026-08-31","updated_at":"2026-07-20T02:14:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Employee id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"effective_date":{"type":"string","description":"Last working day (YYYY-MM-DD)."},"reason":{"type":"string","description":"Reason for termination."}},"required":["effective_date"]},"example":{"effective_date":"2026-08-31","reason":"Resignation"}}}},"security":[{"oauth2":["hrm:write"]}]}},"/v1/hrm/departments":{"get":{"tags":["HRM"],"operationId":"listDepartments","summary":"List departments","description":"Returns the organization's department tree.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"List departments","content":{"application/json":{"example":{"data":[{"code":"production","name":"Production","parent":null,"manager":"emp_1a2b"},{"code":"quality","name":"Quality","parent":"production","manager":null}]}}}}},"security":[{"oauth2":["hrm:read"]}]}},"/v1/hrm/attendance":{"get":{"tags":["HRM"],"operationId":"listAttendance","summary":"List attendance records","description":"Returns clock-in/out records. Filter by employee and date range.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"List attendance records","content":{"application/json":{"example":{"data":[{"id":"att_3c4d","employee_id":"emp_1a2b","date":"2026-07-14","check_in":"08:02","check_out":"17:05","worked_hours":8.05}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"employee_id","in":"query","required":false,"description":"Filter by employee id.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Start date, inclusive (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"End date, inclusive (YYYY-MM-DD).","schema":{"type":"string"}}],"security":[{"oauth2":["hrm:read"]}]},"post":{"tags":["HRM"],"operationId":"createAttendance","summary":"Record attendance","description":"Creates an attendance record for an employee on a given date.\n\nRequires scope `hrm:write`.","responses":{"201":{"description":"Record attendance","content":{"application/json":{"example":{"id":"att_3c4d","employee_id":"emp_1a2b","date":"2026-07-14","created_at":"2026-07-20T02:16:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"Employee id."},"date":{"type":"string","description":"Attendance date (YYYY-MM-DD)."},"check_in":{"type":"string","description":"Clock-in time (HH:mm)."},"check_out":{"type":"string","description":"Clock-out time (HH:mm)."}},"required":["employee_id","date"]},"example":{"employee_id":"emp_1a2b","date":"2026-07-14","check_in":"08:02","check_out":"17:05"}}}},"security":[{"oauth2":["hrm:write"]}]}},"/v1/hrm/leave-requests":{"get":{"tags":["HRM"],"operationId":"listLeaveRequests","summary":"List leave requests","description":"Returns leave requests. Filter by employee or approval status.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"List leave requests","content":{"application/json":{"example":{"data":[{"id":"lve_5f6g","employee_id":"emp_1a2b","type":"annual","from":"2026-08-04","to":"2026-08-08","days":5,"status":"pending","created_at":"2026-07-18T03:10:00Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"employee_id","in":"query","required":false,"description":"Filter by employee id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: pending, approved or rejected.","schema":{"type":"string"}}],"security":[{"oauth2":["hrm:read"]}]},"post":{"tags":["HRM"],"operationId":"createLeaveRequest","summary":"Create a leave request","description":"Submits a leave request for an employee. It starts in status pending.\n\nRequires scope `hrm:write`.","responses":{"201":{"description":"Create a leave request","content":{"application/json":{"example":{"id":"lve_5f6g","employee_id":"emp_1a2b","status":"pending","created_at":"2026-07-20T02:18:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"Employee id."},"type":{"type":"string","description":"Leave type: annual, sick or unpaid."},"from":{"type":"string","description":"First day of leave (YYYY-MM-DD)."},"to":{"type":"string","description":"Last day of leave (YYYY-MM-DD)."}},"required":["employee_id","type","from","to"]},"example":{"employee_id":"emp_1a2b","type":"annual","from":"2026-08-04","to":"2026-08-08"}}}},"security":[{"oauth2":["hrm:write"]}]}},"/v1/hrm/leave-requests/{id}/approvals":{"post":{"tags":["HRM"],"operationId":"approveLeaveRequest","summary":"Approve or reject a leave request","description":"Records an approval decision on a pending leave request.\n\nRequires scope `hrm:write`.","responses":{"201":{"description":"Approve or reject a leave request","content":{"application/json":{"example":{"id":"lve_5f6g","status":"approved","decided_by":"emp_7h8i","decided_at":"2026-07-20T02:20:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Leave request id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","description":"Decision: approve or reject."},"comment":{"type":"string","description":"Optional note recorded with the decision."}},"required":["decision"]},"example":{"decision":"approve","comment":"Coverage arranged."}}}},"security":[{"oauth2":["hrm:write"]}]}},"/v1/hrm/payroll-runs":{"get":{"tags":["HRM"],"operationId":"listPayrollRuns","summary":"List payroll runs","description":"Returns payroll runs. Filter by pay period.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"List payroll runs","content":{"application/json":{"example":{"data":[{"id":"pay_9j0k","period":"2026-06","status":"closed","employee_count":142,"gross_total":{"amount":1842500000,"currency":"VND"},"paid_at":"2026-07-05"}]}}}}},"parameters":[{"name":"period","in":"query","required":false,"description":"Filter by period (YYYY-MM).","schema":{"type":"string"}}],"security":[{"oauth2":["hrm:read"]}]}},"/v1/hrm/payroll-runs/{id}":{"get":{"tags":["HRM"],"operationId":"getPayrollRun","summary":"Retrieve a payroll run","description":"Returns a payroll run with its per-employee payslip lines.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"Retrieve a payroll run","content":{"application/json":{"example":{"id":"pay_9j0k","period":"2026-06","status":"closed","gross_total":{"amount":1842500000,"currency":"VND"},"payslips":[{"employee_id":"emp_1a2b","gross":{"amount":18500000,"currency":"VND"},"net":{"amount":15980000,"currency":"VND"}}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Payroll run id.","schema":{"type":"string"}}],"security":[{"oauth2":["hrm:read"]}]}},"/v1/hrm/positions":{"get":{"tags":["HRM"],"operationId":"listPositions","summary":"List positions","description":"Returns the catalog of job positions and their pay grades.\n\nRequires scope `hrm:read`.","responses":{"200":{"description":"List positions","content":{"application/json":{"example":{"data":[{"code":"line-supervisor","title":"Line supervisor","grade":"G5","department":"production"},{"code":"qa-lead","title":"QA lead","grade":"G6","department":"quality"}]}}}}},"security":[{"oauth2":["hrm:read"]}]}},"/v1/bi/datasets":{"get":{"tags":["BI & Analytics"],"operationId":"listDatasets","summary":"List datasets","description":"Returns a cursor-paginated list of queryable datasets (modelled facts + dimensions). Each dataset exposes the fields you can use as metrics or dimensions.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"List datasets","content":{"application/json":{"example":{"data":[{"id":"ds_sales","name":"Sales orders","module":"crm","fields":[{"name":"order_date","type":"date","role":"dimension"},{"name":"region","type":"string","role":"dimension"},{"name":"channel","type":"string","role":"dimension"},{"name":"revenue","type":"number","role":"metric"},{"name":"quantity","type":"number","role":"metric"}]}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"module","in":"query","required":false,"description":"Filter by source module code, e.g. finance, crm.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/datasets/{id}":{"get":{"tags":["BI & Analytics"],"operationId":"getDataset","summary":"Retrieve a dataset","description":"Returns a single dataset by its id, including the full field list and each field's role.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"Retrieve a dataset","content":{"application/json":{"example":{"id":"ds_sales","name":"Sales orders","module":"crm","grain":"order_line","fields":[{"name":"order_date","type":"date","role":"dimension"},{"name":"region","type":"string","role":"dimension"},{"name":"channel","type":"string","role":"dimension"},{"name":"revenue","type":"number","role":"metric"},{"name":"quantity","type":"number","role":"metric"}],"updated_at":"2026-07-12T04:20:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Dataset id.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/queries":{"post":{"tags":["BI & Analytics"],"operationId":"runQuery","summary":"Run a query","description":"Runs an ad-hoc analytics query against a dataset and returns a columnar result set. Read-only — nothing is persisted.\n\nRequires scope `bi:read`.","responses":{"201":{"description":"Run a query","content":{"application/json":{"example":{"columns":[{"name":"region","type":"string"},{"name":"sum(revenue)","type":"number"}],"rows":[["North",4820000000],["South",3110000000]],"row_count":2,"currency":"VND"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset id to query."},"metrics":{"type":"array","items":{},"description":"Aggregations to compute, e.g. [\"sum(revenue)\", \"count()\"]."},"dimensions":{"type":"array","items":{},"description":"Fields to group by, e.g. [\"region\"]."},"filters":{"type":"object","description":"Field → condition map, e.g. { \"order_date\": { \"gte\": \"2026-01-01\" } }."}},"required":["dataset","metrics"]},"example":{"dataset":"ds_sales","metrics":["sum(revenue)"],"dimensions":["region"],"filters":{"order_date":{"gte":"2026-01-01"}}}}}},"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/kpis":{"get":{"tags":["BI & Analytics"],"operationId":"listKpis","summary":"List KPIs","description":"Returns the configured KPIs with their current value, target and trend.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"List KPIs","content":{"application/json":{"example":{"data":[{"id":"kpi_gross_margin","name":"Gross margin","unit":"percent","value":38.4,"target":40,"trend":"up","period":"2026-07"}]}}}}},"parameters":[{"name":"group","in":"query","required":false,"description":"Filter by KPI group code.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/kpis/{id}":{"get":{"tags":["BI & Analytics"],"operationId":"getKpi","summary":"Retrieve a KPI","description":"Returns a single KPI by its id, including its recent value series.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"Retrieve a KPI","content":{"application/json":{"example":{"id":"kpi_gross_margin","name":"Gross margin","unit":"percent","value":38.4,"target":40,"trend":"up","series":[{"period":"2026-05","value":36.9},{"period":"2026-06","value":37.6},{"period":"2026-07","value":38.4}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"KPI id.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/dashboards":{"get":{"tags":["BI & Analytics"],"operationId":"listDashboards","summary":"List dashboards","description":"Returns a cursor-paginated list of dashboards.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"List dashboards","content":{"application/json":{"example":{"data":[{"id":"dsh_exec","name":"Executive overview","tile_count":6,"updated_at":"2026-07-18T09:00:00Z"}],"has_more":false}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/dashboards/{id}":{"get":{"tags":["BI & Analytics"],"operationId":"getDashboard","summary":"Retrieve a dashboard","description":"Returns a dashboard with its tile layout. Each tile references a KPI or a saved query.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"Retrieve a dashboard","content":{"application/json":{"example":{"id":"dsh_exec","name":"Executive overview","tiles":[{"id":"tl_1","type":"kpi","kpi":"kpi_gross_margin","x":0,"y":0,"w":3,"h":2},{"id":"tl_2","type":"chart","dataset":"ds_sales","metrics":["sum(revenue)"],"dimensions":["region"],"x":3,"y":0,"w":6,"h":4}],"updated_at":"2026-07-18T09:00:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/reports":{"get":{"tags":["BI & Analytics"],"operationId":"listReports","summary":"List reports","description":"Returns the catalog of saved reports and the parameters each one accepts.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"List reports","content":{"application/json":{"example":{"data":[{"id":"rpt_pnl","name":"Profit & loss","params":[{"name":"period","type":"string","required":true},{"name":"cost_center","type":"string","required":false}]}]}}}}},"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/reports/{id}/runs":{"post":{"tags":["BI & Analytics"],"operationId":"runReport","summary":"Run a report","description":"Executes a saved report with the supplied parameters and returns a run. Large reports finish asynchronously — poll the run or subscribe to a webhook.\n\nRequires scope `bi:read`.","responses":{"201":{"description":"Run a report","content":{"application/json":{"example":{"id":"run_5f2a","report":"rpt_pnl","status":"queued","params":{"period":"2026-07","cost_center":"cc_ops"},"requested_at":"2026-07-20T02:10:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Report id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"params":{"type":"object","description":"Parameter map for the report, e.g. { \"period\": \"2026-07\" }."}}},"example":{"params":{"period":"2026-07","cost_center":"cc_ops"}}}}},"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/exports":{"post":{"tags":["BI & Analytics"],"operationId":"createExport","summary":"Create an export","description":"Starts an asynchronous export of a dataset to a downloadable file. The export reads data only; poll it for a download_url.\n\nRequires scope `bi:read`.","responses":{"201":{"description":"Create an export","content":{"application/json":{"example":{"id":"exp_3c8d","dataset":"ds_sales","format":"csv","status":"pending","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset id to export."},"format":{"type":"string","description":"Output format: csv, xlsx or json."},"filters":{"type":"object","description":"Field → condition map applied before export."}},"required":["dataset","format"]},"example":{"dataset":"ds_sales","format":"csv","filters":{"order_date":{"gte":"2026-01-01"}}}}}},"security":[{"oauth2":["bi:read"]}]}},"/v1/bi/exports/{id}":{"get":{"tags":["BI & Analytics"],"operationId":"getExport","summary":"Retrieve an export","description":"Returns the export's status. When status is ready a short-lived download_url is included.\n\nRequires scope `bi:read`.","responses":{"200":{"description":"Retrieve an export","content":{"application/json":{"example":{"id":"exp_3c8d","dataset":"ds_sales","format":"csv","status":"ready","row_count":18402,"download_url":"https://files.apusplatform.com/exports/exp_3c8d.csv?token=…","expires_at":"2026-07-20T03:10:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Export id.","schema":{"type":"string"}}],"security":[{"oauth2":["bi:read"]}]}},"/v1/qms/quality-inspections":{"get":{"tags":["QMS – Quality"],"operationId":"listInspections","summary":"List inspections","description":"Returns a cursor-paginated list of quality inspections. Filter by outcome or by the document inspected.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"List inspections","content":{"application/json":{"example":{"data":[{"id":"qin_1a2b","reference":"GRN-2026-00871","sku":"STEEL-BRKT-08","checked_qty":200,"defect_qty":6,"result":"fail","inspected_by":"usr_4d5e","inspected_at":"2026-07-12T03:55:00Z","updated_at":"2026-07-12T04:20:11Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"result","in":"query","required":false,"description":"Filter by outcome: pass, fail or pending.","schema":{"type":"string"}},{"name":"reference","in":"query","required":false,"description":"Filter by the inspected document, e.g. a GRN or work order.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]},"post":{"tags":["QMS – Quality"],"operationId":"createInspection","summary":"Record an inspection","description":"Records a quality inspection against a document. A fail result can be escalated to a non-conformance.\n\nRequires scope `qms:write`.","responses":{"201":{"description":"Record an inspection","content":{"application/json":{"example":{"id":"qin_1a2b","reference":"GRN-2026-00871","result":"fail","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"Document inspected, e.g. a GRN or work order."},"sku":{"type":"string","description":"Item inspected."},"checked_qty":{"type":"integer","description":"Quantity sampled or inspected."},"defect_qty":{"type":"integer","description":"Quantity found defective (≤ checked_qty)."},"result":{"type":"string","description":"Outcome: pass or fail."}},"required":["reference","sku","checked_qty","defect_qty","result"]},"example":{"reference":"GRN-2026-00871","sku":"STEEL-BRKT-08","checked_qty":200,"defect_qty":6,"result":"fail"}}}},"security":[{"oauth2":["qms:write"]}]}},"/v1/qms/quality-inspections/{id}":{"get":{"tags":["QMS – Quality"],"operationId":"getInspection","summary":"Retrieve an inspection","description":"Returns a single quality inspection by its id, including its measured lines.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"Retrieve an inspection","content":{"application/json":{"example":{"id":"qin_1a2b","reference":"GRN-2026-00871","sku":"STEEL-BRKT-08","checklist_id":"qcl_7h8i","checked_qty":200,"defect_qty":6,"result":"fail","lines":[{"characteristic":"Length (mm)","spec":"8.0 ± 0.1","measured":"8.14","pass":false}],"inspected_by":"usr_4d5e","inspected_at":"2026-07-12T03:55:00Z","updated_at":"2026-07-12T04:20:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Inspection id.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]}},"/v1/qms/non-conformances":{"get":{"tags":["QMS – Quality"],"operationId":"listNonConformances","summary":"List non-conformances","description":"Returns a cursor-paginated list of non-conformance reports (NCRs). Filter by status or severity.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"List non-conformances","content":{"application/json":{"example":{"data":[{"id":"ncr_3c4d","code":"NCR-2026-00042","inspection_id":"qin_1a2b","severity":"major","status":"open","description":"Bracket length out of tolerance on 6 of 200 units.","opened_at":"2026-07-12T04:22:00Z","updated_at":"2026-07-12T04:22:00Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: open or closed.","schema":{"type":"string"}},{"name":"severity","in":"query","required":false,"description":"Filter by severity: minor, major or critical.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]},"post":{"tags":["QMS – Quality"],"operationId":"createNonConformance","summary":"Raise a non-conformance","description":"Raises a non-conformance report (NCR) against a failed inspection.\n\nRequires scope `qms:write`.","responses":{"201":{"description":"Raise a non-conformance","content":{"application/json":{"example":{"id":"ncr_3c4d","code":"NCR-2026-00042","status":"open","created_at":"2026-07-20T02:12:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inspection_id":{"type":"string","description":"Inspection the NCR stems from."},"severity":{"type":"string","description":"Severity: minor, major or critical."},"description":{"type":"string","description":"What is wrong, and where it was found."}},"required":["inspection_id","severity","description"]},"example":{"inspection_id":"qin_1a2b","severity":"major","description":"Bracket length out of tolerance on 6 of 200 units."}}}},"security":[{"oauth2":["qms:write"]}]}},"/v1/qms/non-conformances/{id}":{"get":{"tags":["QMS – Quality"],"operationId":"getNonConformance","summary":"Retrieve a non-conformance","description":"Returns a single non-conformance report (NCR) by its id, including any linked CAPA.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"Retrieve a non-conformance","content":{"application/json":{"example":{"id":"ncr_3c4d","code":"NCR-2026-00042","inspection_id":"qin_1a2b","severity":"major","status":"open","description":"Bracket length out of tolerance on 6 of 200 units.","capa_ids":["capa_5f6g"],"opened_at":"2026-07-12T04:22:00Z","closed_at":null,"updated_at":"2026-07-12T04:22:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Non-conformance id.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]}},"/v1/qms/non-conformances/{id}/close":{"post":{"tags":["QMS – Quality"],"operationId":"closeNonConformance","summary":"Close a non-conformance","description":"Closes a non-conformance report with a resolution note. Fails if it is already closed.\n\nRequires scope `qms:write`.","responses":{"201":{"description":"Close a non-conformance","content":{"application/json":{"example":{"id":"ncr_3c4d","status":"closed","closed_at":"2026-07-20T02:14:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Non-conformance id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","description":"How the non-conformance was dispositioned and resolved."}},"required":["resolution"]},"example":{"resolution":"Defective units returned to supplier; incoming AQL tightened to 0.65."}}}},"security":[{"oauth2":["qms:write"]}]}},"/v1/qms/capa":{"get":{"tags":["QMS – Quality"],"operationId":"listCapa","summary":"List CAPA","description":"Returns a cursor-paginated list of corrective and preventive actions (CAPA). Filter by status.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"List CAPA","content":{"application/json":{"example":{"data":[{"id":"capa_5f6g","code":"CAPA-2026-00019","non_conformance_id":"ncr_3c4d","action":"Re-qualify the stamping die and add a first-article check.","owner_id":"usr_4d5e","status":"open","due_date":"2026-08-05","updated_at":"2026-07-12T05:10:00Z"}],"has_more":true,"next_cursor":"crsr_9a10"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: open, in_progress or done.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]},"post":{"tags":["QMS – Quality"],"operationId":"createCapa","summary":"Open a CAPA","description":"Opens a corrective/preventive action against a non-conformance and assigns an owner.\n\nRequires scope `qms:write`.","responses":{"201":{"description":"Open a CAPA","content":{"application/json":{"example":{"id":"capa_5f6g","code":"CAPA-2026-00019","status":"open","created_at":"2026-07-20T02:16:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"non_conformance_id":{"type":"string","description":"Non-conformance the action addresses."},"action":{"type":"string","description":"Corrective or preventive action to be taken."},"owner_id":{"type":"string","description":"User accountable for completing the action."}},"required":["non_conformance_id","action","owner_id"]},"example":{"non_conformance_id":"ncr_3c4d","action":"Re-qualify the stamping die and add a first-article check.","owner_id":"usr_4d5e"}}}},"security":[{"oauth2":["qms:write"]}]}},"/v1/qms/quality-checklists":{"get":{"tags":["QMS – Quality"],"operationId":"listChecklists","summary":"List checklists","description":"Returns the inspection checklist templates and their characteristics.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"List checklists","content":{"application/json":{"example":{"data":[{"id":"qcl_7h8i","code":"QC-INCOMING-METAL","name":"Incoming metal parts","characteristics":[{"name":"Length (mm)","spec":"8.0 ± 0.1","method":"caliper"},{"name":"Surface finish","spec":"no burrs","method":"visual"}]}]}}}}},"security":[{"oauth2":["qms:read"]}]}},"/v1/qms/quality-checklists/{id}":{"get":{"tags":["QMS – Quality"],"operationId":"getChecklist","summary":"Retrieve a checklist","description":"Returns a single inspection checklist template by its id.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"Retrieve a checklist","content":{"application/json":{"example":{"id":"qcl_7h8i","code":"QC-INCOMING-METAL","name":"Incoming metal parts","characteristics":[{"name":"Length (mm)","spec":"8.0 ± 0.1","method":"caliper"},{"name":"Surface finish","spec":"no burrs","method":"visual"}],"active":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Checklist id.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]}},"/v1/qms/quality-standards":{"get":{"tags":["QMS – Quality"],"operationId":"listStandards","summary":"List standards","description":"Returns the quality standards your organization is certified or working to.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"List standards","content":{"application/json":{"example":{"data":[{"code":"ISO-9001","name":"ISO 9001:2015 Quality management","status":"certified"},{"code":"ISO-14001","name":"ISO 14001:2015 Environmental management","status":"in_progress"}]}}}}},"security":[{"oauth2":["qms:read"]}]}},"/v1/qms/certificates":{"get":{"tags":["QMS – Quality"],"operationId":"listCertificates","summary":"List certificates","description":"Returns quality certificates (e.g. certificates of conformance) issued for items or lots.\n\nRequires scope `qms:read`.","responses":{"200":{"description":"List certificates","content":{"application/json":{"example":{"data":[{"id":"cert_9j0k","number":"COC-2026-00318","sku":"STEEL-BRKT-08","lot":"L-2026-0712","standard":"ISO-9001","issued_at":"2026-07-13T00:00:00Z","valid_until":"2027-07-13T00:00:00Z"}]}}}}},"parameters":[{"name":"sku","in":"query","required":false,"description":"Filter certificates by item.","schema":{"type":"string"}}],"security":[{"oauth2":["qms:read"]}]}},"/v1/eam/assets":{"get":{"tags":["Maintenance (EAM)"],"operationId":"listAssets","summary":"List assets","description":"Returns a cursor-paginated list of assets. Use updated_since for incremental sync.\n\nRequires scope `eam:read`.","responses":{"200":{"description":"List assets","content":{"application/json":{"example":{"data":[{"id":"ast_4a2c","code":"PUMP-042","name":"Coolant pump 042","location":"plant-1/line-a","status":"running","criticality":"high","updated_at":"2026-07-16T08:14:22Z"}],"has_more":true,"next_cursor":"crsr_as21"}}}}},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status: running | idle | maintenance | retired.","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Filter by location code.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"RFC 3339 timestamp; return assets changed after it.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]},"post":{"tags":["Maintenance (EAM)"],"operationId":"createAsset","summary":"Create an asset","description":"Registers a new asset in the equipment register. code must be unique.\n\nRequires scope `eam:write`.","responses":{"201":{"description":"Create an asset","content":{"application/json":{"example":{"id":"ast_4a2c","code":"PUMP-042","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Unique asset code / tag number."},"name":{"type":"string","description":"Display name."},"location":{"type":"string","description":"Location code where the asset is installed."}},"required":["code","name"]},"example":{"code":"PUMP-042","name":"Coolant pump 042","location":"plant-1/line-a"}}}},"security":[{"oauth2":["eam:write"]}]}},"/v1/eam/assets/{id}":{"get":{"tags":["Maintenance (EAM)"],"operationId":"getAsset","summary":"Retrieve an asset","description":"Returns a single asset by its id, or by code (prefix the value with code_).\n\nRequires scope `eam:read`.","responses":{"200":{"description":"Retrieve an asset","content":{"application/json":{"example":{"id":"ast_4a2c","code":"PUMP-042","name":"Coolant pump 042","location":"plant-1/line-a","status":"running","criticality":"high","installed_at":"2023-11-04","updated_at":"2026-07-16T08:14:22Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Asset id.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]},"patch":{"tags":["Maintenance (EAM)"],"operationId":"updateAsset","summary":"Update an asset","description":"Updates mutable fields of an asset. Only supplied fields change.\n\nRequires scope `eam:write`.","responses":{"200":{"description":"Update an asset","content":{"application/json":{"example":{"id":"ast_4a2c","code":"PUMP-042","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Asset id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name."},"location":{"type":"string","description":"Location code where the asset is installed."},"status":{"type":"string","description":"Lifecycle status: running | idle | maintenance | retired."},"criticality":{"type":"string","description":"Criticality rating: low | medium | high."}}},"example":{"status":"maintenance"}}}},"security":[{"oauth2":["eam:write"]}]}},"/v1/eam/maintenance-orders":{"get":{"tags":["Maintenance (EAM)"],"operationId":"listMaintenanceOrders","summary":"List maintenance orders","description":"Returns a cursor-paginated list of maintenance (work) orders, filterable by asset and status.\n\nRequires scope `eam:read`.","responses":{"200":{"description":"List maintenance orders","content":{"application/json":{"example":{"data":[{"id":"mo_8801","number":"WO-2026-8801","asset_id":"ast_4a2c","type":"corrective","status":"open","description":"Seal leak on discharge side.","scheduled_at":"2026-07-22T01:00:00Z","updated_at":"2026-07-18T09:12:04Z"}],"has_more":true,"next_cursor":"crsr_mo44"}}}}},"parameters":[{"name":"asset_id","in":"query","required":false,"description":"Filter by asset.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status: open | scheduled | done.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]},"post":{"tags":["Maintenance (EAM)"],"operationId":"createMaintenanceOrder","summary":"Create a maintenance order","description":"Raises a corrective or preventive maintenance order against an asset.\n\nRequires scope `eam:write`.","responses":{"201":{"description":"Create a maintenance order","content":{"application/json":{"example":{"id":"mo_8802","number":"WO-2026-8802","status":"open","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset the work is performed on."},"type":{"type":"string","description":"Order type: corrective | preventive."},"description":{"type":"string","description":"What needs to be done."},"scheduled_at":{"type":"string","description":"Planned start (RFC 3339)."}},"required":["asset_id","type","description"]},"example":{"asset_id":"ast_4a2c","type":"corrective","description":"Seal leak on discharge side.","scheduled_at":"2026-07-22T01:00:00Z"}}}},"security":[{"oauth2":["eam:write"]}]}},"/v1/eam/maintenance-orders/{id}":{"get":{"tags":["Maintenance (EAM)"],"operationId":"getMaintenanceOrder","summary":"Retrieve a maintenance order","description":"Returns a single maintenance order by its id, including its completion record if closed.\n\nRequires scope `eam:read`.","responses":{"200":{"description":"Retrieve a maintenance order","content":{"application/json":{"example":{"id":"mo_8801","number":"WO-2026-8801","asset_id":"ast_4a2c","type":"corrective","status":"open","description":"Seal leak on discharge side.","scheduled_at":"2026-07-22T01:00:00Z","updated_at":"2026-07-18T09:12:04Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Maintenance order id.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]}},"/v1/eam/maintenance-orders/{id}/completion":{"post":{"tags":["Maintenance (EAM)"],"operationId":"completeMaintenanceOrder","summary":"Complete a maintenance order","description":"Closes a maintenance order, recording labour hours and any spare parts consumed. Consumed parts decrement stock.\n\nRequires scope `eam:write`.","responses":{"201":{"description":"Complete a maintenance order","content":{"application/json":{"example":{"id":"mo_8802","status":"done","completed_at":"2026-07-22T03:30:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Maintenance order id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labor_hours":{"type":"number","description":"Total labour hours spent."},"parts":{"type":"array","items":{},"description":"Parts consumed: [{ sku, quantity }]."}}},"example":{"labor_hours":2.5,"parts":[{"sku":"SEAL-KIT-42","quantity":1}]}}}},"security":[{"oauth2":["eam:write"]}]}},"/v1/eam/assets/{id}/meter-readings":{"get":{"tags":["Maintenance (EAM)"],"operationId":"listMeterReadings","summary":"List meter readings","description":"Returns the recorded meter readings for an asset, newest first.\n\nRequires scope `eam:read`.","responses":{"200":{"description":"List meter readings","content":{"application/json":{"example":{"data":[{"id":"mtr_5501","asset_id":"ast_4a2c","reading":18420,"unit":"hours","recorded_at":"2026-07-19T22:00:00Z"}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Asset id.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]},"post":{"tags":["Maintenance (EAM)"],"operationId":"createMeterReading","summary":"Record a meter reading","description":"Records a meter reading for an asset. Readings can trigger meter-based preventive schedules.\n\nRequires scope `eam:write`.","responses":{"201":{"description":"Record a meter reading","content":{"application/json":{"example":{"id":"mtr_5502","asset_id":"ast_4a2c","reading":18500,"recorded_at":"2026-07-20T02:15:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Asset id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reading":{"type":"number","description":"Meter value."},"unit":{"type":"string","description":"Unit of measure, e.g. hours, km, cycles."}},"required":["reading"]},"example":{"reading":18500,"unit":"hours"}}}},"security":[{"oauth2":["eam:write"]}]}},"/v1/eam/spare-parts":{"get":{"tags":["Maintenance (EAM)"],"operationId":"listSpareParts","summary":"List spare parts","description":"Returns spare parts, optionally filtered to those linked to an asset (its bill of materials).\n\nRequires scope `eam:read`.","responses":{"200":{"description":"List spare parts","content":{"application/json":{"example":{"data":[{"sku":"SEAL-KIT-42","name":"Mechanical seal kit 42mm","on_hand":6,"reorder_point":4,"unit":"pcs"}]}}}}},"parameters":[{"name":"asset_id","in":"query","required":false,"description":"Filter to parts linked to this asset.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]}},"/v1/eam/preventive-schedules":{"get":{"tags":["Maintenance (EAM)"],"operationId":"listPreventiveSchedules","summary":"List preventive schedules","description":"Returns recurring preventive-maintenance schedules, optionally filtered by asset.\n\nRequires scope `eam:read`.","responses":{"200":{"description":"List preventive schedules","content":{"application/json":{"example":{"data":[{"id":"pms_331","asset_id":"ast_4a2c","task":"Inspect and lubricate bearings","interval_days":90,"next_due_at":"2026-09-01","active":true}]}}}}},"parameters":[{"name":"asset_id","in":"query","required":false,"description":"Filter by asset.","schema":{"type":"string"}}],"security":[{"oauth2":["eam:read"]}]},"post":{"tags":["Maintenance (EAM)"],"operationId":"createPreventiveSchedule","summary":"Create a preventive schedule","description":"Creates a recurring preventive-maintenance schedule that auto-generates maintenance orders when due.\n\nRequires scope `eam:write`.","responses":{"201":{"description":"Create a preventive schedule","content":{"application/json":{"example":{"id":"pms_332","asset_id":"ast_4a2c","interval_days":90,"next_due_at":"2026-10-18","created_at":"2026-07-20T02:20:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset the schedule applies to."},"interval_days":{"type":"integer","description":"Recurrence interval in days."},"task":{"type":"string","description":"Task to perform each cycle."}},"required":["asset_id","interval_days","task"]},"example":{"asset_id":"ast_4a2c","interval_days":90,"task":"Inspect and lubricate bearings"}}}},"security":[{"oauth2":["eam:write"]}]}},"/v1/edm/documents":{"get":{"tags":["EDM – Documents"],"operationId":"listEdmDocuments","summary":"List documents","description":"Returns a cursor-paginated list of documents. Use updated_since for incremental sync.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"List documents","content":{"application/json":{"example":{"data":[{"id":"doc_7f21","name":"Supply agreement 2026.pdf","folder_id":"fld_contracts","reference":"supplier:sup_44a1","status":"approved","version":3,"mime_type":"application/pdf","size":284116,"updated_at":"2026-07-14T09:05:22Z"}],"has_more":true,"next_cursor":"crsr_2b70"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"RFC 3339 timestamp; return items changed after it.","schema":{"type":"string"}},{"name":"folder_id","in":"query","required":false,"description":"Filter by folder id.","schema":{"type":"string"}},{"name":"reference","in":"query","required":false,"description":"Filter by linked business object, e.g. order:so_1a2b.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]},"post":{"tags":["EDM – Documents"],"operationId":"createDocument","summary":"Create a document","description":"Registers a document and returns an upload_url. PUT the file bytes to upload_url to attach the first version.\n\nRequires scope `edm:write`.","responses":{"201":{"description":"Create a document","content":{"application/json":{"example":{"id":"doc_7f21","name":"Supply agreement 2026.pdf","folder_id":"fld_contracts","status":"draft","version":0,"upload_url":"https://files.apusplatform.com/upload/doc_7f21?token=…","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"File name, e.g. Supply agreement 2026.pdf."},"folder_id":{"type":"string","description":"Destination folder id."},"reference":{"type":"string","description":"Linked business object, e.g. order:so_1a2b."}},"required":["name","folder_id"]},"example":{"name":"Supply agreement 2026.pdf","folder_id":"fld_contracts","reference":"supplier:sup_44a1"}}}},"security":[{"oauth2":["edm:write"]}]}},"/v1/edm/documents/{id}":{"get":{"tags":["EDM – Documents"],"operationId":"getDocument","summary":"Retrieve a document","description":"Returns a single document by its id, including a short-lived download_url for the current version.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"Retrieve a document","content":{"application/json":{"example":{"id":"doc_7f21","name":"Supply agreement 2026.pdf","folder_id":"fld_contracts","reference":"supplier:sup_44a1","status":"approved","version":3,"mime_type":"application/pdf","size":284116,"download_url":"https://files.apusplatform.com/doc_7f21?token=…","updated_at":"2026-07-14T09:05:22Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]},"patch":{"tags":["EDM – Documents"],"operationId":"updateDocument","summary":"Update a document","description":"Updates mutable fields of a document. Only supplied fields change.\n\nRequires scope `edm:write`.","responses":{"200":{"description":"Update a document","content":{"application/json":{"example":{"id":"doc_7f21","folder_id":"fld_archive","updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"File name."},"folder_id":{"type":"string","description":"Move the document to another folder."},"reference":{"type":"string","description":"Linked business object."}}},"example":{"folder_id":"fld_archive"}}}},"security":[{"oauth2":["edm:write"]}]},"delete":{"tags":["EDM – Documents"],"operationId":"deleteDocument","summary":"Delete a document","description":"Moves a document to the recycle bin (soft delete). Its versions and audit trail are retained.\n\nRequires scope `edm:write`.","responses":{"204":{"description":"Delete a document"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:write"]}]}},"/v1/edm/folders":{"get":{"tags":["EDM – Documents"],"operationId":"listFolders","summary":"List folders","description":"Returns folders, optionally scoped to the children of a parent. Omit parent for the top level.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"List folders","content":{"application/json":{"example":{"data":[{"id":"fld_contracts","name":"Contracts","parent":"fld_root","doc_count":128},{"id":"fld_drawings","name":"Engineering drawings","parent":"fld_root","doc_count":512}]}}}}},"parameters":[{"name":"parent","in":"query","required":false,"description":"Parent folder id; omit for root folders.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]},"post":{"tags":["EDM – Documents"],"operationId":"createFolder","summary":"Create a folder","description":"Creates a folder, optionally nested under a parent.\n\nRequires scope `edm:write`.","responses":{"201":{"description":"Create a folder","content":{"application/json":{"example":{"id":"fld_certs","name":"Quality certificates","parent":"fld_root","created_at":"2026-07-20T02:14:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name."},"parent":{"type":"string","description":"Parent folder id; omit for a root folder."}},"required":["name"]},"example":{"name":"Quality certificates","parent":"fld_root"}}}},"security":[{"oauth2":["edm:write"]}]}},"/v1/edm/folders/{id}":{"get":{"tags":["EDM – Documents"],"operationId":"getFolder","summary":"Retrieve a folder","description":"Returns a single folder by its id.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"Retrieve a folder","content":{"application/json":{"example":{"id":"fld_contracts","name":"Contracts","parent":"fld_root","doc_count":128,"created_at":"2026-01-08T03:40:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Folder id.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]}},"/v1/edm/documents/{id}/approvals":{"post":{"tags":["EDM – Documents"],"operationId":"createApproval","summary":"Record an approval decision","description":"Records the current approver's decision on a document. Approving the final step sets the document status to approved.\n\nRequires scope `edm:write`.","responses":{"201":{"description":"Record an approval decision","content":{"application/json":{"example":{"id":"apr_31c8","document_id":"doc_7f21","decision":"approve","actor":"usr_9a10","document_status":"approved","created_at":"2026-07-20T02:16:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","description":"One of approve, reject."},"comment":{"type":"string","description":"Reviewer note, shown in the audit trail."}},"required":["decision"]},"example":{"decision":"approve","comment":"Terms match the negotiated draft."}}}},"security":[{"oauth2":["edm:write"]}]},"get":{"tags":["EDM – Documents"],"operationId":"listApprovals","summary":"List approvals","description":"Returns the approval history for a document in chronological order.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"List approvals","content":{"application/json":{"example":{"data":[{"id":"apr_2b71","step":1,"decision":"approve","actor":"usr_4c22","created_at":"2026-07-19T08:30:00Z"},{"id":"apr_31c8","step":2,"decision":"approve","actor":"usr_9a10","created_at":"2026-07-20T02:16:00Z"}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]}},"/v1/edm/documents/{id}/versions":{"get":{"tags":["EDM – Documents"],"operationId":"listVersions","summary":"List versions","description":"Returns the version history for a document, newest first. Each version carries its own download_url.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"List versions","content":{"application/json":{"example":{"data":[{"version":3,"size":284116,"author":"usr_9a10","download_url":"https://files.apusplatform.com/doc_7f21/v3?token=…","created_at":"2026-07-14T09:05:22Z"},{"version":2,"size":281044,"author":"usr_4c22","download_url":"https://files.apusplatform.com/doc_7f21/v2?token=…","created_at":"2026-06-30T11:20:00Z"}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]}},"/v1/edm/documents/search":{"get":{"tags":["EDM – Documents"],"operationId":"searchDocuments","summary":"Search documents","description":"Full-text search across document names and extracted content. Optionally scope the search to one folder.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"Search documents","content":{"application/json":{"example":{"data":[{"id":"doc_7f21","name":"Supply agreement 2026.pdf","folder_id":"fld_contracts","score":0.92,"highlight":"…annual <em>supply agreement</em> renewal…"}],"has_more":false}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query.","schema":{"type":"string"}},{"name":"folder_id","in":"query","required":false,"description":"Restrict results to this folder.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]}},"/v1/edm/documents/{id}/permissions":{"get":{"tags":["EDM – Documents"],"operationId":"listPermissions","summary":"List permissions","description":"Returns the access-control entries granted on a document, resolved from direct grants and inherited folder rules.\n\nRequires scope `edm:read`.","responses":{"200":{"description":"List permissions","content":{"application/json":{"example":{"data":[{"principal":"group:legal","role":"editor","inherited_from":"fld_contracts"},{"principal":"usr_9a10","role":"approver","inherited_from":null}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Document id.","schema":{"type":"string"}}],"security":[{"oauth2":["edm:read"]}]}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","summary":"List webhooks","description":"Returns a cursor-paginated list of the webhook endpoints registered for your account.\n\nRequires scope `webhooks:read`.","responses":{"200":{"description":"List webhooks","content":{"application/json":{"example":{"data":[{"id":"whk_5f3a","url":"https://example.com/hooks/apus","events":["sales_order.created","invoice.paid"],"active":true,"created_at":"2026-07-14T09:02:11Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"Filter by active status.","schema":{"type":"boolean"}}],"security":[{"oauth2":["webhooks:read"]}]},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Create a webhook","description":"Registers a webhook endpoint. The response includes the signing_secret — store it now; it is shown only once.\n\nRequires scope `webhooks:write`.","responses":{"201":{"description":"Create a webhook","content":{"application/json":{"example":{"id":"whk_5f3a","url":"https://example.com/hooks/apus","events":["sales_order.created","invoice.paid"],"active":true,"signing_secret":"whsec_7Hk2pQ8sR4vN1mB6xL0dYt9","created_at":"2026-07-20T02:10:00Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint Apus POSTs signed payloads to."},"events":{"type":"array","items":{},"description":"Event types to subscribe to, e.g. [\"invoice.paid\"]."},"active":{"type":"boolean","description":"Whether to start delivering immediately (default true)."}},"required":["url","events"]},"example":{"url":"https://example.com/hooks/apus","events":["sales_order.created","invoice.paid"]}}}},"security":[{"oauth2":["webhooks:write"]}]}},"/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"operationId":"getWebhook","summary":"Retrieve a webhook","description":"Returns a single webhook endpoint by its id. The signing_secret is never returned again after creation.\n\nRequires scope `webhooks:read`.","responses":{"200":{"description":"Retrieve a webhook","content":{"application/json":{"example":{"id":"whk_5f3a","url":"https://example.com/hooks/apus","events":["sales_order.created","invoice.paid"],"active":true,"created_at":"2026-07-14T09:02:11Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"security":[{"oauth2":["webhooks:read"]}]},"patch":{"tags":["Webhooks"],"operationId":"updateWebhook","summary":"Update a webhook","description":"Updates mutable fields of a webhook. Only supplied fields change. Set active:false to pause delivery without deleting.\n\nRequires scope `webhooks:write`.","responses":{"200":{"description":"Update a webhook","content":{"application/json":{"example":{"id":"whk_5f3a","url":"https://example.com/hooks/apus","events":["sales_order.created","invoice.paid","inventory.changed"],"active":true,"updated_at":"2026-07-20T02:12:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint Apus POSTs signed payloads to."},"events":{"type":"array","items":{},"description":"Replacement list of subscribed event types."},"active":{"type":"boolean","description":"Pause (false) or resume (true) delivery."}}},"example":{"events":["sales_order.created","invoice.paid","inventory.changed"]}}}},"security":[{"oauth2":["webhooks:write"]}]},"delete":{"tags":["Webhooks"],"operationId":"deleteWebhook","summary":"Delete a webhook","description":"Deletes a webhook endpoint. Delivery stops immediately and the signing_secret is revoked.\n\nRequires scope `webhooks:write`.","responses":{"204":{"description":"Delete a webhook"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"security":[{"oauth2":["webhooks:write"]}]}},"/v1/webhooks/webhook-events":{"get":{"tags":["Webhooks"],"operationId":"listEventTypes","summary":"List event types","description":"Returns the catalog of event types you can subscribe a webhook to, grouped by module.\n\nRequires scope `webhooks:read`.","responses":{"200":{"description":"List event types","content":{"application/json":{"example":{"data":[{"type":"product.updated","module":"products","desc":"A product's master data changed."},{"type":"inventory.changed","module":"inventory","desc":"On-hand quantity moved at a location."},{"type":"sales_order.created","module":"sales","desc":"A sales order was placed."},{"type":"production_order.completed","module":"manufacturing","desc":"A production order finished."},{"type":"invoice.paid","module":"finance","desc":"An invoice was fully settled."}]}}}}},"security":[{"oauth2":["webhooks:read"]}]}},"/v1/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"operationId":"testWebhook","summary":"Send a test event","description":"Sends a sample event to the endpoint so you can verify signature checking and connectivity. Returns the delivery it created.\n\nRequires scope `webhooks:write`.","responses":{"201":{"description":"Send a test event","content":{"application/json":{"example":{"id":"whd_2c9e","webhook_id":"whk_5f3a","event":"invoice.paid","status":"delivered","response_code":200,"created_at":"2026-07-20T02:14:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","description":"Event type to simulate (default invoice.paid)."}}},"example":{"event":"invoice.paid"}}}},"security":[{"oauth2":["webhooks:write"]}]}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"operationId":"listWebhookDeliveries","summary":"List deliveries","description":"Returns a cursor-paginated log of delivery attempts for a webhook. Use status to find failures worth retrying.\n\nRequires scope `webhooks:read`.","responses":{"200":{"description":"List deliveries","content":{"application/json":{"example":{"data":[{"id":"whd_2c9e","event":"invoice.paid","status":"failed","response_code":500,"attempts":3,"created_at":"2026-07-19T18:40:02Z"}],"has_more":false,"next_cursor":null}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by delivery status: delivered, failed, pending.","schema":{"type":"string"}}],"security":[{"oauth2":["webhooks:read"]}]}},"/v1/webhooks/webhook-deliveries/{id}":{"get":{"tags":["Webhooks"],"operationId":"getDelivery","summary":"Retrieve a delivery","description":"Returns a single delivery attempt, including the signed payload sent and the endpoint's response.\n\nRequires scope `webhooks:read`.","responses":{"200":{"description":"Retrieve a delivery","content":{"application/json":{"example":{"id":"whd_2c9e","webhook_id":"whk_5f3a","event":"invoice.paid","status":"failed","response_code":500,"attempts":3,"signature":"sha256=9f2a1c...","payload":{"id":"inv_8a12","event":"invoice.paid","amount":{"amount":4500000,"currency":"VND"}},"created_at":"2026-07-19T18:40:02Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Delivery id.","schema":{"type":"string"}}],"security":[{"oauth2":["webhooks:read"]}]}},"/v1/webhooks/webhook-deliveries/{id}/retry":{"post":{"tags":["Webhooks"],"operationId":"retryDelivery","summary":"Retry a delivery","description":"Re-sends a failed or pending delivery immediately with the same signed payload. Returns the new attempt.\n\nRequires scope `webhooks:write`.","responses":{"201":{"description":"Retry a delivery","content":{"application/json":{"example":{"id":"whd_2c9e","webhook_id":"whk_5f3a","event":"invoice.paid","status":"delivered","response_code":200,"attempts":4,"created_at":"2026-07-20T02:16:00Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Delivery id.","schema":{"type":"string"}}],"security":[{"oauth2":["webhooks:write"]}]}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client-credentials. Exchange client_id/client_secret for a bearer token.","flows":{"clientCredentials":{"tokenUrl":"https://api.apusplatform.com/v1/oauth/token","scopes":{"bi:read":"Read analytics","crm:read":"Read CRM quotations, leads and opportunities","crm:write":"Write CRM leads","dms:read":"Read distribution","dms:write":"Write distribution","eam:read":"Read maintenance","eam:write":"Write maintenance","edm:read":"Read documents","edm:write":"Write documents","finance:read":"Read finance","finance:write":"Write finance","hrm:read":"Read HR","hrm:write":"Write HR","inventory:read":"Read inventory","inventory:write":"Write inventory","mes:read":"Read production","mes:write":"Write production","orders:read":"Read sales orders","orders:write":"Write sales orders","partners:read":"Read partners","partners:write":"Write partners","products:read":"Read products","products:write":"Write products","purchasing:read":"Read purchase orders","purchasing:write":"Write purchase orders","qms:read":"Read quality","qms:write":"Write quality","webhooks:read":"Read webhooks","webhooks:write":"Write webhooks"}}}}}}}