API publique REST

AuraPOS expose une API publique REST sur https://mon.aurapos.be/api/v1/* pour permettre aux intégrations externes (ERP, e-commerce, BI, outils analytics) de consommer vos données en lecture seule.

Disponibilité

Accessible depuis le backend web AuraPOS, donc :

Inclus dans les éditions Group et Restaurant Group
Optionnel à 24 €/mois pour les éditions Express / Boutique / Studio / Restaurant en mono-site

Documentation interactive Swagger

Toute la spécification OpenAPI 3.1 est disponible et explorable visuellement :

https://mon.aurapos.be/api/docs (Swagger UI cliquable)

Vous pouvez y tester chaque endpoint directement depuis le navigateur en collant votre clé API.

Authentification

Toutes les requêtes nécessitent un header X-API-Key: ak_xxx... où la clé est générée depuis votre dashboard.

Générer une clé API

Connectez-vous sur https://mon.aurapos.be
Naviguez vers Paramètres → API (visible Owner uniquement)
Cliquez + Nouvelle clé
Donnez un nom (ex : "Make.com ETL prod") et une description
Sélectionnez les scopes nécessaires (multi-select) :
- read:catalogue — accès aux produits + familles
- read:clients — accès aux clients globaux + fidélité
- read:tickets — accès aux tickets + lignes (factures B2B incluses)
- read:promotions — accès aux promotions
Cliquez Générer la clé
Copiez immédiatement la clé affichée (format ak_<64 chars hex>) — elle ne sera plus jamais visible

Stockage sécurisé côté serveur

La clé en clair n'est jamais stockée en BD. Seul son hash SHA-256 est conservé. Si vous perdez la clé, il faut la révoquer et en générer une nouvelle.

Révocation

Depuis la page Paramètres → API, chaque clé a un bouton Révoquer qui désactive immédiatement la clé (toutes les requêtes retournent 401 Unauthorized).

Audit

Chaque clé affiche son last_used_at et last_used_ip, vous permettant de détecter une clé compromise ou inactive.

Rate limiting

Pour éviter l'abus, 60 requêtes/minute par clé API. Fenêtre glissante, compteur Postgres atomique.

Headers de réponse :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42 (requêtes restantes dans la fenêtre)
X-RateLimit-Reset: 1716567780 (epoch Unix de fin de fenêtre)
Retry-After: 23 (secondes à attendre, uniquement si HTTP 429)

Versioning

Toutes les routes sont sous /api/v1/. Une future v2 cohabitera sans casser les intégrations existantes.

Endpoints disponibles (v1)

GET /api/v1/produits

Scope requis : read:catalogue.

Query params :

?actif=true|false — filtre par statut actif
?limit=N (défaut 50, max 200)
?offset=M (défaut 0)

Réponse :

{
  "items": [
    {
      "id": "uuid",
      "ean": "5400141000030",
      "code_interne": "OEUF12",
      "nom": "Œufs frais x6",
      "prix_tvac": 1.99,
      "taux_tva": 6,
      "categorie_fiscale": "Nourriture",
      "famille_code": "EPIC",
      "description": "",
      "unite": "pce",
      "emoji": "🥚",
      "actif": true,
      "last_modified": "2026-05-17T12:34:56.789Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

GET /api/v1/familles

Scope : read:catalogue. Pagination identique.

⚠️ Filtre RGPD : les champs email et telephone sont masqués (null / "") si le client n'a PAS donné son consentement marketing. Pour les intégrations comptables qui ont déjà accès aux factures B2B, les données complètes restent disponibles via /api/v1/tickets.

GET /api/v1/tickets

Scope : read:tickets.

Query params :

?debut=YYYY-MM-DD (date début incluse)
?fin=YYYY-MM-DD (date fin incluse)
?facturesOnly=true (uniquement les factures)
?withLignes=true (inclure le détail des lignes, ajoute 1 round-trip BD)

Réponse : tableau de tickets non-annulés avec totaux HTVA / TVA / TVAC, mode paiement, mode consommation, snapshot client.

Si withLignes=true, chaque ticket contient lignes: [...] avec quantité, prix unitaire HTVA/TVAC, taux TVA, montants ventilés.

curl -H "X-API-Key: ak_xxx..." \
  "https://mon.aurapos.be/api/v1/produits?actif=true&limit=10"

Tickets de la semaine dernière avec lignes

curl -H "X-API-Key: ak_xxx..." \
  "https://mon.aurapos.be/api/v1/tickets?debut=2026-05-10&fin=2026-05-16&withLignes=true"

Vérifier le rate limit restant

curl -i -H "X-API-Key: ak_xxx..." \
  "https://mon.aurapos.be/api/v1/familles" | grep -i ratelimit

Exemples Node.js

const resp = await fetch("https://mon.aurapos.be/api/v1/tickets?debut=2026-05-01", {
  headers: { "X-API-Key": process.env.AURAPOS_API_KEY }
});
if (resp.status === 429) {
  const retryAfter = resp.headers.get("Retry-After");
  console.log(`Rate limit, retry in ${retryAfter}s`);
  return;
}
const { items, total } = await resp.json();
console.log(`${items.length}/${total} tickets`);

Sécurité bonnes pratiques

Une clé par intégration : si une fuite, vous révoquez sans impacter les autres
Scope minimum : ne donnez pas read:tickets à un outil qui n'a besoin que du catalogue
Stockage vault : la clé doit vivre dans 1Password, AWS Secrets Manager, Doppler — pas en clair dans Git
Rotation périodique : tournez vos clés tous les 6 mois (créer la nouvelle, migrer l'intégration, révoquer l'ancienne)
Monitor last_used_at : une clé inactive = à révoquer

Cas d'usage typiques

ETL vers entrepôt de données (Make, Zapier, Airbyte) : pull quotidien des tickets pour data warehouse
Sync e-commerce : push catalogue de AuraPOS vers la plateforme e-commerce du client
Dashboard BI custom : Power BI / Tableau / Metabase qui pull les données régulièrement
CRM email : Mailchimp / Brevo qui synchronise les nouveaux clients pour campagne fidélisation
Comptabilité automatisée : intégration directe avec le comptable du client

Webhooks

Pour les notifications temps réel (au lieu de polling), voir Webhooks : 7 événements push avec signature HMAC, retry exponentiel automatique.