API Keys
API keys open your Acosys data to your own apps, scripts, or AI agents, such as n8n, Make, Python, or Claude/ChatGPT with function calling. One API works for every Acosys form, plus ready-made reports shared with the AI Assistant, and each key has exactly the access rights of the role you choose when creating it.
The API is only available on the Acosys cloud service (<tenant>.acosys.co.id), not on self-hosted installations and not on demo accounts.
When to Use It
- Orders from WhatsApp, marketplaces, or web forms should become Sales Invoices or Sales Orders directly, without retyping.
- An AI agent needs to read stock, prices, receivables, or transaction history to answer customers or prepare reports.
- Master data (customers, products, suppliers) has to be synchronized with another system on a schedule.
- Your own dashboard, a scheduled report, or an AI agent needs sales, receivables, payables, stock, cash flow, or profit and loss figures calculated the same way as the Acosys report screens.
Requirements
- Your paid subscription is valid for at least 6 more months (default) when the key is created. This is checked only when creating a key; existing keys keep working while the subscription is active.
- Your role holds the API keys or Users menu (the user list).
- Demo accounts (
demo*.acosys.co.id) can neither create nor use API keys, because demo accounts are shared by anyone.
Creating a Key
- First create a dedicated role for this integration in User Roles, with menus, divisions, warehouses, and table rights as narrow as possible. Do not use the administrator role.
- Open the API keys menu and click New key.
- Enter a Key name as a label (for example
n8n warehouse), choose the Role, then choose the Scope: Read only or Read and write. - Optional: set Valid until so the key expires on its own, and Allowed IPs (IP or CIDR, comma-separated) if your server has a fixed IP.
- Click Create key, then copy the key. The key is shown only once; Acosys stores only its fingerprint.
- After you press I have saved it, the API Developer Guide opens right away, complete with your tenant's API address. You can open it again at any time with the API documentation button.
Address and Authentication
Every tenant has its own API address. Keys look like acsk_<tenant>_<40 characters> and only work on their tenant's subdomain.
https://<tenant>.acosys.co.id/api/v1/
Authorization: Bearer acsk_<tenant>_xxxxxxxx
curl https://<tenant>.acosys.co.id/api/v1/me -H "Authorization: Bearer $ACOSYS_API_KEY"
The full OpenAPI specification is available without a key at https://<tenant>.acosys.co.id/api/v1/openapi, and can be imported directly into Postman or n8n, or used as an AI agent's tool list.
What You Can Do
| Request | Purpose |
|---|---|
GET /v1/me | Key identity, role, scope, remaining free quota, and tariffs. |
GET /v1/forms | Forms this key may use, including whether each can be written. |
GET /v1/forms/{form}/schema | One form's fields: type, required, length, choices, detail lines, and computed fields. |
GET /v1/forms/{form} | List data with search (q), equality filters (filter[field]), sorting, and the next page via cursor; up to 200 rows per page. |
GET /v1/forms/{form}/{id} | One document with its detail lines. Document numbers containing slashes (for example I/SL-000123) may be sent as they are. |
POST /v1/forms/{form} | Create data or a document with its detail lines. Requires an Idempotency-Key header. |
PATCH /v1/forms/{form}/{id} | Change specific fields of existing data. |
GET /v1/tools | The ready-made reports this key may use, with their argument schemas. |
POST /v1/tools/{name} | Run one ready-made report (read only). See Ready-Made Reports. |
- Every form the key's role can access can be read, created, and changed through the API. The limits are the same as on screen: the role's menus, table rights, divisions and warehouses, plus the key's scope. Central subscription data cannot be accessed.
- The API saves through the same path as the screen: form rules, closed-period locks, approvals, and stock checks still apply. Document numbers are generated from the division's numbering format when not sent.
- Fields you do not send get the form's default values, just like opening a new form on screen. Password fields may be sent (stored hashed) but are never returned when reading.
- Figures the browser calculates on screen (gross, net, totals) are sent by your app, except for Sales Invoices.
- Every document created or changed through the API is recorded with creator
api:<key number>, so it is easy to tell apart from manual input.
Sales Invoices Calculated by the Server
For a Sales Invoice, send only the customer, products, and quantities. Price, discounts, tax, COGS, terms, and totals are calculated by the server with the same rules as the screen: customer negotiated prices, price levels, wholesale prices, unit discounts and discount rules, and product taxes. Credit limit and stock (when the role checks stock) are also checked, and the invoice is posted straight to the journal, stock, and receivables, or waits for approval if your company requires it.
curl -X POST https://<tenant>.acosys.co.id/api/v1/forms/sales \
-H "Authorization: Bearer $ACOSYS_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: wa-order-8841" \
-d '{"customerid":"C002","salesdetail":[{"productid":"KOPI-250","salesqty":10}]}'
Payments on the invoice, down payments, serial numbers, and rentals are not yet supported by this server-calculated path.
Ready-Made Reports
The reports used by the AI Assistant are also available through the API: sales summary, receivables, payables, inventory, cash flow, profit and loss, top products, business performance, a comparison of two periods, and a monthly sales check. Totals and summaries are calculated by the server from all report rows, with the same definitions as the report screens, so your app or AI agent does not have to add anything up itself.
curl https://<tenant>.acosys.co.id/api/v1/tools -H "Authorization: Bearer $ACOSYS_API_KEY"
curl -X POST https://<tenant>.acosys.co.id/api/v1/tools/sales_summary \
-H "Authorization: Bearer $ACOSYS_API_KEY" -H "Content-Type: application/json" \
-d '{"period":"last_month","currtrans":"IDR"}'
- The reports listed follow the key's role: the report menus the role holds and the modules included in your plan. The key's role does not need AI Assistant permission.
- The role's division, warehouse, and group limits are enforced by the server and override the arguments sent. The
filterpart of the answer shows the filter that was actually used. - Dates are given as
period(for examplethis_month,last_month,this_year,last_30_days) or asdate_fromanddate_to. Division, salesperson, or currency codes can be looked up withlookup_filter_options. summaryis always complete. Thedatadetails hold at most 40 rows;truncated: truemeans there are more. To fetch every document, use the paginatedGET /v1/forms/{form}.- Reports only read: the AI Assistant's free SQL queries and data-changing functions are not exposed through the API.
Safe Retries
Every POST must carry an Idempotency-Key that is unique per document, such as a UUID. If the network drops and the request is repeated with the same key, you get the first answer (header Idempotent-Replay: true), not a second document. The same key with a different body is rejected with 409.
Limits and Costs
The API needs no extra subscription. Usage is counted per request. The figures in this section are defaults; the figures that apply to your tenant are shown in the API documentation dialog in the API keys menu and in GET /v1/me.
- 1,000 free successful requests per month per tenant by default.
- Above the quota, usage is deducted from your Acosys token balance, the same balance used by the AI Assistant.
- Failed requests are not counted and not charged.
- Charges are calculated once a day, after midnight, for the previous day's usage.
| Request type | Default tokens per request (above quota) |
|---|---|
/me, /forms, schema, /tools, openapi | 0 (free) |
| Reading one document | 1 |
| Reading a list | 2 |
Creating or changing (POST, PATCH) | 5 |
Running a ready-made report (POST /v1/tools/{name}) | 20 (filter code lookup 2, active student count 1) |
- When this month's free quota is used up and the token balance is empty, the API answers
402 INSUFFICIENT_TOKENuntil the balance is topped up or the month changes. - Default rate limits: 60 requests per minute and 5,000 per day per key. Exceeding them returns
429with aRetry-Afterheader. - Remaining quota, rate limits, and the tariffs that apply are always available at
GET /v1/me.
Common Errors
All errors have the same shape: {"error":{"code":"...","message":"...","fields":[...]}}. For AI agents: read fields[].field and message, fix the request, then send it again with a new Idempotency-Key.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED, INVALID_JSON | Header or request body is incomplete. |
| 401 | API_KEY_REQUIRED, INVALID_API_KEY, IP_NOT_ALLOWED, ROLE_NOT_FOUND | No key sent, or the key is wrong, revoked, expired, used from another IP, or its role was deleted. |
| 402 | INSUFFICIENT_TOKEN | This month's free quota is used up and the token balance is empty. |
| 403 | SCOPE_REQUIRED, ROLE_FORBIDDEN, FORM_WRITE_NOT_AVAILABLE | The key's scope or the role's rights do not allow it, or the form is a read-only view. |
| 403 | DEMO_TENANT, API_NOT_AVAILABLE | Called on a demo account, or on an installation that is not the cloud service. |
| 404 | FORM_NOT_FOUND, NOT_FOUND, TOOL_NOT_FOUND | The form, data, or ready-made report does not exist, or is not visible to the key's role. |
| 409 | IDEMPOTENCY_MISMATCH, IDEMPOTENCY_IN_PROGRESS | The Idempotency-Key clashes with another request. |
| 421 | WRONG_HOST | The key was used outside its tenant's subdomain. |
| 422 | VALIDATION_FAILED, CREDIT_LIMIT_EXCEEDED, SAVE_REJECTED, NUMBERING_NOT_CONFIGURED | Data rejected; fields and message point to the wrong field or line. |
| 422 | TOOL_REJECTED | Report arguments rejected; message names the wrong argument and the available ones. |
| 429 | RATE_LIMITED | Too fast; wait as given in the Retry-After header. |
| 500 | TOOL_FAILED | The report failed to run on the server. |
Security
- One dedicated role per integration, with the narrowest possible menus and rights. Changing a role immediately changes the rights of every key that uses it; deleting the role disables its keys.
- Choose Read only when the integration does not need to write.
- Set Allowed IPs and Valid until whenever possible.
- The Last used column in the key list helps you find keys that are no longer used; revoke them.
Common Issues
- The API keys menu does not appear: the menu only exists on the Acosys cloud service, not on demo accounts, and your role must hold the API keys or Users menu.
- Creating a key fails because of the subscription: extend your subscription to the date named in the error message (by default 6 months ahead) in the Upgrade / Renew Tenant menu, then try again.
- Answer
421 WRONG_HOST: call the API at your own tenant's address,https://<tenant>.acosys.co.id/api/v1/, not another address. - Data is missing although it is on screen: the key follows its role's divisions, warehouses, and groups; data outside the role's reach is not visible.
- A report is missing from
GET /v1/tools: add its report menu to the key's role (for example the Profit and Loss report), and make sure its module is in your plan (Profit and Loss and Cash Flow need the accounting module, Receivables needs the credit transaction module).
Menu Location
- Settings / Users & Access / API keys
/apikeys