SimpleERP API#

Use HTTP against the SimpleERP backend. Read domain examples only from the linked reference files; this file stays a navigator and global rules.

Agent execution policy#

• If completing the user request requires running commands/scripts (including curl commands or PowerShell Invoke-WebRequest / Invoke-RestMethod), run them automatically. Do not ask the user to run/execute anything.
• GET /api/health may run without an API key. All other HTTP calls need a resolved x-api-key per Credentials below; if no key is available after that resolution, ask once for the key before issuing authenticated requests (then continue running commands automatically).

Environment#

• Base URL: http://localhost:3000. Resource paths are under /api (example: http://localhost:3000/api/products). If the user names another host, use it instead of localhost.
• Clients: Prefer curl on Unix-like shells; on Windows, curl.exe or Invoke-WebRequest / Invoke-RestMethod in PowerShell.

Credentials#

• Header: x-api-key on every request except GET /api/health.

• Resolution order: (1) API key the user provided in this conversation, if any; (2) environment variable SIMPLEERP_API_KEY; (3) if still missing, ask once for the key, then proceed.

• Do not invent keys, search arbitrary files for secrets, or read unrelated workspace paths to find credentials.

• Production: Admin routes need admin_access. Most resources map to explicit PERMISSION_ID checks; a few route modules use permissions.<name> || {} in code, and where that map has no entry yet, requirePermission receives a falsy id and does not enforce a named permission (API key still required). See references/ENDPOINTS.md (Notes).

Minimal GET example

bash

curl "http://localhost:3000/api/health"

powershell

Invoke-WebRequest -Method GET -Uri "http://localhost:3000/api/health"

Template

bash

curl "http://localhost:3000/api/<resource>?<query_params>"

Domain reference map#

NeedOpenAll paths, methods, auth notesreferences/ENDPOINTS.mdSys-par, currencies, warehouses, partners, customers, suppliersreferences/master-data-endpoints.mdProducts, price lists, related master datareferences/products-and-pricing.mdInventory, deliveries, transfers, adjustmentsreferences/inventory-and-deliveries.mdSale/purchase orders, invoices, paymentsreferences/documents-sales-purchasing.mdReturns, credit memos, debit notesreferences/returns-and-memos.mdUsers, API keys, permissionsreferences/admin-and-permissions.mdChained flows (customer → sale order, etc.)references/workflows.mdReport route copy-paste curlsreferences/reports.mdList query allowlists ( buildFilters), workspace pathsreferences/query-filters.md

Dynamic list query filters#

Most list endpoints build WHERE from a fixed allowlist of query parameters (bind variables; unknown params ignored). See references/query-filters.md for how buildFilters works and workspace-root-relative paths to simpleerp-api source files.

• Common: limit, offset on list endpoints; many support status or foreign-key ids.
• Examples
  • /sys-par — codePrefix, limit, offset
  • /currencies — status, limit, offset
  • /tax — status, limit, offset
  • /partners — status, limit, offset
  • /products — status, sku, limit, offset
  • /customers, /suppliers, /brands, /categories, /price-lists, /areas, /warehouses — status, limit, offset
  • /credit-terms — status, limit, offset
  • /uom — status, prodId, limit, offset
  • /warehouse-zones — warehouseId, status, limit, offset
  • /bank-accounts — status, currencyCode, warehouseId, limit, offset
  • /exchange-rates — source, limit, offset
  • /memberships — status, limit, offset
  • /inventory — warehouseId, prodId, limit, offset
  • /deliveries — orderId (SALE_ORDER only), warehouseId, status, limit, offset
  • /sale-orders — status, customerId, limit, offset
  • /purchase-orders — status, supplierId, limit, offset
  • /cust-returns — status, customerId, saleOrderId, limit, offset
  • /cust-credit-memos, /cust-debit-notes — status, customerId, limit, offset
  • /supp-returns, /supp-credit-memos, /supp-debit-notes — status, supplierId, limit, offset
  • /transfers — status, fromWhId, toWhId, limit, offset
  • /inventory-adjustments — status, warehouseId, limit, offset
  • /permissions — functionId, limit, offset
  • /user-permissions — userId, permissionId, limit, offset
  • /api-key-permissions — apiKeyId, permissionId, limit, offset

Prefer explicit filters and small limit values.

Report endpoints workflow#

Use when the user needs a report and must pick accounts, products, warehouses, partners, customers, or suppliers.

1. Discover (optional) — GET /api/reports. Use includeData=true for quick aggregates. Example: GET /api/reports?includeData=true&topN=10
2. Resolve IDs — Helper lists: /api/reports/helpers/warehouses, .../customers, .../products, .../partners, .../suppliers, .../accounts (for GL). If the user gives names or SKU, search helpers first, then call the report.
3. CSV multi-select — productIds=1,2,3, warehouseIds=10,11, customerIds=5,9, supplierIds=7, accountIds=100,101. Dedupe IDs; use limit / offset where supported.
4. Call the report — Date window: fromDate=YYYY-MM-DD, toDate=YYYY-MM-DD. Full path table: references/ENDPOINTS.md (Reports). Copy-paste curls: references/reports.md.

GET /api/reports returns categories, accessibility metadata, and optional aggregate data; it normalizes singular/CSV filter aliases and may return warnings for bad filters or permissions.

Safety, pagination, and troubleshooting#

• Start with small limit (e.g. 20–50); narrow with status, customerId, supplierId, warehouseId, prodId, and other allowlisted query params from Dynamic list query filters where available.
• Use GET for reads; POST to create; PUT/ PATCH to update; DELETE only when requested and safe. Prefer deactivating via status over deleting master data or financial documents.
• 400: often missing required fields (e.g. priceListId on customers, order dates). 409: duplicates or constraints (e.g. SKU, partner).