API

A API tem um único endpoint GraphQL. Envia um pedido POST com um corpo JSON que contenha a tua query (ou mutação) e, opcionalmente, variables:

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

Todos os carimbos temporais 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 pedido inclui uma credencial no cabeçalho Authorization. Existem dois tipos de credenciais para situações diferentes.

Chaves de API (do lado do servidor)

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

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Tokens de cliente (do lado do cliente)

Para chamar a API a partir de uma interface destinada aos clientes, como um widget da loja ou uma app móvel, gera um token de cliente no teu backend com a mutation mintCustomerToken e passa-o ao cliente. Os tokens de cliente têm curta duração e estão associados a um único cliente: cada pedido só pode consultar os dados desse cliente e executar ações em seu nome. A query me devolve o cliente associado ao token e redeemReward permite-lhe resgatar uma recompensa sem uma chave de comerciante; por isso, o token pode ser enviado para o browser em segurança.

Authorization: Bearer <customer token>

Âmbitos

O âmbito de uma chave de API determina as operações que pode executar. Os âmbitos são cumulativos.

Limites de pedidos

Cada credencial (chave de API ou token de cliente) tem um limite de 600 pedidos por minuto. Ao exceder esse limite, a API devolve o estado HTTP 429 e um cabeçalho Retry-After que indica quantos segundos deves aguardar antes de voltar a tentar.

Consultas

As consultas exigem uma chave com âmbito READ ou superior, ou um token de cliente, que só pode consultar 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 assinaladas.

Exemplo de pedido

Consulta o saldo e o nível de um cliente com uma chave de API do lado do 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 de nível superior, em que cada entrada contém um code em extensions e o estado HTTP correspondente.