Uwierzytelnianie

Format klucza API, uprawnienia, idempotencja i limity zapytań w API integracji wtyczek.

Każde wywołanie /api/v1/plugin/* musi zawierać prawidłowy nagłówek X-Api-Key.

Format klucza

mk_live_<keyId>.<secret>

Klucze wtyczek są powiązane z dokładnie jedną instalacją wtyczki. Sprzedawca tworzy instalację w Ustawienia → Instalacje wtyczek, a następnie generuje klucz w Ustawienia → Klucze API; sekretna część jest pokazana tylko raz, przy tworzeniu.

Tworzenie pierwszego klucza

Działający klucz wymaga aktywnej instalacji wtyczki — klucze bez instalacji są odrzucane przez każdy endpoint /api/v1/plugin/*.

Utwórz instalację. W ustawieniach zespołu otwórz Ustawienia → Instalacje wtyczek i dodaj instalację dla platformy Twojego sklepu. Instalacja wyznacza maksymalny zestaw uprawnień, jakie mogą mieć jej klucze.
Utwórz klucz. Otwórz Ustawienia → Klucze API, utwórz nowy klucz i wybierz swoją instalację. Uprawnienia instalacji zostaną zastosowane do klucza automatycznie; możesz je zawęzić, ale nie rozszerzyć.
Skopiuj sekret do wtyczki. Pełny klucz (mk_live_<keyId>.<secret>) jest pokazany tylko raz, zaraz po utworzeniu. Wklej go w ustawieniach Qamera AI w swojej wtyczce. Jeśli go zgubisz, utwórz nowy klucz — sekretu nie da się wyświetlić ponownie.

Uprawnienia klucza (scope)

Każdy klucz jest wystawiony z jednym lub kilkoma uprawnieniami. Efektywny zestaw to część wspólna uprawnień klucza i uprawnień instalacji — klucz może być węższy niż instalacja, ale nigdy szerszy.

Uprawnienie	Endpointy
`plugin.jobs:create`	`POST /jobs`, `POST /jobs/batch`, `POST /orders/{id}/clone`
`plugin.jobs:read`	`GET /jobs`, `GET /jobs/{id}`, `GET /orders/{id}`, `POST /jobs/{id}/refresh-url`, `POST /jobs/{id}/accept`, `POST /jobs/{id}/reject`, `GET /presets`
`plugin.jobs:cancel`	`DELETE /jobs/{id}`
`plugin.assets:upload`	`POST /assets/upload`
`plugin.catalog:read`	`GET /models`, `GET /sceneries`, `GET /ai-models`, `GET /aspect-ratios`, `GET /pricing`, `GET /presets`, `GET /products`, `GET /products/{id_or_ref}`, `GET /packshots`
`plugin.catalog:write`	`POST /images`, `POST /packshots`, `DELETE /products/{id_or_ref}`, `DELETE /packshots/{id_or_ref}`
`plugin.installations.manage`	`POST /installations/{id}/rotate-hmac`
`plugin.webhooks:manage`	`POST /webhooks/{delivery_id}/replay`

GET /me działa z każdym ważnym kluczem. Wywołanie trasy bez wymaganego uprawnienia zwraca 403 forbidden.

Limit zapytań

Każdy klucz ma limit zapytań na minutę (domyślnie 60). Po jego wyczerpaniu kolejne wywołanie zwraca:

HTTP/1.1 429 Too Many Requests
Retry-After: 47
Content-Type: application/json

{ "error": { "code": "rate_limit_exceeded", "retryable": true, ... } }

Ponów wywołanie po Retry-After sekundach.

Idempotencja

Operacje zapisu przyjmują nagłówek Idempotency-Key: <token>. Przez 24 godziny ponowne wysłanie tego samego żądania z tym samym tokenem zwraca poprzedni wynik zamiast tworzyć duplikat; po tym oknie token jest traktowany jak nowy. Ten sam token z innym body zwraca 409 idempotency_conflict.

Zalecenie: wyprowadź token z lokalnego identyfikatora operacji w Twoim sklepie (np. zamowienie-12345-wysylka).

Dostęp

API wtyczek jest dostępne dla wszystkich kont — wystarczy utworzyć instalację i klucz, nie trzeba się nigdzie zapisywać. Jeśli dostęp dla Twojego konta jest wyłączony, każde wywołanie zwraca 503 z Retry-After: 3600; w takiej sytuacji napisz na support@qamera.ai.

Błędy

Wszystkie błędy mają wspólny format — zobacz listę błędów z pełnym wykazem kodów.