ApsionScan Public API

The public API lets a third-party system (ERP, e-commerce platform, business tool, script) read and write your company’s data in ApsionScan, machine to machine, without going through the user interface.

• Base URL: https://apsionscan.com/api/v1
• Format: UTF-8 JSON, ISO 8601 dates in UTC, camelCase properties
• Authentication: one API key per integration, sent in the Authorization header
• Versioning in the URL: any breaking change will go through /api/v2; adding optional fields is not a breaking change

The API is being built in stages. The authentication layer is in production; business resources arrive in the next releases. This page is updated at every stage (see the date at the top and the history at the bottom).

A key belongs to a company. It is attached to a technical service account, which does not use a seat and cannot sign in to the app. Only the company’s owner and administrators can create or revoke keys.

• In ApsionScan, open Settings › API keys (tab shown with the “Manage API keys” permission, granted by default to the owner and administrators).
• Click “New key”, give it a name, a source and the permissions it needs, then copy the secret shown.

• The secret is shown only once, at creation. ApsionScan only keeps a hash of it and cannot send it back to you.
• Each key has a name, a source (your integration’s identifier, for example erp-x) and a list of scopes.
• Options: expiry date and a list of allowed IP addresses or CIDR ranges. Name, permissions, IPs and expiry can be changed later; the source cannot.

A key looks like aps_live_<prefix>_<secret>. Send it with every request in the Authorization header, using the Bearer scheme.

curl https://apsionscan.com/api/v1/me \
  -H "Authorization: Bearer aps_live_AbCd1234_yourSecretOf32Characters00000000"

{
  "company": { "id": "7c0b…", "name": "Your company" },
  "apiKey": {
    "id": "1f3e…",
    "name": "ERP production",
    "prefix": "aps_live_AbCd1234",
    "source": "erp-x",
    "scopes": ["products:read", "stock:read"],
    "expiresAt": null
  },
  "rateLimit": { "requestsPerMinute": 600 }
}

• Keys are only accepted under /api/v1. Elsewhere the request is rejected (403 api_key_not_allowed).
• Conversely, /api/v1 only accepts keys: an app session or a user token is rejected there (401 api_key_required).
• Only call the API from a server. A key must never appear in a browser, a mobile app or a code repository.

Every request must pass two checks: the key’s scope (what the key is allowed to do) and the service account’s permissions within the company (what the company allows it to do). Grant each key the minimum it needs.

Errors follow RFC 7807 (Content-Type: application/problem+json). Use the stable code field in your logic; detail is human-readable text that may change. requestId (also in the X-Request-Id header) identifies the request for support.

{
  "type": "https://apsionscan.com/en/developers/api#erreurs",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Cette clé API n'a pas le(s) scope(s) requis : stock:write.",
  "instance": "/api/v1/stock-movements",
  "requestId": "6f1c2d9e-…",
  "requiredScopes": ["stock:write"]
}

• Immediate revocation: a revoked key is rejected from the very next request.
• Zero-downtime rotation: a new key can be issued with the same settings while the old one stays active. Switch your integration over, then revoke the old key.
• IP allowlist: when set, only those addresses or ranges can use the key.
• Expiry: a key can have an end date, after which it is rejected.
• Traceability: the date and IP address of the last use are recorded; creation and revocation are written to the company’s activity log.
• One key per integration and per environment: if one leaks, you only revoke that one.

Each key has its own limit (600 requests per minute by default, reported by GET /v1/me). Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window ends). Beyond that, the API responds 429 rate_limited with Retry-After.

The platform-wide limit also applies: 100 requests per minute per IP address.

Every write (POST, PUT, PATCH) requires the Idempotency-Key header: a unique identifier per operation (a UUID, for example), 1 to 255 characters. If the network drops, send the same request again with the same key: you get the same response, without a duplicate.

• Same key, same request: the original response is returned, with the Idempotent-Replayed: true header.
• Same key, different request: 422 idempotency_key_reused.
• Same key while the first request is still running: 409 request_in_progress.
• A 4xx error is stored and returned identically; after a 5xx error, you can retry with the same key.
• Keys are kept for 7 days.

POST /api/v1/stock-movements HTTP/1.1
Authorization: Bearer aps_live_…
Idempotency-Key: 4f9a6c1e-2b7d-4c55-9a1e-0c3f8d2b6e71
Content-Type: application/json

Lists use cursor pagination: limit (1 to 200, default 50) and cursor. The response contains data and nextCursor; pass nextCursor to the next request until it is null. The order is stable (modification date, then identifier).

For incremental sync, add updatedSince (ISO 8601): only items modified since that date are returned. Store the date of your last run and reuse it on the next one.

{
  "data": [ … ],
  "nextCursor": "WyIyMDI2LTEwLTE2VDEwOjAwOjAwLjAwMFoiLCJiIl0"
}

The public API’s OpenAPI specification is available at https://apsionscan.com/api/v1/openapi.json, with an interactive test console at https://apsionscan.com/api/v1/docs. They only describe /api/v1 routes.

Your products can be referred to by your own identifier (externalId), scoped to the key’s source: PUT /v1/products/by-external/{externalId} creates the product if unknown (201, no initial stock) or updates it (200). The SKU is never changed. In a movement or transfer, refer to the product by productId, productExternalId or sku (only one).

curl -X POST https://apsionscan.com/api/v1/stock-movements \
  -H "Authorization: Bearer $APSIONSCAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"productExternalId":"ERP-VIS-1","type":"IN","quantity":50,"locationId":"<uuid>","unitPrice":0.12,"batchNumber":"L-2026-42"}'

Customers, customer orders, suppliers and purchase orders are created or updated by your identifier (PUT …/by-external/{externalId}): 201 on creation, 200 on update. An identical call changes nothing, so you can resend your data at every sync. An order is linked to a customer with customerId or customerExternalId; its contact details are then taken from the customer.

curl -X PUT https://apsionscan.com/api/v1/customer-orders/by-external/WEB-10045 \
  -H "Authorization: Bearer $APSIONSCAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customerExternalId":"CLI-88","lines":[{"sku":"VIS-M6-20","quantity":10}],"confirm":true}'

GET /v1/identify?code=… finds the product or kit behind a code read by your device: ApsionScan code, linked code, SKU, EAN/UPC, or GS1 supplier label (GS1-128, DataMatrix, QR). For a GS1 label, the response also contains gs1: GTIN, lot, dates and quantity.

A kit is received or transferred in a single operation: one receipt (or transfer) per component, grouped and cancellable in one go in ApsionScan. Refer to the kit by kitId, kitExternalId or kitSku. Without lines, the kit composition × kitCount is used, at the prices suggested by GET /v1/kits/{kitId}/receive-template. Transfers take the lots expiring first; all or nothing.

curl -X POST https://apsionscan.com/api/v1/kit-operations/receive \
  -H "Authorization: Bearer $APSIONSCAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kitSku":"PAL-VIS","kitCount":3,"locationId":"<uuid>"}'

• Signed outgoing webhooks to be notified of stock and order status changes.