Przejdź do głównej zawartości

Pola dodatkowe produktów

Pola dodatkowe produktów przechowują przy produkcie własne dane — „Kolor”, „Materiał”, „Kod producenta” — tak jak pola dodatkowe produktów w BaseLinkerze. W Sellrocket są to pola złożone (complex fields) w serwisie PIM: https://{instancja}-pim-api.enterprise.sellrocket.pl (ten sam token co w OMS).

Pola dodatkowe produktów Pola dodatkowe zamówień
Mechanizm pola złożone (PIM) pola elastyczne
Definicja pola /api/complex-fields/v2/complex-fields /api/v2/AdditionalFieldsDefinitions
Wartość w produkcie: complexFields (name, value) osobno, per obiekt (objectId)

Pola elastyczne nie obsługują produktów — pole dodatkowe produktu zakładasz w PIM.

Do zakładania pól i zapisu ich wartości używaj PIM API. Beel API pozwala pola produktów odczytywać — z kluczami jak w BaseLinkerze, jeśli pole ma odpowiednią nazwę (zobacz przykład). Lista pól w Beel API (getInventoryExtraFields) zwraca jednak inne ID niż BaseLinker, a zapis wartości przez Beel API (text_fields w addInventoryProduct) ma obecnie ograniczenia.

Każde pole ma nazwę techniczną (name) — unikalną w instancji, niezmienną po założeniu — i etykietę (caption) widoczną w panelu.

Nazwa techniczna Znaczenie
extra_field|<nazwa> pole dodatkowe produktu — widoczne jako pole dodatkowe m.in. w ofertach (parametry), szablonach wydruków i w Beel API
extra_field|extra_field_<ID z BaseLinkera> pole przeniesione z BaseLinkera — taką nazwę nadaje też import produktów z BaseLinkera
description, description_extra1… opisy produktu — nie zakładaj pól o takich nazwach

Pole bez prefiksu extra_field| nie jest traktowane jako pole dodatkowe produktu.

POST /api/complex-fields/v2/complex-fields:

{
"name": "extra_field|kolor",
"caption": "Kolor",
"type": "Select",
"options": ["czerwony", "niebieski", "zielony"]
}
Pole Opis
name Nazwa techniczna, wymagana, unikalna. Nie da się jej zmienić później.
caption Etykieta w panelu.
type Typ pola (wielkość liter bez znaczenia): Text, LongText, Number, Select, Checkbox, Radio, Date, File, FileLink. Listę zwraca GET …/complex-fields/renderTypes. Inna pisownia (np. long_text) → 400. Przy odczycie typ jest zwracany małymi literami (np. select).
options Wartości do wyboru — dla Select, Radio, Checkbox.
description Opis pola (opcjonalnie).
id Opcjonalne własne ID pola — np. ID z BaseLinkera. Zajęte ID albo zajęta nazwa → 400.
additionalFieldMapping Opcjonalnie: nazwa pola dodatkowego pozycji zamówienia. Gdy pozycja zamówienia jest dodawana z produktu PIM, wartość tego pola produktu jest kopiowana do wskazanego pola pozycji. Jedno pole pozycji może być wskazane tylko przez jedno pole produktu.

Odpowiedź zwraca ID pola. Typy z BaseLinkera przenosisz 1:1: text → Text, number → Number, select → Select, checkbox → Checkbox, radio → Radio, date → Date, file → File.

Pozostałe operacje:

Wartości pól są częścią produktu — tablica complexFields z parami name (nazwa techniczna pola) i value (zawsze tekst):

"complexFields": [
{ "name": "extra_field|kolor", "value": "czerwony" },
{ "name": "extra_field|extra_field_123", "value": "B2B" }
]

Pole dodatkowe produktu „Kolor” ma w BaseLinkerze ID 135. Krok 0 pokazuje, co zwraca BaseLinker; kroki 1–3 przenoszą pole do Sellrocket; krok 4 to te same wywołania co w kroku 0, wysłane do Beel API Sellrocket.

W przykładach: $BL_TOKEN — token BaseLinkera, $SR_INSTANCE — nazwa instancji Sellrocket, $SR_TOKEN — token API Sellrocket, $BEEL_TOKEN — token połączenia Beel API. Katalog i produkt mają w Sellrocket inne ID niż w BaseLinkerze (BL: katalog 307, produkt 2685; Sellrocket: katalog 1000000001, produkt 5000439262). Odpowiedzi są skrócone do pól istotnych w przykładzie.

Krok 0a. BaseLinker — lista pól dodatkowych

Okno terminala
curl -X POST "https://api.baselinker.com/connector.php" \
-H "X-BLToken: $BL_TOKEN" \
--data-urlencode "method=getInventoryExtraFields" \
--data-urlencode "parameters={}"
{
"status": "SUCCESS",
"extra_fields": [
{ "extra_field_id": 135, "name": "Kolor", "kind": 0, "editor_type": "text" }
]
}

Krok 0b. BaseLinker — produkt

Okno terminala
curl -X POST "https://api.baselinker.com/connector.php" \
-H "X-BLToken: $BL_TOKEN" \
--data-urlencode "method=getInventoryProductsData" \
--data-urlencode 'parameters={"inventory_id": 307, "products": [2685]}'
{
"status": "SUCCESS",
"products": {
"2685": {
"ean": "5901234123457",
"sku": "KUB-450-RED",
"tax_rate": 23,
"prices": { "105": 59.99 },
"stock": { "bl_206": 12 },
"text_fields": {
"name": "Kubek termiczny 450 ml",
"description": "Kubek termiczny ze stali nierdzewnej.",
"extra_field_135": "czerwony"
}
}
}
}

Krok 1. Sellrocket PIM — załóż pole z ID i nazwą z BaseLinkera

Nazwa extra_field|extra_field_135 sprawia, że Beel API zwraca wartość pod kluczem extra_field_135 (krok 4b).

Okno terminala
curl -X POST "https://$SR_INSTANCE-pim-api.enterprise.sellrocket.pl/api/complex-fields/v2/complex-fields" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": 135,
"name": "extra_field|extra_field_135",
"caption": "Kolor",
"type": "Text"
}'

Odpowiedź: 135 (ID pola). Zajęte ID albo nazwa → 400.

Krok 2. Sellrocket PIM — zapisz wartość w produkcie

Okno terminala
curl -X PUT "https://$SR_INSTANCE-pim-api.enterprise.sellrocket.pl/api/products/v3/products/5000439262" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": 5000439262,
"complexFields": [
{ "name": "extra_field|extra_field_135", "value": "czerwony" }
]
}'

id w treści musi być takie samo jak w adresie. Przy nowym produkcie podaj complexFields w POST /api/products/v2/products.

Krok 3. Sellrocket PIM — sprawdź produkt

Okno terminala
curl "https://$SR_INSTANCE-pim-api.enterprise.sellrocket.pl/api/products/v4/products/5000439262?includes.includeComplexFields=true" \
-H "Authorization: Bearer $SR_TOKEN"
"complexFields": [
{ "id": 4410, "name": "extra_field|extra_field_135", "value": "czerwony" }
]

(id w complexFields to ID wpisu wartości, nie pola.)

Krok 4a. Sellrocket Beel API — lista pól dodatkowych (jak krok 0a)

Okno terminala
curl -X POST "https://$SR_INSTANCE-beel-api.enterprise.sellrocket.pl/connector.php" \
-H "X-BLToken: $BEEL_TOKEN" \
--data-urlencode "method=getInventoryExtraFields" \
--data-urlencode "parameters={}"
{
"status": "SUCCESS",
"extra_fields": [
{ "extra_field_id": 1969453817, "name": "Kolor", "kind": 0, "options": [] }
]
}

Krok 4b. Sellrocket Beel API — produkt (jak krok 0b)

Okno terminala
curl -X POST "https://$SR_INSTANCE-beel-api.enterprise.sellrocket.pl/connector.php" \
-H "X-BLToken: $BEEL_TOKEN" \
--data-urlencode "method=getInventoryProductsData" \
--data-urlencode 'parameters={"inventory_id": 1000000001, "products": [5000439262]}'
{
"status": "SUCCESS",
"products": {
"5000439262": {
"ean": "5901234123457",
"sku": "KUB-450-RED",
"tax_rate": 23,
"prices": { "1000000002": 59.99 },
"stock": { "bl_1000000003": 12 },
"text_fields": {
"name": "Kubek termiczny 450 ml",
"description": "Kubek termiczny ze stali nierdzewnej.",
"extra_field_135": "czerwony"
}
}
}
}
BaseLinker (krok 0) Sellrocket Beel API (krok 4)
extra_field_id pola „Kolor” 135 1969453817 — liczba wyliczona z nazwy pola; stała dla danej nazwy, ale nigdy równa ID z BL
editor_type text brak
klucz w text_fields extra_field_135 extra_field_135 ✔ bez zmian
ID produktu, katalogu, grup cenowych, magazynów 2685, 307, 105, bl_206 inne — nadaje Sellrocket

Zapis przez Beel API: addInventoryProduct z text_fields: { "extra_field_135": "…" } odpowiada SUCCESS, ale nie zmienia wartości, a przy tworzeniu nowego produktu pola dodatkowe nie są zapisywane. Wartości pól produktów zapisuj przez PIM API (krok 2). Pola bez wartości nie są zwracane w text_fields. Token Beel API przekazuj w nagłówku X-BLToken (w połączeniu Beel nazwa nagłówka musi być X-BLToken) albo w polu token w treści żądania.

  • Nazwa jest kluczem — wartości w produktach są powiązane z polem po nazwie technicznej, której nie da się zmienić. Ustal ją na stałe przed pierwszym zapisem.
  • Usunięcie pola kasuje jego wartości we wszystkich produktach.
  • Literówka w nazwie pola nie daje błędu — wartość zostanie pominięta (przy tworzeniu i aktualizacji produktu). Po zapisie sprawdź produkt (GET z includes.includeComplexFields=true).
  • Odczyt bez includes.includeComplexFields=true nie zwraca pól produktu — brak pól w odpowiedzi nie oznacza, że produkt ich nie ma.
  • Prefiks extra_field| — bez niego pole nie będzie widoczne jako pole dodatkowe produktu (oferty, wydruki, Beel API).
  • purgeExistingComplexFields — przy aktualizacji zastępuje całą listę, łącznie z opisami produktu.
  • Beel API: extra_field_id z listy pól nie występuje w danych produktu — klucz w text_fields pochodzi z nazwy pola (zobacz ramkę wyżej).
BaseLinker Sellrocket (PIM)
getInventoryExtraFields GET /api/complex-fields/v2/complex-fields
extra_field_<ID> w text_fields complexFields produktu, pole extra_field|extra_field_<ID>
editor_type type pola (Text, Number, Select…)