API

API udostępnia jeden punkt końcowy GraphQL. Wyślij żądanie POST z treścią JSON zawierającą query (lub mutację) oraz opcjonalne variables:

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

Wszystkie znaczniki czasu są ciągami w formacie ISO-8601, a wszystkie identyfikatory to Shopify GID (na przykład gid://shopify/Customer/123) o ile nie podano inaczej. Punkty są liczbami całkowitymi.

Uwierzytelnianie

Każde żądanie zawiera dane uwierzytelniające w nagłówku Authorization. W zależności od sytuacji używa się jednego z dwóch rodzajów danych uwierzytelniających.

Klucze API (po stronie serwera)

Klucze API identyfikują Twoje zaplecze. Utwórz je na stronie API keys w panelu administracyjnym Gibbond. Każdy klucz otrzymuje zakres uprawnień (READ, WRITE lub ADMIN). Klucz jest wyświetlany tylko raz podczas tworzenia i ma postać glk_live_…. Przekaż go jako token typu bearer:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Tokeny klienta (po stronie klienta)

Gdy chcesz wywołać API z interfejsu dla klienta (widżetu sklepu lub aplikacji mobilnej), utwórz token klienta za pomocą mutacji mintCustomerToken w swoim zapleczu, a następnie przekaż token klientowi. Tokeny klienta są krótkotrwałe i ograniczone do jednego klienta — żądanie wykonane z takim tokenem może odczytywać dane wyłącznie tego klienta i wykonywać operacje tylko na jego koncie. Zapytanie me zwraca klienta przypisanego do tokenu, a redeemReward działa dla tego klienta bez klucza sprzedawcy, dlatego token można bezpiecznie przekazać do przeglądarki.

Authorization: Bearer <customer token>

Zakresy uprawnień

Zakres klucza API określa, jakie operacje może on wykonywać. Zakresy są kumulatywne.

Limity zapytań

Każde dane uwierzytelniające (klucz API lub token klienta) mają limit 600 żądań na minutę. Po przekroczeniu limitu API zwraca kod HTTP 429 z nagłówkiem Retry-After określającym liczbę sekund, które należy odczekać przed ponowieniem żądania.

Zapytania

Zapytania wymagają klucza o zakresie co najmniej READ albo tokenu klienta (który umożliwia odczyt wyłącznie danych przypisanego do niego klienta).

Mutacje

Mutacje wymagają klucza WRITE o ile nie zaznaczono inaczej; operacje wymagające uprawnień ADMIN są odpowiednio oznaczone.

Przykładowe żądanie

Odczytaj saldo i poziom klienta za pomocą klucza API używanego po stronie serwera:

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

Kody błędów

Błędy są zgodne z konwencją GraphQL: główna tablica errors zawiera wpisy z kodem code w obiekcie extensions oraz odpowiadającym mu statusem HTTP.