Publieke REST API

AuraPOS stelt een publieke REST API beschikbaar op https://mon.aurapos.be/api/v1/* om externe integraties (ERP, e-commerce, BI, analytics tools) uw gegevens read-only te laten consumeren.

Beschikbaarheid

Toegankelijk via AuraPOS-webbackend:

Inbegrepen in Group en Restaurant Group edities
Optioneel €24/maand voor Express / Boutique / Studio / Restaurant mono-site

Interactieve Swagger documentatie

Volledige OpenAPI 3.1 spec visueel verkenbaar:

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

U kunt elk endpoint direct vanuit de browser testen door uw API-sleutel te plakken.

Authenticatie

Alle requests vereisen een header X-API-Key: ak_xxx....

Een API-sleutel genereren

Log in op https://mon.aurapos.be
Ga naar Instellingen → API (alleen Owner)
Klik + Nieuwe sleutel
Geef naam (bv. "Make.com ETL prod") en beschrijving
Selecteer nodige scopes (multi-select):
- read:catalogue — toegang tot producten + families
- read:clients — toegang tot globale klanten + loyaliteit
- read:tickets — toegang tot tickets + regels
- read:promotions — toegang tot promoties
Klik Sleutel genereren
Kopieer onmiddellijk de getoonde sleutel (formaat ak_<64 chars hex>) — wordt nooit meer zichtbaar

Veilige opslag serverzijdig

De cleartext-sleutel wordt nooit in BD opgeslagen. Alleen zijn SHA-256 hash wordt bewaard.

Intrekking

Vanuit Instellingen → API heeft elke sleutel een Intrekken-knop die de sleutel onmiddellijk deactiveert.

Audit

Elke sleutel toont last_used_at en last_used_ip.

Rate limiting

60 requests/minuut per API-sleutel. Glijdend venster, atomische Postgres-teller.

Response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1716567780 (epoch Unix)
Retry-After: 23 (alleen bij HTTP 429)

Versiebeheer

Alle routes onder /api/v1/. Een toekomstige v2 zal coexisteren zonder bestaande integraties te breken.

Beschikbare endpoints (v1)

GET /api/v1/produits

Scope: read:catalogue. Query: ?actif=true|false, ?limit=N (max 200), ?offset=M.

GET /api/v1/familles

Scope: read:catalogue. Identieke paginatie.

GET /api/v1/clients

Scope: read:clients.

⚠️ AVG-filter: email en telephone worden gemaskeerd (null / "") als de klant GEEN marketingtoestemming heeft gegeven.

GET /api/v1/tickets

Scope: read:tickets. Query: ?debut=YYYY-MM-DD, ?fin=YYYY-MM-DD, ?facturesOnly=true, ?withLignes=true.

GET /api/v1/promotions

Scope: read:promotions. Filter ?actif=true|false.

curl voorbeelden

Actieve producten oplijsten

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

Tickets van vorige week met regels

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

Beveiligings best practices

Eén sleutel per integratie
Minimum scope: geef geen read:tickets aan een tool die alleen catalogus nodig heeft
Vault-opslag: in 1Password, AWS Secrets Manager, Doppler
Periodieke rotatie: draai sleutels elke 6 maanden
Monitor last_used_at: inactieve sleutel = in te trekken

Typische gebruikssituaties

ETL naar data warehouse (Make, Zapier, Airbyte)
E-commerce sync: push catalogus van AuraPOS naar e-commerce platform
Custom BI dashboard (Power BI / Tableau / Metabase)
Email CRM: Mailchimp / Brevo voor nieuwe klantencampagnes
Geautomatiseerde boekhouding

Webhooks

Voor realtime notificaties (i.p.v. polling), zie Webhooks.