Основні процеси

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

Перш ніж почати: кожен сценарій потребує інсталяції плагіна та прив'язаного до неї ключа API — див. Автентифікація, де налаштування описано крок за кроком.

Два поняття, яких достатньо для старту:

• Сесія (замовлення) — один виклик POST /jobs: спільна конфігурація (стиль, сценерія, модель, пропорції) застосована до одного чи кількох продуктів. Ідентифікується через order_id.
• Пакшот — фото продукту на чистому, нейтральному тлі. Фотосесію можна замовити лише для продукту, який має прийнятий пакшот.

Повний словник — на сторінці огляду.

A. Фотосесія з готового пакшота

Найкоротший шлях до готових зображень: продавець уже має пакшот продукту, тож ви завантажуєте його, реєструєте й одразу замовляєте сесію.

1. POST /assets/upload      → тимчасова адреса для завантаження файлу
2. PUT <upload_url>         → надішліть файл пакшота
3. POST /packshots          → зареєструйте пакшот (прийнятий одразу)
4. POST /jobs               → замовте фотосесію
5. webhook / GET /jobs/{id} → отримайте готові зображення
6. POST /jobs/{id}/accept   → (необов'язково) оцініть результати

Навчальний матеріал: сесія з готового пакшота →

B. Пакшот зі звичайного фото з магазину

Продавець має лише звичайне фото продукту (наприклад, із телефона). Спершу ви генеруєте кілька варіантів пакшота, продавець обирає один, і після його прийняття можна замовляти фотосесії. Саме тут діє вимога прийнятого пакшота: сесія для продукту без прийнятого пакшота повертає помилку 422 packshot_not_approved.

1. POST /assets/upload + PUT      → завантажте фото з магазину
2. POST /images                   → зареєструйте фото в каталозі
3. POST /jobs (job_type=packshot) → замовте N варіантів пакшота
4. POST /jobs/{id}/accept         → прийміть обраний варіант
   POST /jobs/{id}/reject         → відхиліть решту
5. POST /jobs                     → замовте фотосесію

Навчальний матеріал: пакшот із фото →

C. Параметри сесії — стиль, сценерія, модель

Перш ніж надіслати сесію, покажіть продавцеві, що можна обрати. П'ять ендпойнтів повертають повний каталог: стилі (пресети) з мініатюрами та галереями, моделі, сценерії, доступні AI-моделі з вартістю в кредитах і пропорції зображення. Із цих даних ви побудуєте екран вибору у своєму плагіні.

GET /presets        → стилі з мініатюрами, галереями та вартістю
GET /models         → моделі (акаунт + маркетплейс)
GET /sceneries      → сценерії (акаунт + маркетплейс)
GET /ai-models      → AI-моделі, доступні для плану акаунта
GET /aspect-ratios  → пропорції зображення (одна за замовчуванням)

Навчальний матеріал: параметри сесії →

D. Багато продуктів одночасно

Потрібно відзняти весь асортимент? Одна сесія приймає до 100 продуктів, а POST /jobs/batch — до 100 сесій в одному виклику (загалом до 5000 зображень). Відповідь — HTTP 207: кожна сесія проходить або відхиляється незалежно від інших.

1. Підготуйте сесії (продукти + конфігурація)
2. POST /jobs/batch  → до 100 сесій одночасно
3. HTTP 207          → результат для кожної сесії (accepted / failed)
4. Отримайте результати через вебхуки або опитування

Навчальний матеріал: сесії гуртом →

E. Отримання результатів

Коли завдання завершується, ми надсилаємо вебхук на адресу вашої інсталяції — з підписом HMAC, автоматичними повторами та можливістю повторного надсилання. Якщо не хочете утримувати ендпойнт вебхука, можете опитувати GET /jobs/{id}. Адреси для завантаження результатів дійсні щонайменше 7 днів; свіжу адресу отримаєте одним викликом.

вебхук (push)                   GET /jobs/{id} (pull)
  ├─ перевірте підпис HMAC        ├─ перевіряйте статус
  ├─ відповідайте 2xx             └─ завантажте outputs[].url
  └─ завантажте outputs[].url
адреса прострочена? → POST /jobs/{id}/refresh-url

Навчальний матеріал: отримання результатів →

F. Повторна сесія (регенерація)

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

1. POST /orders/{id}/clone  (заголовок Idempotency-Key обов'язковий)
   ├─ порожнє тіло           → ті самі продукти й кількість зображень
   └─ тіло із subjects[]     → нова кількість зображень для продукту
2. Отримайте результати, як у процесі E

Навчальний матеріал: повторна сесія →

Що далі

• Автентифікація — ключі API та дозволи, перш ніж почати.
• Ендпойнти — повний список маршрутів, коли ви вже знаєте процеси.
• Перелік помилок — кожен код помилки з причиною та способом виправлення.