API

L’API utilise un seul point de terminaison GraphQL. Envoie une requête POST avec un corps JSON contenant ta query (ou mutation) et, si besoin, des variables :

POST https://app.gibbond.com/api/v1/graphql

Tous les horodatages sont des chaînes ISO-8601 et tous les identifiants sont des GID Shopify (par exemple gid://shopify/Customer/123), sauf indication contraire. Les points sont des nombres entiers.

Authentification

Chaque requête contient un identifiant dans l’en-tête Authorization. Il existe deux types d’identifiants, adaptés à des situations différentes.

Clés API (côté serveur)

Les clés API identifient ton backend. Crée-les dans la page API keys de l’admin Gibbond ; chacune reçoit une autorisation (READ, WRITE ou ADMIN). Une clé n’est affichée qu’une fois, lors de sa création, et ressemble à glk_live_…. Transmets-la comme jeton bearer :

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Jetons client (côté client)

Pour appeler l’API depuis une interface destinée aux clients (un widget de boutique ou une application mobile), génère un jeton client depuis ton backend avec la mutation mintCustomerToken, puis transmets-le au client. Les jetons client sont de courte durée et associés à un seul client : une requête effectuée avec ce jeton ne peut consulter que les données de ce client et agir pour son compte. La requête me renvoie le client associé au jeton, et redeemReward permet à ce client d’échanger une récompense sans clé API du marchand ; le jeton peut donc être transmis au navigateur en toute sécurité.

Authorization: Bearer <customer token>

Autorisations

Les autorisations d’une clé API déterminent les opérations qu’elle peut exécuter. Elles sont cumulatives.

Limites de requêtes

Chaque identifiant d’authentification (clé API ou jeton client) est limité à 600 requêtes par minute. En cas de dépassement, l’API renvoie le statut HTTP 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre avant de réessayer.

Requêtes

Les requêtes nécessitent une clé avec l’autorisation READ au minimum, ou un jeton client qui ne peut lire que les données de ce client.

Mutations

Les mutations nécessitent une clé WRITE, sauf indication contraire ; les opérations ADMIN sont signalées.

Exemple de requête

Consulte le solde et le palier d’un client avec une clé API côté serveur :

curl https://app.gibbond.com/api/v1/graphql \
  -X POST \
  -H "Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id: ID!) { customer(id: $id) { email balance pending lifetime tier { name multiplier } } }",
    "variables": { "id": "gid://shopify/Customer/123456789" }
  }'

Codes d’erreur

Les erreurs suivent la convention GraphQL : un tableau errors de premier niveau, dont chaque entrée contient un code dans extensions et le statut HTTP correspondant.