API-sleutels en authenticatie
Elke call naar de Connect API heeft een API-sleutel nodig in de header X-Api-Key. De public booking API (/public/v1) heeft geen sleutel nodig.
Publishable keys en geheime sleutels
Elke API-sleutel die je aanmaakt, is een paar:
| Deel | Prefix | Gebruik in | Toegang |
|---|---|---|---|
| Publishable key (publieke sleutel) | pk_ | Je klantenapp of website | Alleen wat een klant kan doen: locaties, inloggen, het menu, restaurantbestellingen, de productcatalogus, de betaalstatus en het eigen account van de klant. |
| Geheime sleutel | cnct_ | Je eigen server | Elk endpoint, inclusief de winkelwagen, webshopbestellingen en verzendopvragingen. |
Behandel de geheime sleutel als een wachtwoord. Zet hem nooit in een app of op een webpagina.
Deze endpoints hebben de geheime sleutel nodig. Een publishable key krijgt 403 PUBLISHABLE_KEY_NOT_ALLOWED:
GET /store/shipping/locationsGET /store/shipping/delivery-optionsPOST /store/orders- alles onder
/store/cart/…
Sleutels horen bij je organisatie en werken met al haar actieve verkoopkanalen. Er zijn geen aparte test- en livesleutels.
Een sleutel aanmaken
- Log in op my.conciar.com als admin of manager. Employees kunnen geen sleutels beheren.
- Open Management → API Keys en klik op New API Key (of op Create first key als de lijst leeg is).
- Vul een Key Name in van maximaal 100 tekens en klik op Create Key.
- Kopieer in API Key Created de publishable key en de geheime sleutel met hun Copy-knoppen en klik daarna op Done.
Sleutels worden maar één keer getoond
Conciar bewaart alleen een hash van elke sleutel. Ben je een sleutel kwijt, maak dan een nieuwe aan.
De lijst toont van elke sleutel de eerste tekens, de datum waarop hij is aangemaakt en wanneer hij voor het laatst is gebruikt.
Een sleutel vervangen of intrekken
Conciar heeft geen knop om sleutels te roteren. Zo vervang je een sleutel:
- Maak een nieuwe sleutel aan.
- Zet je app of server over op de nieuwe sleutel.
- Trek de oude sleutel in of verwijder hem.
Revoke stopt de sleutel meteen; hij blijft in de lijst staan als "Revoked" en kan niet meer worden aangezet. Delete haalt hem uit de lijst. Beide werken op het hele paar: als je de publishable key intrekt, trek je ook de bijbehorende geheime sleutel in.
Calls vanuit een browser
De Connect API stuurt geen CORS-headers, dus een browser blokkeert calls die vanuit JavaScript op een ander domein worden gedaan. Roep de API aan vanaf je server of vanuit een native app. Een webshop kan zijn calls via de eigen backend laten lopen; zo blijft de geheime sleutel ook buiten de pagina.
Fouten
Fouten komen terug als JSON. Kijk eerst naar de HTTP-status.
| Status | Body | Oorzaak |
|---|---|---|
| 401 | {"message": "API key required."} | Geen X-Api-Key-header. |
| 401 | {"message": "Invalid or expired API key."} | De sleutel is onjuist, ingetrokken of verwijderd. |
| 401 | {"message": "Unauthenticated."} | Een klantendpoint zonder geldig bearer token. |
| 403 | {"status": false, "message": "PUBLISHABLE_KEY_NOT_ALLOWED"} | Dit endpoint heeft de geheime sleutel nodig. |
| 404 | {"message": "X-Sales-Channel header is required."} | Geen X-Sales-Channel-header bij een /store/…-call. |
| 404 | {"message": "…"} | Het kanaaltoken is onbekend, inactief of van een andere organisatie. |
| 409 | {"status": false, "message": "IDEMPOTENCY_KEY_REUSED"} | Een Idempotency-Key is opnieuw gebruikt voor een andere bestelling, of de eerste bestelling wordt nog geplaatst (IDEMPOTENCY_KEY_IN_PROGRESS). |
| 422 | {"message": "…", "errors": {…}} | Validatie mislukt. Andere fouten in de request geven {"status": false, "message": "CODE"}. |
| 429 | {"message": "Too Many Attempts."} | Boven een rate limit. Wacht het aantal seconden uit Retry-After. |
| 503 | {"maintenance": true, "message": "…"} | Het verkoopkanaal staat in onderhoudsmodus. |
De public booking API geeft {"status": false, "code": "…"} terug, bijvoorbeeld NOT_FOUND, UNAVAILABLE of INVALID.
Rate limits
Responses bevatten X-RateLimit-Limit en X-RateLimit-Remaining.
Connect API
| Limiet | Geteld per |
|---|---|
| 300 requests per minuut, hele API | IP-adres |
POST /app/init: 30 per minuut | sleutel |
POST /store/cart/init: 30 per minuut | sleutel |
| Andere wijzigingen in de winkelwagen: 120 per minuut | sleutel |
| Betaalstatus: 60 per minuut | sleutel |
| Een restaurantbestelling plaatsen, betalen of annuleren: 10 per minuut | sleutel |
| Status van restaurantbestelling: 30 per minuut | sleutel |
| Alle restaurantbestellingen voor één store: 60 nieuwe bestellingen en 120 betaal- of annuleercalls per minuut | store |
register, otp/request en otp/resend: 5 per minuut | IP-adres |
otp/verify: 20 per minuut | IP-adres |
| Inlogcodes: 1 per minuut en 5 per uur | e-mailadres |
Voor een publishable key betekent "per sleutel" per sleutel en IP-adres, zodat één drukke app-gebruiker de limiet niet opmaakt voor alle anderen.
Vraag je te snel een nieuwe inlogcode aan, dan krijg je 429 {"status": false, "message": "OTP_COOLDOWN", "retry_after": 42}.
Public booking API
| Limiet | Geteld per |
|---|---|
| 120 keer lezen en 10 reserveringen of wijzigingen per minuut | restaurant en IP-adres |
| Cadeaukaarten: 60 keer lezen en 6 aankopen per minuut | restaurant en IP-adres |