{"openapi":"3.1.0","info":{"title":"Voltrus ERP API","version":"0.1.0","x-voltrus-spec-version":"1"},"servers":[{"url":"/"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"security":[{"bearer":[]}],"paths":{"/api/whoami":{"get":{"operationId":"whoami.get","summary":"Show who is calling: actor, token kind, role, company, time zone and today","tags":["whoami"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"role is agent, ops or admin. For an agent, agent_changes explains that governed writes become proposals.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/meta/entities":{"get":{"operationId":"meta.entities.list","summary":"List every entity with its writable fields, line fields, enums and id kind","tags":["meta"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"The registry behind the generic create and edit forms. Read it before creating or proposing a record of an entity you have not used.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/entities/{entity}":{"get":{"operationId":"entities.records.list","summary":"Search records of an entity by text and field filters","tags":["entities"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"q matches searchable fields case-insensitively; any other query parameter named after a field of the entity is an exact filter (numbers and true/false are converted). Unknown parameters are ignored. Pages: has_more and next_offset tell whether to ask again with offset. Entity names and their fields: GET /api/meta/entities.","x-voltrus-idempotent":true,"x-voltrus-paged":true,"x-voltrus-example":{"params":{"entity":"customer","q":"logam","limit":"20"}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring over the searchable fields","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, at most 200)","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Rows to skip; use next_offset from the previous page","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sort","in":"query","required":false,"description":"A field to sort by, \"-field\" for descending; newest first when absent","schema":{"type":"string"}},{"name":"with_total","in":"query","required":false,"description":"1 to also return total: the rows matched across every page","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"entities.records.create","summary":"Create a record directly","tags":["entities"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only and refused while the trial or subscription is read-only. Agents propose the same change with POST /api/proposals (op create). Entity names and their fields: GET /api/meta/entities.","x-voltrus-example":{"params":{"entity":"customer"},"body":{"name":"PT Satu","npwp":"0123456789012345"}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The record's fields; document entities take a lines array. Entity names and their fields: GET /api/meta/entities.","additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/entities/{entity}/{id}":{"get":{"operationId":"entities.records.get","summary":"Fetch one record with all its fields and lines","tags":["entities"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"entity":"item","id":"RM-BOLT"}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"entities.records.update","summary":"Update fields of a record directly","tags":["entities"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only. Send only the fields that change. Pass expected_updated_at to refuse the write (409) when someone changed the record since you read it. Agents propose with op update. Entity names and their fields: GET /api/meta/entities.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"entity":"item","id":"RM-BOLT"},"body":{"reorder_point":900}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}},{"name":"expected_updated_at","in":"query","required":false,"description":"Optimistic lock: the updated_at you read; a newer row gets 409","schema":{"type":"string","format":"date-time"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The fields to change. Entity names and their fields: GET /api/meta/entities.","additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"entities.records.delete","summary":"Delete a record (soft delete)","tags":["entities"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only. Refused for entities that are never deleted generically (posted documents, ledgers) and for records already in use.","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/entities/{entity}/{id}/transition":{"post":{"operationId":"entities.records.transition","summary":"Move a record through its state machine (confirm, receive, ship, issue...)","tags":["entities"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only; runs the side effects (stock movements, journals, delivery orders). to is the target status or action; payload carries action input such as receipt lines or a ship quantity. Only entities with a state machine; GL periods and journals have their own routes. Agents propose with op transition.","x-voltrus-example":{"params":{"entity":"sales_order","id":"SO-2026-0001"},"body":{"to":"confirmed"}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Target status or action, e.g. confirmed, receive, ship, issued"},"payload":{"type":"object","description":"Action input, e.g. {lines:[...]} for a receipt","additionalProperties":true}},"required":["to"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/{sku}":{"get":{"operationId":"stock.item.get","summary":"Show on-hand stock, value and recent movements of one item","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"sku":"RM-BOLT"}},"parameters":[{"name":"sku","in":"path","required":true,"description":"Item SKU","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/by-warehouse":{"get":{"operationId":"stock.by_warehouse.list","summary":"List on-hand quantities per item and warehouse","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"warehouse","in":"query","required":false,"description":"Only this warehouse id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/by-bin":{"get":{"operationId":"stock.by_bin.list","summary":"List on-hand quantities per item, warehouse and bin","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"item","in":"query","required":false,"description":"Only this item SKU","schema":{"type":"string"}},{"name":"warehouse","in":"query","required":false,"description":"Only this warehouse id","schema":{"type":"string"}},{"name":"bin","in":"query","required":false,"description":"Only this bin id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/below-reorder":{"get":{"operationId":"stock.below_reorder.list","summary":"List items whose stock is below their reorder point","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/lots":{"get":{"operationId":"stock.lots.list","summary":"List the lots of an item with quantities, expiry and the FEFO pick","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"item","in":"query","required":true,"description":"Item SKU","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/recall":{"get":{"operationId":"stock.recall.get","summary":"Trace a lot: where it came from and every customer it shipped to","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"lot","in":"query","required":true,"description":"Lot number","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/serials":{"get":{"operationId":"stock.serials.list","summary":"List the serial numbers of an item and where each one is","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"item","in":"query","required":true,"description":"Item SKU","schema":{"type":"string"}},{"name":"warehouse","in":"query","required":false,"description":"Only this warehouse id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/serial-trace":{"get":{"operationId":"stock.serial_trace.get","summary":"Trace one serial number through every movement","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"serial","in":"query","required":true,"description":"Serial number","schema":{"type":"string"}},{"name":"item","in":"query","required":false,"description":"Item SKU, when the same serial exists on several items","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/movements":{"post":{"operationId":"stock.movements.create","summary":"Record a manual stock adjustment or scrap","tags":["stock"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only. Manual movements are adjust or scrap; receipts, issues, shipments and transfers come from their documents. qty is signed (negative takes stock out). A serial movement moves exactly one unit. Posts the matching inventory journal; a reason_code sends its non-inventory side to the code's account (variance otherwise), and an in-only code refuses a negative qty (and the reverse).","x-voltrus-example":{"body":{"item_sku":"RM-BOLT","qty":-12,"reason":"scrap","reason_code":"DAMAGE"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_sku":{"type":"string"},"qty":{"type":"number","description":"Signed quantity: positive adds, negative removes"},"reason":{"type":"string","enum":["adjust","scrap"]},"reason_code":{"type":"string","description":"Adjustment reason code (GET /api/inventory/reason-codes); its GL account takes the other side. Required when require_adjust_reason is on"},"warehouse_id":{"type":"string","description":"Default MAIN"},"bin_id":{"type":"string"},"lot_no":{"type":"string"},"expiry_date":{"type":"string","format":"date"},"serial_no":{"type":"string"}},"required":["item_sku","qty","reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/cost-layers":{"get":{"operationId":"stock.cost_layers.list","summary":"List an item's FIFO cost layers, oldest first","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Open layers (all=1 includes used-up ones) per warehouse with received date, source, remaining qty, unit cost and value, plus the totals and their average. Layers exist under costing_method fifo.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"item_sku":"RM-BOLT"}},"parameters":[{"name":"item_sku","in":"query","required":true,"description":"Item","schema":{"type":"string"}},{"name":"warehouse_id","in":"query","required":false,"description":"One warehouse only","schema":{"type":"string"}},{"name":"all","in":"query","required":false,"description":"1 to include used-up layers","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/movements/{id}/cost":{"get":{"operationId":"stock.movements.cost","summary":"Show what a stock movement was valued at and which layers it used","tags":["stock"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"posted_unit_cost and posted_value (any costing method), the FIFO layers it consumed and the layers it opened.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/stock/cost-adjustments":{"post":{"operationId":"stock.cost_adjustments.create","summary":"Add landed cost or a price correction to a receipt after the fact","tags":["stock"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"FIFO only. Spreads an IDR amount over the layers a purchase order's receipts of the item opened: the share still in stock changes those layers' unit cost (Dr/Cr inventory), the share already consumed goes to COGS, the other side to GRNI (default), AP or variance. Negative amounts lower the cost.","x-voltrus-example":{"body":{"purchase_order_id":"PO-ID","item_sku":"RM-BOLT","amount":150000,"kind":"landed_cost"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purchase_order_id":{"type":"string"},"item_sku":{"type":"string"},"amount":{"type":"number","description":"IDR; negative lowers the cost"},"kind":{"type":"string","enum":["landed_cost","price_correction"]},"offset":{"type":"string","enum":["grni","ap","variance"],"default":"grni"},"note":{"type":"string"}},"required":["purchase_order_id","item_sku","amount"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/records/{entity}/{id}/comments":{"get":{"operationId":"records.comments.list","summary":"List a record's discussion","tags":["records"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"records.comments.create","summary":"Post a comment on a record","tags":["records","comments"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Mention people with @username or @email; mentioned people are notified. Refused while the tenant is read-only.","x-voltrus-example":{"params":{"entity":"sales_order","id":"SO-2026-0001"},"body":{"body":"@dewi customer asked to ship Friday"}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Comment text (Markdown, @mentions)"}},"required":["body"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/records/{entity}/{id}/activities":{"get":{"operationId":"records.activities.list","summary":"List a record's follow-up activities","tags":["records","activities"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"records.activities.create","summary":"Plan a follow-up activity on a record","tags":["records","activities"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"An assignee other than you is notified.","x-voltrus-example":{"params":{"entity":"invoice","id":"INV-2026-0042"},"body":{"summary":"Call about overdue payment","kind":"call","due_date":"2026-12-01","assignee":"dewi"}},"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"},"kind":{"type":"string","enum":["todo","call","meeting","follow_up"],"default":"todo"},"due_date":{"type":"string","format":"date"},"assignee":{"type":"string","description":"Username or email, with or without @"}},"required":["summary"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/records/{entity}/{id}/links":{"get":{"operationId":"records.links.get","summary":"List the documents linked to a record (orders, receipts, invoices, payments...)","tags":["records"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/records/{entity}/{id}/next-actions":{"get":{"operationId":"records.next_actions.list","summary":"List the next steps available on a record (invoice it, ship it, make a work order...)","tags":["records"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/records/{entity}/{id}/next-actions/{action}":{"post":{"operationId":"records.next_actions.run","summary":"Run a next step on a record","tags":["records"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"OPS callers run it directly unless propose is true; an agent token always gets a proposal for an approver (the response says mode: executed or proposed). Credit control or bill matching may also turn it into a proposal.","parameters":[{"name":"entity","in":"path","required":true,"description":"Entity name, e.g. item, customer, sales_order (see /api/meta/entities)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}},{"name":"action","in":"path","required":true,"description":"Action name from GET .../next-actions","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rationale":{"type":"string","description":"Why: shown to the approver when it becomes a proposal"},"payload":{"type":"object","description":"Action input","additionalProperties":true},"propose":{"type":"boolean","description":"Make a proposal even when you could run it"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/comments/{id}":{"patch":{"operationId":"comments.update","summary":"Edit your own comment shortly after posting it","tags":["comments"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Only the author, and only within the edit window; after that, add a new comment.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Comment id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"}},"required":["body"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"comments.delete","summary":"Delete a comment","tags":["comments"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"The author or an OPS user.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Comment id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/activities":{"get":{"operationId":"activities.list","summary":"List follow-up activities across all records","tags":["activities"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-paged":true,"x-voltrus-example":{"params":{"assignee":"me","status":"open"}},"parameters":[{"name":"assignee","in":"query","required":false,"description":"\"me\" for the caller, a username, or omit for everyone","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"open, done or cancelled","schema":{"type":"string","enum":["open","done","cancelled"]}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, at most 200)","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/activities/{id}":{"patch":{"operationId":"activities.close","summary":"Mark an open activity done or cancelled","tags":["activities"],"x-voltrus-role":"any","x-voltrus-agent":"agent","parameters":[{"name":"id","in":"path","required":true,"description":"Activity id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","cancelled"]}},"required":["status"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/history":{"get":{"operationId":"history.list","summary":"List the audit trail, newest first","tags":["history"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Every call and change, filtered to one entity or one record.","x-voltrus-idempotent":true,"x-voltrus-paged":true,"parameters":[{"name":"entity","in":"query","required":false,"description":"Only this entity","schema":{"type":"string"}},{"name":"id","in":"query","required":false,"description":"Only this record id (with entity)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, at most 500)","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","required":false,"description":"Rows to skip; use next_offset from the previous page","schema":{"type":"integer","minimum":0,"default":0}},{"name":"with_total","in":"query","required":false,"description":"1 to also return total: the rows matched across every page","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/proposals":{"get":{"operationId":"proposals.list","summary":"List proposals in the approval inbox, oldest first","tags":["proposals"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-paged":true,"parameters":[{"name":"status","in":"query","required":false,"description":"Default pending","schema":{"type":"string","enum":["pending","approved","rejected","applied","failed"]}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, at most 200)","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Rows to skip; use next_offset from the previous page","schema":{"type":"integer","minimum":0,"default":0}},{"name":"with_total","in":"query","required":false,"description":"1 to also return total: the rows matched across every page","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"proposals.create","summary":"Propose a create, update or transition for an approver to decide","tags":["proposals"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"The agent path for every record change. The change is validated now (a transition is dry-run) and applied only when an OPS user approves it. rationale is shown to the approver. Entity names and their fields: GET /api/meta/entities.","x-voltrus-example":{"body":{"entity":"item","op":"update","id":"RM-BOLT","changes":{"reorder_point":900},"rationale":"Usage doubled over the last 90 days"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"string"},"op":{"type":"string","enum":["create","update","transition"]},"id":{"type":"string","description":"Record id (update and transition)"},"changes":{"type":"object","description":"Fields for create/update; {to, payload?} for transition","additionalProperties":true},"rationale":{"type":"string","description":"Why, for the approver"},"model":{"type":"string","description":"The AI model proposing, for the audit trail"}},"required":["entity","op","changes","rationale"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/proposals/{id}/approve":{"post":{"operationId":"proposals.approve","summary":"Approve a pending proposal and apply it","tags":["proposals"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only. Re-validates against the current state and applies it in one batch; a failure leaves the proposal failed with the reason.","parameters":[{"name":"id","in":"path","required":true,"description":"Proposal id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Decision note"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/proposals/{id}/reject":{"post":{"operationId":"proposals.reject","summary":"Reject a pending proposal with a reason","tags":["proposals"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Proposal id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/execute":{"post":{"operationId":"execute.apply","summary":"Apply a create or update directly, without a proposal","tags":["execute"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS escape hatch; audited. Transitions go through /api/entities/{entity}/{id}/transition.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"string"},"op":{"type":"string","enum":["create","update"]},"id":{"type":"string","description":"Record id (update)"},"changes":{"type":"object","additionalProperties":true}},"required":["entity","op","changes"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/export":{"get":{"operationId":"export.tenant.get","summary":"Download every business record of the company as one JSON bundle","tags":["export"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/notifications":{"get":{"operationId":"notifications.list","summary":"List notifications and the unread count","tags":["notifications"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"unread","in":"query","required":false,"description":"1 for unread only","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/notifications/read-all":{"post":{"operationId":"notifications.read_all","summary":"Mark every notification read for yourself","tags":["notifications"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Read state is per person: others keep their own unread tray. Answers how many were marked.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/notifications/sweep":{"post":{"operationId":"notifications.sweep","summary":"Raise notifications for overdue invoices and low stock","tags":["notifications"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Skips ones already notified and not yet read by anyone, so running it daily is safe. OPS only.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/notifications/{id}":{"post":{"operationId":"notifications.read","summary":"Mark one notification read for yourself","tags":["notifications"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Read state is per person. An unknown id is 404.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Notification id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/me/push-devices":{"post":{"operationId":"me.push_devices.register","summary":"Register your phone for push notifications from the Voltrus app","tags":["notifications"],"x-voltrus-role":"any","x-voltrus-agent":"denied","description":"Signed-in people only (an app or console session). A pending proposal is pushed to the phones of the people who can decide it. Registering the same token again moves it to you and refreshes it.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","platform"],"properties":{"token":{"type":"string","description":"Expo push token: ExponentPushToken[…]"},"platform":{"type":"string","enum":["ios","android"],"description":"Phone platform"},"lang":{"type":"string","enum":["id","en"],"description":"Language of the notification text (default id)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"me.push_devices.remove","summary":"Stop push notifications to one of your phones","tags":["notifications"],"x-voltrus-role":"any","x-voltrus-agent":"denied","description":"The app calls it on sign-out. Only removes a token registered to you.","x-voltrus-idempotent":true,"parameters":[{"name":"token","in":"query","required":true,"description":"The Expo push token to remove","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/users":{"get":{"operationId":"users.list","summary":"List the people who use the company","tags":["users"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"users.create","summary":"Add a person","tags":["users"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Refused when the plan's user limit is reached or the email is taken.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string","enum":["admin","ops","viewer"],"default":"viewer"}},"required":["email"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/users/{id}":{"patch":{"operationId":"users.update","summary":"Change a person's role or deactivate them","tags":["users"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"User id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["admin","ops","viewer"]},"active":{"type":"boolean","description":"false deactivates"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tokens":{"get":{"operationId":"tokens.list","summary":"List API tokens (never their secrets)","tags":["tokens"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"tokens.create","summary":"Issue an API token for an agent or an OPS integration","tags":["tokens"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"The secret is returned once, in this response only.","x-voltrus-example":{"body":{"name":"claude-laptop","kind":"agent"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["agent","ops"]}},"required":["name","kind"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tokens/{id}":{"delete":{"operationId":"tokens.revoke","summary":"Revoke an API token","tags":["tokens"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Token id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/oauth/connections":{"get":{"operationId":"oauth.connections.list","summary":"List chat apps connected through OAuth (ChatGPT, Claude and others)","tags":["tokens"],"x-voltrus-role":"admin","x-voltrus-agent":"read","description":"One row per connection: the app, the person who allowed it, and when.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/oauth/connections/{id}":{"delete":{"operationId":"oauth.connections.revoke","summary":"Disconnect a chat app connected through OAuth","tags":["tokens"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Revokes every token of the connection at once; the app has to be connected again.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Connection (grant) id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/onboarding/import":{"post":{"operationId":"onboarding.import.run","summary":"Import items, suppliers, customers, opening stock or open invoices and bills from CSV","tags":["onboarding"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS only. csv is the raw text with its header row; the result lists created, skipped and refused rows. stock and open_invoices / open_bills (number, customer or supplier, issue_date, due_date, currency, fx_rate, amount_open) load with no journal: the opening balance books them once, so open documents are refused after it is posted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["items","suppliers","customers","stock","open_invoices","open_bills"]},"csv":{"type":"string","description":"CSV text including the header row"}},"required":["kind","csv"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/onboarding/epicor":{"post":{"operationId":"onboarding.epicor.run","summary":"Seed master data from an Epicor Kinetic company","tags":["onboarding"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Admin only. Run with dryRun true first to see what would be imported.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseUrl":{"type":"string","format":"uri"},"token":{"type":"string"},"apiKey":{"type":"string"},"companyId":{"type":"string"},"dryRun":{"type":"boolean"}},"required":["baseUrl","token","companyId"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/plan":{"get":{"operationId":"plan.get","summary":"Show the plan, its limits, usage and trial or subscription state","tags":["plan"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/billing":{"get":{"operationId":"billing.overview.get","summary":"Show the subscription, upcoming charge and payment methods","tags":["billing"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/billing/invoices":{"get":{"operationId":"billing.invoices.list","summary":"List subscription invoices","tags":["billing"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"billing.invoices.issue","summary":"Issue the subscription invoice for a period","tags":["billing"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Returns the existing invoice (200) when the period is already invoiced.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/billing/invoices/{id}/mark-paid":{"post":{"operationId":"billing.invoices.mark_paid","summary":"Record payment of a subscription invoice and extend the plan","tags":["billing"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","parameters":[{"name":"id","in":"path","required":true,"description":"Billing invoice id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"paid_at":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/billing/subscription/cancel":{"post":{"operationId":"billing.subscription.cancel","summary":"Cancel the subscription","tags":["billing"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/integrations/kaseer/sales":{"post":{"operationId":"integrations.kaseer.sales.post","summary":"Post sales from a Kaseer POS store","tags":["integrations"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Kaseer Cloud forwards finished sales here (at most 25 per request). Each sale is booked to the store's walk-in customer (kaseer-<store id>): lines whose SKU is an item become a sales order, confirmed and shipped (stock out, cost of goods); the whole receipt becomes an issued invoice dated on the sale's business day, at prices before tax with the receipt's tax as tax_percent; each tender becomes a payment through accounts[method] (a GL asset account), else cash. A loyalty tender with no account stays open on the invoice. Idempotent by sale id: a posted sale answers duplicate, a failed one carries on where it stopped. Always 200, with a status per sale (posted, duplicate, failed + error). IDR only.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["store","sales"],"properties":{"store":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"warehouse_id":{"type":"string","description":"Warehouse the item lines ship from; empty = the main warehouse"},"accounts":{"type":"object","description":"Tender method (cash, card, qris, transfer, loyalty) → GL asset account (code or id); unmapped methods go to cash","additionalProperties":{"type":"string"}},"sales":{"type":"array","items":{"type":"object","description":"Kaseer sale: id, number, at, currency, lines[{sku, name, qty, netMinor, taxMinor}], tenders[{method, appliedMinor}], netMinor, taxMinor, totalMinor","additionalProperties":true}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"get":{"operationId":"integrations.kaseer.sales.list","summary":"List sales received from Kaseer and how each was posted","tags":["integrations"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"status","in":"query","required":false,"description":"pending, posted or failed","schema":{"type":"string","enum":["pending","posted","failed"]}},{"name":"store","in":"query","required":false,"description":"Kaseer store id","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, at most 500)","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/webhooks":{"get":{"operationId":"webhooks.list","summary":"List webhook endpoints","tags":["webhooks"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"webhooks.create","summary":"Add a webhook endpoint for events","tags":["webhooks"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Deliveries are signed with the secret (generated when omitted, returned once) and retried with backoff.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["proposal.decided","stock.below_reorder","entity.changed","maintenance.overdue","maintenance.escalated","billing.invoice_issued","billing.payment_received","billing.subscription_past_due","workorder.released"]}},"secret":{"type":"string"}},"required":["url","events"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/webhooks/deliveries":{"get":{"operationId":"webhooks.deliveries.list","summary":"List webhook deliveries and their retry state","tags":["webhooks"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-paged":true,"parameters":[{"name":"status","in":"query","required":false,"description":"pending, delivered or failed","schema":{"type":"string","enum":["pending","delivered","failed"]}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, at most 200)","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/webhooks/{id}":{"delete":{"operationId":"webhooks.delete","summary":"Remove a webhook endpoint","tags":["webhooks"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Deliveries already queued still go out.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/webhooks/{id}/test":{"post":{"operationId":"webhooks.test","summary":"Send a test event to a webhook endpoint","tags":["webhooks"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/accounts":{"get":{"operationId":"gl.accounts.list","summary":"List the chart of accounts","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"gl.accounts.create","summary":"Add an account to the chart of accounts","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Refused (409) when the code exists.","x-voltrus-example":{"body":{"code":"6-1150","name":"Biaya admin bank","type":"expense"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Account code, e.g. 1-1100"},"name":{"type":"string"},"type":{"type":"string","enum":["asset","liability","equity","revenue","expense"]},"currency":{"type":"string","description":"3-letter ISO code, e.g. IDR or USD","default":"IDR"},"tax_code_id":{"type":["string","null"],"description":"gl_tax_code id"},"active":{"type":"boolean"},"parent_id":{"type":["string","null"],"description":"Header account this one sits under"},"is_header":{"type":"boolean","description":"A header groups accounts and takes no postings"},"statement_section":{"type":["string","null"],"enum":["current_assets","fixed_assets","other_assets","current_liabilities","long_term_liabilities","equity","revenue","cogs","operating_expenses","other","income_tax"],"description":"Null: derived from code and type"},"cash_flow_class":{"type":["string","null"],"enum":["cash","operating","adjustment","investing","financing"],"description":"Where the account lands on the cash-flow statement"}},"required":["code","name","type"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/accounts/{id}":{"patch":{"operationId":"gl.accounts.update","summary":"Change an account","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Only the fields sent change. 404 for an unknown account, 409 for a code already taken.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Account id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Account code, e.g. 1-1100"},"name":{"type":"string"},"type":{"type":"string","enum":["asset","liability","equity","revenue","expense"]},"currency":{"type":"string","description":"3-letter ISO code, e.g. IDR or USD","default":"IDR"},"tax_code_id":{"type":["string","null"],"description":"gl_tax_code id"},"active":{"type":"boolean"},"parent_id":{"type":["string","null"],"description":"Header account this one sits under"},"is_header":{"type":"boolean","description":"A header groups accounts and takes no postings"},"statement_section":{"type":["string","null"],"enum":["current_assets","fixed_assets","other_assets","current_liabilities","long_term_liabilities","equity","revenue","cogs","operating_expenses","other","income_tax"],"description":"Null: derived from code and type"},"cash_flow_class":{"type":["string","null"],"enum":["cash","operating","adjustment","investing","financing"],"description":"Where the account lands on the cash-flow statement"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"gl.accounts.delete","summary":"Delete an account","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Refused (409) while accounts sit under a header or postings use it.","parameters":[{"name":"id","in":"path","required":true,"description":"Account id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/accounts/seed-structure":{"post":{"operationId":"gl.accounts.seed_structure","summary":"Add the standard header accounts and file accounts under them","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Creates missing header accounts and assigns parents and statement sections by code.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/tax-codes":{"get":{"operationId":"gl.tax_codes.list","summary":"List tax codes","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"gl.tax_codes.create","summary":"Add a tax code","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Refused (409) when the code exists.","x-voltrus-example":{"body":{"code":"PPN11","name":"PPN 11%","percent":11,"kind":"output"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"1-20 characters"},"name":{"type":"string","description":"1-120 characters"},"percent":{"type":"number","minimum":0,"maximum":100},"kind":{"type":"string","enum":["output","input","exempt","non"]},"active":{"type":"boolean"}},"required":["code","name","percent","kind"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/tax-codes/{id}":{"patch":{"operationId":"gl.tax_codes.update","summary":"Change a tax code","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Tax code id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"1-20 characters"},"name":{"type":"string","description":"1-120 characters"},"percent":{"type":"number","minimum":0,"maximum":100},"kind":{"type":"string","enum":["output","input","exempt","non"]},"active":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"gl.tax_codes.delete","summary":"Delete a tax code","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Tax code id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/periods":{"get":{"operationId":"gl.periods.list","summary":"List accounting periods and whether each is open, closed or locked","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/periods/close":{"post":{"operationId":"gl.periods.close","summary":"Close an accounting month to new postings","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Postings dated in a closed month are refused afterwards.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"year":2026,"month":10}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer","minimum":1,"maximum":12}},"required":["year","month"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/periods/reopen":{"post":{"operationId":"gl.periods.reopen","summary":"Reopen a closed accounting month","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Refused (404) for a month that was never closed.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer","minimum":1,"maximum":12}},"required":["year","month"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/journals":{"get":{"operationId":"gl.journals.list","summary":"List journals, newest first","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-paged":true,"parameters":[{"name":"kind","in":"query","required":false,"description":"Journal kind","schema":{"type":"string","enum":["po_receipt","so_shipment","wo_consume","wo_produce","inventory_adjust","invoice_issue","payment","credit_note","fx_settlement","manual"]}},{"name":"status","in":"query","required":false,"description":"Journal status","schema":{"type":"string","enum":["draft","posted","voided"]}},{"name":"period_id","in":"query","required":false,"description":"Accounting period id","schema":{"type":"string"}},{"name":"source_type","in":"query","required":false,"description":"Document type that posted it, e.g. invoice, payment, manual_entry","schema":{"type":"string"}},{"name":"source_id","in":"query","required":false,"description":"Id of that document","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Entry date on or after (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Entry date on or before (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (1-200, default 50)","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Rows to skip; use next_offset from the previous page","schema":{"type":"integer","minimum":0,"default":0}},{"name":"with_total","in":"query","required":false,"description":"1 to also return total: the journals matched across every page","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"gl.journals.create","summary":"Draft a manual journal entry","tags":["gl"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"A draft counts nowhere until an admin posts it.","x-voltrus-low-risk":true,"x-voltrus-example":{"body":{"entry_date":"2026-11-30","memo":"Biaya admin bank","lines":[{"account_code":"6-1100","debit":25000},{"account_key":"cash","credit":25000}]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entry_date":{"type":"string","format":"date","description":"Journal date (YYYY-MM-DD); default today in the company zone"},"memo":{"type":"string"},"reference":{"type":"string"},"lines":{"type":"array","items":{"type":"object","description":"One of account_id, account_code or account_key names the account; debit or credit, not both","properties":{"account_id":{"type":"string"},"account_code":{"type":"string","description":"e.g. 6-1100"},"account_key":{"type":"string","description":"Mapping key, e.g. cash, tax_payable"},"debit":{"type":"number","minimum":0},"credit":{"type":"number","minimum":0},"description":{"type":"string"},"party_type":{"type":"string","enum":["customer","supplier"]},"party_id":{"type":"string"},"cost_center_id":{"type":"string"},"project_id":{"type":"string"}}},"description":"At least two lines; must balance to post"}},"required":["lines"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/journals/{id}":{"get":{"operationId":"gl.journals.get","summary":"Show one journal with its lines","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Journal id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"gl.journals.update","summary":"Change a draft manual journal","tags":["gl"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Only drafts change (409 once posted); journals that documents post are read-only.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Journal id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entry_date":{"type":"string","format":"date","description":"Journal date (YYYY-MM-DD); default today in the company zone"},"memo":{"type":"string"},"reference":{"type":"string"},"lines":{"type":"array","items":{"type":"object","description":"One of account_id, account_code or account_key names the account; debit or credit, not both","properties":{"account_id":{"type":"string"},"account_code":{"type":"string","description":"e.g. 6-1100"},"account_key":{"type":"string","description":"Mapping key, e.g. cash, tax_payable"},"debit":{"type":"number","minimum":0},"credit":{"type":"number","minimum":0},"description":{"type":"string"},"party_type":{"type":"string","enum":["customer","supplier"]},"party_id":{"type":"string"},"cost_center_id":{"type":"string"},"project_id":{"type":"string"}}},"description":"At least two lines; must balance to post"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"gl.journals.delete","summary":"Delete a draft manual journal","tags":["gl"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Only drafts (409 once posted).","parameters":[{"name":"id","in":"path","required":true,"description":"Journal id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/journals/{id}/post":{"post":{"operationId":"gl.journals.post","summary":"Post a draft manual journal to the ledger","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"It must balance, have two lines or more, use active accounts and fall in an open period; it gets its JM/YYYY/MM/NNNN number. Never edited afterwards.","parameters":[{"name":"id","in":"path","required":true,"description":"Journal id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/journals/{id}/reverse":{"post":{"operationId":"gl.journals.reverse","summary":"Reverse a posted manual journal","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Posts its mirror image on the date given, once (409 when already reversed).","parameters":[{"name":"id","in":"path","required":true,"description":"Journal id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Reversal date (YYYY-MM-DD)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/opening-balance":{"get":{"operationId":"gl.opening_balance.preview","summary":"Preview the opening balance journal at a cutover date","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Worked out from records without journals: open invoices and bills, unbilled shipments, goods received not invoiced, stock, work in process, customer advances.","x-voltrus-idempotent":true,"parameters":[{"name":"date","in":"query","required":false,"description":"Cutover date (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"gl.opening_balance.preview_with_lines","summary":"Preview the opening balance with your own lines added","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Changes nothing: the same preview as the GET, with lines for bank, assets, loans and capital.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"YYYY-MM-DD"},"lines":{"type":"array","description":"Lines the system cannot know (bank and cash, fixed assets, loans, capital); the difference goes to opening equity","items":{"type":"object","properties":{"account_code":{"type":"string"},"account_key":{"type":"string"},"debit":{"type":"number","minimum":0},"credit":{"type":"number","minimum":0},"description":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/opening-balance/post":{"post":{"operationId":"gl.opening_balance.post","summary":"Post the opening balance journal","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Once per company (source_type opening_balance); the difference goes to opening equity (3-9000). Afterwards reports stop deriving legacy entries.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"YYYY-MM-DD"},"lines":{"type":"array","description":"Lines the system cannot know (bank and cash, fixed assets, loans, capital); the difference goes to opening equity","items":{"type":"object","properties":{"account_code":{"type":"string"},"account_key":{"type":"string"},"debit":{"type":"number","minimum":0},"credit":{"type":"number","minimum":0},"description":{"type":"string"}}}}},"required":["date"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/fx-revaluation":{"get":{"operationId":"gl.fx_revaluation.preview","summary":"Preview the month-end revaluation of foreign-currency balances","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Open foreign-currency invoices, bills and bank accounts restated at the month-end rate.","x-voltrus-idempotent":true,"parameters":[{"name":"date","in":"query","required":false,"description":"Month-end date (YYYY-MM-DD); default the last month end","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"gl.fx_revaluation.run","summary":"Post the month-end FX revaluation and its reversal","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Unrealised gain or loss to fx_gain_loss, reversed on the first of the next month. Once per month: running it again returns the posted one.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Month-end date (YYYY-MM-DD); default the last month end"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/year-end-close":{"get":{"operationId":"gl.year_end_close.status","summary":"Show whether a year is closed and preview its closing journal","tags":["gl"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year; default last year","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"gl.year_end_close.close","summary":"Close a fiscal year","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Posts the closing journal (profit or loss to retained earnings) and locks the year's periods. Running it again returns the closed year.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"}},"required":["year"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/gl/year-end-close/reopen":{"post":{"operationId":"gl.year_end_close.reopen","summary":"Reopen a closed fiscal year","tags":["gl"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Reverses the closing journal and unlocks the periods. 404 when the year is not closed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"}},"required":["year"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/exchange-rates/fetch":{"post":{"operationId":"fx.rates.fetch","summary":"Fetch the BI JISDOR and Kurs Pajak rates for today now","tags":["fx"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Stores the official transaction and tax rates whatever the automatic-rates setting is. Adds rates only; posts nothing.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/exchange-rates/lookup":{"get":{"operationId":"fx.rates.lookup","summary":"Look up the exchange rate on or before a date","tags":["fx"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"404 when no rate exists on or before the date.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"currency":"USD","date":"2026-11-20"}},"parameters":[{"name":"currency","in":"query","required":true,"description":"Currency to convert from, e.g. USD","schema":{"type":"string","description":"3-letter ISO code, e.g. IDR or USD"}},{"name":"date","in":"query","required":false,"description":"Date (YYYY-MM-DD); default today","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"type","in":"query","required":false,"description":"Transaction rate (BI JISDOR) or tax rate (Kurs Pajak)","schema":{"type":"string","enum":["transaction","tax"],"default":"transaction"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/pricing/quote":{"get":{"operationId":"pricing.quote","summary":"Work out the price a customer pays or a supplier charges for an item","tags":["pricing"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Pass customer or supplier. Applies price lists, quantity breaks, unit conversion and currency.","x-voltrus-idempotent":true,"parameters":[{"name":"item","in":"query","required":true,"description":"Item SKU","schema":{"type":"string"}},{"name":"customer","in":"query","required":false,"description":"Customer id (selling price)","schema":{"type":"string"}},{"name":"supplier","in":"query","required":false,"description":"Supplier id (buying price)","schema":{"type":"string"}},{"name":"qty","in":"query","required":false,"description":"Quantity","schema":{"type":"number"}},{"name":"uom","in":"query","required":false,"description":"Unit of measure","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Price date (YYYY-MM-DD); default today","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"currency","in":"query","required":false,"description":"Currency of the price","schema":{"type":"string","description":"3-letter ISO code, e.g. IDR or USD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/pricing/compare":{"get":{"operationId":"pricing.compare","summary":"Compare suppliers' quotes for an item","tags":["pricing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"item","in":"query","required":true,"description":"Item SKU","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Date (YYYY-MM-DD); default today","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/batches":{"post":{"operationId":"payments.batches.create","summary":"Record one payment that settles several invoices of one party","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Writes one payment row per invoice (RCP/ or PAY/ number) and posts each settlement journal: cash against AR or AP at the batch rate, realised FX against the booking rate of each invoice, PPh 23 withheld to prepaid PPh 23. Refused (400) for an invoice that is not open, of another party or currency, or over its open amount.","x-voltrus-example":{"body":{"direction":"receivable","party_id":"CUST-1","paid_at":"2026-11-20","allocations":[{"invoice_id":"INV-1","amount":5450000,"withholding_amount":100000}]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"type":"string","enum":["receivable","payable"],"description":"receivable: a customer receipt; payable: a supplier payment"},"party_type":{"type":"string","enum":["customer","supplier"]},"party_id":{"type":"string"},"currency":{"type":"string","description":"3-letter ISO code, e.g. IDR or USD"},"fx_rate":{"type":"number","description":"IDR per unit; default the transaction rate on paid_at"},"amount":{"type":"number","minimum":0,"description":"Must equal the allocations sum when given"},"paid_at":{"type":"string","format":"date","description":"Default today"},"reference":{"type":"string"},"bank_account_id":{"type":"string","description":"GL bank account; default the cash account"},"allocations":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount":{"type":"number","minimum":0,"description":"In the invoice's currency"},"withholding_amount":{"type":"number","minimum":0,"description":"PPh 23 the customer withheld from this invoice"},"withholding_slip_no":{"type":"string","description":"Bukti potong number"}},"required":["invoice_id","amount"]}}},"required":["direction","party_id","allocations"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"get":{"operationId":"payments.batches.list","summary":"List payment batches","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"party_id","in":"query","required":false,"description":"Customer or supplier id","schema":{"type":"string"}},{"name":"run_id","in":"query","required":false,"description":"Payment run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/batches/{id}":{"get":{"operationId":"payments.batches.get","summary":"Show one payment batch with its payments","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Batch id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/open-invoices":{"get":{"operationId":"payments.open_invoices.list","summary":"List a party's open invoices or bills with what is still owed","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"direction","in":"query","required":false,"description":"receivable: customer invoices; payable: supplier bills","schema":{"type":"string","enum":["receivable","payable"],"default":"receivable"}},{"name":"party_id","in":"query","required":true,"description":"Customer or supplier id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/run-proposal":{"get":{"operationId":"payments.runs.proposal","summary":"List supplier bills due by a date for a payment run","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"due_by","in":"query","required":false,"description":"Due on or before (YYYY-MM-DD); default today","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"supplier_id","in":"query","required":false,"description":"Comma-separated supplier ids to include","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/runs":{"post":{"operationId":"payments.runs.create","summary":"Pay selected supplier bills in one run","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"One payment batch per supplier and currency, sharing a run id; each posts its settlement journal. Export the bank bulk-transfer file afterwards.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paid_at":{"type":"string","format":"date","description":"Default today"},"bank_account_id":{"type":"string"},"fx_rates":{"type":"object","additionalProperties":{"type":"number"},"description":"IDR per unit by currency; missing ones take the transaction rate on paid_at"},"bills":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount":{"type":"number","minimum":0}},"required":["invoice_id"]}}},"required":["bills"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"get":{"operationId":"payments.runs.list","summary":"List payment runs","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/runs/{id}/export.csv":{"get":{"operationId":"payments.runs.export_csv","summary":"Download a payment run's bank bulk-transfer CSV","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Payment run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account":{"post":{"operationId":"payments.on_account.create","summary":"Record customer money received before it is matched to invoices","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Numbered OA/YYYY/MM/NNNN. Posts Dr bank / Cr unapplied receipts (2-1250) at the receipt rate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"amount":{"type":"number","minimum":0},"currency":{"type":"string","description":"3-letter ISO code, e.g. IDR or USD","default":"IDR"},"fx_rate":{"type":"number","description":"Default the transaction rate on received_at"},"received_at":{"type":"string","format":"date","description":"Default today"},"reference":{"type":"string"},"bank_account_id":{"type":"string"},"notes":{"type":"string"}},"required":["customer_id","amount"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"get":{"operationId":"payments.on_account.list","summary":"List money held on account with what is left on each","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"customer_id","in":"query","required":false,"description":"Customer id","schema":{"type":"string"}},{"name":"open","in":"query","required":false,"description":"1: only receipts not reversed with something left","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account/{id}":{"get":{"operationId":"payments.on_account.get","summary":"Show a receipt on account with its applications and refunds","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Receipt id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account/{id}/apply":{"post":{"operationId":"payments.on_account.apply","summary":"Settle invoices from money held on account","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Posts Dr unapplied receipts / Cr AR per invoice, realised FX against the invoice rate. 409 for a reversed receipt; 400 when allocations exceed what is left.","parameters":[{"name":"id","in":"path","required":true,"description":"Receipt id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allocations":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount":{"type":"number","minimum":0,"description":"In the invoice's currency"}},"required":["invoice_id","amount"]}},"applied_at":{"type":"string","format":"date","description":"Default today"}},"required":["allocations"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account/{id}/unapply":{"post":{"operationId":"payments.on_account.unapply","summary":"Undo applications of money on account, reopening the invoices","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Each undo posts Dr AR / Cr unapplied receipts at the original rates.","parameters":[{"name":"id","in":"path","required":true,"description":"Receipt id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_ids":{"type":"array","items":{"type":"string"},"description":"Applications to undo; default all"},"date":{"type":"string","format":"date","description":"Default today"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account/{id}/refund":{"post":{"operationId":"payments.on_account.refund","summary":"Pay money left on account back to the customer","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Numbered OAR/YYYY/MM/NNNN. Posts Dr unapplied receipts at the receipt rate / Cr bank at the refund rate, the difference to FX gain/loss. 400 above what is left; 409 for a reversed receipt.","parameters":[{"name":"id","in":"path","required":true,"description":"Receipt id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Default everything left"},"refunded_at":{"type":"string","format":"date","description":"Default today"},"fx_rate":{"type":"number"},"bank_account_id":{"type":"string"},"reference":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account/{id}/reverse":{"post":{"operationId":"payments.on_account.reverse","summary":"Reverse a receipt on account recorded in error","tags":["payments"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Posts the mirror of its journal; a statement line posted to it is open to post again. 409 while anything is applied from it or a refund stands.","parameters":[{"name":"id","in":"path","required":true,"description":"Receipt id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Default today"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/on-account/refunds/{refund_id}/reverse":{"post":{"operationId":"payments.on_account.refund_reverse","summary":"Reverse a refund of money on account recorded in error","tags":["payments"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Posts the mirror of the refund's journal at its own rates; the amount is on account again. 409 when already reversed or a statement line is posted to it.","parameters":[{"name":"refund_id","in":"path","required":true,"description":"Refund id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Default today"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/import":{"post":{"operationId":"bank.statements.import","summary":"Import a bank statement and auto-match its lines","tags":["bank"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"CSV (date,amount,reference,description) or MT940 text. Lines start unmatched; auto-match runs after. Posts nothing.","x-voltrus-low-risk":true,"x-voltrus-example":{"body":{"stmt_ref":"BCA-2026-11","body":"date,amount,reference,description\n2026-11-20,5450000,TRF123,PT Gaya Logam"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stmt_ref":{"type":"string","description":"Statement reference, e.g. BCA-2026-11"},"body":{"type":"string","description":"CSV or MT940 text"}},"required":["stmt_ref","body"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/match":{"post":{"operationId":"bank.transactions.match","summary":"Auto-match unmatched statement lines to open invoices","tags":["bank"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Proposes matches (single invoices, PPh 23 short-pays, several invoices of one customer); posts nothing.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/transactions":{"get":{"operationId":"bank.transactions.list","summary":"List statement lines, newest first (up to 500)","tags":["bank"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"status","in":"query","required":false,"description":"Line status","schema":{"type":"string","enum":["unmatched","matched","cleared","ignored"]}},{"name":"feed_id","in":"query","required":false,"description":"Only lines from this bank feed","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/feeds":{"get":{"operationId":"bank.feeds.list","summary":"List bank feeds (push from a mutation service, or a SNAP BI pull) and their last sync","tags":["bank"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Credentials are never returned. A push feed shows push_path, the URL its sender POSTs to.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"bank.feeds.create","summary":"Connect a bank feed (admin)","tags":["bank"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"push: a mutation service (Moota, mutasibank, ...) or middleware POSTs signed transactions to /api/bank/feeds/{id}/push; the signing secret is answered once. snap_bca: Voltrus pulls BCA SNAP BI bank statements with the company's own API credentials (checked by asking for an access token). Credentials are stored encrypted (SECRETS_KEY).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["push","snap_bca"]},"name":{"type":"string","description":"e.g. BCA operasional"},"bank_account_id":{"type":"string","description":"GL bank account (asset) the lines belong to"},"account_number":{"type":"string","description":"Bank account number; push lines for other numbers are skipped; required for snap_bca"},"source":{"type":"string","description":"push: moota, mutasibank, other"},"secret":{"type":"string","description":"push: a signing secret of your own (default generated)"},"client_key":{"type":"string"},"client_secret":{"type":"string"},"private_key":{"type":"string","description":"snap_bca: RSA private key, PKCS#8 PEM"},"partner_id":{"type":"string"},"channel_id":{"type":"string","default":"95051"},"base_url":{"type":"string","description":"snap_bca: https://sandbox.bca.co.id, BCA production, or a fixed-IP relay"},"interval_minutes":{"type":"integer","minimum":15,"default":60}},"required":["provider","name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/feeds/{id}":{"get":{"operationId":"bank.feeds.get","summary":"One bank feed","tags":["bank"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Bank feed id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"bank.feeds.update","summary":"Rename, pause or resume a bank feed, or change its GL bank account (admin)","tags":["bank"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Bank feed id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"bank_account_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"bank.feeds.delete","summary":"Disconnect a bank feed and erase its credentials (admin); its lines stay","tags":["bank"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","parameters":[{"name":"id","in":"path","required":true,"description":"Bank feed id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/feeds/{id}/sync":{"post":{"operationId":"bank.feeds.sync","summary":"Pull a SNAP feed now (\"Sync now\"), then auto-match","tags":["bank"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"From the day before its last line up to today (at most 30 days back), deduplicated. A failure marks the feed error and tells ops.","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Bank feed id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/transactions/{id}":{"patch":{"operationId":"bank.transactions.update","summary":"Set a statement line's status or match it to an invoice by hand","tags":["bank"],"x-voltrus-role":"any","x-voltrus-agent":"governed","description":"Clears the match proposed by auto-match. 409 for a line already posted as a receipt.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Statement line id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["unmatched","matched","cleared","ignored"]},"matched_invoice_id":{"type":"string","description":"Required for status matched"}},"required":["status"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/bank/transactions/{id}/post":{"post":{"operationId":"bank.transactions.post","summary":"Post a statement line: receipt, on account, payout, supplier payment or bank charge","tags":["bank"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Incoming. invoices: settles the matched invoices (less any PPh 23 withheld) at the rate of the line date; on_account: holds the money for the customer; payout: settles what a rail (Apple, Google Play, Polar, DOKU, ...) owes for its RevKlik sales, the fee true-up to platform fees and the rest to FX gain/loss. transfer: Dr bank / Cr account_id, money from another own account such as a DOKU settlement. Outgoing. reconcile: ties the line to a supplier payment already booked (payment_batch_id, default the matched one); bills: pays the matched or given bills as one supplier payment; expense: Dr account_id / Cr bank (bank charges). The default is what the matcher found. Clears the line. 400 for lines already cleared or ignored. The bank account defaults to the one of the line's feed.","parameters":[{"name":"id","in":"path","required":true,"description":"Statement line id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["invoices","on_account","payout","transfer","reconcile","bills","expense"]},"payment_batch_id":{"type":"string","description":"reconcile: the supplier payment; default the matched one"},"account_id":{"type":"string","description":"expense: the GL account spent on (bank charges); transfer: the account the money came from (DOKU clearing)"},"memo":{"type":"string","description":"expense: journal memo; default the line description"},"rail":{"type":"string","description":"payout: the rail; default the one the matcher found"},"event_ids":{"type":"array","items":{"type":"string"},"description":"payout: the revenue events it covers; default every open event of the rail up to the line date"},"up_to":{"type":"string","format":"date","description":"payout: last business date it covers"},"fee_adjustment":{"type":"number","description":"payout in another currency than the sales: IDR of the difference that is fees"},"customer_id":{"type":"string","description":"on_account: the customer; default the matched one"},"allocations":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount":{"type":"number","minimum":0,"description":"In the invoice's currency"},"withholding_amount":{"type":"number","minimum":0,"description":"PPh 23 the customer withheld from this invoice"},"withholding_slip_no":{"type":"string","description":"Bukti potong number"}},"required":["invoice_id","amount"]}},"withholding_amount":{"type":"number","minimum":0,"description":"A line matched by hand to one invoice: the PPh 23 withheld"},"bank_account_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/invoicing/from-sales-order/{id}":{"post":{"operationId":"invoicing.from_sales_order.create","summary":"Draft an invoice for chosen lines of a sales order","tags":["invoicing"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Quantities may not exceed what is still uninvoiced; unbilled order charges and any down payment deduction ride on it. Only confirmed or shipped orders (400 otherwise). The invoice posts nothing until issued.","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Sales order id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"item_sku":{"type":"string"},"qty":{"type":"number"},"unit_price":{"type":"number"}},"required":["item_sku","qty"]}}},"required":["lines"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/overview":{"get":{"operationId":"reports.overview","summary":"Show dashboard totals: stock value, open orders, receivables and activity","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/finance":{"get":{"operationId":"reports.finance","summary":"Show stock valuation, open-document aging and account totals","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/balance-sheet":{"get":{"operationId":"reports.balance_sheet","summary":"Show the balance sheet (Neraca) with comparatives","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"date","in":"query","required":false,"description":"As of (YYYY-MM-DD); default today","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/income-statement":{"get":{"operationId":"reports.income_statement","summary":"Show the income statement (Laba Rugi) with comparatives","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/cash-flow":{"get":{"operationId":"reports.cash_flow","summary":"Show the cash-flow statement (indirect method)","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/month-end":{"get":{"operationId":"reports.month_end","summary":"Show the month-end close checklist","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"month","in":"query","required":false,"description":"Month (YYYY-MM); default the current month","schema":{"type":"string","description":"YYYY-MM"}},{"name":"grni_days","in":"query","required":false,"description":"Days after which goods received not invoiced is flagged","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/trial-balance":{"get":{"operationId":"reports.trial_balance","summary":"Show the trial balance from posted journals","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/trial-balance/accounts":{"get":{"operationId":"reports.trial_balance_accounts","summary":"Show the trial balance per account with opening and closing balances","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Balances are debit-positive. from defaults to the first of the month of to; to defaults to today. Rows carry their nearest header account.","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/finance/pl-by-cost-center":{"get":{"operationId":"finance.pl_by_cost_center","summary":"Show revenue, expense and net per cost centre","tags":["finance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/finance/pl-by-project":{"get":{"operationId":"finance.pl_by_project","summary":"Show revenue, expense and net per project","tags":["finance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"project","in":"query","required":false,"description":"One project id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/finance/account-totals":{"get":{"operationId":"finance.account_totals","summary":"Show account totals, optionally for a cost centre","tags":["finance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"cost_center","in":"query","required":false,"description":"Cost centre id","schema":{"type":"string"}},{"name":"children","in":"query","required":false,"description":"0: only that cost centre, not the ones under it","schema":{"type":"string","enum":["0","1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/finance/budget-vs-actual":{"get":{"operationId":"finance.budget_vs_actual","summary":"Compare a budget with actual postings","tags":["finance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"budget","in":"query","required":true,"description":"Budget id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/finance/mapping":{"get":{"operationId":"finance.mapping.get","summary":"Show which GL account each ledger key posts to","tags":["finance"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"finance.mapping.set","summary":"Change which GL account ledger keys post to","tags":["finance"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Send {key: account code} for the keys to change; 400 for an unknown key or empty account. Affects every later posting.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"cash":"1-1100"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"description":"Ledger key → account code, e.g. {\"cash\": \"1-1100\"}"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/export/finance":{"get":{"operationId":"finance.export","summary":"Export journal entries as CSV for an accounting package","tags":["finance"],"x-voltrus-role":"admin","x-voltrus-agent":"read","description":"Returns JSON with the CSV in \"csv\". A run_id makes re-runs observable (duplicate: true with the same payload hash).","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"format","in":"query","required":false,"description":"Target package","schema":{"type":"string","enum":["generic","jurnal","kledo","accurate"],"default":"generic"}},{"name":"locale","in":"query","required":false,"description":"Column names: vendor (as the package names them) or id (Indonesian)","schema":{"type":"string","enum":["vendor","id"],"default":"vendor"}},{"name":"run_id","in":"query","required":false,"description":"Client-chosen id for this export run","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/coretax":{"get":{"operationId":"tax.coretax.export","summary":"Export issued invoices for the Coretax e-Faktur import","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"JSON with invoices and issues; format=xml downloads the Coretax XML.","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":true,"description":"First day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"to","in":"query","required":true,"description":"Last day (YYYY-MM-DD)","schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"format","in":"query","required":false,"description":"xml for the Coretax file","schema":{"type":"string","enum":["json","xml"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/ebupot":{"get":{"operationId":"tax.ebupot.export","summary":"Export a month's withholding slips for e-Bupot Unifikasi","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"bppu: PPh 23 and 4(2); bpnr: PPh 26. JSON with slips and issues; format=xml downloads the bulk XML.","x-voltrus-idempotent":true,"parameters":[{"name":"month","in":"query","required":true,"description":"Month (YYYY-MM)","schema":{"type":"string","description":"YYYY-MM"}},{"name":"form","in":"query","required":false,"description":"Form","schema":{"type":"string","enum":["bppu","bpnr"],"default":"bppu"}},{"name":"format","in":"query","required":false,"description":"xml for the Coretax file","schema":{"type":"string","enum":["json","xml"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/withholding-worksheet":{"get":{"operationId":"tax.withholding_worksheet.get","summary":"Show a month's SPT Masa PPh Unifikasi worksheet","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Withholding by tax object code, reconciled with the PPh payable accounts; format=csv downloads it.","x-voltrus-idempotent":true,"parameters":[{"name":"month","in":"query","required":true,"description":"Month (YYYY-MM)","schema":{"type":"string","description":"YYYY-MM"}},{"name":"format","in":"query","required":false,"description":"csv to download","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/remittances":{"get":{"operationId":"tax.remittances.list","summary":"List tax payments to the state","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"period","in":"query","required":false,"description":"Tax month (YYYY-MM)","schema":{"type":"string","description":"YYYY-MM"}},{"name":"tax_type","in":"query","required":false,"description":"Tax type","schema":{"type":"string","enum":["pph23","pph4_2","ppn","pph26","pph_final","pph21"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"tax.remittances.create","summary":"Draft a tax payment to the state","tags":["tax"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Numbered SSP/YYYY/MM/NNNN. A draft posts nothing.","x-voltrus-low-risk":true,"x-voltrus-example":{"body":{"tax_type":"pph23","period":"2026-10","amount":300000,"paid_at":"2026-11-10"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_type":{"type":"string","enum":["pph23","pph4_2","ppn","pph26","pph_final","pph21"]},"period":{"type":"string","description":"Tax month paid for (YYYY-MM)"},"amount":{"type":"number","minimum":0},"paid_at":{"type":"string","format":"date","description":"Date paid (YYYY-MM-DD)"},"billing_code":{"type":"string","description":"Kode billing"},"ntpn":{"type":"string","description":"NTPN from the bank receipt; required before posting"},"bank_account_id":{"type":"string","description":"GL account paid from; default the cash account"},"notes":{"type":"string"},"allow_overpay":{"type":"boolean","description":"Allow paying more than the payable account holds"}},"required":["tax_type","period","amount"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/remittances/proposal":{"get":{"operationId":"tax.remittances.proposal","summary":"Show what is owed to the state for a tax month","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"PPN: output VAT (tax_payable) less input VAT (vat_input, PPN Masukan) booked in the month, less input carried forward from earlier months; ppn shows the split. Posting a PPN remittance offsets the month's input against output in the same journal.","x-voltrus-idempotent":true,"parameters":[{"name":"period","in":"query","required":true,"description":"Tax month (YYYY-MM)","schema":{"type":"string","description":"YYYY-MM"}},{"name":"tax_type","in":"query","required":false,"description":"Tax type","schema":{"type":"string","enum":["pph23","pph4_2","ppn","pph26","pph_final","pph21"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/remittances/types":{"get":{"operationId":"tax.remittances.types","summary":"List the tax types that can be paid and their payable accounts","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/remittances/{id}":{"get":{"operationId":"tax.remittances.get","summary":"Show one tax payment","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Remittance id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"tax.remittances.update","summary":"Change a draft tax payment","tags":["tax"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"409 once posted.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Remittance id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_type":{"type":"string","enum":["pph23","pph4_2","ppn","pph26","pph_final","pph21"]},"period":{"type":"string","description":"Tax month paid for (YYYY-MM)"},"amount":{"type":"number","minimum":0},"paid_at":{"type":"string","format":"date","description":"Date paid (YYYY-MM-DD)"},"billing_code":{"type":"string","description":"Kode billing"},"ntpn":{"type":"string","description":"NTPN from the bank receipt; required before posting"},"bank_account_id":{"type":"string","description":"GL account paid from; default the cash account"},"notes":{"type":"string"},"allow_overpay":{"type":"boolean","description":"Allow paying more than the payable account holds"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"tax.remittances.delete","summary":"Delete a draft tax payment","tags":["tax"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"409 once posted.","parameters":[{"name":"id","in":"path","required":true,"description":"Remittance id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/remittances/{id}/post":{"post":{"operationId":"tax.remittances.post","summary":"Post a paid tax payment to the ledger","tags":["tax"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Posts Dr the tax payable account / Cr bank. Needs the NTPN (400). 409 when already posted, or when the amount is more than the payable account holds on the paid date unless allow_overpay.","parameters":[{"name":"id","in":"path","required":true,"description":"Remittance id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allow_overpay":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/maintenance/due":{"get":{"operationId":"maintenance.due.list","summary":"List open and in-progress maintenance per asset with how overdue it is","tags":["maintenance"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Due dates are compared with the company's business date.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"within":"7"}},"parameters":[{"name":"within","in":"query","required":false,"description":"Only work due within this many days","schema":{"type":"integer","minimum":0}},{"name":"overdue","in":"query","required":false,"description":"1 = overdue only","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assets/depreciation":{"get":{"operationId":"assets.depreciation.preview","summary":"Preview the depreciation a run would post up to a month","tags":["assets"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"period":"2026-10"}},"parameters":[{"name":"period","in":"query","required":false,"description":"Month to depreciate up to; defaults to last month","schema":{"type":"string","description":"Month as YYYY-MM"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assets/depreciate":{"post":{"operationId":"assets.depreciation.run","summary":"Post depreciation for every unposted month up to a period","tags":["assets"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Posts one depreciation journal per asset and month not yet posted. dry_run (query 1 or body true) previews without posting. Refused for agents and read-only tenants.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"period":"2026-10"}},"parameters":[{"name":"period","in":"query","required":false,"description":"Month to depreciate up to (or body.period); defaults to last month","schema":{"type":"string","description":"Month as YYYY-MM"}},{"name":"dry_run","in":"query","required":false,"description":"1 = preview only","schema":{"type":"string","enum":["1"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"Month as YYYY-MM"},"dry_run":{"type":"boolean","description":"Preview only"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assets/{code}":{"get":{"operationId":"assets.asset.get","summary":"Show an asset with its depreciation schedule and book value","tags":["assets"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"code","in":"path","required":true,"description":"Asset code","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assets/{code}/maintenance":{"get":{"operationId":"assets.maintenance.list","summary":"List an asset's maintenance history","tags":["assets"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"code","in":"path","required":true,"description":"Asset code","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/checklists/{id}/runs":{"get":{"operationId":"checklists.run.list","summary":"List a checklist's submitted runs, optionally for one record","tags":["checklists"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Checklist id","schema":{"type":"string"}},{"name":"ref_type","in":"query","required":false,"description":"Record kind the run was for (maintenance, work_order)","schema":{"type":"string"}},{"name":"ref_id","in":"query","required":false,"description":"Record id the run was for","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"checklists.run.submit","summary":"Submit a checklist run against a maintenance or work order","tags":["checklists"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Every step is answered once with a value of its kind; failed steps are recorded. Runs are immutable. Refused for an inactive checklist (409).","x-voltrus-example":{"params":{"id":"CL-PM-PUMP"},"body":{"ref_type":"maintenance","ref_id":"MT-0042","answers":[{"step_id":"step-1","value":true}]}},"parameters":[{"name":"id","in":"path","required":true,"description":"Checklist id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ref_type":{"type":"string","description":"Record kind: maintenance or work_order"},"ref_id":{"type":"string","description":"Record id"},"answers":{"type":"array","items":{"type":"object","properties":{"step_id":{"type":"string","description":"Checklist step id"},"value":{"type":["boolean","number","string"],"description":"Answer of the step's kind (check, number, text)"}},"required":["step_id","value"]}}},"required":["ref_type","ref_id","answers"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/mrp":{"get":{"operationId":"mrp.report.get","summary":"Show demand, supply and net position per item with pegging and suggestions","tags":["mrp"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Suggestions (buy, make, transfer) carry need_by and due_date; late ones are flagged. Feed selected suggestions to POST /api/mrp/convert.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/mrp/convert":{"post":{"operationId":"mrp.suggestions.convert","summary":"Turn MRP suggestions into draft purchase orders or requisitions, work orders and transfers","tags":["mrp","requisitions"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"One draft purchase order per supplier and warehouse, one draft work order per make line, one draft stock transfer per warehouse pair. Drafts only: nothing is ordered until they are confirmed. Refused when a buy line has no supplier. When the company buys through requisitions (GET /api/settings/requisitions: mrp_buy_target purchase_requisition) or buy_as is purchase_requisition, buy lines become one draft purchase requisition per warehouse instead (approved under the company rule, then converted to purchase orders); buy_as purchase_order is refused then.","x-voltrus-low-risk":true,"x-voltrus-example":{"body":{"suggestions":[{"item_sku":"RM-BOLT","action":"buy","qty":500,"due_date":"2026-12-15"}]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","description":"One MRP suggestion, as GET /api/mrp returns it","properties":{"item_sku":{"type":"string","description":"Item to buy, make or move"},"action":{"type":"string","enum":["buy","make","transfer"]},"qty":{"type":"number","minimum":0,"description":"Positive quantity"},"due_date":{"type":"string","format":"date","description":"When it is needed (arrives, for a transfer)"},"need_by":{"type":"string","format":"date","description":"Accepted for due_date; for a transfer with a due_date, its ship date"},"supplier_id":{"type":"string","description":"Buy lines: supplier; defaults to the warehouse's or the item's default supplier"},"warehouse_id":{"type":"string","description":"Receiving warehouse (transfers: destination)"},"from_warehouse_id":{"type":"string","description":"Transfers: the warehouse the stock leaves"},"ship_date":{"type":"string","format":"date","description":"Transfers: when it leaves; not after due_date"}},"required":["item_sku","action","qty"]},"description":"Selected suggestions (alias: lines)"},"warehouse_id":{"type":"string","description":"Warehouse for lines without their own"},"buy_as":{"type":"string","enum":["purchase_order","purchase_requisition"],"description":"What buy lines become; default the company setting mrp_buy_target"}},"required":["suggestions"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/requisitions/{id}/approval":{"get":{"operationId":"requisitions.approval.get","summary":"Show who may approve a purchase requisition under the company rule","tags":["requisitions"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"rule (any_ops, cost_center_owner, amount_threshold), the estimated value in IDR, requires (any_ops, admin_or_approvers, cost_center_owner, escalation), the logins that may decide, whether admins decide or may override, who is excluded as its requester, and eligible: whether the caller may approve or reject it now. Approving is POST /api/entities/purchase_requisition/{id}/transition {to: approved} (OPS) or a proposal (agents); an OPS user the rule does not name gets 409 and proposes it instead.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase requisition id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/production/where-used":{"get":{"operationId":"production.where_used.list","summary":"List the active bills of materials that use an item at any depth","tags":["production"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"item":"RM-PLATE"}},"parameters":[{"name":"item","in":"query","required":true,"description":"Item SKU","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/production/work-orders/{id}/cost":{"get":{"operationId":"production.work_order.cost","summary":"Show a work order's materials, labour, overhead, output and variance","tags":["production"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Work order id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/timezone":{"get":{"operationId":"settings.timezone.get","summary":"Show the company's time zone, your display zone and today's business date","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Business dates (payments, journals, orders) follow the company zone; your own zone only changes how times are shown.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.timezone.set","summary":"Set the company's time zone","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Decides which day \"today\" is wherever the app fills in a date. Empty means UTC. Refused (400) for an unknown zone or a body without value.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":"Asia/Jakarta"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":["string","null"],"description":"IANA time zone name such as Asia/Jakarta; empty or null for the default"}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/my-timezone":{"put":{"operationId":"settings.my_timezone.set","summary":"Set the zone times are shown to you in","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Display only; empty follows the company zone. A shared token has no person behind it and gets 409.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":"Asia/Makassar"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":["string","null"],"description":"IANA time zone name such as Asia/Jakarta; empty or null for the default"}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/costing-method":{"get":{"operationId":"settings.costing_method.get","summary":"Show the costing method setting","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"How stock is valued: moving average, standard cost or FIFO (cost layers consumed oldest first).","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.costing_method.set","summary":"Switch the costing method, revaluing stock on hand","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"moving_average, standard or fifo. With stock on hand the switch needs revalue: true (otherwise 409): switching to FIFO opens one layer per item and warehouse at the current unit cost; switching away collapses the layers to their average; each item whose value changes is revalued in one journal (a Dr/Cr inventory line per item with item_sku, the net against variance), recorded in cost_adjustment. Inventory entries outside the stock ledger (manual journals) are left alone and stay visible in the reconciliation. Admin only; an agent can only propose it.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":"fifo","revalue":true}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","enum":["moving_average","standard","fifo"]},"revalue":{"type":"boolean","description":"Confirm the revaluation when there is stock on hand"}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/approval-controls":{"get":{"operationId":"settings.approval_controls.get","summary":"Show the self-approval rule and the approval limits by amount","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"self_approval: sole_approver_only (the proposer may approve their own proposal only when nobody else can) or never. limits: IDR amounts per kind (purchase_order approve, supplier_bill issue, payment for money going out incl. batches and runs); null = no limit. Above a limit, an admin approves.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.approval_controls.set","summary":"Set the self-approval rule and the approval limits by amount","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Send only what changes. A limit of null removes it. Admin only.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"self_approval":"sole_approver_only","limits":{"purchase_order":50000000,"supplier_bill":null,"payment":100000000}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"self_approval":{"type":"string","enum":["sole_approver_only","never"]},"limits":{"type":"object","properties":{"purchase_order":{"type":"number","minimum":0,"description":"IDR, or null for no limit"},"supplier_bill":{"type":"number","minimum":0,"description":"IDR, or null for no limit"},"payment":{"type":"number","minimum":0,"description":"IDR, or null for no limit"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/budget-control":{"get":{"operationId":"settings.budget_control.get","summary":"Show the budget control setting","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"What happens when a purchase goes over its budget.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.budget_control.set","summary":"Set the budget control setting","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"What happens when a purchase goes over its budget.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":"block"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","enum":["off","warn","block"]}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/fx-auto-rates":{"get":{"operationId":"settings.fx_auto_rates.get","summary":"Show the automatic exchange rates setting","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Fetch BI JISDOR and Kurs Pajak rates every night.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.fx_auto_rates.set","summary":"Set the automatic exchange rates setting","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Fetch BI JISDOR and Kurs Pajak rates every night.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":"on"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","enum":["off","on"]}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/credit-control":{"get":{"operationId":"settings.credit_control.get","summary":"Show the credit control setting","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"What happens when a sales order takes a customer over its credit limit.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.credit_control.set","summary":"Set the credit control setting","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"What happens when a sales order takes a customer over its credit limit.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":"approval"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","enum":["off","warn","approval"]}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/sales-tax":{"get":{"operationId":"settings.sales_tax.get","summary":"Show the PPN percent new sales orders take for taxable customers","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.sales_tax.set","summary":"Set the PPN percent for new sales orders to taxable customers","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"11 = PPN on DPP nilai lain (the default); 0 = the company is not a PKP. Existing orders keep their percent.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"value":11}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":100,"description":"Percent"}},"required":["value"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/tax-identity":{"get":{"operationId":"settings.tax_identity.get","summary":"Show the seller NPWP, NITKU and name the Coretax export uses","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.tax_identity.set","summary":"Set the seller NPWP, NITKU or name for Coretax","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Send only the fields to change. NPWP and NITKU are stored as digits (dots, dashes and spaces are dropped).","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seller_npwp":{"type":"string","description":"NPWP, digits"},"seller_nitku":{"type":"string","description":"NITKU, digits"},"seller_name":{"type":"string","description":"Registered seller name"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/company":{"get":{"operationId":"settings.company.get","summary":"Show the letterhead printed on invoices and delivery orders","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.company.set","summary":"Set the company name, address or phone for printed documents","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Send only the fields to change. Name and phone up to 120 characters, address up to 500.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":["string","null"]},"company_address":{"type":["string","null"]},"company_phone":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/bill-match":{"get":{"operationId":"settings.bill_match.get","summary":"Show how supplier bills are matched to orders and receipts","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.bill_match.set","summary":"Set the bill matching mode and price tolerances","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"mode: off, approval (a bill outside tolerance needs approval) or block. Send only the fields to change.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"mode":"approval","tolerance_percent":5}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["off","approval","block"]},"tolerance_percent":{"type":"number","minimum":0,"description":"Allowed price difference, percent"},"tolerance_amount":{"type":"number","minimum":0,"description":"Allowed price difference, amount"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/requisitions":{"get":{"operationId":"settings.requisitions.get","summary":"Show the purchase requisition approval rule and what MRP buy lines become","tags":["settings","requisitions"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.requisitions.set","summary":"Set who approves purchase requisitions and whether MRP buys through them","tags":["settings","requisitions"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"approval_rule: any_ops (default: any OPS user), cost_center_owner (the owner or deputy of every line's cost centre, or of one above them all; else escalation_approvers, else an admin) or amount_threshold (up to threshold_amount any OPS user, above it an admin or one of approvers). admin_override: an admin may always decide. self_approval false: whoever created or submitted a requisition may not decide it. The rule applies to every requisition, whoever created it. Admins are the users with the admin role in Users (src/auth.ts isAdmin). mrp_buy_target: purchase_order (default, MRP buy lines become draft POs) or purchase_requisition. Send only the fields to change.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"approval_rule":"amount_threshold","threshold_amount":10000000,"approvers":["finance@pabrik.co.id"]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_rule":{"type":"string","enum":["any_ops","cost_center_owner","amount_threshold"]},"threshold_amount":{"type":"number","minimum":0,"description":"Largest estimated value (IDR) any OPS user approves under amount_threshold"},"approvers":{"type":"array","items":{"type":"string"},"description":"Logins (username or email) that approve above the threshold besides admins"},"escalation_approvers":{"type":"array","items":{"type":"string"},"description":"Logins that decide when no cost centre owner or deputy covers every line; empty = admins"},"admin_override":{"type":"boolean","description":"An admin may approve or reject any requisition"},"self_approval":{"type":"boolean","description":"false: requesters (creator, submitter) may not decide their own requisition"},"mrp_buy_target":{"type":"string","enum":["purchase_order","purchase_requisition"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/tax-rates":{"get":{"operationId":"settings.tax_rate.list","summary":"List tax rate presets","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"settings.tax_rate.create","summary":"Add a tax rate preset","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-example":{"body":{"name":"PPN 11%","percent":11}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"1-60 characters"},"percent":{"type":"number","minimum":0,"maximum":100},"active":{"type":"boolean"}},"required":["name","percent"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/tax-rates/{id}":{"patch":{"operationId":"settings.tax_rate.update","summary":"Change a tax rate preset","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Documents already issued keep the percent they copied.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Tax rate id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"1-60 characters"},"percent":{"type":"number","minimum":0,"maximum":100},"active":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"settings.tax_rate.delete","summary":"Delete a tax rate preset","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Tax rate id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/automations/recipes":{"get":{"operationId":"automations.recipe.list","summary":"List ready-made automation recipes","tags":["automations"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/automations":{"get":{"operationId":"automations.automation.list","summary":"List automations","tags":["automations"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"automations.automation.create","summary":"Create an automation from a trigger, conditions and actions","tags":["automations"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-example":{"body":{"name":"Flag big orders","trigger_type":"entity_created","trigger_config":{"entity":"sales_order"},"conditions":[{"path":"total","op":"gt","value":100000000}],"actions":[{"type":"webhook_event","event":"big_order"}]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"trigger_type":{"type":"string","enum":["entity_created","entity_updated","transition","event","daily"]},"trigger_config":{"type":"object","description":"entity for record triggers, event for event triggers, to for a transition into one status","properties":{"entity":{"type":"string"},"event":{"type":"string","enum":["stock.below_reorder","maintenance.overdue","proposal.decided"]},"to":{"type":"string"}}},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Field path on the record"},"op":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","contains","exists"]},"value":{"description":"Value to compare with"}},"required":["path","op"]}},"actions":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string","enum":["set_fields","create_record","transition","propose","webhook_event"]}},"required":["type"]}}},"required":["name","trigger_type","actions"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/automations/{id}":{"get":{"operationId":"automations.automation.get","summary":"Show an automation with its trigger, conditions and actions","tags":["automations"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Automation id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"automations.automation.update","summary":"Change an automation","tags":["automations"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Fields left out keep their value.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Automation id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"trigger_type":{"type":"string","enum":["entity_created","entity_updated","transition","event","daily"]},"trigger_config":{"type":"object","description":"entity for record triggers, event for event triggers, to for a transition into one status","properties":{"entity":{"type":"string"},"event":{"type":"string","enum":["stock.below_reorder","maintenance.overdue","proposal.decided"]},"to":{"type":"string"}}},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Field path on the record"},"op":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","contains","exists"]},"value":{"description":"Value to compare with"}},"required":["path","op"]}},"actions":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string","enum":["set_fields","create_record","transition","propose","webhook_event"]}},"required":["type"]}}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"automations.automation.delete","summary":"Delete an automation","tags":["automations"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Automation id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/automations/{id}/runs":{"get":{"operationId":"automations.run.list","summary":"List an automation's recent runs","tags":["automations"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Automation id","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many runs (default 50)","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/automations/{id}/test":{"post":{"operationId":"automations.automation.test","summary":"Dry-run an automation against a sample record","tags":["automations"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Evaluates the conditions and describes the actions it would take; changes nothing.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Automation id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sample":{"type":"object","additionalProperties":true,"description":"A record as the trigger would see it"}},"required":["sample"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/automations/{id}/toggle":{"post":{"operationId":"automations.automation.toggle","summary":"Turn an automation on or off","tags":["automations"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Automation id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"true turns it on; anything else turns it off"}},"required":["enabled"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/custom-fields":{"get":{"operationId":"custom_fields.field.list","summary":"List custom field definitions, optionally for one entity","tags":["custom_fields"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"query","required":false,"description":"Entity name, e.g. sales_order","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"custom_fields.field.create","summary":"Add a custom field to an entity","tags":["custom_fields"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Entity, key and type cannot change later. Select fields need options. The stock ledger takes no custom fields.","x-voltrus-example":{"body":{"entity":"sales_order","key":"po_ref","label":"Customer PO","type":"text"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"string","description":"Entity name, e.g. sales_order"},"key":{"type":"string","description":"Field key, snake_case"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","boolean","select"]},"options":{"type":"array","items":{"type":"string"},"description":"Select fields only"},"sort_order":{"type":"integer"}},"required":["entity","key","label","type"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/custom-fields/{id}":{"patch":{"operationId":"custom_fields.field.update","summary":"Change a custom field's label, options or order","tags":["custom_fields"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Custom field id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"sort_order":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"custom_fields.field.delete","summary":"Delete a custom field definition","tags":["custom_fields"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Custom field id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/schedules":{"get":{"operationId":"report_schedules.schedule.list","summary":"List scheduled report emails","tags":["report_schedules"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"report_schedules.schedule.create","summary":"Schedule a report to be emailed daily or weekly","tags":["report_schedules"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"A built-in report (mrp, maintenance_due, stock_below_reorder, finance_journal) or kind custom_report with a published report layout: its printed layout is the email body and its rows the CSV attachment.","x-voltrus-example":{"body":{"name":"Morning MRP","kind":"mrp","recipients":["owner@example.com"],"frequency":"daily"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["mrp","maintenance_due","stock_below_reorder","finance_journal","custom_report"],"description":"custom_report: a published report layout (report_layout_id)"},"recipients":{"type":"array","items":{"type":"string","format":"email"},"description":"1-10 email addresses"},"frequency":{"type":"string","enum":["daily","weekly"]},"enabled":{"type":"boolean"},"report_layout_id":{"type":"string","description":"custom_report: the published report layout to send"},"params":{"type":"object","description":"custom_report: param values, e.g. {\"from\": \"prev_month_start\", \"to\": \"prev_month_end\"}"}},"required":["name","kind","recipients","frequency"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/schedules/{id}":{"patch":{"operationId":"report_schedules.schedule.update","summary":"Change a report schedule","tags":["report_schedules"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Schedule id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["mrp","maintenance_due","stock_below_reorder","finance_journal","custom_report"],"description":"custom_report: a published report layout (report_layout_id)"},"recipients":{"type":"array","items":{"type":"string","format":"email"},"description":"1-10 email addresses"},"frequency":{"type":"string","enum":["daily","weekly"]},"enabled":{"type":"boolean"},"report_layout_id":{"type":"string","description":"custom_report: the published report layout to send"},"params":{"type":"object","description":"custom_report: param values, e.g. {\"from\": \"prev_month_start\", \"to\": \"prev_month_end\"}"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"report_schedules.schedule.delete","summary":"Delete a report schedule","tags":["report_schedules"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Schedule id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/schedules/{id}/run":{"post":{"operationId":"report_schedules.schedule.run","summary":"Send a scheduled report to its recipients now","tags":["report_schedules"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Schedule id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/proposals/{id}":{"get":{"operationId":"proposals.get","summary":"Fetch one proposal with its status, decision and result","tags":["proposals"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"For an API-call proposal (op \"call\") result_json holds the replayed answer once approved; apply_error says why a replay failed.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Proposal id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/settings/agent-permissions":{"get":{"operationId":"settings.agent_permissions.get","summary":"Show which operations agents may run without asking","tags":["settings"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"allowed: operation ids on the company allow-list. candidates: governed operations marked low-risk, offered for the list; allow_listable: every other operation that may be listed. Any other governed operation an agent calls becomes a proposal an approver decides.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"settings.agent_permissions.set","summary":"Set the operations agents may run without asking","tags":["settings"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Replaces the allow-list. Only governed operations may be listed; the allow-list and proposal decisions themselves never can. Unknown ids are refused (400).","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"allowed":[]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"array","items":{"type":"string"},"description":"Operation ids, e.g. [\"bank.transactions.match\"]"}},"required":["allowed"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/connection":{"get":{"operationId":"revenue.connection.get","summary":"Show whether RevKlik is connected, which sites count as revenue and the last sync","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Never returns the token, only its first and last four characters. secrets_key_set says whether the server can store a token.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"revenue.connection.connect","summary":"Connect RevKlik with an rvt_ account token","tags":["revenue"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"The token needs sites:read, analytics:read and analytics:export; it is checked against RevKlik and stored encrypted (SECRETS_KEY). since is the first day whose sales to book; site_ids default to every site the token sees. Admin only; agents may not.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"rvt_ account token"},"since":{"type":"string","format":"date"},"site_ids":{"type":"array","items":{"type":"string"}},"auto_sync":{"type":"boolean","default":true}},"required":["token","since"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"revenue.connection.update","summary":"Change which RevKlik sites count, the start date or nightly sync","tags":["revenue"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site_ids":{"type":"array","items":{"type":"string"}},"since":{"type":"string","format":"date"},"auto_sync":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"revenue.connection.delete","summary":"Disconnect RevKlik (booked revenue stays)","tags":["revenue"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/connection/test":{"post":{"operationId":"revenue.connection.test","summary":"Check the stored RevKlik token still works and refresh the site list","tags":["revenue"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/sync":{"post":{"operationId":"revenue.sync.run","summary":"Book new RevKlik sales and refunds now","tags":["revenue"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Reads each site from its cursor (35 days back, for late App Store reports) and books every new sale and refund: Dr platform receivable and platform fees / Cr revenue at the day's rate. Idempotent per RevKlik id; events RevKlik no longer reports are reversed, and an unsettled sale whose basis, amount or reported proceeds changed is reversed on its own date and booked again (restated). A missing FX rate holds the event until the rate exists. Runs nightly by itself.","x-voltrus-low-risk":true,"x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date","description":"Re-read from this day instead of the cursors"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/summary":{"get":{"operationId":"revenue.summary.get","summary":"Show a month's revenue by rail, product and site, and what each rail still owes","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"month","in":"query","required":false,"description":"YYYY-MM; default this month","schema":{"type":"string","description":"YYYY-MM"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/events":{"get":{"operationId":"revenue.events.list","summary":"List booked RevKlik sales and refunds, newest first","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"month","in":"query","required":false,"description":"YYYY-MM","schema":{"type":"string","description":"YYYY-MM"}},{"name":"rail","in":"query","required":false,"description":"apple, google_play, polar, pakasir, doku, stripe, ...","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"posted or reversed","schema":{"type":"string","enum":["posted","reversed"]}},{"name":"open","in":"query","required":false,"description":"1: only events no payout settled yet","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"At most 500","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/receivables":{"get":{"operationId":"revenue.receivables.list","summary":"Show what each rail still owes, per currency","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"rail","in":"query","required":false,"description":"apple, google_play, polar, pakasir, doku, stripe, ...","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/payouts":{"get":{"operationId":"revenue.payouts.list","summary":"List platform payouts received","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"rail","in":"query","required":false,"description":"apple, google_play, polar, pakasir, doku, stripe, ...","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"At most 200","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"revenue.payouts.create","summary":"Record a rail's payout and settle the sales it covers","tags":["revenue"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Dr bank / Cr platform receivable at the booked IDR; when paid in the sales currency, the difference in that currency is a fee true-up (platform fees), the rest FX gain/loss. Covers every open event of the rail up to up_to (default received_at) or the named event_ids. Posting a bank statement line with action payout does the same for an imported line.","x-voltrus-example":{"body":{"rail":"apple","received_at":"2026-11-30","amount":1200000,"currency":"IDR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rail":{"type":"string","description":"apple, google_play, polar, pakasir, doku, stripe, ..."},"received_at":{"type":"string","format":"date"},"amount":{"type":"number","minimum":0},"currency":{"type":"string","default":"IDR"},"fx_rate":{"type":"number","description":"IDR per unit; default the day's transaction rate"},"bank_account_id":{"type":"string"},"reference":{"type":"string"},"event_ids":{"type":"array","items":{"type":"string"}},"up_to":{"type":"string","format":"date"},"fee_adjustment":{"type":"number","description":"Payout in another currency than the sales: IDR of the difference that is fees"}},"required":["rail","received_at","amount"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/payouts/{id}":{"get":{"operationId":"revenue.payouts.get","summary":"Show one payout with the sales it settled","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Payout id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/account-map":{"get":{"operationId":"revenue.account_map.list","summary":"List the revenue account per RevKlik site and product","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"revenue.account_map.set","summary":"Set or clear the revenue account of a RevKlik site or product","tags":["revenue"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"product empty = the whole site; account_id null clears the row (sales then credit the app_revenue mapping key). Applies to sales booked afterwards.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site_id":{"type":"string"},"product":{"type":"string"},"account_id":{"type":["string","null"]}},"required":["site_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/revenue/settings":{"get":{"operationId":"revenue.settings.get","summary":"Show each rail's revenue basis: gross or proceeds","tags":["revenue"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"rail_basis is the company's choice per rail; defaults are the built-in ones (Polar, Lemon Squeezy, Paddle: proceeds; every other rail: gross).","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"revenue.settings.set","summary":"Set a rail's revenue basis: gross or proceeds","tags":["revenue"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"gross: revenue is the customer price and the commission an expense; proceeds: revenue is what the rail pays. rail_basis maps a rail to \"gross\", \"proceeds\" or null (back to the default). Applies to sales booked afterwards. To restate sales already booked, run the sync with since: every sale no payout has settled yet is reversed on its own date and booked again on the new basis; settled sales stay as they are. The same sync also replaces estimated proceeds with the rail's reported ones. Admin only.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"rail_basis":{"apple":"proceeds","google_play":"proceeds"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rail_basis":{"type":"object","additionalProperties":{"type":["string","null"],"enum":["gross","proceeds"]},"description":"apple, google_play, polar, pakasir, doku, stripe, ..."}},"required":["rail_basis"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/pph-final":{"get":{"operationId":"tax.pph_final.worksheet","summary":"Show the year's PPh final 0.5% per month: turnover, tax, accrued, paid, deadline","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Turnover is RevKlik revenue plus issued customer invoices before PPN. format=csv downloads it. Billing code 411128-420; due by the 15th of the next month (next working day).","x-voltrus-idempotent":true,"parameters":[{"name":"year","in":"query","required":false,"description":"4-digit year; default this year","schema":{"type":"integer"}},{"name":"format","in":"query","required":false,"description":"csv for a download","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/pph-final/settings":{"get":{"operationId":"tax.pph_final.settings_get","summary":"Show who pays PPh final and for which years","tags":["tax"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"tax.pph_final.settings_set","summary":"Set the PPh final taxpayer type and registration year","tags":["tax"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"op 7 tax years, pt_perorangan/koperasi/cv 4, pt 3 (computed only when final_until_year is set: PP 20/2026 may exclude a regular PT). off turns it off.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"taxpayer_type":{"type":"string","enum":["off","op","pt_perorangan","koperasi","cv","pt"]},"registered_year":{"type":"integer"},"final_until_year":{"type":["integer","null"]}},"required":["taxpayer_type"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/tax/pph-final/accrue":{"post":{"operationId":"tax.pph_final.accrue","summary":"Book an ended month's PPh final to pay","tags":["tax"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Dr PPh final expense / Cr PPh final payable for what the month owes less earlier accruals of it; pay it with a pph_final tax remittance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"YYYY-MM"}},"required":["period"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/inventory-valuation":{"get":{"operationId":"reports.inventory_valuation","summary":"Value stock on hand as of a date, by item, warehouse or item type","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"On-hand quantity and value at the end of as_of. Value is what each stock movement's journal posted to the inventory account plus item-tagged value entries (revaluations), never today's cost, so it holds for moving average, standard and FIFO. An item's value is split over warehouses by quantity. unvalued_qty is stock moved by movements that posted no journal (zero cost, pre-GL history).","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"as_of":"2026-10-31","group_by":"type"}},"parameters":[{"name":"as_of","in":"query","required":false,"description":"Business date (YYYY-MM-DD, company time zone); default today","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","required":false,"description":"item (default), warehouse (item × warehouse) or type","schema":{"type":"string","enum":["item","warehouse","type"]}},{"name":"warehouse_id","in":"query","required":false,"description":"Only this warehouse","schema":{"type":"string"}},{"name":"item_sku","in":"query","required":false,"description":"Only this item","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"csv for a CSV download; JSON otherwise","schema":{"type":"string","enum":["csv"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/inventory-valuation/reconciliation":{"get":{"operationId":"reports.inventory_valuation.reconciliation","summary":"Reconcile stock value as of a date to the inventory GL account","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"GL balance of the inventory account (and the accounts under it) against the stock ledger value. The difference is listed entry by entry: journals to the inventory account with no stock movement or item (manual journals, bills booked straight to inventory) and journals of movements that no longer exist. Also lists movements that posted no journal (quantity without value) and shows WIP separately.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"as_of":"2026-10-31"}},"parameters":[{"name":"as_of","in":"query","required":false,"description":"Business date (YYYY-MM-DD, company time zone); default today","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/slow-moving":{"get":{"operationId":"reports.slow_moving","summary":"List slow-moving and dead stock by last movement","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Per item and warehouse with stock on hand: last receipt, last consumption (issue or shipment), last movement, days since each, value, an aging bucket (0-90, 91-180, 181-365, >365 days since last consumption, or since the first receipt when never consumed) and a dead flag when that age passes days (default 365).","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"as_of":"2026-11-30","days":"180"}},"parameters":[{"name":"as_of","in":"query","required":false,"description":"Business date (YYYY-MM-DD, company time zone); default today","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","required":false,"description":"Days without consumption that make stock dead; default 365","schema":{"type":"integer","minimum":1,"default":365}},{"name":"warehouse_id","in":"query","required":false,"description":"Only this warehouse","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"csv for a CSV download; JSON otherwise","schema":{"type":"string","enum":["csv"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/runs":{"get":{"operationId":"costing.runs.list","summary":"List cost roll-up runs, newest first","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"costing.runs.create","summary":"Roll up standard costs from BOMs and routings into draft estimates","tags":["costing"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Bottom-up over the active BOMs: materials (BOM qty in base units plus scrap) at the component cost, labour and overhead at the work centres' hourly_rate and overhead_rate (setup spread over the costing lot size: item.costing_lot_size, else min_order_qty, else 1), and the latest subcontract service cost for items made outside. material_source: item_cost (item.unit_cost) or last_purchase (latest receipt's landed cost). Omit items to roll up every manufactured item; the components below the given items are rolled too. Missing costs, BOM cycles and missing work centres make an estimate an error; nothing is guessed. Changes no standard.","x-voltrus-low-risk":true,"x-voltrus-example":{"body":{"items":["FG-FRAME"],"material_source":"item_cost"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"description":"Item SKUs to roll up (with their manufactured components); omit for all"},"material_source":{"type":"string","enum":["item_cost","last_purchase"],"default":"item_cost"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/runs/{id}":{"get":{"operationId":"costing.runs.get","summary":"Show a roll-up run with its estimates and their differences to the current standard","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/runs/{id}/mark":{"post":{"operationId":"costing.runs.mark","summary":"Mark every draft estimate of a run for release","tags":["costing"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Estimates with errors are skipped and listed. An item's earlier marked estimate goes back to draft.","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/runs/{id}/release":{"post":{"operationId":"costing.runs.release","summary":"Release every marked estimate of a run as the new standards","tags":["costing"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Admin only and only under standard costing (409 otherwise). Sets item.unit_cost and revalues the stock on hand in every warehouse: qty × (new − old), Dr/Cr inventory against standard_cost_revaluation in one journal (source standard_cost_revaluation). Open work orders are not revalued: the difference lands in production variance at close.","parameters":[{"name":"id","in":"path","required":true,"description":"Run id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"effective_date":{"type":"string","format":"date","description":"YYYY-MM-DD business date, today or earlier; defaults to today"},"reason":{"type":"string","description":"Why the standard changes (kept on the price change)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/estimates/{id}":{"get":{"operationId":"costing.estimates.get","summary":"Show one cost estimate by element, component and operation","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Estimate id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/estimates/{id}/mark":{"post":{"operationId":"costing.estimates.mark","summary":"Mark a draft cost estimate for release","tags":["costing"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"409 for an estimate with errors or not in draft. The item's earlier marked estimate goes back to draft.","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Estimate id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/estimates/{id}/cancel":{"post":{"operationId":"costing.estimates.cancel","summary":"Set a draft, error or marked cost estimate aside","tags":["costing"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Estimate id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/estimates/{id}/release":{"post":{"operationId":"costing.estimates.release","summary":"Release a marked cost estimate as the item standard and revalue its stock","tags":["costing"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Admin only and only under standard costing (409 otherwise). Sets item.unit_cost and revalues the stock on hand in every warehouse: qty × (new − old), Dr/Cr inventory against standard_cost_revaluation in one journal (source standard_cost_revaluation). Open work orders are not revalued: the difference lands in production variance at close.","parameters":[{"name":"id","in":"path","required":true,"description":"Estimate id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"effective_date":{"type":"string","format":"date","description":"YYYY-MM-DD business date, today or earlier; defaults to today"},"reason":{"type":"string","description":"Why the standard changes (kept on the price change)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/items/{sku}":{"get":{"operationId":"costing.items.get","summary":"Show an item's standard, its current and marked estimates and its price changes","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"sku","in":"path","required":true,"description":"Item SKU","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/price-changes":{"get":{"operationId":"costing.price_changes.list","summary":"List standard price changes and their revaluations","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"item_sku","in":"query","required":false,"description":"One item","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Effective on or after","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Effective on or before","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"costing.price_changes.create","summary":"Change an item's standard cost by hand and revalue its stock","tags":["costing"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"For a purchased item's yearly standard or a correction. reason is required. Admin only and only under standard costing (409 otherwise). Sets item.unit_cost and revalues the stock on hand in every warehouse: qty × (new − old), Dr/Cr inventory against standard_cost_revaluation in one journal (source standard_cost_revaluation). Open work orders are not revalued: the difference lands in production variance at close. Under standard costing a plain item edit of unit_cost is refused while stock is on hand: use this.","x-voltrus-example":{"body":{"item_sku":"RM-PLATE","new_cost":86000,"reason":"Standard 2027: supplier price list"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_sku":{"type":"string"},"new_cost":{"type":"number","minimum":0,"description":"IDR per base unit"},"effective_date":{"type":"string","format":"date","description":"YYYY-MM-DD business date, today or earlier; defaults to today"},"reason":{"type":"string"}},"required":["item_sku","new_cost","reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/revaluations":{"get":{"operationId":"costing.revaluations.list","summary":"List revaluations from price changes (same as price-changes)","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Each record has its lines per warehouse (GET one) and its journal: value-only inventory entries no stock movement carries.","x-voltrus-idempotent":true,"parameters":[{"name":"item_sku","in":"query","required":false,"description":"One item","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Effective on or after","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Effective on or before","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/revaluations/{id}":{"get":{"operationId":"costing.revaluations.get","summary":"Show one price change with its revaluation per warehouse and its journal","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Price change id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/revaluations/{id}/reverse":{"post":{"operationId":"costing.revaluations.reverse","summary":"Reverse an item's latest price change","tags":["costing"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"A price change back to the cost before it, revaluing the stock on hand now; the estimate it replaced becomes current again. Only the item's latest change; reason required; admin only.","parameters":[{"name":"id","in":"path","required":true,"description":"Price change id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"effective_date":{"type":"string","format":"date","description":"YYYY-MM-DD business date, today or earlier; defaults to today"}},"required":["reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/costing/work-orders/{id}/variances":{"get":{"operationId":"costing.work_orders.variances","summary":"Compare a work order's actual cost by element with the released standard","tags":["costing"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Material (subcontract included), labour and overhead: actual against the released estimate × qty produced. Without a released estimate only the total variance is known.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Work order id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/settings":{"get":{"operationId":"inventory.settings.get","summary":"Show the inventory control settings","tags":["inventory"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Reason code requirement, ABC thresholds and lookback, count frequencies per class, working days, blind cycle counts, nightly drafting and the recount tolerance.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"inventory.settings.set","summary":"Change the inventory control settings","tags":["inventory"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Admin only; send only the settings to change. require_adjust_reason (manual adjustments and scrap must name a reason code), abc_a_percent / abc_b_percent (cumulative consumption-value shares, C is the rest), abc_lookback_days, count_frequency {A, B, C} (counts a year), working_days (ISO weekdays), blind_cycle_counts, auto_draft (the nightly job drafts the day's cycle counts), recount_tolerance_percent and recount_tolerance_value (null turns a limit off).","x-voltrus-example":{"body":{"recount_tolerance_percent":5,"recount_tolerance_value":500000,"auto_draft":true}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"require_adjust_reason":{"type":"boolean"},"abc_a_percent":{"type":"number","minimum":1,"maximum":99},"abc_b_percent":{"type":"number","minimum":0,"maximum":99},"abc_lookback_days":{"type":"integer","minimum":1},"count_frequency":{"type":"object","properties":{"A":{"type":"number"},"B":{"type":"number"},"C":{"type":"number"}}},"working_days":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7}},"blind_cycle_counts":{"type":"boolean"},"auto_draft":{"type":"boolean"},"recount_tolerance_percent":{"type":["number","null"]},"recount_tolerance_value":{"type":["number","null"],"description":"IDR: variance qty × unit cost"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/reason-codes":{"get":{"operationId":"inventory.reason_codes.list","summary":"List adjustment reason codes and the GL account each posts to","tags":["inventory"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Active codes; all=1 includes inactive ones. The defaults (COUNT, CORRECTION, DAMAGE, EXPIRED, THEFT, SAMPLE, WRITE_OFF, FOUND) are created on first use.","x-voltrus-idempotent":true,"parameters":[{"name":"all","in":"query","required":false,"description":"1: include inactive codes","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"inventory.reason_codes.create","summary":"Add an adjustment reason code","tags":["inventory"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Its account takes the non-inventory side of adjustments, scrap and count variances that name it; the inventory or WIP account itself is refused. 409 when the code exists.","x-voltrus-example":{"body":{"code":"DAMAGE_TRANSIT","name":"Damaged in transit","direction":"out","account_code":"6-9100"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Upper-case code, 1-32 letters, digits, \"_\" or \"-\" (cannot be renamed)"},"name":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"],"description":"in: only adds stock (FOUND); out: only takes it (DAMAGE); both"},"account_code":{"type":"string","description":"GL account the non-inventory side posts to; empty or null = the variance mapping"},"account_id":{"type":"string","description":"The same account by id"},"active":{"type":"boolean"}},"required":["code","name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/reason-codes/{code}":{"patch":{"operationId":"inventory.reason_codes.update","summary":"Change a reason code's name, direction, account or active flag","tags":["inventory"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"COUNT stays active and both-way: stock counts post with it.","parameters":[{"name":"code","in":"path","required":true,"description":"Reason code","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Upper-case code, 1-32 letters, digits, \"_\" or \"-\" (cannot be renamed)"},"name":{"type":"string"},"direction":{"type":"string","enum":["in","out","both"],"description":"in: only adds stock (FOUND); out: only takes it (DAMAGE); both"},"account_code":{"type":"string","description":"GL account the non-inventory side posts to; empty or null = the variance mapping"},"account_id":{"type":"string","description":"The same account by id"},"active":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"inventory.reason_codes.delete","summary":"Delete a reason code no movement has used","tags":["inventory"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"409 once movements were posted with it (deactivate it instead) and for COUNT.","parameters":[{"name":"code","in":"path","required":true,"description":"Reason code","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/abc":{"get":{"operationId":"inventory.abc.preview","summary":"Preview the ABC classification of items by consumption value","tags":["inventory"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Consumption value per active item over the lookback: shipments and work-order issues less returns, at the value their journals posted. Ranked high to low; A while the running share before the item is under abc_a_percent, B under A + B, C after and for items with no consumption. Shows the current and proposed class and pinned items.","x-voltrus-idempotent":true,"parameters":[{"name":"lookback_days","in":"query","required":false,"description":"Days of consumption; default the setting (365)","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/abc/recalculate":{"post":{"operationId":"inventory.abc.recalculate","summary":"Write the ABC classes onto the items","tags":["inventory"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Sets item.abc_class to the proposed class for every item not pinned (abc_pinned keeps a class a person set on the item).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lookback_days":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/cycle-counts/plan":{"get":{"operationId":"inventory.cycle_counts.plan","summary":"Show which items the cycle count schedule counts on a day","tags":["inventory"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Per warehouse with stock: the items due (never counted, or counted longer ago than 365 / frequency days for their class; unclassified items count as C), within each class's daily share (items × frequency / working days a year, rounded up), never-counted and longest-ago first. Items on an open count are skipped. Nothing is due on a non-working day unless force=1, which lists every due item.","x-voltrus-idempotent":true,"parameters":[{"name":"date","in":"query","required":false,"description":"Business date; default today","schema":{"type":"string","format":"date"}},{"name":"warehouse_id","in":"query","required":false,"description":"Only this warehouse","schema":{"type":"string"}},{"name":"force","in":"query","required":false,"description":"1: every due item, not just the day's share","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/cycle-counts/draft":{"post":{"operationId":"inventory.cycle_counts.draft","summary":"Draft the day's cycle counts","tags":["inventory"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"One draft stock_count per warehouse with the plan's items (source cycle, reason COUNT, blind per blind_cycle_counts unless blind is given), lines uncounted. Counters enter quantities with POST /api/inventory/counts/{id}/entries; posting needs every line counted.","x-voltrus-low-risk":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date"},"warehouse_id":{"type":"string"},"force":{"type":"boolean"},"blind":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/counts/{id}/sheet":{"get":{"operationId":"inventory.counts.sheet","summary":"Show a stock count sheet: lines, what is counted, and the book quantity when the caller may see it","tags":["inventory"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"A blind draft hides expected_qty, book_qty and variance from counters; admins (supervisors) see them, with each entered line's variance and recount flag. Posted counts show the posting snapshot.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Stock count id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/inventory/counts/{id}/entries":{"post":{"operationId":"inventory.counts.entries","summary":"Enter counted quantities on a draft stock count","tags":["inventory"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Each entry names line_id, or item_sku (+ bin_id; an item not on the sheet adds a line), with counted_qty and optionally a reason_code. The book quantity is snapshotted; a variance beyond the recount tolerance flags the line, and entering it again is the recount (count_round 2). Posting the count (transition posted) books the variances.","x-voltrus-low-risk":true,"x-voltrus-example":{"body":{"lines":[{"item_sku":"RM-BOLT","counted_qty":412},{"item_sku":"RM-PLATE","counted_qty":37,"reason_code":"DAMAGE"}]}},"parameters":[{"name":"id","in":"path","required":true,"description":"Stock count id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"line_id":{"type":"string"},"item_sku":{"type":"string"},"bin_id":{"type":"string"},"counted_qty":{"type":"number","minimum":0},"reason_code":{"type":"string"}},"required":["counted_qty"]}}},"required":["lines"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/reports/adjustments-by-reason":{"get":{"operationId":"reports.adjustments_by_reason","summary":"Report adjustments, scrap and count variances by reason code","tags":["reports"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Per reason code and movement kind over business dates from-to (default this month): movements, how many came from counts, qty in and out, signed value and the account the other side posted to.","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"from":"2026-11-01","to":"2026-11-30"}},"parameters":[{"name":"from","in":"query","required":false,"description":"First business date; default the first of to's month","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last business date; default today","schema":{"type":"string","format":"date"}},{"name":"warehouse_id","in":"query","required":false,"description":"Only this warehouse","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/catalog":{"get":{"operationId":"queries.catalog.list","summary":"List the sources saved queries can read","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Every entity, each document's lines (sales_order_line, …), the stock movement ledger and the company's user-defined tables (ud_<key>), with the relations each can join.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/catalog/{source}":{"get":{"operationId":"queries.catalog.get","summary":"Describe one query source's columns, custom fields and relations","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"x-voltrus-example":{"params":{"source":"sales_order_line"}},"parameters":[{"name":"source","in":"path","required":true,"description":"Source name, e.g. sales_order_line","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/validate":{"post":{"operationId":"queries.query.validate","summary":"Check a query definition without running it","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Always answers 200: {valid: true, columns, params} or {valid: false, error} naming the first problem and the valid choices.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"definition":{"source":"sales_order_line","joins":[{"alias":"so","relation":"sales_order","type":"inner"},{"alias":"c","relation":"so.customer"}],"columns":[{"field":"c.name","name":"customer"},{"field":"so.order_date","bucket":"month","name":"month"},{"expr":"sum(qty * unit_price)","name":"revenue","format":"currency"}],"filters":[{"field":"so.status","op":"not_in","value":["draft","cancelled"]},{"field":"so.order_date","op":">=","param":"from"}],"params":[{"name":"from","type":"date","default":"year_start","label":"From"}],"sort":[{"column":"revenue","dir":"desc"}],"limit":100}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"type":"object","description":"A declarative query (no SQL). {source, joins?, columns, filters?, having?, params?, sort?, limit?, distinct?}. source: a catalog source (GET /api/queries/catalog), e.g. sales_order_line. joins: [{alias, relation, type?: left|inner}] where relation is a relation of the source (\"sales_order\") or of an earlier alias (\"so.customer\"). columns: [{field: \"qty\" | \"so.order_date\" | \"cf.<custom field>\", agg?: sum|avg|min|max|count|count_distinct, bucket?: day|month|quarter|year, name?, label?, format?: text|number|currency|percent|date|boolean}] or a calculated column {expr: \"qty * unit_price\", name}. Expressions: + - * / ||, = != < <= > >=, and/or/not, coalesce, nullif, round(x, digits), abs, lower, upper, trim, length, substr, concat, if(cond, a, b), is_null, year, month, day, month_key, quarter_key, year_key, and the aggregates sum, avg, min, max, count, count_distinct. With any aggregate, the other columns group the rows. filters: [{field | expr, op, value | param}] or {any: [filters]} for OR; ops: = != < <= > >= in not_in contains starts_with is_null not_null. having: [{column, op, value | param}] filters output columns (aggregates). params: [{name, type: string|number|date|boolean, label?, required?, default?, multiple?}]; date values may be today, today-30, month_start, prev_month_start, prev_month_end, quarter_start, year_start. An optional param with no value drops its filters. sort: [{column, dir: asc|desc}]. limit: up to 5000 rows (default 1000).","additionalProperties":true}},"required":["definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/preview":{"post":{"operationId":"queries.query.preview","summary":"Run an unsaved query definition and show the first rows","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Runs on the server, scoped to your company, and returns at most 200 rows (default 50): {columns, rows, row_count, has_more, params}.","x-voltrus-idempotent":true,"x-voltrus-example":{"body":{"definition":{"source":"sales_order_line","joins":[{"alias":"so","relation":"sales_order","type":"inner"},{"alias":"c","relation":"so.customer"}],"columns":[{"field":"c.name","name":"customer"},{"field":"so.order_date","bucket":"month","name":"month"},{"expr":"sum(qty * unit_price)","name":"revenue","format":"currency"}],"filters":[{"field":"so.status","op":"not_in","value":["draft","cancelled"]},{"field":"so.order_date","op":">=","param":"from"}],"params":[{"name":"from","type":"date","default":"year_start","label":"From"}],"sort":[{"column":"revenue","dir":"desc"}],"limit":100},"limit":10}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"type":"object","description":"A declarative query (no SQL). {source, joins?, columns, filters?, having?, params?, sort?, limit?, distinct?}. source: a catalog source (GET /api/queries/catalog), e.g. sales_order_line. joins: [{alias, relation, type?: left|inner}] where relation is a relation of the source (\"sales_order\") or of an earlier alias (\"so.customer\"). columns: [{field: \"qty\" | \"so.order_date\" | \"cf.<custom field>\", agg?: sum|avg|min|max|count|count_distinct, bucket?: day|month|quarter|year, name?, label?, format?: text|number|currency|percent|date|boolean}] or a calculated column {expr: \"qty * unit_price\", name}. Expressions: + - * / ||, = != < <= > >=, and/or/not, coalesce, nullif, round(x, digits), abs, lower, upper, trim, length, substr, concat, if(cond, a, b), is_null, year, month, day, month_key, quarter_key, year_key, and the aggregates sum, avg, min, max, count, count_distinct. With any aggregate, the other columns group the rows. filters: [{field | expr, op, value | param}] or {any: [filters]} for OR; ops: = != < <= > >= in not_in contains starts_with is_null not_null. having: [{column, op, value | param}] filters output columns (aggregates). params: [{name, type: string|number|date|boolean, label?, required?, default?, multiple?}]; date values may be today, today-30, month_start, prev_month_start, prev_month_end, quarter_start, year_start. An optional param with no value drops its filters. sort: [{column, dir: asc|desc}]. limit: up to 5000 rows (default 1000).","additionalProperties":true},"params":{"type":"object","description":"Param values, e.g. {\"from\": \"2026-01-01\"}"},"limit":{"type":"integer","minimum":1,"maximum":200}},"required":["definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries":{"get":{"operationId":"queries.query.list","summary":"List saved queries: published ones and your drafts","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"q","in":"query","required":false,"description":"Words in the name or description","schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"all: every draft too (OPS reviewers)","schema":{"type":"string","enum":["all"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"queries.query.create","summary":"Save a new query as a private draft","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"The draft is yours (and visible to OPS reviewers) until it is published (queries.query.publish). Refused (400) with the first problem in the definition, 409 when the name is taken.","x-voltrus-example":{"body":{"name":"Revenue by customer and month","definition":{"source":"sales_order_line","joins":[{"alias":"so","relation":"sales_order","type":"inner"},{"alias":"c","relation":"so.customer"}],"columns":[{"field":"c.name","name":"customer"},{"field":"so.order_date","bucket":"month","name":"month"},{"expr":"sum(qty * unit_price)","name":"revenue","format":"currency"}],"filters":[{"field":"so.status","op":"not_in","value":["draft","cancelled"]},{"field":"so.order_date","op":">=","param":"from"}],"params":[{"name":"from","type":"date","default":"year_start","label":"From"}],"sort":[{"column":"revenue","dir":"desc"}],"limit":100}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the company, up to 120 characters"},"description":{"type":"string"},"definition":{"type":"object","description":"A declarative query (no SQL). {source, joins?, columns, filters?, having?, params?, sort?, limit?, distinct?}. source: a catalog source (GET /api/queries/catalog), e.g. sales_order_line. joins: [{alias, relation, type?: left|inner}] where relation is a relation of the source (\"sales_order\") or of an earlier alias (\"so.customer\"). columns: [{field: \"qty\" | \"so.order_date\" | \"cf.<custom field>\", agg?: sum|avg|min|max|count|count_distinct, bucket?: day|month|quarter|year, name?, label?, format?: text|number|currency|percent|date|boolean}] or a calculated column {expr: \"qty * unit_price\", name}. Expressions: + - * / ||, = != < <= > >=, and/or/not, coalesce, nullif, round(x, digits), abs, lower, upper, trim, length, substr, concat, if(cond, a, b), is_null, year, month, day, month_key, quarter_key, year_key, and the aggregates sum, avg, min, max, count, count_distinct. With any aggregate, the other columns group the rows. filters: [{field | expr, op, value | param}] or {any: [filters]} for OR; ops: = != < <= > >= in not_in contains starts_with is_null not_null. having: [{column, op, value | param}] filters output columns (aggregates). params: [{name, type: string|number|date|boolean, label?, required?, default?, multiple?}]; date values may be today, today-30, month_start, prev_month_start, prev_month_end, quarter_start, year_start. An optional param with no value drops its filters. sort: [{column, dir: asc|desc}]. limit: up to 5000 rows (default 1000).","additionalProperties":true}},"required":["name","definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/{id}":{"get":{"operationId":"queries.query.get","summary":"Fetch a saved query with its published definition and your draft","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Query id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"queries.query.update","summary":"Edit your draft of a query, or start a draft of a published one","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Changes only the draft; the published version keeps running until the draft is published. 409 while someone else has a draft.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Query id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the company, up to 120 characters"},"description":{"type":"string"},"definition":{"type":"object","description":"A declarative query (no SQL). {source, joins?, columns, filters?, having?, params?, sort?, limit?, distinct?}. source: a catalog source (GET /api/queries/catalog), e.g. sales_order_line. joins: [{alias, relation, type?: left|inner}] where relation is a relation of the source (\"sales_order\") or of an earlier alias (\"so.customer\"). columns: [{field: \"qty\" | \"so.order_date\" | \"cf.<custom field>\", agg?: sum|avg|min|max|count|count_distinct, bucket?: day|month|quarter|year, name?, label?, format?: text|number|currency|percent|date|boolean}] or a calculated column {expr: \"qty * unit_price\", name}. Expressions: + - * / ||, = != < <= > >=, and/or/not, coalesce, nullif, round(x, digits), abs, lower, upper, trim, length, substr, concat, if(cond, a, b), is_null, year, month, day, month_key, quarter_key, year_key, and the aggregates sum, avg, min, max, count, count_distinct. With any aggregate, the other columns group the rows. filters: [{field | expr, op, value | param}] or {any: [filters]} for OR; ops: = != < <= > >= in not_in contains starts_with is_null not_null. having: [{column, op, value | param}] filters output columns (aggregates). params: [{name, type: string|number|date|boolean, label?, required?, default?, multiple?}]; date values may be today, today-30, month_start, prev_month_start, prev_month_end, quarter_start, year_start. An optional param with no value drops its filters. sort: [{column, dir: asc|desc}]. limit: up to 5000 rows (default 1000).","additionalProperties":true}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"queries.query.delete","summary":"Delete a saved query for everyone","tags":["queries"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Refused (409) while a dashboard or report layout uses it.","parameters":[{"name":"id","in":"path","required":true,"description":"Query id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/{id}/run":{"get":{"operationId":"queries.query.run","summary":"Run a saved query on the server and return its rows","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Runs the published version (draft=1: your draft). Scoped to your company; returns {query, columns, rows, row_count, has_more, next_offset, params}. format=csv answers a CSV file. A required param without a value is refused (400).","x-voltrus-idempotent":true,"x-voltrus-paged":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Query id","schema":{"type":"string"}},{"name":"params","in":"query","required":false,"description":"Param values as a JSON object, e.g. {\"from\":\"2026-01-01\"}; each param may also be its own query key (?from=2026-01-01)","schema":{"type":"object"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (up to the query limit, at most 5000)","schema":{"type":"integer","minimum":1,"maximum":5000}},{"name":"offset","in":"query","required":false,"description":"Rows to skip (paging)","schema":{"type":"integer","minimum":0}},{"name":"draft","in":"query","required":false,"description":"1: run your draft instead of the published version","schema":{"type":"boolean"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/{id}/publish":{"post":{"operationId":"queries.query.publish","summary":"Publish a query draft to the whole company","tags":["queries"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"The draft replaces the published definition and everyone may run it. `revision` (required, 400 without it) is the draft revision you reviewed: if the draft changed since, the publish is refused (409). An agent's call becomes a proposal an OPS user approves.","x-voltrus-example":{"body":{"revision":1}},"parameters":[{"name":"id","in":"path","required":true,"description":"Query id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","description":"The draft revision to publish (draft.revision from queries.query.get)"}},"required":["revision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/queries/{id}/draft":{"delete":{"operationId":"queries.draft.discard","summary":"Discard your draft of a query","tags":["queries"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"A query never published is deleted with its draft; a published one keeps its published version.","parameters":[{"name":"id","in":"path","required":true,"description":"Query id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards":{"get":{"operationId":"dashboards.dashboard.list","summary":"List dashboards: published ones and your drafts","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"q","in":"query","required":false,"description":"Words in the name or description","schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"all: every draft too (OPS reviewers)","schema":{"type":"string","enum":["all"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"dashboards.dashboard.create","summary":"Save a new dashboard as a private draft","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Widgets may use your own draft queries while the dashboard is a draft; publishing needs every query published.","x-voltrus-example":{"body":{"name":"Sales overview","definition":{"params":[{"name":"from","type":"date","default":"year_start","label":"From"}],"widgets":[{"id":"revenue","type":"number","title":"Revenue this year","query_id":"<query id>","x":0,"y":0,"w":3,"h":2,"options":{"value":"revenue"}},{"id":"by-month","type":"bar","title":"Revenue by month","query_id":"<query id>","x":3,"y":0,"w":9,"h":4,"options":{"label":"month","series":["revenue"]}}]}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the company"},"description":{"type":"string"},"definition":{"type":"object","description":"A grid of widgets, each backed by a saved query: {params?: [ParamDef], widgets: [{id, type: number|table|bar|line, title, query_id, params?, x, y, w, h, options?}]}. The grid has 12 columns: x 0-11, w 1-12 (x + w <= 12), y >= 0, h 1-12 rows (a row is about 76 px). options: number {value: numeric column}; table {columns?: [columns], limit?: 1-200}; bar and line {label: x-axis column, series: [numeric columns, 1-8], limit?}. Columns are output columns of the widget query. Dashboard params are asked once and passed to every widget query with a param of the same name; a widget's params are fixed values. A published dashboard may only use published queries.","additionalProperties":true}},"required":["name","definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards/preview":{"post":{"operationId":"dashboards.dashboard.preview","summary":"Check an unsaved dashboard and run its widgets","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Answers {definition (normalized), params, widgets: [{id, type, title, result | error}]}; 400 names the first invalid widget.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"type":"object","description":"A grid of widgets, each backed by a saved query: {params?: [ParamDef], widgets: [{id, type: number|table|bar|line, title, query_id, params?, x, y, w, h, options?}]}. The grid has 12 columns: x 0-11, w 1-12 (x + w <= 12), y >= 0, h 1-12 rows (a row is about 76 px). options: number {value: numeric column}; table {columns?: [columns], limit?: 1-200}; bar and line {label: x-axis column, series: [numeric columns, 1-8], limit?}. Columns are output columns of the widget query. Dashboard params are asked once and passed to every widget query with a param of the same name; a widget's params are fixed values. A published dashboard may only use published queries.","additionalProperties":true},"params":{"type":"object","description":"Dashboard param values"}},"required":["definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards/home":{"get":{"operationId":"dashboards.home.get","summary":"Show which dashboard replaces the home overview","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"dashboards.home.set","summary":"Make a published dashboard the home page, or restore the standard overview","tags":["dashboards"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dashboard_id":{"type":["string","null"],"description":"A published dashboard; null for the standard overview"}},"required":["dashboard_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards/{id}":{"get":{"operationId":"dashboards.dashboard.get","summary":"Fetch a dashboard with its published layout and your draft","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"dashboards.dashboard.update","summary":"Edit your draft of a dashboard (widgets, layout, name)","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"agent","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the company"},"description":{"type":"string"},"definition":{"type":"object","description":"A grid of widgets, each backed by a saved query: {params?: [ParamDef], widgets: [{id, type: number|table|bar|line, title, query_id, params?, x, y, w, h, options?}]}. The grid has 12 columns: x 0-11, w 1-12 (x + w <= 12), y >= 0, h 1-12 rows (a row is about 76 px). options: number {value: numeric column}; table {columns?: [columns], limit?: 1-200}; bar and line {label: x-axis column, series: [numeric columns, 1-8], limit?}. Columns are output columns of the widget query. Dashboard params are asked once and passed to every widget query with a param of the same name; a widget's params are fixed values. A published dashboard may only use published queries.","additionalProperties":true}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"dashboards.dashboard.delete","summary":"Delete a dashboard for everyone","tags":["dashboards"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards/{id}/data":{"get":{"operationId":"dashboards.dashboard.data","summary":"Run a dashboard's widget queries and return their data","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Each widget answers {result} or {error}; one broken widget does not fail the others. draft=1 shows your draft.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}},{"name":"params","in":"query","required":false,"description":"Dashboard param values as JSON; each may also be its own query key","schema":{"type":"object"}},{"name":"draft","in":"query","required":false,"description":"1: your draft","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards/{id}/publish":{"post":{"operationId":"dashboards.dashboard.publish","summary":"Publish a dashboard draft to the whole company","tags":["dashboards"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"`revision` (required) is the draft revision reviewed. Refused (409) while a widget uses an unpublished query or the draft moved past the revision sent. An agent's call becomes a proposal.","parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","description":"The draft revision to publish (draft.revision)"}},"required":["revision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/dashboards/{id}/draft":{"delete":{"operationId":"dashboards.draft.discard","summary":"Discard your draft of a dashboard","tags":["dashboards"],"x-voltrus-role":"any","x-voltrus-agent":"agent","parameters":[{"name":"id","in":"path","required":true,"description":"Dashboard id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/report-layouts":{"get":{"operationId":"report_layouts.layout.list","summary":"List report layouts: published ones and your drafts","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"q","in":"query","required":false,"description":"Words in the name or description","schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"all: every draft too (OPS reviewers)","schema":{"type":"string","enum":["all"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"report_layouts.layout.create","summary":"Save a new report layout as a private draft","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"agent","x-voltrus-example":{"body":{"name":"Monthly sales by customer","definition":{"query_id":"<query id>","title":"Sales by customer","group_by":["customer"],"totals":["revenue"],"params":{"from":"prev_month_start"},"orientation":"portrait"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the company"},"description":{"type":"string"},"definition":{"type":"object","description":"A printable report over a saved query: {query_id, title, subtitle?, orientation?: portrait|landscape, columns?: [{column, label?, align?: left|right|center, format?: text|number|currency|percent|date|boolean, width?: percent}], group_by?: [up to 2 output columns], totals?: [numeric output columns, summed per group and overall], params?: {fixed param values}, footer?, limit?: 1-5000, replaces the query limit; without it up to 5000 rows unless the query sets one}. The header carries the company name, address and phone from settings (company_name, company_address, company_phone), the print date and the params used.","additionalProperties":true}},"required":["name","definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/report-layouts/preview":{"post":{"operationId":"report_layouts.layout.preview","summary":"Check an unsaved report layout and render it","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Answers {title, columns, result, html, csv}; html is the printable page.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"type":"object","description":"A printable report over a saved query: {query_id, title, subtitle?, orientation?: portrait|landscape, columns?: [{column, label?, align?: left|right|center, format?: text|number|currency|percent|date|boolean, width?: percent}], group_by?: [up to 2 output columns], totals?: [numeric output columns, summed per group and overall], params?: {fixed param values}, footer?, limit?: 1-5000, replaces the query limit; without it up to 5000 rows unless the query sets one}. The header carries the company name, address and phone from settings (company_name, company_address, company_phone), the print date and the params used.","additionalProperties":true},"params":{"type":"object"}},"required":["definition"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/report-layouts/{id}":{"get":{"operationId":"report_layouts.layout.get","summary":"Fetch a report layout with its published version and your draft","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Report layout id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"report_layouts.layout.update","summary":"Edit your draft of a report layout","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"agent","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Report layout id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the company"},"description":{"type":"string"},"definition":{"type":"object","description":"A printable report over a saved query: {query_id, title, subtitle?, orientation?: portrait|landscape, columns?: [{column, label?, align?: left|right|center, format?: text|number|currency|percent|date|boolean, width?: percent}], group_by?: [up to 2 output columns], totals?: [numeric output columns, summed per group and overall], params?: {fixed param values}, footer?, limit?: 1-5000, replaces the query limit; without it up to 5000 rows unless the query sets one}. The header carries the company name, address and phone from settings (company_name, company_address, company_phone), the print date and the params used.","additionalProperties":true}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"report_layouts.layout.delete","summary":"Delete a report layout for everyone","tags":["report_layouts"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Refused (409) while a report schedule sends it.","parameters":[{"name":"id","in":"path","required":true,"description":"Report layout id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/report-layouts/{id}/render":{"get":{"operationId":"report_layouts.layout.render","summary":"Render a report: printable HTML, CSV or JSON","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"format=html (default) answers a printable A4 page (print it or save it as PDF from the browser), csv the rows, json {title, columns, result}. Params as for queries.query.run.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Report layout id","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"html (default), csv or json","schema":{"type":"string","enum":["html","csv","json"]}},{"name":"params","in":"query","required":false,"description":"Param values as JSON; each may also be its own query key","schema":{"type":"object"}},{"name":"draft","in":"query","required":false,"description":"1: your draft","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/report-layouts/{id}/publish":{"post":{"operationId":"report_layouts.layout.publish","summary":"Publish a report layout draft to the whole company","tags":["report_layouts"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Needs its query published. `revision` (required) is the draft revision reviewed: 409 if the draft moved past it. An agent's call becomes a proposal.","parameters":[{"name":"id","in":"path","required":true,"description":"Report layout id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","description":"The draft revision to publish (draft.revision)"}},"required":["revision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/report-layouts/{id}/draft":{"delete":{"operationId":"report_layouts.draft.discard","summary":"Discard your draft of a report layout","tags":["report_layouts"],"x-voltrus-role":"any","x-voltrus-agent":"agent","parameters":[{"name":"id","in":"path","required":true,"description":"Report layout id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables":{"get":{"operationId":"user_tables.table.list","summary":"List the company's user-defined tables with their fields and record counts","tags":["user_tables"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"user_tables.table.create","summary":"Create a user-defined table (a new record type) with its fields","tags":["user_tables"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Its records live at /api/user-tables/{key}/records, in proposals as entity ud_<key>, and in saved queries as source ud_<key>. title_field (default: the first text field) names records in lists and search. Admin; an agent's call becomes a proposal.","x-voltrus-example":{"body":{"key":"vehicle","label":"Vehicles","fields":[{"key":"plate","label":"Plate number","type":"text","required":true},{"key":"capacity_kg","label":"Capacity (kg)","type":"number"},{"key":"kind","label":"Kind","type":"select","options":["truck","van","motorbike"]},{"key":"warehouse_id","label":"Home warehouse","type":"reference","ref_target":"warehouse"}]}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"snake_case, unique in the company, not starting with ud_"},"label":{"type":"string"},"description":{"type":"string"},"title_field":{"type":"string"},"fields":{"type":"array","items":{"type":"object","description":"{key (snake_case), label, type: text|number|date|boolean|select|reference, required?, options? (select), ref_target? (reference: an entity such as customer or item, or another user table ud_<key>), sort_order?}. key, type and ref_target never change.","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","boolean","select","reference"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"ref_target":{"type":"string"},"sort_order":{"type":"integer"}},"required":["key","label","type"]}}},"required":["key","label","fields"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables/search":{"get":{"operationId":"user_tables.record.search","summary":"Search records of every user-defined table by title or text value","tags":["user_tables"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"q","in":"query","required":true,"description":"At least 2 characters","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1-100, default 20","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables/{table}":{"get":{"operationId":"user_tables.table.get","summary":"Show one user-defined table with its fields","tags":["user_tables"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"user_tables.table.update","summary":"Rename a user-defined table or change its title field","tags":["user_tables"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","x-voltrus-idempotent":true,"parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"description":{"type":["string","null"]},"title_field":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"user_tables.table.delete","summary":"Delete a user-defined table and its records","tags":["user_tables"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Refused (409) while another table references it or a published query reads it.","parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables/{table}/fields":{"post":{"operationId":"user_tables.field.add","summary":"Add a field to a user-defined table","tags":["user_tables"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"A required field on a table that has records needs \"default\", written to every record in the same batch.","parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"{key (snake_case), label, type: text|number|date|boolean|select|reference, required?, options? (select), ref_target? (reference: an entity such as customer or item, or another user table ud_<key>), sort_order?}. key, type and ref_target never change.","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","boolean","select","reference"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"ref_target":{"type":"string"},"sort_order":{"type":"integer"},"default":{"description":"Value for existing records"}},"required":["key","label","type"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables/{table}/fields/{key}":{"patch":{"operationId":"user_tables.field.update","summary":"Change a user-table field's label, options, required flag or order","tags":["user_tables"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Removing a select option still in use, or requiring a field some records lack, is refused (409).","x-voltrus-idempotent":true,"parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Field key","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"user_tables.field.delete","summary":"Delete a user-table field and its values","tags":["user_tables"],"x-voltrus-role":"admin","x-voltrus-agent":"governed","description":"Refused (409) while a published query may read the field (its definition names the table and the field key), or for the title field.","parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Field key","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables/{table}/records":{"get":{"operationId":"user_tables.record.list","summary":"List records of a user-defined table","tags":["user_tables"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"q searches the title and text fields; any field key is an exact filter (?kind=truck); sort=field or -field (default -created_at).","x-voltrus-idempotent":true,"x-voltrus-paged":true,"parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Words in the title or a text field","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Field, title, created_at or updated_at; - for descending","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1-200, default 50","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"user_tables.record.create","summary":"Add a record to a user-defined table","tags":["user_tables"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"OPS write directly (201). An agent's call becomes an entity proposal (entity ud_<key>, 202 with proposal_id) an approver decides; explain it with X-Voltrus-Rationale.","parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Field values by field key, e.g. {\"plate\": \"B 1234 XY\", \"capacity_kg\": 2000}","additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/user-tables/{table}/records/{id}":{"get":{"operationId":"user_tables.record.get","summary":"Fetch one user-table record","tags":["user_tables"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"patch":{"operationId":"user_tables.record.update","summary":"Change fields of a user-table record","tags":["user_tables"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Send only the fields to change; null clears one. An agent's call becomes an entity proposal (202). expected_updated_at guards against a concurrent change (409).","x-voltrus-idempotent":true,"parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}},{"name":"expected_updated_at","in":"query","required":false,"description":"Refuse (409) if the record changed since","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Field values by field key, e.g. {\"plate\": \"B 1234 XY\", \"capacity_kg\": 2000}","additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"user_tables.record.delete","summary":"Delete a user-table record","tags":["user_tables"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","parameters":[{"name":"table","in":"path","required":true,"description":"Table key (or ud_<key>)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Record id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/config":{"get":{"operationId":"assistant.config.get","summary":"Show whether the assistant is available and how it is configured","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"provider (workers-ai or openai-compatible), transport (agent WebSocket or sse), models, capability check result, four-eyes setting, retention. Never the API key.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"assistant.config.set","summary":"Set the assistant provider, models, approval rule and retention","tags":["assistant"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"provider workers-ai (metered as AI credits) or openai-compatible (BYOK: base_url, api_key, chat_model, vision_model). api_key is stored encrypted; send \"\" to clear it. require_other_approver stops users approving proposals their own assistant made. retention_days for attachments.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["workers-ai","openai-compatible"]},"base_url":{"type":"string"},"api_key":{"type":"string"},"chat_model":{"type":"string"},"vision_model":{"type":"string"},"require_other_approver":{"type":"boolean"},"retention_days":{"type":"number"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/config/check":{"post":{"operationId":"assistant.config.check","summary":"Test the assistant provider for tool calling and vision","tags":["assistant"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Runs one tool call and, with a vision model, one image request. Without tool calling the provider cannot run the assistant.","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/usage":{"get":{"operationId":"assistant.usage.get","summary":"Show AI credit usage against the plan","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Your own usage; scope=tenant (admins) adds usage per user, per day and per kind for this month.","x-voltrus-idempotent":true,"parameters":[{"name":"scope","in":"query","required":false,"description":"me (default) or tenant","schema":{"type":"string","enum":["me","tenant"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/conversations":{"get":{"operationId":"assistant.conversations.list","summary":"List your assistant conversations","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"archived","in":"query","required":false,"description":"1 to include archived","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"assistant.conversations.create","summary":"Start an assistant conversation","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"Returns the conversation and agent_name, the instance the console connects to.","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/conversations/{id}":{"patch":{"operationId":"assistant.conversations.update","summary":"Rename or archive an assistant conversation","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"agent","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation or attachment id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"archived":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"assistant.conversations.delete","summary":"Delete an assistant conversation","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"agent","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation or attachment id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/conversations/{id}/chat":{"post":{"operationId":"assistant.conversations.chat","summary":"Send a message and stream the reply (servers without Durable Objects)","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"On-prem transport: a UI message stream over HTTP. Cloud consoles use the WebSocket at /agents/voltrus-chat/{agent_name}.","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation or attachment id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/conversations/{id}/messages":{"get":{"operationId":"assistant.conversations.messages","summary":"Read the messages of a conversation (servers without Durable Objects)","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation or attachment id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/attachments":{"get":{"operationId":"assistant.attachments.list","summary":"List the attachments of a conversation","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"conversation_id","in":"query","required":true,"description":"Conversation id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"assistant.attachments.upload","summary":"Upload a file to a conversation","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"agent","description":"multipart/form-data: file, conversation_id, extract (JSON from the browser: sheets, text pages, scanned page numbers), page_<n> (rendered scanned pages). PDF, images, Excel/ODS/Numbers, CSV, Word (.docx), text; 20 MB per file, 50 pages, 20,000 rows per sheet.","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/attachments/{id}/file":{"get":{"operationId":"assistant.attachments.file","summary":"Download an attachment or one of its rendered pages","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation or attachment id","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Rendered page number of a scanned PDF","schema":{"type":"number"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/attachments/{id}":{"delete":{"operationId":"assistant.attachments.delete","summary":"Delete an attachment","tags":["assistant"],"x-voltrus-role":"any","x-voltrus-agent":"agent","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation or attachment id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/assistant/imports/{id}/apply":{"post":{"operationId":"assistant.imports.apply","summary":"Apply a staged spreadsheet import batch","tags":["assistant"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Writes the rows of an import batch staged by the assistant (stage_import): creates new records and updates existing ones by natural key, through the same validation as single creates. The body carries the batch hash, counts and a sample for the approver; a changed batch is refused. Up to 500 rows per approval; already applied rows are skipped, so a failed or partial batch continues on the next approval.","parameters":[{"name":"id","in":"path","required":true,"description":"Import batch id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch_id":{"type":"string"},"entity":{"type":"string"},"hash":{"type":"string"},"counts":{"type":"object"},"sample":{"type":"array","items":{"type":"object"}}},"required":["hash"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging":{"get":{"operationId":"messaging.get","summary":"Show the Telegram and WhatsApp connections and your own links and notice switches","tags":["messaging"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Tokens are never returned, only their first and last characters.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/telegram":{"put":{"operationId":"messaging.telegram.connect","summary":"Connect the company Telegram bot","tags":["messaging"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Checks the @BotFather token (getMe), stores it encrypted and points the bot webhook at this server when it is reachable over https. A token Telegram refuses is 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Bot token from @BotFather"}},"required":["token"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/whatsapp":{"put":{"operationId":"messaging.whatsapp.connect","summary":"Connect the company WhatsApp Business number (Cloud API) and name its templates","tags":["messaging"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Checks the number with the Graph API and stores the token encrypted; without token the stored one is kept. templates maps notice, invoice_issued, invoice_reminder, order_shipped and po_sent to Meta-approved template names.","x-voltrus-example":{"body":{"phone_number_id":"123456789012345","language":"id","templates":{"notice":"voltrus_notice","invoice_reminder":"voltrus_invoice_reminder"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Permanent system-user access token"},"phone_number_id":{"type":"string","description":"Numeric phone number id from WhatsApp Manager"},"language":{"type":"string","description":"Template language code, default id"},"templates":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/{provider}":{"delete":{"operationId":"messaging.disconnect","summary":"Disconnect Telegram or WhatsApp","tags":["messaging"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Forgets the token; messages still waiting over it fail. Links people made stay for a reconnect.","parameters":[{"name":"provider","in":"path","required":true,"description":"telegram or whatsapp","schema":{"type":"string","enum":["telegram","whatsapp"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/telegram/link":{"post":{"operationId":"messaging.telegram.link","summary":"Get a one-time link that connects your Telegram to your notices","tags":["messaging"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Open it in Telegram and press Start. Valid 30 minutes. OPS people only; a shared token has no person behind it (409).","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/telegram/link/check":{"post":{"operationId":"messaging.telegram.link_check","summary":"Check whether your Telegram is linked","tags":["messaging"],"x-voltrus-role":"any","x-voltrus-agent":"denied","description":"Where Telegram cannot reach the server (no webhook), reads the bot updates and applies pending Start presses first.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/whatsapp/me":{"put":{"operationId":"messaging.whatsapp.me","summary":"Set your own WhatsApp number for notices","tags":["messaging"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Entering it is your opt-in (recorded in the audit). 08… numbers are read as Indonesian.","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string"}},"required":["phone"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/{provider}/me":{"delete":{"operationId":"messaging.me.unlink","summary":"Stop notices to you over Telegram or WhatsApp","tags":["messaging"],"x-voltrus-role":"any","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"parameters":[{"name":"provider","in":"path","required":true,"description":"telegram or whatsapp","schema":{"type":"string","enum":["telegram","whatsapp"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/preferences":{"put":{"operationId":"messaging.preferences.set","summary":"Turn one notice type on or off for you on one channel","tags":["messaging"],"x-voltrus-role":"any","x-voltrus-agent":"denied","x-voltrus-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["proposal_pending","proposal_decision","invoice_overdue","stock_low","mention","billing","automation","activity"]},"provider":{"type":"string","enum":["telegram","whatsapp"]},"enabled":{"type":"boolean"}},"required":["type","provider","enabled"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/test":{"post":{"operationId":"messaging.test","summary":"Send yourself a test notice on every linked channel","tags":["messaging"],"x-voltrus-role":"any","x-voltrus-agent":"denied","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/whatsapp/send":{"post":{"operationId":"messaging.whatsapp.send","summary":"Send a customer or supplier a WhatsApp message about a document","tags":["messaging"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"kind invoice_issued or invoice_reminder (customer invoice), order_shipped (sales order), po_sent (purchase order). Uses the template the admin named for the kind and the document's contact phone, or to. Refused (409) without a template, a phone, or when one is already waiting. An agent asking for it creates a proposal: the message goes out once an approver approves.","x-voltrus-example":{"body":{"kind":"invoice_reminder","id":"<invoice id>"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["invoice_issued","invoice_reminder","order_shipped","po_sent"]},"id":{"type":"string","description":"Invoice, sales order or purchase order id"},"to":{"type":"string","description":"WhatsApp number; default the document contact"}},"required":["kind","id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/deliveries":{"get":{"operationId":"messaging.deliveries.list","summary":"List Telegram and WhatsApp messages sent, waiting or failed","tags":["messaging"],"x-voltrus-role":"admin","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"status","in":"query","required":false,"description":"pending, sent or failed","schema":{"type":"string","enum":["pending","sent","failed"]}},{"name":"ref_entity","in":"query","required":false,"description":"Only messages about this entity","schema":{"type":"string"}},{"name":"ref_id","in":"query","required":false,"description":"Only messages about this record","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"At most this many (default 100, max 500)","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/messaging/deliveries/{id}/retry":{"post":{"operationId":"messaging.deliveries.retry","summary":"Send a failed message again","tags":["messaging"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","parameters":[{"name":"id","in":"path","required":true,"description":"Message delivery id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs":{"get":{"operationId":"payroll.runs.list","summary":"List payroll runs with their gross, net and PPh 21","tags":["payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"period","in":"query","required":false,"description":"Only this month (YYYY-MM)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs/{id}":{"get":{"operationId":"payroll.runs.get","summary":"Show a payroll run: totals per cost centre and, for a draft, the journal it will post","tags":["payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Payroll run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs/import":{"post":{"operationId":"payroll.runs.import","summary":"Import a month's payroll export (Talenta or any CSV) as a draft run","tags":["payroll"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"One row per employee or per cost centre; rows are grouped by cost centre and no amount per person is kept. Columns are found by name (gross, bpjs_kes_company, jht_company, jp_company, jkk, jkm, bpjs_kes_employee, jht_employee, jp_employee, pph21, other_deductions, net_pay, cost_center; Talenta and Indonesian names too) or mapped with columns. A row whose net pay is not gross less the employee BPJS, PPh 21 and other deductions is refused (400), as is a second live run for the same period and reference (409).","x-voltrus-example":{"body":{"period":"2026-11","csv":"cost_center,headcount,gross,jht_company,jht_employee,pph21,net_pay\nPROD,12,96000000,3552000,1920000,2100000,91980000"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"YYYY-MM"},"csv":{"type":"string"},"pay_date":{"type":"string","format":"date","description":"Journal date; default the last day of the period"},"reference":{"type":"string","description":"Tells two runs of one month apart (THR, a correction run)"},"source":{"type":"string","enum":["csv","talenta"]},"columns":{"type":"object","additionalProperties":{"type":"string"},"description":"field → CSV header"},"cost_centers":{"type":"object","additionalProperties":{"type":"string"},"description":"value in the file → cost centre id"},"notes":{"type":"string"}},"required":["period","csv"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs/{id}/post":{"post":{"operationId":"payroll.runs.post","summary":"Post a draft payroll run to the ledger","tags":["payroll"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Dr salary_expense and bpjs_expense per cost centre / Cr pph21_payable, bpjs_payable, payroll_deductions, salaries_payable, on the pay date.","parameters":[{"name":"id","in":"path","required":true,"description":"Payroll run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs/{id}/pay":{"post":{"operationId":"payroll.runs.pay","summary":"Record paying net salaries or the BPJS bill of a posted run","tags":["payroll"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"what net: Dr salaries_payable; what bpjs: Dr bpjs_payable (both shares); Cr the bank account (cash key when none). PPh 21 is a tax remittance (tax_type pph21).","parameters":[{"name":"id","in":"path","required":true,"description":"Payroll run id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"what":{"type":"string","enum":["net","bpjs"]},"paid_at":{"type":"string","format":"date"},"bank_account_id":{"type":"string","description":"GL asset account in IDR"}},"required":["what"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs/{id}/void":{"post":{"operationId":"payroll.runs.void","summary":"Void a payroll run (a posted one is reversed)","tags":["payroll"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"A posted run with a payment recorded is refused (409): reverse the payment first.","parameters":[{"name":"id","in":"path","required":true,"description":"Payroll run id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/talenta":{"get":{"operationId":"payroll.talenta.get","summary":"Show the Talenta API connection and which organization feeds which cost centre","tags":["payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"The client secret is never returned.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"payroll.talenta.connect","summary":"Connect the Talenta API with Mekari HMAC credentials (admin)","tags":["payroll"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"client_secret is stored encrypted and kept when omitted. organizations maps Talenta organization ids to cost centres; without it a pull is one company-wide line.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"environment":{"type":"string","enum":["production","sandbox"],"default":"production"},"organizations":{"type":"object","additionalProperties":{"type":"string"},"description":"{\"<talenta organization id>\": \"<cost centre code>\"}"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"payroll.talenta.disconnect","summary":"Disconnect the Talenta API and erase its secret (admin)","tags":["payroll"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payroll/runs/import-talenta":{"post":{"operationId":"payroll.runs.import_talenta","summary":"Create a draft payroll run from Talenta's payroll report for a month","tags":["payroll"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"Reads GET /v2/talenta/v3/payroll/report per mapped organization (company totals, no employee data). Gross is basic salary plus allowances; employee BPJS and PPh 21 by name among deductions; company BPJS among benefits; other deductions make up the take-home pay. A benefit that is not BPJS is refused. 409 for a month already imported (give another reference).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"YYYY-MM"},"pay_date":{"type":"string","format":"date","description":"Default the last day of the month"},"reference":{"type":"string","description":"e.g. THR for a second run in the month"},"notes":{"type":"string"}},"required":["period"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/gateway":{"get":{"operationId":"payments.gateway.get","summary":"Show the DOKU connection and the notification path to enter in the DOKU Back Office","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"The secret key is never returned, only its last characters.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/gateway/doku":{"put":{"operationId":"payments.gateway.doku.connect","summary":"Connect DOKU Checkout (admin)","tags":["payments"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Client-Id and Secret Key from the DOKU Back Office (secret kept when omitted), sandbox or production, and the GL asset account receipts land in until DOKU settles.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"secret_key":{"type":"string"},"environment":{"type":"string","enum":["sandbox","production"],"default":"sandbox"},"clearing_account_id":{"type":"string","description":"GL asset account, e.g. \"Saldo DOKU\""},"due_minutes":{"type":"integer","minimum":15,"maximum":43200,"default":4320,"description":"How long a payment page stays open"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"delete":{"operationId":"payments.gateway.doku.disconnect","summary":"Disconnect DOKU and erase its secret key (admin)","tags":["payments"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/links":{"get":{"operationId":"payments.links.list","summary":"List DOKU payment links, newest first","tags":["payments"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"invoice_id","in":"query","required":false,"description":"Only this invoice","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Link status","schema":{"type":"string","enum":["pending","paid","failed","expired","cancelled"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"post":{"operationId":"payments.links.create","summary":"Create a DOKU payment page for an open customer invoice","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"For the invoice's open amount in IDR (issued or partly paid). A pending link for the same amount that has not expired is answered again. When the customer pays, DOKU's notification books the receipt into the clearing account and the invoice is paid.","x-voltrus-low-risk":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/payments/links/{id}/cancel":{"post":{"operationId":"payments.links.cancel","summary":"Stop offering a pending payment link","tags":["payments"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","x-voltrus-low-risk":true,"parameters":[{"name":"id","in":"path","required":true,"description":"Payment link id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/settings":{"get":{"operationId":"hr.settings.get","summary":"Show HR, attendance and payroll settings","tags":["hr"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"hr: geofence {lat, lng, radius_m} or null, require_photo, require_face, face_threshold, face_margin, contractor_induction_required. payroll (payroll users only): late_rule and early_rule {policy: none|flat_per_day|per_minute|percent_per_day|tiered, …}, minimum_wage, jkk_rate, statutory_overrides, proration, overtime_requires_approval, deduct_absence. payroll_users, hr_approvers, agent_payroll_access, and can_payroll for the caller.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}},"put":{"operationId":"hr.settings.set","summary":"Change HR, attendance and payroll settings","tags":["hr"],"x-voltrus-role":"admin","x-voltrus-agent":"denied","description":"Admin only. Partial: {hr?, payroll?, payroll_users?, hr_approvers?, agent_payroll_access?}; keys left out keep their value.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hr":{"type":"object","additionalProperties":true},"payroll":{"type":"object","additionalProperties":true},"payroll_users":{"type":"array","items":{"type":"string"},"description":"Logins (username or email) that read and run payroll"},"hr_approvers":{"type":"array","items":{"type":"string"},"description":"Logins that approve leave and overtime for everyone"},"agent_payroll_access":{"type":"boolean","description":"Let agents read pay data (FR-36)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/me":{"get":{"operationId":"hr.me.get","summary":"Show the caller as an employee: today, this week, leave balance, check-in rules","tags":["hr"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"The employee whose email is the caller's login; employee null when none is linked.","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/check-in":{"post":{"operationId":"hr.attendance.check_in","summary":"Check the signed-in employee in or out","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"denied","description":"event_type in|out (default: out after a recent in, else in). The company may require location inside its geofence (lat, lng, accuracy_m), a photo (data URL) and a face match (embedding). Agents are refused.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"type":"string","enum":["in","out"]},"lat":{"type":"number"},"lng":{"type":"number"},"accuracy_m":{"type":"number"},"photo":{"type":"string","description":"data:image/jpeg;base64,…"},"embedding":{"type":"array","items":{"type":"number"},"description":"512 numbers: a face embedding from the console face engine or a kiosk"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/days":{"get":{"operationId":"hr.attendance.days","summary":"List attendance days: shift, first in, last out, late, early, overtime, status","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"One row per employee and day, derived from events, roster, holidays and approved leave. status present|late|absent|leave|holiday|off|scheduled. overtime_minutes is what payroll may pay (approved and worked). Default range: the last 7 days.","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, YYYY-MM-DD (default today)","schema":{"type":"string","format":"date"}},{"name":"employee_id","in":"query","required":false,"description":"One employee","schema":{"type":"string"}},{"name":"cost_center_id","in":"query","required":false,"description":"One department (cost centre)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only days with this status","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/summary":{"get":{"operationId":"hr.attendance.summary","summary":"Summarise attendance per employee over a range","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Working, present, late, absent, leave and holiday days; late, early, worked and overtime minutes; missing check-outs. Default: the last 30 days.","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, YYYY-MM-DD (default today)","schema":{"type":"string","format":"date"}},{"name":"employee_id","in":"query","required":false,"description":"One employee","schema":{"type":"string"}},{"name":"cost_center_id","in":"query","required":false,"description":"One department (cost centre)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/board":{"get":{"operationId":"hr.attendance.board","summary":"Show who is in, late or absent on a day","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"date","in":"query","required":false,"description":"Day, YYYY-MM-DD (default today)","schema":{"type":"string","format":"date"}},{"name":"cost_center_id","in":"query","required":false,"description":"One department","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/export":{"get":{"operationId":"hr.attendance.export","summary":"Download attendance days as CSV","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, YYYY-MM-DD (default today)","schema":{"type":"string","format":"date"}},{"name":"employee_id","in":"query","required":false,"description":"One employee","schema":{"type":"string"}},{"name":"cost_center_id","in":"query","required":false,"description":"One department (cost centre)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/import":{"post":{"operationId":"hr.attendance.import","summary":"Import check-ins from a fingerprint machine export (CSV)","tags":["hr","attendance"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Columns employee_id, ts (ISO, or \"YYYY-MM-DD HH:MM\" in the company zone), event_type (in|out; empty alternates per employee and day). dry_run defaults to true; events already there are skipped. HR approvers and admins.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"dry_run":{"type":"boolean"}},"required":["csv"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/employees/import":{"post":{"operationId":"hr.employees.import","summary":"Import employees from a CSV (dry run first)","tags":["hr"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Columns by name, English or Indonesian (code/kode, name/nama, department/departemen, shift, join_date/tanggal_masuk, nik, npwp, ptkp_status, bank fields, …); code and name are required. Department, shift and work centre cells take the id or the name. Pay columns (pay_model, base_salary, daily_rate, hourly_rate, labor_cost_rate) fill employee_pay and need payroll access. dry_run defaults to true; an existing code is skipped unless update is true. HR approvers and admins.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"dry_run":{"type":"boolean"},"update":{"type":"boolean"}},"required":["csv"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/anomalies":{"get":{"operationId":"hr.attendance.anomalies","summary":"Find repeated lateness, absences, missing check-outs and check-ins outside the geofence","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, YYYY-MM-DD (default today)","schema":{"type":"string","format":"date"}},{"name":"employee_id","in":"query","required":false,"description":"One employee","schema":{"type":"string"}},{"name":"cost_center_id","in":"query","required":false,"description":"One department (cost centre)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/attendance/photos/{id}":{"get":{"operationId":"hr.attendance.photo","summary":"Show the proof photo of a check-in","tags":["hr","attendance"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"For HR approvers, payroll users, admins and the employee.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"attendance_event id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/leave/balance":{"get":{"operationId":"hr.leave.balance","summary":"Show leave quota, used and pending days per leave type","tags":["hr","leave"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"employee_id","in":"query","required":false,"description":"Employee (default: the caller)","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"Calendar year (default this year)","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/approval/{entity}/{id}":{"get":{"operationId":"hr.approval.get","summary":"Show who may approve a leave or overtime request","tags":["hr","leave"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"entity","in":"path","required":true,"description":"leave_request or overtime_request","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Request id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/face/consent":{"post":{"operationId":"hr.face.consent","summary":"Record or withdraw an employee's consent to face recognition","tags":["hr","face"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"consent false deletes their face templates (UU PDP, FR-39). HR approvers, payroll users and admins.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"consent":{"type":"boolean"}},"required":["employee_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/face/templates":{"get":{"operationId":"hr.face.templates.list","summary":"List who has consented and how many face templates each has","tags":["hr","face"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Counts only; templates never leave the server.","x-voltrus-idempotent":true,"parameters":[{"name":"employee_id","in":"query","required":false,"description":"One employee","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/face/enroll":{"post":{"operationId":"hr.face.enroll","summary":"Enrol face embeddings for an employee who consented","tags":["hr","face"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Up to 10 templates per employee (several poses); replace: true starts over. Refused when a template looks like another enrolled employee.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"embeddings":{"type":"array","items":{"type":"array","items":{"type":"number"},"description":"512 numbers: a face embedding from the console face engine or a kiosk"}},"poses":{"type":"array","items":{"type":"string"}},"replace":{"type":"boolean"}},"required":["employee_id","embeddings"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/face/templates/{employee}":{"delete":{"operationId":"hr.face.templates.delete","summary":"Delete an employee's face templates","tags":["hr","face"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","parameters":[{"name":"employee","in":"path","required":true,"description":"Employee code","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/face/identify":{"post":{"operationId":"hr.face.identify","summary":"Identify a face against the enrolled employees (console kiosk mode)","tags":["hr","face"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"Returns the best match above the threshold unless ambiguous. record: true also records the matched employee's event (event_type in|out, source kiosk).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"embedding":{"type":"array","items":{"type":"number"},"description":"512 numbers: a face embedding from the console face engine or a kiosk"},"record":{"type":"boolean"},"event_type":{"type":"string","enum":["in","out"]}},"required":["embedding"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/payroll/runs/{id}/lines":{"get":{"operationId":"hr.payroll.lines","summary":"List a payroll run's lines with their breakdown","tags":["hr","payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Payroll users and admins (FR-36).","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"pay_run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/payroll/runs/{id}/payslips/{employee}":{"get":{"operationId":"hr.payroll.payslip","summary":"Show one employee's payslip in a payroll run","tags":["hr","payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"Payroll users and admins; an employee sees their own once the run is posted.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"pay_run id","schema":{"type":"string"}},{"name":"employee","in":"path","required":true,"description":"Employee code","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/payroll/runs/{id}/payslips/{employee}/pdf":{"get":{"operationId":"hr.payroll.payslip_pdf","summary":"Download a payslip as PDF","tags":["hr","payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","description":"One A4 page, bilingual labels. The employee themself once the run is posted; payroll users and admins always.","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"pay_run id","schema":{"type":"string"}},{"name":"employee","in":"path","required":true,"description":"Employee code","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/payroll/runs/{id}/email-payslips":{"post":{"operationId":"hr.payroll.email_payslips","summary":"Email each employee their payslip PDF","tags":["hr","payroll"],"x-voltrus-role":"ops","x-voltrus-agent":"denied","description":"For a posted or paid run: sends each employee the PDF at the email on their employee record (never anyone else's). employee_ids narrows it to a re-send. Without the SEND_EMAIL binding nothing is sent and the note says so. Payroll users and admins.","parameters":[{"name":"id","in":"path","required":true,"description":"pay_run id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/payroll/runs/{id}/bank-file":{"get":{"operationId":"hr.payroll.bank_file","summary":"Download a payroll run's bank transfer list (CSV)","tags":["hr","payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"id","in":"path","required":true,"description":"pay_run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/payroll/my-payslips":{"get":{"operationId":"hr.payroll.my_payslips","summary":"List the caller's own posted payslips","tags":["hr","payroll"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/labor/clock-on":{"post":{"operationId":"hr.labor.clock_on","summary":"Clock an employee on to a work order (step)","tags":["hr","labor"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","description":"employee_id defaults to the caller's employee. Clocking on to another job clocks off the current one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"work_order_id":{"type":"string"},"work_order_step_id":{"type":"string"},"source":{"type":"string","enum":["console","mobile","kiosk"]}},"required":["work_order_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/labor/clock-off":{"post":{"operationId":"hr.labor.clock_off","summary":"Clock an employee off their current job","tags":["hr","labor"],"x-voltrus-role":"ops","x-voltrus-agent":"governed","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"labor_entry_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/labor/open":{"get":{"operationId":"hr.labor.open","summary":"List who is clocked on to which job now","tags":["hr","labor"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/labor/utilization":{"get":{"operationId":"hr.labor.utilization","summary":"Compare time on jobs with time present, per employee","tags":["hr","labor"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"parameters":[{"name":"from","in":"query","required":false,"description":"First day","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day","schema":{"type":"string","format":"date"}},{"name":"cost_center_id","in":"query","required":false,"description":"One department","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}},"/api/hr/visitors/on-site":{"get":{"operationId":"hr.visitors.on_site","summary":"List visitors and contractors on site now (evacuation list)","tags":["hr","visitors"],"x-voltrus-role":"any","x-voltrus-agent":"read","x-voltrus-idempotent":true,"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid input: { error }"},"403":{"description":"Not allowed: { error, hint }"},"404":{"description":"Not found: { error }"},"409":{"description":"Conflicts with the current state: { error }"}}}}}}