Aller au contenu

Documentation développeurs

L'API ouverte de Reko

Une API REST en lecture seule pour connecter Reko à votre caisse ou votre logiciel de compta : fichier client, retours, fidélité et bons émis. Authentifiée par clé, scopée à votre seul commerce.

Authentification

Générez une clé depuis votre tableau de bord (menu « Clés API »). Elle n'est affichée qu'une seule fois : notez-la à sa création. Envoyez-la dans l'en-tête Authorizationde chaque requête :

curl https://goreko.fr/api/v1/clients \
  -H "Authorization: Bearer grk_live_VOTRE_CLE"

Une requête sans clé, avec une clé invalide ou révoquée reçoit une réponse 401 :

{
  "error": "unauthorized",
  "message": "Clé API manquante, invalide ou révoquée. …"
}

Points d'accès

Tous en lecture seule, paginés par curseur. limit borne le nombre de résultats (20 par défaut, 100 maximum) ; cursorreprend là où la page précédente s'est arrêtée (valeur pagination.nextCursor de la réponse, absente/nullquand il n'y a plus rien à charger).

GET/api/v1/clients

Fichier client opt-in : téléphone, email, nombre de visites, date de dernière visite, préférence donnée à l'inscription.

Paramètres : ?limit (défaut 20, max 100) ?cursor

{
  "data": [
    {
      "id": "cma1b2c3d4e5f6g7h8i9",
      "phone": "+33612345678",
      "email": "client@example.com",
      "visitsCount": 4,
      "lastVisitAt": "2026-06-28T10:15:00.000Z",
      "preferences": { "zeroParty": "Plutôt le matin" }
    }
  ],
  "pagination": { "limit": 20, "nextCursor": null }
}
GET/api/v1/feedbacks

Retours privés laissés au comptoir (note 1-5 et message). Jamais les avis Google eux-mêmes — ceux-ci vivent sur votre fiche Google.

Paramètres : ?limit (défaut 20, max 100) ?cursor

{
  "data": [
    {
      "id": "cmb2c3d4e5f6g7h8i9j0",
      "rating": 4,
      "message": "Accueil impeccable, merci !",
      "createdAt": "2026-06-30T08:42:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "nextCursor": null }
}
GET/api/v1/loyalty/members

Membres de votre programme de fidélité : référence courte (celle affichée sur la carte du client), tampons, points et palier.

Paramètres : ?limit (défaut 20, max 100) ?cursor

{
  "data": [
    {
      "id": "cmc3d4e5f6g7h8i9j0k1",
      "reference": "cmc3d4e5",
      "stampsCount": 6,
      "pointsBalance": 0,
      "tierLevel": 0
    }
  ],
  "pagination": { "limit": 20, "nextCursor": null }
}
GET/api/v1/vouchers

Bons « prochaine visite » émis après un passage : code, libellé, statut (ISSUED / REDEEMED / EXPIRED) et date d'expiration.

Paramètres : ?limit (défaut 20, max 100) ?cursor

{
  "data": [
    {
      "id": "cmd4e5f6g7h8i9j0k1l2",
      "code": "7F3K9P",
      "label": "Un café offert",
      "status": "ISSUED",
      "expiresAt": "2026-07-28T00:00:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "nextCursor": null }
}

Limite de débit

60 requêtes par minute et par clé. Au-delà, réponse 429 avec les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.

Données scopées à votre commerce

Chaque clé n'ouvre que sur les données du commerce qui l'a générée : aucune clé ne peut lire le fichier client, les retours ou les bons d'un autre commerce.

Un endpoint qui vous manque ? Écrivez à contact@goreko.fr.