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).
Jak to działa
Dział zatytułowany „Jak to działa”- Typ właściciela (
ownerType) — rodzaj obiektu, do którego należy pole: zamówienie, pozycja zamówienia, zwrot, pozycja zwrotu i inne. Listę zwracaGET /api/v2/AdditionalFieldsOwners: każdy właściciel ma czytelną nazwę (name, np. „Order”, „Line Item”) i identyfikator (type) w postaci szablonu adresu. W poluownerTypeprzekazujtype, dokładnie tak, jak zwraca go API (razem z nawiasami klamrowymi) — sama nazwa „Order” nie zadziała. W przykładach poniżej<OWNER_ORDER>oznaczatypewłaściciela „Order”. - Definicja — opis pola dla danego typu właściciela:
fieldName(nazwa techniczna),fieldDisplayName(etykieta w panelu),fieldType, opcjonalniepredefinedValues(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ł.
Identyfikatory
Dział zatytułowany „Identyfikatory”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) |
Definiowanie pola
Dział zatytułowany „Definiowanie pola”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).
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"] }'Własne ID — migracja z BaseLinkera
Dział zatytułowany „Własne ID — migracja z BaseLinkera”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
idsystem nadaje ID od 1 000 000 000 wzwyż — ID z BaseLinkera się z nimi nie zderzą. idjest 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/AdditionalFieldsDefinitionsnie przyjmujeid. DELETE /api/v2/AdditionalFieldsDefinitionsusuwa 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.
Zapis wartości
Dział zatytułowany „Zapis wartości”-
Jeden obiekt —
PUT /api/v2/AdditionalFieldsOkno 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. -
Wiele obiektów naraz —
PUT /api/v2/AdditionalFields/manyprzyjmuje tablicę takich samych obiektów. Używaj go przy aktualizacji wielu zamówień lub pozycji. -
Pliki —
POST /api/v2/AdditionalFields/Fileprzesyła plik i zapisuje do niego link w polu;POST /api/v2/AdditionalFields/File/Linkzapisuje 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.
Odczyt wartości
Dział zatytułowany „Odczyt wartości”| 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" }]Wyszukiwanie po wartości
Dział zatytułowany „Wyszukiwanie po wartości”GET /api/v6/Orders/findByAdditionalField(OMS) — ID zamówień, w których poleAdditionalFieldNamema wartośćAdditionalFieldValue. Przydaje się, gdy w polu trzymasz własny identyfikator.GET /api/v3/AdditionalFields/Search— ID obiektów dowolnego typu z daną wartością pola.- Lista zamówień
GET /api/v5/Ordersma filtrElasticFieldValue.
Historia zmian
Dział zatytułowany „Historia zmian”GET /api/v2/AdditionalFields/history (objectId, ownerType, from) zwraca zmiany wartości z autorem i datą; wersja /history/flatten — w postaci płaskiej listy.
Typowe zastosowania
Dział zatytułowany „Typowe zastosowania”- 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.
Na co uważać
Dział zatytułowany „Na co uważać”- 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. ownerTypetotype, nie nazwa — pobierz listę właścicieli raz i zapisz identyfikatory w konfiguracji integracji.- Dla
listprzekazuj wyłącznie wartości zpredefinedValues.
Odpowiedniki w BaseLinker
Dział zatytułowany „Odpowiedniki w BaseLinker”getOrderExtraFields→GET /api/v2/AdditionalFieldsDefinitionszOwnerType=typewł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_fieldswsetOrderFields→PUT /api/v2/AdditionalFields.custom_extra_fieldswgetOrders→withOrderEf=truewPOST /api/v3/Orders/byIdslubGET /api/v3/Orders/with-elastic-fields/{orderId}.extra_field_1/2→ stałe pola zamówieniaadditionalField1/2(nie pola elastyczne).
Zobacz też
Dział zatytułowany „Zobacz też”- Pola dodatkowe produktów — pola złożone w PIM
- Pobieranie zamówień
- Dodawanie zamówień
- Referencja: Pola elastyczne

