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

Requirements

Creating a Key

  1. 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.
  2. Open the API keys menu and click New key.
  3. Enter a Key name as a label (for example n8n warehouse), choose the Role, then choose the Scope: Read only or Read and write.
  4. 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.
  5. Click Create key, then copy the key. The key is shown only once; Acosys stores only its fingerprint.
  6. 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.
Keep the key like a password. If it leaks, click Revoke on that key; apps using it stop immediately. Then create a new key.

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

RequestPurpose
GET /v1/meKey identity, role, scope, remaining free quota, and tariffs.
GET /v1/formsForms this key may use, including whether each can be written.
GET /v1/forms/{form}/schemaOne 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/toolsThe 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.

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"}'

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.

Request typeDefault tokens per request (above quota)
/me, /forms, schema, /tools, openapi0 (free)
Reading one document1
Reading a list2
Creating or changing (POST, PATCH)5
Running a ready-made report (POST /v1/tools/{name})20 (filter code lookup 2, active student count 1)

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.

HTTPCodeMeaning
400IDEMPOTENCY_KEY_REQUIRED, INVALID_JSONHeader or request body is incomplete.
401API_KEY_REQUIRED, INVALID_API_KEY, IP_NOT_ALLOWED, ROLE_NOT_FOUNDNo key sent, or the key is wrong, revoked, expired, used from another IP, or its role was deleted.
402INSUFFICIENT_TOKENThis month's free quota is used up and the token balance is empty.
403SCOPE_REQUIRED, ROLE_FORBIDDEN, FORM_WRITE_NOT_AVAILABLEThe key's scope or the role's rights do not allow it, or the form is a read-only view.
403DEMO_TENANT, API_NOT_AVAILABLECalled on a demo account, or on an installation that is not the cloud service.
404FORM_NOT_FOUND, NOT_FOUND, TOOL_NOT_FOUNDThe form, data, or ready-made report does not exist, or is not visible to the key's role.
409IDEMPOTENCY_MISMATCH, IDEMPOTENCY_IN_PROGRESSThe Idempotency-Key clashes with another request.
421WRONG_HOSTThe key was used outside its tenant's subdomain.
422VALIDATION_FAILED, CREDIT_LIMIT_EXCEEDED, SAVE_REJECTED, NUMBERING_NOT_CONFIGUREDData rejected; fields and message point to the wrong field or line.
422TOOL_REJECTEDReport arguments rejected; message names the wrong argument and the available ones.
429RATE_LIMITEDToo fast; wait as given in the Retry-After header.
500TOOL_FAILEDThe report failed to run on the server.

Security

Common Issues

Menu Location