API best practices

Give each integration its own user and token

A token acts as the user who created it. Create a Joomla user for each integration (for example erp-integration). Put it in a group with access to the administrator, then assign it a Next Inventory role that allows only what the integration needs. Sign in as that user and create the token. This way:

• the ledger shows the integration's changes under its own name;
• a person leaving the company never breaks the integration;
• blocking that one user stops the integration at once.

Grant the fewest scopes

A stock-sync job needs items:read and stock:write, not items:delete. Both the scopes and the role must allow an action, so keep both narrow.

Expire and rotate

Set an expiry date on tokens for temporary jobs. To rotate a token, create the new one, switch the integration over, then revoke the old one. A revoked or disabled token is refused at once.

Keep tokens out of URLs and code

Send the token in a header, never in a query string. Query strings end up in server logs. Store it in your system's secret store or environment, not in source control.

If every request answers 401

Some Apache setups running PHP through FastCGI drop the Authorization header before PHP sees it, and every request answers 401 MISSING_TOKEN. Open Configuration → REST API and its Health tab: it tests exactly this and shows the fix for your server (usually renaming Joomla's htaccess.txt to .htaccess, or CGIPassAuth On). Until then, send X-NextInventory-Token: <token> instead.

Avoid duplicate stock movements

If a request times out, you cannot tell from the client whether the movement was recorded. Send every write with an Idempotency-Key header (see conventions) and retry with the same key: the movement is recorded once, however many times you send it. Give each movement a unique reference (your order or document number) as well, so people can find it in Next Inventory.

Don't overwrite each other's edits

When your system and people in Next Inventory can edit the same records, read the record first and send its ETag as If-Match with your PATCH (see conventions). A 412 means someone changed it since: read it again and decide whether your change still applies.

Stay under the rate limit

A token may make 300 reads and 120 changes per minute unless the site sets other limits. Watch the RateLimit-Remaining header and slow down before it reaches 0. For a bulk import, send requests one after another rather than in parallel, and when you get 429, wait the Retry-After seconds before continuing. Prefer one stock movement with many lines to many movements with one line each.

Page through large lists

Use limit and offset, and stop when you have fetched meta.total rows. Keep limit at a few hundred at most.

Prefer webhooks to polling

Instead of polling /transactions every minute, subscribe a webhook to stock_movement.finalized. Next Inventory then tells your system when stock changes.