Przejdź do głównej zawartości

Pola dodatkowe zamówień

Pola elastyczne to własne pola, które dopisujesz do zamówień, pozycji zamówień, zwrotów i innych obiektów — odpowiednik custom_extra_fields z BaseLinkera. Integracje używają ich do przechowywania własnych identyfikatorów i znaczników: numeru dokumentu w ERP, informacji „przekazano do magazynu”, numeru listu z zewnętrznego systemu. Pola obsługuje osobny serwis: https://{instancja}-additional-fields-api.enterprise.sellrocket.pl (ten sam token co w OMS).

  • Typ właściciela (ownerType) — rodzaj obiektu, do którego należy pole: zamówienie, pozycja zamówienia, zwrot, pozycja zwrotu i inne. Listę zwraca GET /api/v2/AdditionalFieldsOwners: każdy właściciel ma czytelną nazwę (name, np. „Order”, „Line Item”) i identyfikator (type) w postaci szablonu adresu. W polu ownerType przekazuj type, dokładnie tak, jak zwraca go API (razem z nawiasami klamrowymi) — sama nazwa „Order” nie zadziała. W przykładach poniżej <OWNER_ORDER> oznacza type właściciela „Order”.
  • Definicja — opis pola dla danego typu właściciela: fieldName (nazwa techniczna), fieldDisplayName (etykieta w panelu), fieldType, opcjonalnie predefinedValues (wartości do wyboru).
  • Wartość — przypisana do konkretnego obiektu: ownerType + objectId (np. ID zamówienia) + fieldName → fieldValue. Wartość zawsze przesyłasz jako tekst.
  • Historia — każda zmiana wartości jest zapisywana; możesz sprawdzić, kto i kiedy ją zmienił.

W polach elastycznych występują trzy różne identyfikatory — łatwo je pomylić:

Identyfikator Gdzie występuje Co oznacza
ID definicji id przy tworzeniu definicji, definitionId w odczycie wartości Numer samego pola (np. „Status w ERP”). W Beel API to extra_field_id.
objectId Zapis i odczyt wartości ID obiektu, do którego należy wartość — np. ID zamówienia albo pozycji.
fieldName Definicja i wartości Nazwa techniczna pola — klucz przy zapisie wartości przez REST API.

ID definicji nadaje system (od 1 000 000 000 wzwyż), chyba że podasz własne id przy tworzeniu definicji. ID jest unikalne w całej instancji, dla wszystkich typów obiektów (zamówienie, zwrot…).

Typy pól (GET /api/v2/AdditionalFieldTypes):

fieldType Zawartość
text Krótki tekst
long_text Długi tekst
number Liczba
bool Tak / nie
list Jedna z wartości predefinedValues
link Adres URL
file_link Plik (link do pliku)

POST /api/v2/AdditionalFieldsDefinitions tworzy definicję. Jeśli pole o tej nazwie dla tego typu właściciela już istnieje, żądanie kończy się błędem — sprawdź wcześniej GET /api/v2/AdditionalFieldsDefinitions?OwnerType=<OWNER_ORDER> (w adresie zakoduj wartość, np. encodeURIComponent).

Okno terminala
curl -X POST "https://$SR_INSTANCE-additional-fields-api.enterprise.sellrocket.pl/api/v2/AdditionalFieldsDefinitions" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ownerType": "<OWNER_ORDER>",
"fieldName": "erp_status",
"fieldDisplayName": "Status w ERP",
"fieldType": "list",
"predefinedValues": ["oczekuje", "przekazano", "błąd"]
}'

Jeśli integracja korzysta z Beel API i ma w kodzie ID pól dodatkowych z BaseLinkera, załóż definicje z tymi samymi ID. POST /api/v2/AdditionalFieldsDefinitions przyjmuje opcjonalne pole id:

{
"id": 135,
"ownerType": "<OWNER_ORDER>",
"fieldName": "typ_klienta",
"fieldDisplayName": "Typ klienta",
"fieldType": "list",
"predefinedValues": ["B2B", "B2C"]
}
  • Bez id system nadaje ID od 1 000 000 000 wzwyż — ID z BaseLinkera się z nimi nie zderzą.
  • id jest unikalne w całej instancji, dla wszystkich typów obiektów (zamówienie, zwrot…). Jeśli w BaseLinkerze pole zamówienia i pole zwrotu mają ten sam numer, tylko jedno z nich dostanie ID z BL.
  • ID istniejącego pola nie zmienisz przez API — PUT /api/v2/AdditionalFieldsDefinitions nie przyjmuje id.
  • DELETE /api/v2/AdditionalFieldsDefinitions usuwa pole razem ze wszystkimi jego wartościami we wszystkich zamówieniach. Nie usuwaj i nie zakładaj pola od nowa tylko po to, żeby zmienić ID.
editor_type w BaseLinker fieldType w Sellrocket
text text lub long_text
number number
select, radio list (options → predefinedValues)
checkbox bool (pole z kilkoma opcjami do zaznaczenia — text)
date text
file file_link

Kroki dla nowej instancji i dla pól, które już mają wartości, opisuje Beel API → Różnice → ID pól takie jak w BaseLinkerze. Wszystkie identyfikatory, które da się zachować przy migracji (statusy, źródła zamówień, konta kurierskie, pola), zbiera strona Identyfikatory z BaseLinkera.

  1. Jeden obiekt — PUT /api/v2/AdditionalFields

    Okno terminala
    curl -X PUT "https://$SR_INSTANCE-additional-fields-api.enterprise.sellrocket.pl/api/v2/AdditionalFields" \
    -H "Authorization: Bearer $SR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "objectId": 204295,
    "ownerType": "<OWNER_ORDER>",
    "fields": [
    { "fieldName": "erp_status", "fieldType": "list", "fieldValue": "przekazano" },
    { "fieldName": "erp_document", "fieldType": "text", "fieldValue": "WZ/2026/10/0042" }
    ]
    }'

    Odpowiedź zawiera listę zapisanych pól (createdFields) dla obiektu.

  2. Wiele obiektów naraz — PUT /api/v2/AdditionalFields/many przyjmuje tablicę takich samych obiektów. Używaj go przy aktualizacji wielu zamówień lub pozycji.

  3. Pliki — POST /api/v2/AdditionalFields/File przesyła plik i zapisuje do niego link w polu; POST /api/v2/AdditionalFields/File/Link zapisuje link do pliku przechowywanego u Ciebie.

Pola elastyczne zamówienia i pozycji możesz też przekazać przy tworzeniu zamówienia (elasticFields w zamówieniu, additionalFields w pozycji) — zobacz Dodawanie zamówień. Pola pozycji mają ownerType pozycji zamówienia (type właściciela „Line Item”), a objectId to ID pozycji.

Potrzeba Endpoint
Pola jednego obiektu (także puste — z definicjami) GET /api/v2/AdditionalFields?objectId=…&ownerType=…
Pola wielu obiektów POST /api/v3/AdditionalFields/MultipleObjects — { "ids": [...], "ownerType": "<OWNER_ORDER>" }
Zamówienie razem z polami GET /api/v3/Orders/with-elastic-fields/{orderId} (OMS)
Wiele zamówień z polami POST /api/v3/Orders/byIds?withOrderEf=true&withLineItemEf=true (OMS)
[
{
"objectId": 204295,
"ownerType": "<OWNER_ORDER>",
"definitionId": 31,
"fieldName": "erp_document",
"fieldDisplayName": "Dokument w ERP",
"fieldType": "text",
"fieldValue": "WZ/2026/10/0042"
}
]

GET /api/v2/AdditionalFields/history (objectId, ownerType, from) zwraca zmiany wartości z autorem i datą; wersja /history/flatten — w postaci płaskiej listy.

  • Numer dokumentu w ERP — po zaksięgowaniu zamówienia zapisz numer dokumentu; obsługa widzi go w panelu, a Ty możesz wyszukać zamówienie po tym numerze.
  • Flaga dla automatyzacji — integracja ustawia pole (np. erp_status = przekazano), a automatyzacja sprzedawcy uwzględnia je w warunkach i np. zmienia status.
  • Stan synchronizacji — znacznik „wysłano do WMS” zamiast osobnej bazy po Twojej stronie.
  • Nazwa techniczna (fieldName) jest kluczem — nie zmieniaj jej po wdrożeniu; etykietę (fieldDisplayName) możesz zmieniać dowolnie.
  • Usunięcie definicji usuwa wszystkie wartości pola — w każdym obiekcie instancji.
  • Uzgodnij nazwy z instancją — pola są wspólne dla całej instancji. Używaj prefiksu integracji (np. erp_), żeby nie kolidować z polami sprzedawcy.
  • ownerType to type, nie nazwa — pobierz listę właścicieli raz i zapisz identyfikatory w konfiguracji integracji.
  • Dla list przekazuj wyłącznie wartości z predefinedValues.
  • getOrderExtraFields → GET /api/v2/AdditionalFieldsDefinitions z OwnerType = type właściciela „Order”.
  • extra_field_id → ID definicji (id / definitionId); ID z BaseLinkera możesz nadać przy tworzeniu definicji — zobacz Własne ID.
  • custom_extra_fields w setOrderFields → PUT /api/v2/AdditionalFields.
  • custom_extra_fields w getOrders → withOrderEf=true w POST /api/v3/Orders/byIds lub GET /api/v3/Orders/with-elastic-fields/{orderId}.
  • extra_field_1/2 → stałe pola zamówienia additionalField1/2 (nie pola elastyczne).