Publiczny interfejs API Escher V2 (/v1/*) wymaga tokenu Bearer w każdym żądaniu. Twórz i zarządzaj tokenami na stronie Tokeny API — otwórz menu konta w lewym dolnym rogu paska bocznego i wybierz Tokeny API (/settings/api-tokens).
Najpierw musisz włączyć dostęp do API
Tokeny API są ograniczone dostępem. Strona pozwala na tworzenie tokenów tylko wtedy, gdy dostęp do API jest włączony na Twoim koncie.
Jeśli tak nie jest, strona wyświetla:
API access isn't enabled on your account. Contact your account manager at support@theprintspace.co.uk to request it.
Wyślij wiadomość email na adres support@theprintspace.co.uk, aby włączyć dostęp, a następnie wróć na stronę.
Kto potrzebuje tokenów API
- Artyści budujący niestandardowe integracje (np. stronę portfolio, która uruchamia drop na żądanie).
- Agencje zarządzające wieloma kontami artystów za pomocą automatyzacji.
- Programiści budujący wewnętrzne narzędzia komunikujące się z API.
Jeśli używasz tylko interfejsu webowego do ręcznego tworzenia drop, nie potrzebujesz tokenu.
Jak tworzyć
- Otwórz stronę Tokeny API (menu konta → Tokeny API).
- Wpisz Nazwę tokenu (pole zawiera placeholder "Token name (e.g. 'Backend CI')"), aby móc go później zidentyfikować.
- Opcjonalnie wpisz Webhook URL — patrz poniżej. Pole zawiera placeholder "Webhook URL (optional, https://…)"; zostaw je puste lub podaj pełny adres URL z
https://. - Kliknij Generate token.
- Pełny token jest wyświetlany raz, z notatką "Copy this token now — it will never be shown again." Skopiuj go natychmiast.
- Przechowuj go bezpiecznie — w menedżerze sekretów, zmiennych środowiskowych CI/CD lub pliku
.envpoza kontrolą wersji.
Nowe tokeny pojawiają się na liście z kolumnami: Name, Prefix, Webhook, Created, Last used. Przechowywany jest tylko prefiks — pełny token nie może być pobrany po utworzeniu.
Opcjonalny webhook URL
Każdy token może mieć opcjonalny adres webhook URL z protokołem https://. Ustaw go podczas generowania tokenu lub edytuj później: kliknij ikonę ołówka obok komórki Webhook w wierszu tokenu, wpisz pełny adres URL z https:// (lub go usuń) i zapisz.
Co możesz zrobić z tokenem
Pełna powierzchnia /v1 jest udokumentowana w endpoint OpenAPI (/openapi.json w usłudze API). Typowe operacje:
- Tworzenie drop —
POST /v1/drops. - Dodawanie produktów do drop —
POST /v1/drops/{drop_id}/products. - Konfigurowanie wariantów —
PUT /v1/drops/{drop_id}/products/{product_id}/variants. - Publikowanie —
POST /v1/drops/{drop_id}/publish. - Sprawdzanie statusu publikacji —
GET /v1/drops/{drop_id}/publish-attempts/latest. - Generowanie rekomendacji —
POST /v1/recommendations. - Ekstrahowanie stylów strony z URL —
POST /v1/styles/extract(zwraca pięć wariantów do wyboru). - Zapisywanie predefiniowanego stylu strony —
POST /v1/styles.
Uwierzytelnianie
Przesyłaj token jako nagłówek Bearer w każdym żądaniu:
Authorization: Bearer <your-token>
Brakujący, unieważniony lub nieważny token zwraca HTTP 401. Jeśli dostęp do API został wyłączony na koncie, otrzymasz HTTP 403.
Limity szybkości
- Endpoint do odczytu: 120 żądań na minutę na użytkownika.
- Endpoint do zapisu: 30 żądań na minutę na użytkownika.
Przekroczone żądania zwracają HTTP 429 z nagłówkiem Retry-After. Limity są per użytkownika, a nie per token, więc wiele tokenów dla tego samego użytkownika dzieli ten sam limit.
Cykl życia tokenu
- Unieważnienie — kliknij przycisk Revoke w wierszu tokenu i potwierdź okno dialogowe ("Revoke … This cannot be undone and the token will stop working immediately."). Przyszłe żądania z tym tokenem zwrócą 401.
- Rotacja — wygeneruj nowy token, przełącz integrację na jego używanie, a następnie unieważnij stary token. Brak przestojów, jeśli zrobisz to we właściwej kolejności.
- Wygaśnięcie — tokeny nie wygasają automatycznie domyślnie. Obracaj je co 6–12 miesięcy jako praktykę bezpieczeństwa.
Nie udostępniaj
Tokeny to pełne poświadczenia — każdy, kto je ma, może działać jako Ty na platformie, łącznie z publikowaniem drop i edytowaniem produktów. Traktuj je z taką samą ostrożnością jak hasło.