Skip to content

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.

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.

  • 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 gets 409 and does not make a second record. Without an id, 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 #.

This example makes an invoice for a service, adds one line and confirms it. Set two variables first:

Terminal window
POSTO=https://app.postoerp.com/api/v1/acme
POSTO_API_KEY=posto_pk_... # your key secret

Find the IDs of the partner, the item and the VAT rate:

Terminal window
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"

Send the document type:

Terminal window
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 } }

Set the partner and the due days. This first save gives the invoice its number:

Terminal window
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." } } }
Terminal window
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 } }
Terminal window
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.”

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:

Terminal window
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

The paths are below /api/v1/<tenant>. “Lines” shows the documents that have the routes of their lines.

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

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