API інтеграції плагінів

Це API дає змогу плагіну електронної комерції (Saleor, Shoper, PrestaShop, Shopify та іншим) замовляти в Qamera AI професійні фото продуктів продавця: пакшоти на чистому тлі та цілі фотосесії в обраному стилі. Ви завантажуєте звичайне фото або готовий пакшот, замовляєте сесію, а готові зображення отримуєте вебхуком або простим опитуванням.

Почніть з основних процесів. Кожен підтримуваний сценарій — від фото з магазину до готової сесії — описано там стисло, з покроковим навчальним матеріалом.

Швидкі посилання

• Основні процеси — усі сценарії інтеграції стисло + навчальні матеріали.
• Автентифікація — ключі API, дозволи, обмеження запитів.
• Ендпойнти — кожен маршрут: що повертає і коли його використати.
• Протокол webhook — форма повідомлень, підпис, повтори.
• Приклади curl — шпаргалка з готовими викликами.
• Субобробники — треті сторони, що обробляють дані продавця.
• Перелік помилок — кожен код із причиною та способом виправлення.
• Контракт OpenAPI 3.1 (YAML) — повна специфікація для генератора коду або власних інструментів.
• Інтерактивна документація API (Redoc) — той самий контракт у вигляді зручної документації, без жодного налаштування.

Словник

• Завдання — одне завдання генерації, результатом якого є одне зображення. Надсилання сесії створює images_count завдань для кожного продукту.
• Сесія (замовлення) — один виклик POST /jobs: спільна конфігурація (стиль, сценерія, модель, пропорції) застосована до одного чи кількох продуктів. Ідентифікується через order_id.
• Продукт у сесії — один запис у subjects[]: який продукт сфотографувати, з якого пакшота та скільки зображень згенерувати.
• Пакшот — фото продукту на чистому, нейтральному тлі, готове до подальшої обробки. Фотосесії генеруються з прийнятого пакшота.
• Інсталяція плагіна — одне з'єднання між магазином продавця та Qamera AI. Ключі API, продукти й вебхуки належать до однієї інсталяції.
• Ваш ідентифікатор (external_ref) — сталий ідентифікатор, який ваш плагін призначає записам каталогу (продуктам, зображенням, пакшотам), напр. shop1:product-7. Він пов'язує дані Qamera AI з вашим магазином: повторна реєстрація з тим самим external_ref повертає наявний запис, а в шляхах на кшталт GET /products/{id_or_ref} можна передати його замість UUID.
• Дозвіл ключа (scope) — те, що ключ API може робити (напр. plugin.jobs:create). Виклик без потрібного дозволу повертає 403 forbidden.
• Тимчасова адреса файлу — обмежена в часі адреса для завантаження або отримання файлу. Адреси для завантаження результатів дійсні щонайменше 7 днів; свіжу адресу отримаєте через POST /jobs/{id}/refresh-url.

Версіонування

Основна версія є частиною адреси (/api/v1/plugin/...). Зміни, що нічого не ламають (нові поля, нові коди помилок), випускаються без зміни версії та оголошуються в журналі змін. Несумісні зміни з'являться під /api/v2/....