API

A API tem um único endpoint GraphQL. Envie uma solicitação POST com um corpo JSON contendo sua query (ou mutação) e, opcionalmente, variables:

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

Todos os registros de data e hora são strings ISO-8601 e todos os IDs são GIDs da Shopify (por exemplo, gid://shopify/Customer/123), salvo indicação em contrário. Os pontos são números inteiros.

Autenticação

Cada solicitação inclui uma credencial no cabeçalho Authorization. Há dois tipos de credenciais para situações diferentes.

Chaves de API (lado do servidor)

As chaves de API identificam seu backend. Crie-as na página API keys do admin da Gibbond, onde cada chave recebe um escopo (READ, WRITE ou ADMIN). A chave é exibida apenas uma vez, durante a criação, e tem um formato semelhante a glk_live_…. Envie-a como um token bearer:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Tokens de cliente (lado do cliente)

Para chamar a API em uma interface voltada aos clientes, como um widget da loja ou um app para celular, gere um token de cliente pelo seu backend com a mutation mintCustomerToken e repasse-o ao cliente. Os tokens de cliente têm curta duração e são vinculados a um único cliente: cada solicitação só pode consultar os dados desse cliente e executar ações em seu nome. A query me retorna o cliente associado ao token, e redeemReward permite que ele resgate uma recompensa sem uma chave de lojista; assim, o token pode ser enviado ao navegador com segurança.

Authorization: Bearer <customer token>

Escopos

O escopo de uma chave de API determina quais operações ela pode executar. Os escopos são cumulativos.

Limites de requisições

Cada credencial (chave de API ou token de cliente) tem um limite de 600 solicitações por minuto. Ao exceder esse limite, a API retorna o status HTTP 429 e um cabeçalho Retry-After que informa quantos segundos aguardar antes de tentar novamente.

Consultas

As consultas exigem uma chave com escopo READ ou superior, ou um token de cliente, que só pode acessar os dados do próprio cliente.

Mutações

As mutations exigem uma chave WRITE, salvo indicação em contrário; as operações ADMIN estão identificadas.

Exemplo de requisição

Consulte o saldo e o nível de um cliente usando uma chave de API no 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 erro

Os erros seguem a convenção GraphQL: um array errors no nível superior, com cada entrada contendo um code em extensions e o status HTTP correspondente.