Dokumentacja API

API v4 pozwala połączyć własny sklep ze SpaceIs. W tej sekcji znajdziesz zasady integracji oraz przykłady obsługi wariantów i koszyka. Pełna lista endpointów jest dostępna pod adresem api.spaceis.pl.

Adres i autoryzacja

Adres bazowy API:

https://api.spaceis.pl/v4

Do żądań używaj klucza API wybranej licencji. Przekazuj go w nagłówku Authorization, a nie w adresie URL.

Authorization: Bearer TWOJ_KLUCZ_API
Accept: application/json

Przy wysyłaniu JSON dodaj nagłówek Content-Type: application/json.

Klucz API

Wywołuj API z serwera swojego sklepu. Klucza nie umieszczaj w kodzie JavaScript wysyłanym do przeglądarki, publicznym repozytorium ani logach dostępnych dla klientów. Klucz daje dostęp do danych i operacji wybranej licencji.

Pierwsze żądanie

W poniższych przykładach SPACEIS_API_KEY oznacza zmienną środowiskową z Twoim kluczem. Identyfikatory, adresy e-mail i dane gracza są przykładowe. Zastąp je danymi ze swojego sklepu.

curl --request GET 'https://api.spaceis.pl/v4/servers' \
  --header "Authorization: Bearer $SPACEIS_API_KEY" \
  --header 'Accept: application/json'

Prawidłowa odpowiedź zawiera dane w polu data:

{
  "success": true,
  "type": "response",
  "data": []
}

Pusta tablica w tym przykładzie oznacza brak serwerów. Po ich dodaniu otrzymasz listę, z której pobierzesz identyfikatory do kolejnych żądań.

Sposoby integracji płatności

Sposób	Zastosowanie
Link produktu z pola `paymentUrl`	Przekierowanie kupującego do wyboru wariantu i płatności na stronie SpaceIs.
`POST /cart/paymentUrl`	Utworzenie linku do koszyka z wybranymi wariantami i ilościami.
`POST /transaction/cartPayment`	Rozpoczęcie płatności za koszyk z własnego formularza sklepu.
`POST /transaction/variantPayment`	Dotychczasowa płatność za pojedynczy wariant.

Jeżeli korzystasz ze strony płatności SpaceIs, używaj zwróconego paymentUrl bez samodzielnego składania adresu. Dzięki temu link uwzględni również aktywną własną domenę płatności.

Obsługa odpowiedzi i błędów

Sprawdzaj kod HTTP i treść odpowiedzi. Kod 200 po utworzeniu płatności oznacza przyjęcie żądania, a nie potwierdzenie wpłaty.

Kod HTTP	Znaczenie
`200`	Żądanie obsłużone prawidłowo.
`400`	Operacja niedostępna lub nie udało się rozpocząć płatności. Szczegóły zawiera odpowiedź.
`401`	Brak prawidłowego klucza API.
`402`	Licencja nie jest aktywna.
`403`	Operacja jest niedozwolona lub funkcja jest wyłączona.
`404`	Nie znaleziono zasobu dostępnego dla tej licencji.
`409`	Konflikt przy realizacji operacji, np. kod rabatowy nie jest już dostępny.
`422`	Nieprawidłowe dane lub niedozwolona zawartość koszyka.
`429`	Przekroczono limit żądań lub limit zakupów.
`500`	Błąd podczas obsługi żądania.

Przykładowa odpowiedź błędu:

{
  "success": false,
  "type": "error",
  "message": "invalid variant"
}

Błędy walidacji mogą mieć pola message i errors, bez success i type. W takiej odpowiedzi klucze errors wskazują pola wymagające poprawy, np. items.0.variantId.

Przy limicie zapytań uwzględnij nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i Retry-At. Ostatni z nich, zwracany po przekroczeniu limitu, określa liczbę sekund oczekiwania. Nie traktuj każdego kodu 429 jako ograniczenia API: może też oznaczać limit zakupów produktu.