API

L’API espone un unico endpoint GraphQL. Invia una richiesta POST con un corpo JSON che contenga la query (o mutation) ed eventualmente le variables:

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

Tutti i timestamp sono stringhe ISO-8601 e tutti gli ID sono GID Shopify (ad esempio gid://shopify/Customer/123), salvo diversa indicazione. I punti sono numeri interi.

Autenticazione

Ogni richiesta include una credenziale nell’header Authorization. Esistono due tipi di credenziali, pensati per casi d’uso diversi.

Chiavi API (lato server)

Le chiavi API identificano il tuo backend. Creale nella pagina API keys dell’admin Gibbond; a ciascuna viene assegnato un ambito (READ, WRITE o ADMIN). La chiave viene mostrata una sola volta al momento della creazione e ha un aspetto simile a glk_live_…. Inviala come token bearer:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Token cliente (lato client)

Per chiamare l’API da un’interfaccia rivolta ai clienti, come un widget del negozio o un’app mobile, genera dal backend un token cliente con la mutation mintCustomerToken e passalo al client. I token cliente sono di breve durata e associati a un solo cliente: le richieste possono leggere dati ed eseguire azioni solo per quel cliente. La query me restituisce il cliente associato al token e redeemReward consente a quel cliente di riscattare un premio senza una chiave API del negozio; il token può quindi essere passato in sicurezza al browser.

Authorization: Bearer <customer token>

Ambiti di accesso

L’ambito di una chiave API determina quali operazioni può eseguire. Gli ambiti sono cumulativi.

Limiti di frequenza

Ogni credenziale (chiave API o token cliente) è limitata a 600 richieste al minuto. Se superi il limite, l’API restituisce lo stato HTTP 429 e un header Retry-After che indica quanti secondi attendere prima di riprovare.

Query

Per eseguire le query serve una chiave con ambito almeno READ oppure un token cliente, che può leggere solo i dati del cliente associato.

Mutation

Le mutation richiedono una chiave WRITE, salvo diversa indicazione; le operazioni ADMIN sono segnalate.

Esempio di richiesta

Leggi il saldo punti e il livello di un cliente usando una chiave API lato server:

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" }
  }'

Codici di errore

Gli errori seguono la convenzione GraphQL: l’array errors al livello principale contiene voci con un code in extensions e il corrispondente stato HTTP.