Dokumentacja
API crosello
Pobieraj listy cross-sell i up-sell dla produktów z wgranego feedu.
Jak to działa
Wgrywasz feed produktów (CSV). Silnik buduje macierz relacji między kategoriami, czyta karty produktów i wylicza dla każdego produktu dwie listy:
- cross_sell — produkty z kategorii podrzędnych o relacji
consumable_for(materiały eksploatacyjne) iaccessory_for(akcesoria), dopasowane do produktu (marka, seria, model, system); - upsell — droższe zamienniki (
substitute_of, ten sam rodzaj, cena ×1,1–1,8) i produkty używane razem (complementary_to).
Listy są liczone raz na przebieg feedu i serwowane bez opóźnienia. Każda pozycja ma pole evidence: confirmed (zgodność potwierdzona na kartach), probable, category (z kategorii, bez deklaracji zgodności na karcie), similarity (podobieństwo opisu), weak.
Gdy sklep nie sprzedaje urządzenia, do którego pasuje produkt (np. etui do telefonu w sklepie z samymi akcesoriami), lista cross_sell zawiera dodatki innego rodzaju do tego samego urządzenia. Pole relation podaje wtedy relację pozycji do tego urządzenia, a evidence: confirmed (ten sam model na kartach obu produktów) albo category (wspólna kategoria modelu w sklepie). Wolne miejsca tej listy uzupełniają akcesoria uniwersalne do takich urządzeń (np. uchwyt, ładowarka), zawsze z evidence = category.
Uwierzytelnianie
Klucz API tworzysz w panelu. Każde żądanie: Authorization: Bearer ck_… (albo nagłówek X-Api-Key). Klucz jest tajny — używaj go tylko po stronie serwera.
Błędy: kod HTTP i {"error": {"code", "message"}}, np. 401 bad_api_key, 404 product_not_found, 409 feed_not_ready.
Rekomendacje
GET /v1/feeds/{feed_id}/products/{product_id}/recommendations
Parametry: lists = cross_sell, upsell albo obie (domyślnie), limit 1–5 (domyślnie 5).
{
"feed_id": "feed_3f2a9c1b07e4", "run_id": "run_…", "product_id": "3545", "name": "Ekspres do kawy JURA WE6",
"cross_sell": [
{"product_id": "38424", "name": "JURA filtr do wody Claris Pro Smart+", "relation": "consumable_for", "evidence": "confirmed", "score": 0.846, "position": 1}
],
"upsell": [
{"product_id": "62289", "name": "Ekspres do kawy JURA J10", "relation": "substitute_of", "evidence": "weak", "score": 0.889, "position": 1}
]
}
POST /v1/feeds/{feed_id}/recommendations
Dobór dla zestawu produktów, np. ostatnich zakupów klienta w newsletterze. Wyniki z list produktów wejściowych są sumowane (pozycja wyżej i mocniejszy dowód ważą więcej); produkty wejściowe i exclude_ids są pomijane.
POST /v1/feeds/feed_3f2a9c1b07e4/recommendations
{"product_ids": ["3545", "9753"], "exclude_ids": ["38424"], "lists": ["cross_sell", "upsell"], "limit": 8}
{"items": [{"product_id": "13278", "name": "…", "list": "cross_sell", "relation": "accessory_for", "evidence": "probable",
"score": 0.85, "position": 1, "because_of": ["3545"]}],
"missing_product_ids": []}
Limity: do 50 produktów wejściowych, limit 1–50.
Historia klienta: zakupy i przeglądane kategorie
Gdy masz historię klienta, wyślij w jednym zapytaniu jego zakupy (product_ids) i kategorie, które przeglądał (viewed_categories). Listy powstają z zakupionych produktów, a pozycje z przeglądanych kategorii trafiają wyżej (wynik ×1,5). Przykład: klient kupił ekspres i przeglądał kawę ziarnistą — w newsletterze kawa z jego listy cross-sell wyprzedzi inne akcesoria.
POST /v1/feeds/feed_3f2a9c1b07e4/recommendations
{"product_ids": ["3545"],
"viewed_categories": ["Kawa > Kawa ziarnista", "Akcesoria do ekspresów"],
"exclude_ids": ["38424"], "limit": 6}
{"items": [{"product_id": "20871", "name": "Kawa ziarnista Lavazza Qualità Oro 1 kg", "list": "cross_sell",
"relation": "consumable_for", "evidence": "probable", "score": 1.275, "position": 1,
"because_of": ["3545"], "viewed_categories": ["kawa-kawa-ziarnista"]},
{"product_id": "13278", "name": "…", "list": "cross_sell", "relation": "accessory_for", "evidence": "probable",
"score": 0.85, "position": 2, "because_of": ["3545"]}],
"missing_product_ids": [],
"viewed_categories": {"used": ["kawa-kawa-ziarnista", "akcesoria-do-ekspresow"], "supported": true}}
viewed_categories— do 50 kategorii z historii przeglądania: nazwa („Kawa ziarnista”), ścieżka jak w feedzie („Kawa > Kawa ziarnista”) albo identyfikator. Wielkość liter i polskie znaki nie mają znaczenia; nazwa pasuje do kategorii, którą kończy się ścieżka.product_ids— zakupy klienta (wymagane, 1–50); to z nich pochodzą rekomendacje. Same przeglądane kategorie bez zakupów nie wystarczą.- W odpowiedzi pozycje z przeglądanych kategorii mają pole
viewed_categories, aviewed_categories.usedpokazuje, jak rozpoznaliśmy przesłane kategorie. viewed_categories.supported: falseoznacza, że listy feedu opublikowano przed wprowadzeniem tej funkcji — użyj w panelu „Przelicz listy” (bez kosztu modelu), żeby kategorie zaczęły działać.
Feedy
POST /v1/feeds?name=…
Treść: plik CSV (content-type: text/csv) albo formularz multipart/form-data z polem file (przy plikach powyżej ok. 30 MB wysyłaj surową treść, np. curl --data-binary @feed.csv; nazwę podaj w parametrze name). Kolumny rozpoznawane automatycznie; nadpisanie: parametr columns (JSON), np. {"id": "SKU", "name": "Nazwa", "categories": "Kategoria", "category_path_sep": " > "}. Pola: id, name (wymagane), categories, brand, description, short, spec, price, stock. Odpowiedź 202 z feedem; przetwarzanie trwa zwykle 10–40 minut.
422 mapping_required zwraca nagłówek pliku i rozpoznane kolumny — wyślij plik ponownie z columns.
GET /v1/feeds · GET /v1/feeds/{feed_id}
Stan: queued, processing (pole stage), ready, error; products, cost_usd (koszt LLM przebiegów), ready = są opublikowane listy.
PUT /v1/feeds/{feed_id}/file
Nowa wersja pliku w tym samym feedzie: karty, które się nie zmieniły, nie są czytane ponownie. Do końca przebiegu API serwuje poprzednie listy.
POST /v1/feeds/{feed_id}/run · DELETE /v1/feeds/{feed_id}
Ponowne przetworzenie bez zmiany pliku: bez treści — pełny przebieg; {"resume": true} wznawia od etapu, na którym przerwał się ostatni przebieg; {"from": "s5"} przelicza od wskazanego etapu (np. same listy po aktualizacji silnika, bez kosztu modelu). Usunięcie feedu z plikami i listami.
Limity konta testowego: 3 feedy, 15 000 produktów w feedzie, plik do 100 MB.