API publique d'ApsionScan

L'API publique permet à un système tiers (ERP, e-commerce, outil métier, script) de lire et d'écrire les données de votre entreprise dans ApsionScan, de machine à machine, sans passer par l'interface.

• URL de base : https://apsionscan.com/api/v1
• Format : JSON en UTF-8, dates ISO 8601 en UTC, propriétés en camelCase
• Authentification : une clé API par intégration, envoyée dans l’en-tête Authorization
• Versionnement dans l’URL : toute rupture de contrat passera par /api/v2 ; l’ajout de champs optionnels n’est pas une rupture

L'API est construite par étapes. Le socle d'authentification est en production ; les ressources métier arrivent dans les prochaines versions. Cette page est mise à jour à chaque étape (voir la date en haut de page et l'historique en bas).

Une clé appartient à une entreprise. Elle est rattachée à un compte de service technique, qui n'occupe pas de siège et ne peut pas se connecter à l'interface. Seuls le propriétaire et les administrateurs de l'entreprise peuvent créer ou révoquer des clés.

• Dans ApsionScan, ouvrez Paramètres › Clés API (onglet visible avec la permission « Gérer les clés API », accordée par défaut au propriétaire et aux administrateurs).
• Cliquez sur « Nouvelle clé », donnez-lui un nom, une source et les droits nécessaires, puis copiez le secret affiché.

• Le secret n’est affiché qu’une seule fois, à la création. ApsionScan n’en garde qu’une empreinte et ne peut pas vous le renvoyer.
• Chaque clé porte un nom, une source (l’identifiant de votre intégration, par exemple erp-x) et une liste de scopes.
• Options : date d’expiration et liste d’adresses IP ou de plages CIDR autorisées. Le nom, les droits, les IP et l’expiration restent modifiables ensuite ; la source, non.

Une clé a la forme aps_live_<préfixe>_<secret>. Envoyez-la à chaque requête dans l’en-tête Authorization, avec le schéma Bearer.

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

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

• Les clés ne sont acceptées que sous /api/v1. Ailleurs, la requête est refusée (403 api_key_not_allowed).
• À l’inverse, /api/v1 n’accepte que des clés : une session de l’application ou un jeton utilisateur y est refusé (401 api_key_required).
• Appelez l’API uniquement depuis un serveur. Une clé ne doit jamais apparaître dans un navigateur, une application mobile ou un dépôt de code.

Chaque requête doit passer deux contrôles : le scope de la clé (ce que la clé a le droit de faire) et les permissions du compte de service dans l'entreprise (ce que l'entreprise l'autorise à faire). Accordez à chaque clé le minimum nécessaire.

Les erreurs suivent la RFC 7807 (Content-Type: application/problem+json). Utilisez le champ code, stable, dans votre logique ; detail est un texte lisible qui peut évoluer. requestId (aussi dans l’en-tête X-Request-Id) identifie la requête auprès du 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"]
}

• Révocation immédiate : une clé révoquée est refusée dès la requête suivante.
• Rotation sans interruption : une nouvelle clé peut être émise avec les mêmes réglages pendant que l’ancienne reste active. Basculez votre intégration, puis révoquez l’ancienne.
• Liste d’IP : si elle est renseignée, seules ces adresses ou plages peuvent utiliser la clé.
• Expiration : une clé peut avoir une date de fin, après laquelle elle est refusée.
• Traçabilité : la date et l’adresse IP de la dernière utilisation sont conservées ; la création et la révocation sont inscrites au journal d’activité de l’entreprise.
• Une clé par intégration et par environnement : en cas de fuite, vous ne révoquez que celle-là.

Chaque clé a sa propre limite (par défaut 600 requêtes par minute, indiquée par GET /v1/me). Chaque réponse porte RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (secondes avant la fin de la fenêtre). Au-delà, l’API répond 429 rate_limited avec Retry-After.

La limite générale de la plateforme s’applique aussi : 100 requêtes par minute et par adresse IP.

Chaque écriture (POST, PUT, PATCH) exige l’en-tête Idempotency-Key : un identifiant unique par opération (un UUID par exemple), de 1 à 255 caractères. En cas de coupure réseau, renvoyez la même requête avec la même clé : vous obtenez la même réponse, sans doublon.

• Même clé, même requête : la réponse d’origine est renvoyée, avec l’en-tête Idempotent-Replayed: true.
• Même clé, requête différente : 422 idempotency_key_reused.
• Même clé pendant que la première requête est en cours : 409 request_in_progress.
• Une erreur 4xx est conservée et renvoyée à l’identique ; après une erreur 5xx, vous pouvez réessayer avec la même clé.
• Les clés sont conservées 7 jours.

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

Les listes sont paginées par curseur : limit (1 à 200, 50 par défaut) et cursor. La réponse contient data et nextCursor ; passez nextCursor à la requête suivante jusqu’à ce qu’il vaille null. L’ordre est stable (date de modification, puis identifiant).

Pour une synchronisation incrémentale, ajoutez updatedSince (ISO 8601) : seuls les éléments modifiés depuis cette date sont renvoyés. Conservez la date de votre dernier passage et réutilisez-la au suivant.

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

La spécification OpenAPI de l’API publique est disponible sur https://apsionscan.com/api/v1/openapi.json, et une console de test interactive sur https://apsionscan.com/api/v1/docs. Elles ne décrivent que les routes /api/v1.

Vos produits peuvent être désignés par votre propre identifiant (externalId), propre à la source de la clé : PUT /v1/products/by-external/{externalId} crée le produit s’il est inconnu (201, sans stock initial) ou le met à jour (200). Le SKU n’est jamais modifié. Dans un mouvement ou un transfert, désignez le produit par productId, productExternalId ou sku (un seul).

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

Clients, commandes client, fournisseurs et bons de commande se créent ou se mettent à jour par votre identifiant (PUT …/by-external/{externalId}) : 201 à la création, 200 à la mise à jour. Un appel identique ne modifie rien, vous pouvez donc renvoyer vos données à chaque synchronisation. Une commande se rattache à un client par customerId ou customerExternalId ; ses coordonnées sont alors reprises du client.

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=… retrouve le produit ou le kit d’un code lu par votre terminal : code ApsionScan, code associé, SKU, EAN/UPC, ou étiquette fournisseur GS1 (GS1-128, DataMatrix, QR). Pour une étiquette GS1, la réponse contient aussi gs1 : GTIN, lot, dates et quantité.

Un kit se réceptionne ou se transfère en une seule opération : une entrée (ou un transfert) par composant, regroupés et annulables d’un coup dans ApsionScan. Désignez le kit par kitId, kitExternalId ou kitSku. Sans lines, la composition du kit × kitCount est utilisée, aux prix proposés par GET /v1/kits/{kitId}/receive-template. Le transfert prend d’abord les lots qui périment en premier ; tout ou rien.

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

• Webhooks sortants signés pour être notifié des changements de stock et de statut des commandes.