Integración de la API

Cómo encajan las piezas

Hay dos credenciales; elegir la adecuada es fundamental:

• Clave de API (glk_live_…) — identifica tu backend. Puede leer y modificar los datos de todos los miembros, por lo que solo debe guardarse en tu servidor. Úsala para las operaciones entre servidores y para crear tokens de cliente.
• Token de cliente — una credencial de corta duración asociada a un solo cliente. Tu backend lo genera con la clave de API y se lo entrega a un cliente (navegador o app). Este solo puede consultar los datos de esa persona y actuar en su nombre, así que el token puede enviarse al dispositivo de forma segura.

Elige el patrón adecuado

Función auxiliar para solicitudes

Todas las llamadas tienen la misma estructura, así que puedes encapsularla una sola vez. Este ejemplo de Node usa fetch, que viene integrado (Node 18+):

// gibbond.js
const ENDPOINT = "https://app.gibbond.com/api/v1/graphql";

export async function gibbond(query, variables, token) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + token,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, variables }),
  });

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("Retry-After") || 1);
    const err = new Error("Rate limited");
    err.retryAfter = retryAfter;
    throw err;
  }

  const json = await res.json();
  if (json.errors && json.errors.length) {
    const code = json.errors[0].extensions && json.errors[0].extensions.code;
    throw new Error(code + ": " + json.errors[0].message);
  }
  return json.data;
}

Patrón 1 — Desde tu backend (servidor a servidor)

Con una clave WRITE puedes realizar acciones para cualquier miembro de tu tienda. Inscribe a un cliente en el programa de fidelización, consulta sus datos y asígnale puntos:

import { gibbond } from "./gibbond.js";
const KEY = process.env.GIBBOND_API_KEY;
const id = "gid://shopify/Customer/123456789";

// Enroll a customer (idempotent — safe to call again).
await gibbond(
  "mutation($id: ID!, $email: String) { enrollCustomer(customerId: $id, email: $email) { ok customer { enrolled } } }",
  { id, email: "ada@example.com" },
  KEY,
);

// Read their balance and tier.
const { customer } = await gibbond(
  "query($id: ID!) { customer(id: $id) { balance pending lifetime tier { name multiplier } } }",
  { id },
  KEY,
);

// Grant points. idempotencyKey makes retries safe — the same key never double-applies.
await gibbond(
  "mutation($id: ID!, $pts: Int!, $k: String) { awardPoints(customerId: $id, points: $pts, reason: \"Newsletter signup\", idempotencyKey: $k) { ok pointsApplied balance { balance } } }",
  { id, pts: 100, k: "newsletter-123456789" },
  KEY,
);

Patrón 2 — En una app móvil o web

No incluyas nunca la clave de API en una app. En su lugar, crea un endpoint pequeño en tu servidor que genere un token de cliente para el usuario con sesión iniciada y permite que la app se comunique directamente con Gibbond usando ese token.

¿De dónde sale el GID del cliente?

Un token de cliente queda vinculado al GID que pasas a mintCustomerToken, así que debes asegurarte de generarlo para el cliente correcto. Gibbond autentica tu backend mediante la clave de API, pero no autentica al comprador final. Antes de generar el token, tu servidor debe saber y poder verificar qué cliente de Shopify ha iniciado sesión. Hay tres formas de establecerlo, por orden de preferencia:

En tu servidor

Tu propio sistema de autenticación indica qué cliente de Shopify ha iniciado sesión (su GID). Genera un token para ese cliente:

import express from "express";
import { gibbond } from "./gibbond.js";

const app = express();

// requireAuth is YOUR session middleware; it sets req.customerGid.
app.post("/loyalty/session", requireAuth, async (req, res) => {
  const data = await gibbond(
    "mutation($id: ID!) { mintCustomerToken(customerId: $id, ttlSeconds: 900) { token expiresAt } }",
    { id: req.customerGid },
    process.env.GIBBOND_API_KEY, // WRITE key, server-side only
  );
  // Hand the app the token, when it expires, and the id it is bound to.
  res.json({
    token: data.mintCustomerToken.token,
    expiresAt: data.mintCustomerToken.expiresAt,
    customerId: req.customerGid,
  });
});

En la app

Obtén un token de tu servidor y llama directamente a Gibbond. La consulta me devuelve el cliente asociado al token, así que no hace falta indicar un ID:

// 1. Get a short-lived token from YOUR backend.
const session = await fetch("/loyalty/session", { method: "POST" }).then(r => r.json());

// 2. Call Gibbond with the customer token.
async function loyalty(query, variables) {
  const res = await fetch("https://app.gibbond.com/api/v1/graphql", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + session.token,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, variables }),
  });
  return (await res.json()).data;
}

// Show the member their points, tier, and reward codes.
const { me } = await loyalty("{ me { name balance lifetime tier { name multiplier } } }");
const { activeCodes } = await loyalty(
  "query($id: ID!) { activeCodes(customerId: $id) { code rewardName status expiresAt } }",
  { id: session.customerId },
);

renderRewardsScreen(me, activeCodes);

Canjear desde la app

Con un token de cliente se puede canjear una recompensa para uno mismo, sin una clave de comerciante en el dispositivo. La mutación devuelve un código de descuento de un solo uso que se aplica en el checkout:

const { redeemReward } = await loyalty(
  "mutation($id: ID!, $reward: ID!) { redeemReward(customerId: $id, rewardId: $reward) { ok code { code rewardName pointsSpent expiresAt } } }",
  { id: session.customerId, reward: "gid_or_reward_id_from_rewards_query" },
);
if (redeemReward.ok) applyDiscountCode(redeemReward.code.code);

Patrón 3 — Asignar puntos desde otro canal de venta

Cuando un pedido se realice fuera del checkout de Shopify —en un POS, marketplace o tienda headless—, regístralo con awardPointsForOrder. Gibbond aplica el multiplicador de nivel, los boosts activos y los hitos igual que en un pedido nativo. orderId evita duplicar puntos al volver a intentarlo:

await gibbond(
  `mutation($input: OrderInput!) {
    awardPointsForOrder(input: $input) {
      ok
      pointsApplied
      balance { balance lifetime }
    }
  }`,
  {
    input: {
      orderId: "pos-2026-000123",
      customerId: "gid://shopify/Customer/123456789",
      customerEmail: "ada@example.com",
      orderName: "POS #000123",
      lineItems: [
        { productId: "gid://shopify/Product/55", collectionIds: ["gid://shopify/Collection/9"], lineTotal: 42.0 },
        { lineTotal: 8.5 },
      ],
    },
  },
  process.env.GIBBOND_API_KEY,
);

Cada artículo puede incluir productId y collectionIds opcionales, además de un lineTotal obligatorio. Así, los boosts y las exclusiones por producto y colección se aplican igual que en los pedidos de Shopify. Para confirmar los puntos más adelante, por ejemplo, tras preparar el pedido, llama a confirmPoints(customerId, orderId); para revertirlos en un reembolso, llama a clawbackPoints con una clave ADMIN.

Errores, reintentos e idempotencia

• Códigos. Los errores se devuelven en un array de GraphQL errors; consulta errors[0].extensions.code: UNAUTHENTICATED (401), FORBIDDEN (403, permiso incorrecto), RATE_LIMITED (429), BAD_USER_INPUT (400), NOT_FOUND (404).
• Límites de solicitudes. 600 solicitudes por minuto y credencial. Si recibes 429, espera los segundos indicados en el encabezado Retry-After y vuelve a intentarlo.
• Idempotencia. Envía una idempotencyKey a awardPoints y un orderId estable a awardPointsForOrder. Reenviar la misma clave o el mismo pedido no vuelve a asignar los puntos, así que puedes repetir la solicitud si falla la red.
• Caducidad del token. Si recibes UNAUTHENTICATED con un token de cliente, genera otro y vuelve a intentarlo.

Lista de comprobación de seguridad

• Guarda las claves de API únicamente en secretos del servidor; nunca en los paquetes de la app, el código del navegador ni el control de versiones.
• Usa un token de cliente para cualquier función que se ejecute en un dispositivo; nunca una clave de API.
• Asigna a cada integración el permiso mínimo que necesita (una clave READ para los paneles, WRITE para acumular/canjear puntos y ADMIN solo para reembolsos/correcciones).
• Si sospechas que una clave se ha filtrado, renuévala de inmediato desde el panel; la revocación surte efecto al instante.
• Genera tokens de cliente con el valor mínimo práctico de ttlSeconds.

Para ver la lista completa de tipos, consultas, mutaciones y campos, consulta la referencia de la API.