Resources
The API has two kinds of resources:
- Master data: items, partners, storages, VAT rates and other lists.
- Documents: invoices, orders, goods receipts and other business documents. Most documents have lines.
Each resource is under its module: /api/v1/<tenant>/<module>/<resource>. The tables at the end of this page list every path.
The routes of a resource
Section titled “The routes of a resource”| Action | Route | Answer |
|---|---|---|
| List | GET /<path> |
200, an array of records |
| Read | GET /<path>/:id |
200, one record |
| Create | POST /<path> |
201, the new record |
| Update | PATCH /<path>/:id |
200, the saved record |
| Delete | DELETE /<path>/:id |
200, { "data": { "id": "…" } } |
A document has more routes:
| Action | Route | Rule |
|---|---|---|
| Read the lines | GET /<path>/:id/items |
|
| Add a line | POST /<path>/:id/items |
Only on an unconfirmed document |
| Change a line | PATCH /<path>/:id/items/:itemId |
Only on an unconfirmed document |
| Delete a line | DELETE /<path>/:id/items/:itemId |
Only on an unconfirmed document |
| Confirm | POST /<path>/:id/confirm |
The document needs at least one line, if it has lines |
| Unconfirm | POST /<path>/:id/unconfirm |
|
| Convert | POST /<path>/:id/convert/:target |
Makes a new document from this one |
| Copy | POST /<path>/:id/copy |
Makes an unsaved copy without a number |
| Cancel, restore | POST /<path>/:id/cancel, POST /<path>/:id/restore |
Only an unconfirmed document is cancelled |
| Connections | GET /<path>/:id/connections |
The documents that this one comes from or goes to |
Some documents have more routes. Some documents refuse an action: for example, a document that only a conversion makes refuses a create.
Rules for writes
Section titled “Rules for writes”- Update sends only the fields that change. The API merges them with the stored record and checks the whole record.
- Create takes an optional
id, a UUID that your program makes. Then a retry of the same create gets409and does not make a second record. Without anid, the API makes one. - Delete of a confirmed document gets
422. Unconfirm it first. - Most documents get their number on the first save with a
PATCH. Before that, the number (uid) ends with#.
Worked example: a sales invoice
Section titled “Worked example: a sales invoice”This example makes an invoice for a service, adds one line and confirms it. Set two variables first:
POSTO=https://app.postoerp.com/api/v1/acmePOSTO_API_KEY=posto_pk_... # your key secret1. Find the master data
Section titled “1. Find the master data”Find the IDs of the partner, the item and the VAT rate:
curl "$POSTO/masters/subjects" -H "Authorization: Bearer $POSTO_API_KEY"curl "$POSTO/masters/items" -H "Authorization: Bearer $POSTO_API_KEY"curl "$POSTO/masters/vats" -H "Authorization: Bearer $POSTO_API_KEY"2. Create the invoice
Section titled “2. Create the invoice”Send the document type:
curl "$POSTO/sales/invoices" \ -H "Authorization: Bearer $POSTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"documentType": "SALES_INVOICE"}'The answer is 201 with the new invoice. Its number has no sequence yet:
{ "data": { "id": "01a1d5a5-e127-7a93-87ce-f790c2ad2cf3", "uid": "26-330-#", "isConfirmed": false, "subjectId": null } }3. Save the header
Section titled “3. Save the header”Set the partner and the due days. This first save gives the invoice its number:
curl -X PATCH "$POSTO/sales/invoices/$INVOICE_ID" \ -H "Authorization: Bearer $POSTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"subjectId": "'"$PARTNER_ID"'", "dueDays": 30}'{ "data": { "id": "01a1d5a5-e127-7a93-87ce-f790c2ad2cf3", "uid": "26-330-5", "dueDays": 30, "dateDue": "2026-12-13" } }Without a partner, the answer is 422:
{ "error": { "code": "validation", "message": "Partner is missing.", "fields": { "subjectId": "Partner is missing." } } }4. Add a line
Section titled “4. Add a line”curl "$POSTO/sales/invoices/$INVOICE_ID/items" \ -H "Authorization: Bearer $POSTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"itemId": "'"$SERVICE_ID"'", "quantity": 2, "price": 100, "vatId": "'"$VAT_ID"'"}'The answer is 201 with the line and its totals:
{ "data": { "id": "…", "quantity": 2, "price": 100, "vatPercent": 18, "totalNet": 200, "totalVatAmount": 36, "totalGross": 236 } }5. Confirm the invoice
Section titled “5. Confirm the invoice”curl -X POST "$POSTO/sales/invoices/$INVOICE_ID/confirm" \ -H "Authorization: Bearer $POSTO_API_KEY"{ "data": { "uid": "26-330-5", "isConfirmed": true, "grandTotalNet": 200, "grandTotalVatAmount": 36, "grandTotalGross": 236 } }A second confirm gets 422 “The document is already confirmed.”
Convert: an invoice with goods
Section titled “Convert: an invoice with goods”An invoice with goods needs a confirmed goods issue before its confirm. Without one, the confirm gets 422 “No confirmed goods issue.” Convert the invoice to a goods issue:
curl -X POST "$POSTO/sales/invoices/$INVOICE_ID/convert/movement" \ -H "Authorization: Bearer $POSTO_API_KEY"The answer is 201 with the new document and its path:
{ "data": { "id": "01a1d5a6-aaee-73b8-ae30-3cbe32e45f89", "documentTypeId": 4, "url": "/inventory/issues/01a1d5a6-aaee-73b8-ae30-3cbe32e45f89" } }Confirm the goods issue at POST /inventory/issues/:id/confirm, then confirm the invoice. An unknown conversion target gets 404 “Unknown conversion.”
These are the conversion targets of the sales documents:
| From | Target | Makes |
|---|---|---|
/sales/quotes |
order |
A sales order |
/sales/orders |
invoice |
An invoice |
/sales/orders |
movement |
A goods issue |
/sales/invoices |
movement |
A goods issue |
All resources
Section titled “All resources”The paths are below /api/v1/<tenant>. “Lines” shows the documents that have the routes of their lines.
Documents
Section titled “Documents”| Module | Document | Path | Lines |
|---|---|---|---|
| Inventory | Goods receipts | /inventory/receipts |
Yes |
| Inventory | Valuations | /inventory/valuations |
Yes |
| Inventory | Goods issues | /inventory/issues |
Yes |
| Inventory | Transfers | /inventory/transfers |
Yes |
| Inventory | Consumptions | /inventory/consumptions |
Yes |
| Inventory | Stock adjustments | /inventory/adjustments |
Yes |
| Inventory | Stock counts | /inventory/counts |
Yes |
| Retail | Retail valuations | /retail/valuations |
Yes |
| Retail | Bills | /retail/pos/transactions |
Yes |
| Retail | End of day reports | /retail/pos-end-of-days |
No |
| Sales | Quotes | /sales/quotes |
Yes |
| Sales | Sales orders | /sales/orders |
Yes |
| Sales | Invoices | /sales/invoices |
Yes |
| Sales | Consolidated invoices | /sales/consolidated-invoices |
Yes |
| Sales | Loans and gifts | /sales/issues |
Yes |
| Sales | Sales returns | /sales/returns |
Yes |
| Purchasing | Requisitions | /purchasing/requisitions |
Yes |
| Purchasing | Purchase orders | /purchasing/orders |
Yes |
| Purchasing | Purchase returns | /purchasing/returns |
Yes |
| Pricing | Price changes | /pricing/price-changes |
Yes |
| Salary | Payroll registers | /payroll/registers |
Yes |
| Fixed assets | Asset receipts | /assets/receipts |
Yes |
| Fixed assets | Asset write-offs | /assets/write-offs |
Yes |
| Fixed assets | Depreciations | /assets/depreciations |
Yes |
| Finance | Journals | /finance/journals |
Yes |
| Finance | Vendor bills | /finance/vendor-bills |
Yes |
| Finance | Credit memos | /finance/memo-credits |
Yes |
| Finance | Debit memos | /finance/memo-debits |
Yes |
| Finance | Payments | /finance/payments |
Yes |
| Finance | Bank reconciliations | /finance/bank-reconciliations |
Yes |
| Cash | Cash payments | /cash/issues |
No |
| Cash | Cash receipts | /cash/receipts |
No |
Master data
Section titled “Master data”All master data is in the module masters.
| Master data | Path |
|---|---|
| Asset categories | /masters/asset-categories |
| Assets | /masters/assets |
| Bank accounts | /masters/bank-accounts |
| Banks | /masters/banks |
| Cash registers | /masters/cash-registers |
| Chart of accounts - Analytic | /masters/accounts |
| Chart of accounts - Classes | /masters/account-types |
| Chart of accounts - Groups | /masters/account-groups |
| Chart of accounts - Synthetic | /masters/account-subgroups |
| Cities | /masters/cities |
| Contacts | /masters/contacts |
| Departments | /masters/departments |
| Discount groups - Items | /masters/item-discount-groups |
| Discount groups - Partners | /masters/subject-discount-groups |
| Discount matrix | /masters/discount-group-mappings |
| Employees | /masters/employees |
| Fiscal devices | /masters/fiscal-devices |
| Item attributes | /masters/item-attributes |
| Item categories | /masters/item-categories |
| Items | /masters/items |
| Journal types | /masters/journal-types |
| Locations | /masters/locations |
| Municipalities | /masters/counties |
| Partner categories | /masters/subject-categories |
| Partners | /masters/subjects |
| Payment methods | /masters/payment-methods |
| Profit centers | /masters/profit-centers |
| Salary components | /masters/salary-structure-item-categories |
| Salary structures | /masters/salary-structures |
| Storages | /masters/storages |
| Tags | /masters/tags |
| Tills | /masters/pos |
| VAT rates | /masters/vats |