Przejdź do głównej zawartości

Produkty (PIM)

Produkty w Sellrocket żyją w osobnym serwisie PIM (https://{instancja}-pim-api.enterprise.sellrocket.pl), z tym samym tokenem co OMS. Jeśli znasz magazyn BaseLinkera (Inventory), model będzie znajomy: katalogi, magazyny, grupy cenowe, warianty i zestawy. Ten przewodnik opisuje model danych oraz odczyt i zapis produktów. Masową aktualizację stanów i cen opisuje Synchronizacja stanów i cen.

Obiekt Opis
Katalog Odpowiednik Inventory w BaseLinkerze. Ma przypisane magazyny (warehouseIds), grupy cenowe (priceGroupIds) i języki (languages) oraz domyślny magazyn i grupę cenową.
Magazyn Miejsce, w którym produkt ma stan. Jeden produkt ma osobny stan w każdym magazynie katalogu.
Grupa cenowa Cennik (np. detal, hurt, marketplace). Produkt ma osobną cenę w każdej grupie cenowej.
Kategoria Drzewo kategorii (parentId) w obrębie katalogu.
Producent Słownik producentów (manufacturerId).
Produkt sku, ean, name, vat, weight, width, height, length, categoryId, manufacturerId, isBundle, parentId.
Wariant Produkt z parentId wskazującym produkt nadrzędny (np. rozmiar, kolor).
Zestaw Produkt z isBundle: true i listą składników (bundleItems). Jego stan jest wyliczany ze stanów składników.

Kolekcje produktu:

  • stocks — stany per magazyn: warehouseId, quantity, locationName (lokalizacja magazynowa),
  • productPriceGroups — ceny per grupa cenowa: priceGroupId, price,
  • properties — cechy (name, value, opcjonalnie externalId),
  • complexFields — pola złożone (name, value): opisy i pola dodatkowe produktu — zobacz Pola dodatkowe produktów,
  • productLinks — powiązania z ofertami w kanałach sprzedaży: connectionId (połączenie w OMS), externalProductId, externalVariantId,
  • bundleItems — składniki zestawu: bundleItemProductId, quantity,
  • additionalEans — dodatkowe kody EAN (ean, quantity — liczba sztuk w opakowaniu z tym kodem, description), translations — tłumaczenia w językach katalogu.
  1. Pobierz słowniki

    Identyfikatory katalogów, magazynów i grup cenowych są różne w każdej instancji — pobierz je na starcie:

    Okno terminala
    curl "https://$SR_INSTANCE-pim-api.enterprise.sellrocket.pl/api/catalogs/v2/products-catalogs?includeWarehouseIds=true&includePriceGroupIds=true" \
    -H "Authorization: Bearer $SR_TOKEN"

    Pozostałe słowniki: kategorie, producenci, magazyny, grupy cenowe, języki.

  2. Pobierz listę produktów

    Okno terminala
    curl "https://$SR_INSTANCE-pim-api.enterprise.sellrocket.pl/api/products/v4/products?catalogId=1&pageSize=100&pageNumber=0&includes.includeStocks=true&includes.includeProductLinks=true" \
    -H "Authorization: Bearer $SR_TOKEN"
    {
    "totalRecords": 1250,
    "totalPages": 13,
    "data": [
    {
    "id": 5012,
    "name": "Kubek termiczny 450 ml",
    "sku": "KT-450",
    "ean": "5901234123457",
    "catalogId": 1,
    "vat": 23,
    "isBundle": false,
    "isParent": false,
    "stocks": [{ "warehouseId": 3, "quantity": 18, "locationName": "A-01-02" }],
    "productLinks": [
    { "connectionId": 7, "externalProductId": "15734098211", "externalVariantId": null }
    ]
    }
    ]
    }

    GET /api/products/v4/products filtruje m.in. po sku/skus, ean/eans (dopasowuje także dodatkowe kody EAN; eans — maksymalnie 100 wartości; domyślnie dopasowanie jest częściowe i bez rozróżniania wielkości liter, a dokładne włączysz parametrem strictFilter=true), categoryId, warehouseId, zakresach stanu i ceny, isBundle oraz powiązaniach (productConnections, hasNoProductConnections). Kolekcje dołączasz flagami includes.* (includeStocks, includeProperties, includeProductLinks, includeComplexFields, includeVariants, includeBundleItems, includeTranslations…). pageSize może wynosić maksymalnie 1000.

  3. Pobierz pełne dane wybranych produktów

Do złożonych warunków (np. po wartości cechy albo pola złożonego) użyj POST /api/products/v3/advanced-filter — dostępne pola zwraca GET /api/products/v3/advanced-filter/field-definitions. Same identyfikatory pasujących produktów zwraca GET /api/products/v3/products/ids.

Utworzenie — POST /api/products/v2/products:

{
"catalogId": 1,
"name": "Kubek termiczny 450 ml",
"sku": "KT-450",
"ean": "5901234123457",
"vat": 23,
"weight": 0.35,
"categoryId": 12,
"manufacturerId": 4,
"stocks": [{ "warehouseId": 3, "quantity": 18, "locationName": "A-01-02" }],
"productPriceGroups": [{ "priceGroupId": 2, "price": 59.99 }],
"properties": [{ "name": "Kolor", "value": "czarny" }]
}

Wiele produktów utworzysz przez POST /api/products/v2/products/bulkCreate. Wariant to zwykły produkt z parentId, zestaw — produkt z isBundle: true i bundleItems.

Aktualizacja — PUT /api/products/v3/products/{id} działa jak częściowa zmiana: pole pominięte lub null pozostaje bez zmian. W treści podaj id produktu — takie samo jak w adresie (inaczej 400). Kolekcje są scalane po kluczu — stany po warehouseId, ceny po priceGroupId, cechy i pola złożone po name:

{
"id": 5012,
"name": "Kubek termiczny 450 ml czarny",
"stocks": [{ "warehouseId": 3, "quantity": 25 }],
"properties": [{ "name": "Pojemność", "value": "450 ml" }],
"purgeExistingProperties": true
}

Flagi purgeExistingStocks, purgeExistingProductPriceGroups, purgeExistingProperties, purgeExistingProductLinks i purgeExistingComplexFields zastępują całą kolekcję — elementy, których nie przekażesz, zostaną usunięte. W przykładzie powyżej produkt będzie miał tylko jedną cechę („Pojemność”), a stan w magazynie 3 zostanie nadpisany bez ruszania pozostałych magazynów.

Zmianę wybranych pól w wielu produktach naraz wykonasz przez POST /api/products/v2/products/bulkUpdate.

Powiązanie (productLinks) łączy produkt z PIM z ofertą lub produktem w kanale sprzedaży — tak Sellrocket wie, której pozycji zamówienia odpowiada produkt i gdzie wysyłać stany oraz ceny. Powiązania możesz zapisywać w produkcie albo osobno: POST /api/product-links/v2/product-links.

Mapowanie w drugą stronę (np. pozycja zamówienia z marketplace → produkt w katalogu):

Zdjęcia nie są częścią obiektu produktu — obsługuje je Galeria zdjęć API (https://{instancja}-image-gallery-api.enterprise.sellrocket.pl). Zdjęcia przypisuje się do obiektu (entityName — typ obiektu, entityId — jego ID) w numerowanych slotach (slot: 0, 1, 2…):

{
"entities": [
{
"entityName": "<typ obiektu>",
"entityId": "5012",
"pictures": [
{ "slot": 0, "imageLink": "https://cdn.example.com/kt-450-front.jpg" },
{ "slot": 1, "imageLink": "https://cdn.example.com/kt-450-side.jpg" }
]
}
],
"replaceAll": false
}
  • Pola złożone tylko na żądanie. Odczyt produktu zwraca complexFields (opisy, pola dodatkowe) tylko z includes.includeComplexFields=true. Wartość pola, którego nie ma w PIM, jest przy zapisie pomijana bez błędu — zobacz Pola dodatkowe produktów.
  • Listy zwijają warianty. GET /api/products/v4/products przy dopasowaniu w wariancie zwraca produkt nadrzędny. Warianty pobierzesz z includes.includeVariants=true lub z GET /api/products/v4/products/{id}.
  • productLinks i bundleItems w aktualizacji to zawsze pełna lista. Jeśli je przekażesz, muszą zawierać wszystkie elementy — brakujące zostaną usunięte. To samo dotyczy additionalEans.
  • Stanu zestawu nie ustawiasz. Zestaw liczy stan ze składników, a składniki muszą należeć do tego samego katalogu. Zobacz Synchronizacja stanów i cen.
  • Dwa identyfikatory połączenia. W powiązaniu connectionId to liczbowe ID połączenia z OMS (GET /api/v3/Connections); externalConnectionId to tekstowy identyfikator po stronie integracji.
  • Paginacja PIM jest inna niż w OMS: pageSize/pageNumber i odpowiedź { data, totalRecords, totalPages } — zobacz Konwencje API.
BaseLinker Sellrocket (PIM)
getInventories GET /api/catalogs/v2/products-catalogs
getInventoryWarehouses, getInventoryPriceGroups GET /api/warehouses/v2/warehouses, GET /api/price-groups/v2/product-price-groups
getInventoryCategories, getInventoryManufacturers GET /api/categories/v2/categories, GET /api/manufacturers/v2/products-manufacturers
getInventoryExtraFields GET /api/complex-fields/v2/complex-fields — zobacz Pola dodatkowe produktów
extra_field_<ID> w text_fields complexFields produktu, pole extra_field|extra_field_<ID>
getInventoryProductsList GET /api/products/v4/products
getInventoryProductsData POST /api/products/v4/productsByIds
addInventoryProduct (nowy) POST /api/products/v2/products
addInventoryProduct (edycja) PUT /api/products/v3/products/{id}
deleteInventoryProduct DELETE /api/products/v2/products/{id}
links w produkcie Powiązania produktów

Metody katalogu dostępne w trybie zgodności z BaseLinkerem: Beel API → Katalog.