crosello Dokumentacja API

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:

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}}

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.