Clés API et authentification
Chaque appel à l'API Connect nécessite une clé API dans l'en-tête X-Api-Key. L'API publique de réservation (/public/v1) ne nécessite aucune clé.
Clés publiques et secrètes
Chaque clé API que vous créez est une paire :
| Partie | Préfixe | À utiliser dans | Accès |
|---|---|---|---|
| Clé publique | pk_ | Votre app client ou votre site web | Uniquement ce qu'un client peut faire : établissements, connexion, carte, commandes restaurant, catalogue de produits, statut de paiement et compte du client. |
| Clé secrète | cnct_ | Votre propre serveur | Tous les endpoints, y compris le panier, les commandes de la boutique en ligne et les recherches d'expédition. |
Traitez la clé secrète comme un mot de passe. Ne la mettez jamais dans une app ni dans une page web.
Ces endpoints nécessitent la clé secrète. Une clé publique reçoit 403 PUBLISHABLE_KEY_NOT_ALLOWED :
GET /store/shipping/locationsGET /store/shipping/delivery-optionsPOST /store/orders- tout ce qui se trouve sous
/store/cart/…
Les clés appartiennent à votre organisation et fonctionnent avec tous ses canaux de vente actifs. Il n'y a pas de clés de test et de clés live distinctes.
Créer une clé
- Connectez-vous à my.conciar.com en tant qu'admin ou manager. Le rôle Employee ne peut pas gérer les clés.
- Ouvrez Management → API Keys et cliquez sur New API Key (ou sur Create first key si la liste est vide).
- Saisissez un Key Name, de 100 caractères maximum, et cliquez sur Create Key.
- Dans API Key Created, copiez la clé publique et la clé secrète avec leurs boutons Copy, puis cliquez sur Done.
Les clés ne sont affichées qu'une seule fois
Conciar ne conserve qu'un hash de chaque clé. Si vous perdez une clé, créez-en une nouvelle.
La liste affiche les premiers caractères de chaque clé, sa date de création et sa dernière utilisation.
Remplacer ou révoquer une clé
Conciar n'a pas de bouton de rotation des clés. Pour remplacer une clé :
- Créez une nouvelle clé.
- Passez votre app ou votre serveur sur la nouvelle clé.
- Révoquez ou supprimez l'ancienne clé.
Revoke désactive la clé immédiatement ; elle reste dans la liste avec le statut « Revoked » et ne peut pas être réactivée. Delete la retire de la liste. Les deux agissent sur toute la paire : révoquer la clé publique révoque aussi sa clé secrète.
Appels depuis un navigateur
L'API Connect n'envoie pas d'en-têtes CORS : un navigateur bloque donc les appels faits en JavaScript depuis un autre domaine. Appelez-la depuis votre serveur ou depuis une app native. Une boutique en ligne peut faire passer ses appels par son propre backend, ce qui garde aussi la clé secrète hors de la page.
Erreurs
Les erreurs sont renvoyées en JSON. Vérifiez d'abord le statut HTTP.
| Statut | Corps | Cause |
|---|---|---|
| 401 | {"message": "API key required."} | Pas d'en-tête X-Api-Key. |
| 401 | {"message": "Invalid or expired API key."} | La clé est incorrecte, révoquée ou supprimée. |
| 401 | {"message": "Unauthenticated."} | Un endpoint client sans bearer token valide. |
| 403 | {"status": false, "message": "PUBLISHABLE_KEY_NOT_ALLOWED"} | Cet endpoint nécessite la clé secrète. |
| 404 | {"message": "X-Sales-Channel header is required."} | Pas d'en-tête X-Sales-Channel sur un appel /store/…. |
| 404 | {"message": "…"} | Le jeton du canal est inconnu, inactif ou appartient à une autre organisation. |
| 409 | {"status": false, "message": "IDEMPOTENCY_KEY_REUSED"} | Une Idempotency-Key a été réutilisée pour une autre commande, ou la première commande est encore en cours de création (IDEMPOTENCY_KEY_IN_PROGRESS). |
| 422 | {"message": "…", "errors": {…}} | La validation a échoué. Les autres erreurs de requête renvoient {"status": false, "message": "CODE"}. |
| 429 | {"message": "Too Many Attempts."} | Une limite de requêtes est dépassée. Attendez le nombre de secondes indiqué dans Retry-After. |
| 503 | {"maintenance": true, "message": "…"} | Le canal de vente est en mode maintenance. |
L'API publique de réservation renvoie {"status": false, "code": "…"}, par exemple NOT_FOUND, UNAVAILABLE ou INVALID.
Limites de requêtes
Les réponses contiennent X-RateLimit-Limit et X-RateLimit-Remaining.
API Connect
| Limite | Comptée par |
|---|---|
| 300 requêtes par minute, toute l'API | Adresse IP |
POST /app/init : 30 par minute | Clé |
POST /store/cart/init : 30 par minute | Clé |
| Autres modifications du panier : 120 par minute | Clé |
| Statut de paiement : 60 par minute | Clé |
| Création, paiement ou annulation d'une commande restaurant : 10 par minute | Clé |
| Statut d'une commande restaurant : 30 par minute | Clé |
| Toutes les commandes restaurant d'un même point de vente : 60 nouvelles commandes et 120 appels de paiement ou d'annulation par minute | Point de vente |
register, otp/request et otp/resend : 5 par minute | Adresse IP |
otp/verify : 20 par minute | Adresse IP |
| Codes de connexion : 1 par minute et 5 par heure | Adresse e-mail |
Pour une clé publique, « par clé » signifie par clé et par adresse IP : un utilisateur très actif de l'app n'épuise donc pas la limite pour tous les autres.
Demander un nouveau code de connexion trop tôt renvoie 429 {"status": false, "message": "OTP_COOLDOWN", "retry_after": 42}.
API publique de réservation
| Limite | Comptée par |
|---|---|
| 120 lectures et 10 réservations ou modifications par minute | Restaurant et adresse IP |
| Cartes cadeaux : 60 lectures et 6 achats par minute | Restaurant et adresse IP |