ID pola — zwane też kodem lub identyfikatorem symbolicznym — to nazwa, po której Bitrix24 rozpoznaje pole w robotach, procesach biznesowych, REST API i webhookach. Pola systemowe mają stałe, czytelne kody — TITLE, OPPORTUNITY; pola użytkownika otrzymują kod postaci UF_CRM_ z liczbą. W artykule omówimy, gdzie sprawdzić kod pola, dlaczego to samo pole zapisuje się różnie w różnych API i jak używać kodów w automatyzacji.

Czym jest ID pola i czym różni się od nazwy?

Każde pole ma dwie nazwy. Nazwę — „Kwota", „Źródło" — widzą użytkownicy; można ją zmieniać w dowolnym momencie, nie wpływa to na pracę systemu. Kod — OPPORTUNITY, SOURCE_ID — to identyfikator służbowy: po nim pole odnajdują roboty, procesy biznesowe, zapytania API oraz szablony dokumentów. Kod jest ustalany przy tworzeniu pola i dalej się nie zmienia. Stąd praktyczna reguła: w automatyzacji opieraj się na kodzie, a nie na nazwie. Zmiana nazwy pola zepsuje wszystko, co jest powiązane z tekstem nazwy, i nie ruszy tego, co powiązane z kodem — dlatego integracje i procesy zbudowane na kodach przetrwają każde kosmetyczne poprawki karty.

Jak poznać ID pola w ustawieniach CRM?

Najkrótsza droga to ustawienia pól: otwórz CRM → Ustawienia, wybierz obiekt i potrzebne pole — kod wyświetla się w karcie pola. Kody systemowe są sensowne: TITLE — nazwa, OPPORTUNITY — kwota, ASSIGNED_BY_ID — osoba odpowiedzialna, COMMENTS — komentarz. Pola użytkownika otrzymują automatyczny kod postaci UF_CRM_ plus długa liczba — nie da się go nadać ręcznie przy tworzeniu przez interfejs, więc „nieczytelny" kod to normalność. W zadaniach pola użytkownika mają przedrostek UF_, w procesach inteligentnych kody budowane są na tej samej zasadzie. Jeśli pole utworzono dawno i nikt nie pamięta po co, kod pomaga znaleźć wszystkie miejsca, w których jest używane — od procesów biznesowych po webhooki.

Jak otrzymać pełną listę pól przez API?

Gdy pól są dziesiątki, wygodniej zapytać o całą listę naraz: metody REST postaci crm.deal.fields i crm.contact.fields (lub uniwersalna crm.item.fields) zwracają JSON ze wszystkimi polami obiektu — kod, typ i nazwę każdego. Wystarczy webhook przychodzący z uprawnieniami do CRM: wstaw URL metody do przeglądarki i otrzymaj pełny katalog pól swojego portalu. Ten sam chwyt rozwiązuje zadanie odwrotne — po nazwie znaleźć kod, gdy ustawień CRM nie ma pod ręką. Lista pól przyda się również przy podstawianiu wartości do zmiennych procesu biznesowego: zanim zaczniesz budować proces, warto wypisać kody wszystkich pól, które odczytuje i zapisuje.

Dlaczego TITLE i title to jedno pole?

W Bitrix24 są dwie generacje REST API, a kody zapisuje się w nich różnie. Stare metody (crm.deal.update) i kreator procesów biznesowych używają wielkich liter: TITLE, OPPORTUNITY, UF_CRM_…. Uniwersalne API crm.item.* używa camelCase: title, opportunity, assignedById. To jedno i to samo pole w dwóch zapisach, a pomyłka między nimi to częsta przyczyna sytuacji „robot zadziałał, a wartość się nie zapisała". Reguła: format kodu sprawdzaj w dokumentacji konkretnej metody lub w podpowiedzi robota. Na przykład robot „Aktualizuj deal po ID" działa przez uniwersalne API i przyjmuje JSON w camelCase: {"title":"Nowy deal","stageId":"C1:WON","opportunity":50000}.

Jak używać ID pól w robotach?

Trzy typowe operacje. Odczytać wartość po kodzie — robot „Pobierz wartość pola powiązanego obiektu": typ obiektu, jego ID i kod pola (TITLE, ASSIGNED_BY_ID lub UF_CRM_…) — na wyjściu wartość i znacznik „znaleziono" Y/N. Zapisać kilka pól naraz — „Aktualizuj deal po ID": ID deala oraz JSON, w którym klucze to właśnie kody pól. Rozłożyć odpowiedź systemu zewnętrznego — „Wyciągnij wartość z JSON po ścieżce": pobiera wartość po ścieżce przez kropkę (na przykład data.user.email) z JSON, który zwrócił webhook lub serwis zewnętrzny, i zwraca ją jako ciąg plus znacznik „ścieżkę znaleziono" Y/N. We wszystkich trzech przypadkach kody pól to wspólny język między CRM, procesem i systemami zewnętrznymi.

Podsumowanie

Kod pola to stały identyfikator służbowy: kody systemowe są czytelne (TITLE, OPPORTUNITY), kody użytkownika generowane są z przedrostkiem UF_CRM_. Sprawdzaj kody w ustawieniach pól CRM lub przez metody *.fields i w automatyzacji opieraj się wyłącznie na nich. Roboty do odczytu i zapisu pól po kodach znajdziesz w katalogu Roboteki; nie ma potrzebnego — opisz zadanie, zrobimy robota bezpłatnie.