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).
Jak to działa
Dział zatytułowany „Jak to działa”| 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.
Nazwy pól
Dział zatytułowany „Nazwy pól”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.
Założenie pola
Dział zatytułowany „Założenie pola”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:
GET /api/complex-fields/v2/complex-fields— lista pól (stronicowana; filtrfieldName),GET …/{id}— jedno pole,POST …/byNames— pola o podanych nazwach.PUT /api/complex-fields/v2/complex-fields/{id}— zmiana etykiety, opisu, typu, wartości do wyboru iadditionalFieldMapping. W treści podaj teżid(takie samo jak w adresie). Nazwy i ID nie zmienisz —namew treści jest ignorowane.DELETE /api/complex-fields/v2/complex-fields/{id}— usuwa pole razem z jego wartościami we wszystkich produktach.
Zapis i odczyt wartości
Dział zatytułowany „Zapis i odczyt wartości”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" }]- Zapis: przy tworzeniu produktu (
POST /api/products/v2/products) i aktualizacji (PUT /api/products/v3/products/{id}). Pole musi być wcześniej założone — wartość wiąże się z polem po nazwie. Wartość dla pola, którego nie ma w PIM, jest pomijana bez błędu — przy tworzeniu i przy aktualizacji. Przy aktualizacji podaj w treściidproduktu (takie samo jak w adresie).purgeExistingComplexFields: truezastępuje wszystkie wartości pól produktu przesłaną listą (także opisy) — bez tej flagi przesłane wartości są dopisywane i aktualizowane. - Pliki (
File,FileLink):POST /api/v3/products/{productId}/complex-fields/{complexFieldName}/File. - Odczyt:
GET /api/products/v4/products/{id}?includes.includeComplexFields=true— bez tego parametrucomplexFieldsnie są zwracane. Filtrowanie produktów po wartości pola:POST /api/products/v3/advanced-filter.
Przeniesienie pola z BaseLinkera — krok po kroku
Dział zatytułowany „Przeniesienie pola z BaseLinkera — krok po kroku”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
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
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).
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
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
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)
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)
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" } } }}Różnice między krokiem 0 a 4
Dział zatytułowany „Różnice między krokiem 0 a 4”| 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.
Na co uważać
Dział zatytułowany „Na co uważać”- 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 (
GETzincludes.includeComplexFields=true). - Odczyt bez
includes.includeComplexFields=truenie 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_idz listy pól nie występuje w danych produktu — klucz wtext_fieldspochodzi z nazwy pola (zobacz ramkę wyżej).
Odpowiedniki w BaseLinker
Dział zatytułowany „Odpowiedniki w BaseLinker”| 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…) |
Zobacz też
Dział zatytułowany „Zobacz też”- Produkty (PIM)
- Pola dodatkowe zamówień — pola elastyczne zamówień, pozycji i zwrotów
- Beel API → Identyfikatory z BaseLinkera — które ID da się zachować przy migracji
- Referencja: PIM API → Pola złożone

