API

La API tiene un único endpoint de GraphQL. Envía una solicitud POST con un cuerpo JSON que incluya tu query (o mutación) y, de forma opcional, variables:

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

Todas las marcas de tiempo son cadenas ISO-8601 y todos los ID son GID de Shopify (por ejemplo, gid://shopify/Customer/123), salvo que se indique lo contrario. Los puntos son números enteros.

Autenticación

Cada solicitud incluye una credencial en el encabezado Authorization. Hay dos tipos de credenciales para situaciones distintas.

Claves de API (lado del servidor)

Las claves de API identifican tu backend. Créala en la página API keys del panel de Gibbond y asígnale un ámbito (READ, WRITE o ADMIN). La clave se muestra una sola vez al crearla y tiene un aspecto similar a glk_live_…. Envíala como token bearer:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Tokens de cliente (lado del cliente)

Para llamar a la API desde una interfaz destinada a los clientes, como un widget de la tienda o una aplicación móvil, genera un token de cliente desde tu backend con la mutación mintCustomerToken y pásaselo al cliente. Los tokens de cliente son de corta duración y están vinculados a un único cliente: solo permiten consultar los datos de ese cliente y realizar acciones en su nombre. La consulta me devuelve el cliente asociado al token, y redeemReward permite que ese cliente canjee una recompensa sin una clave de comerciante; por eso, el token se puede enviar al navegador de forma segura.

Authorization: Bearer <customer token>

Permisos

El ámbito de una clave de API determina qué operaciones puede ejecutar. Los permisos son acumulativos.

Límites de solicitudes

Cada credencial (clave de API o token de cliente) tiene un límite de 600 solicitudes por minuto. Si lo superas, la API devuelve el estado HTTP 429 con un encabezado Retry-After que indica cuántos segundos debes esperar antes de volver a intentarlo.

Consultas

Para realizar consultas, necesitas una clave con permiso READ como mínimo o un token de cliente, que solo puede leer los datos de ese cliente.

Mutaciones

Las mutaciones requieren una clave WRITE, salvo que se indique lo contrario. Las operaciones ADMIN están señaladas.

Ejemplo de solicitud

Consulta el saldo y el nivel de un cliente con una clave de API del lado del servidor:

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

Códigos de error

Los errores siguen la convención de GraphQL: un array errors de nivel superior, con cada entrada incluyendo un code en extensions y el estado HTTP correspondiente.