Автентифікація

Формат API-ключа, дозволи, ідемпотентність та обмеження запитів в API інтеграції плагінів.

Кожен виклик /api/v1/plugin/* має містити правильний заголовок X-Api-Key.

Формат ключа

mk_live_<keyId>.<secret>

Ключі плагіна пов'язані рівно з однією інсталяцією плагіна. Продавець створює інсталяцію в Налаштування → Встановлення плагінів, а потім генерує ключ у Налаштування → API Ключі; секретна частина показується лише раз, під час створення.

Створення першого ключа

Робочий ключ потребує активної інсталяції плагіна — ключі без інсталяції відхиляються кожним ендпойнтом /api/v1/plugin/*.

Створіть інсталяцію. У налаштуваннях команди відкрийте Налаштування → Встановлення плагінів і додайте інсталяцію для платформи вашого магазину. Інсталяція визначає максимальний набір дозволів, які можуть мати її ключі.
Створіть ключ. Відкрийте Налаштування → API Ключі, створіть новий ключ і виберіть свою інсталяцію. Дозволи інсталяції буде застосовано до ключа автоматично; їх можна звузити, але не розширити.
Скопіюйте секрет у плагін. Повний ключ (mk_live_<keyId>.<secret>) показується лише раз, одразу після створення. Вставте його в налаштуваннях Qamera AI у вашому плагіні. Якщо ви його втратите, створіть новий ключ — секрет не можна показати повторно.

Дозволи ключа (scope)

Кожен ключ видається з одним або кількома дозволами. Фактичний набір — це перетин дозволів ключа та дозволів інсталяції: ключ може бути вужчим за інсталяцію, але ніколи ширшим.

Дозвіл	Ендпойнти
`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 працює з будь-яким дійсним ключем. Виклик маршруту без потрібного дозволу повертає 403 forbidden.

Обмеження запитів

Кожен ключ має ліміт запитів на хвилину (за замовчуванням 60). Після його вичерпання наступний виклик повертає:

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

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

Повторіть виклик через Retry-After секунд.

Ідемпотентність

Операції запису приймають заголовок Idempotency-Key: <token>. Протягом 24 годин повторне надсилання того самого запиту з тим самим токеном повертає попередній результат замість створення дубліката; після цього вікна токен трактується як новий. Той самий токен з іншим тілом повертає 409 idempotency_conflict.

Рекомендація: формуйте токен із локального ідентифікатора операції у вашому магазині (напр. zamowienie-12345-wysylka).

Доступ

API плагінів доступне для всіх облікових записів — достатньо створити інсталяцію та ключ, окрема реєстрація не потрібна. Якщо доступ для вашого облікового запису вимкнено, кожен виклик повертає 503 із Retry-After: 3600; у такому разі напишіть на support@qamera.ai.

Помилки

Усі помилки мають спільний формат — див. перелік помилок із повним списком кодів.