API integracji wtyczek

To API pozwala wtyczce e-commerce (Saleor, Shoper, PrestaShop, Shopify i inne) zamawiać w Qamera AI profesjonalne zdjęcia produktów sprzedawcy: packshoty na czystym tle i całe sesje zdjęciowe w wybranym stylu. Wysyłasz zwykłe zdjęcie lub gotowy packshot, zamawiasz sesję, a gotowe zdjęcia odbierasz webhookiem albo zwykłym odpytaniem.

Zacznij od głównych procesów. Każdy obsługiwany przebieg — od zdjęcia ze sklepu do gotowej sesji — jest tam opisany w pigułce, z samouczkiem krok po kroku.

Szybkie linki

• Główne procesy — wszystkie przebiegi integracji w pigułce + samouczki.
• Uwierzytelnianie — klucze API, uprawnienia, limity zapytań.
• Endpointy — każda trasa: co zwraca i kiedy jej użyć.
• Protokół webhook — kształt powiadomień, podpis, ponowienia.
• Przykłady curl — ściąga z gotowymi wywołaniami.
• Subprocesory — podmioty trzecie przetwarzające dane sprzedawcy.
• Lista błędów — każdy kod z przyczyną i sposobem naprawy.
• Kontrakt OpenAPI 3.1 (YAML) — pełna specyfikacja do generatora kodu lub własnych narzędzi.
• Interaktywna dokumentacja API (Redoc) — ten sam kontrakt w formie przeglądalnej dokumentacji, bez żadnej konfiguracji.

Słowniczek

• Zadanie — pojedyncze zadanie generowania, którego wynikiem jest jedno zdjęcie. Wysłanie sesji tworzy images_count zadań dla każdego produktu.
• Sesja (zamówienie) — jedno wywołanie POST /jobs: wspólna konfiguracja (styl, sceneria, modelka, proporcje) zastosowana do jednego lub wielu produktów. Identyfikowana przez order_id.
• Produkt w sesji — jeden wpis w subjects[]: który produkt sfotografować, z którego packshota i ile zdjęć wygenerować.
• Packshot — zdjęcie produktu na czystym, neutralnym tle, gotowe do dalszej obróbki. Sesje zdjęciowe są generowane z zaakceptowanego packshota.
• Instalacja wtyczki — jedno połączenie między sklepem sprzedawcy a Qamera AI. Klucze API, produkty i webhooki należą do jednej instalacji.
• Twój identyfikator (external_ref) — stały identyfikator, który Twoja wtyczka nadaje rekordom katalogu (produktom, zdjęciom, packshotom), np. sklep1:produkt-7. Wiąże dane w Qamera AI z Twoim sklepem: ponowna rejestracja z tym samym external_ref zwraca istniejący rekord, a w ścieżkach typu GET /products/{id_or_ref} możesz go podać zamiast UUID.
• Uprawnienie klucza (scope) — to, co klucz API może robić (np. plugin.jobs:create). Wywołanie bez wymaganego uprawnienia zwraca 403 forbidden.
• Tymczasowy adres pliku — ograniczony czasowo adres do wgrania lub pobrania pliku. Adresy pobierania wyników są ważne co najmniej 7 dni; świeży adres uzyskasz przez POST /jobs/{id}/refresh-url.

Wersjonowanie

Wersja główna jest częścią adresu (/api/v1/plugin/...). Zmiany, które niczego nie psują (nowe pola, nowe kody błędów), wchodzą bez zmiany wersji i są ogłaszane w changelogu. Zmiany niezgodne wstecz pojawią się pod /api/v2/....