Die Feld-ID — auch Code oder symbolischer Bezeichner genannt — ist der Name, unter dem Bitrix24 ein Feld in Robotern, Geschäftsprozessen, der REST-API und Webhooks erkennt. Systemfelder haben feste, lesbare Codes — TITLE, OPPORTUNITY; Benutzerfelder erhalten einen Code der Form UF_CRM_ mit einer Zahl. In diesem Artikel klären wir, wo man den Feldcode sieht, warum dasselbe Feld in verschiedenen APIs unterschiedlich geschrieben wird und wie man Codes in der Automatisierung verwendet.

Was ist eine Feld-ID und wie unterscheidet sie sich vom Namen?

Jedes Feld hat zwei Namen. Den Namen — „Betrag", „Quelle" — sehen die Benutzer; er lässt sich jederzeit ändern, auf die Arbeit des Systems hat das keinen Einfluss. Der Code — OPPORTUNITY, SOURCE_ID — ist ein technischer Bezeichner: anhand von ihm finden Roboter, Geschäftsprozesse, API-Anfragen und Dokumentvorlagen das Feld. Der Code wird beim Anlegen des Feldes festgelegt und ändert sich danach nicht mehr. Daraus folgt eine praktische Regel: stützen Sie sich in der Automatisierung auf den Code, nicht auf den Namen. Eine Umbenennung des Feldes zerstört alles, was am Namenstext hängt, und lässt alles unberührt, was am Code hängt — deshalb überstehen Integrationen und Prozesse, die auf Codes aufgebaut sind, jede kosmetische Korrektur der Karte.

Wie findet man die Feld-ID in den CRM-Einstellungen?

Der kürzeste Weg sind die Feldeinstellungen: öffnen Sie CRM → Einstellungen, wählen Sie die Entität und das gewünschte Feld — der Code wird in der Feldkarte angezeigt. Systemcodes sind aussagekräftig: TITLE — Name, OPPORTUNITY — Betrag, ASSIGNED_BY_ID — Verantwortlicher, COMMENTS — Kommentar. Benutzerfelder erhalten einen automatischen Code der Form UF_CRM_ plus eine lange Zahl — ihn beim Anlegen über die Oberfläche manuell zu vergeben, ist nicht möglich, deshalb ist ein „unlesbarer" Code normal. In Aufgaben haben Benutzerfelder das Präfix UF_, in Smart-Prozessen werden die Codes nach demselben Prinzip gebildet. Wenn ein Feld vor langer Zeit angelegt wurde und niemand mehr weiß, wozu, hilft der Code, alle Stellen zu finden, an denen es verwendet wird — von Geschäftsprozessen bis zu Webhooks.

Wie erhält man die vollständige Feldliste über die API?

Wenn es Dutzende Felder gibt, ist es bequemer, die ganze Liste auf einmal abzufragen: REST-Methoden wie crm.deal.fields und crm.contact.fields (oder das universelle crm.item.fields) geben ein JSON mit allen Feldern der Entität zurück — Code, Typ und Name jedes einzelnen. Es genügt ein eingehender Webhook mit CRM-Rechten: fügen Sie die URL der Methode in den Browser ein und Sie erhalten ein vollständiges Feldverzeichnis Ihres Portals. Derselbe Kniff löst die umgekehrte Aufgabe — anhand des Namens den Code zu finden, wenn die CRM-Einstellungen nicht zur Hand sind. Die Feldliste ist auch beim Einsetzen von Werten in Prozessvariablen nützlich: bevor man einen Prozess baut, lohnt es sich, die Codes aller Felder herauszuschreiben, die er liest und schreibt.

Warum sind TITLE und title dasselbe Feld?

In Bitrix24 gibt es zwei Generationen der REST-API, und die Codes werden darin unterschiedlich geschrieben. Die alten Methoden (crm.deal.update) und der Workflow-Designer verwenden Großbuchstaben: TITLE, OPPORTUNITY, UF_CRM_…. Die universelle API crm.item.* verwendet camelCase: title, opportunity, assignedById. Es ist dasselbe Feld in zwei Schreibweisen, und die Verwechslung zwischen ihnen ist eine häufige Ursache für die Situation „der Roboter hat gearbeitet, aber der Wert wurde nicht geschrieben". Regel: das Codeformat entnehmen Sie der Dokumentation der konkreten Methode oder dem Hinweis im Roboter. Zum Beispiel arbeitet der Roboter „Deal per ID aktualisieren" über die universelle API und nimmt JSON in camelCase entgegen: {"title":"Neuer Deal","stageId":"C1:WON","opportunity":50000}.

Wie verwendet man Feld-IDs in Robotern?

Drei typische Operationen. Einen Wert anhand des Codes lesen — der Roboter „Feldwert einer verknüpften Entität abrufen": Entitätstyp, ihre ID und der Feldcode (TITLE, ASSIGNED_BY_ID oder UF_CRM_…) — als Ausgabe der Wert und das Kennzeichen „gefunden" J/N. Mehrere Felder auf einmal schreiben — „Deal per ID aktualisieren": die Deal-ID und ein JSON, dessen Schlüssel eben jene Feldcodes sind. Die Antwort einer externen Entität zerlegen — „Wert aus JSON per Pfad extrahieren": er holt einen Wert über einen punktgetrennten Pfad (zum Beispiel data.user.email) aus dem JSON, das ein Webhook oder ein externer Dienst zurückgegeben hat, und gibt ihn als Zeichenkette plus das Kennzeichen „Pfad gefunden" J/N zurück. In allen drei Fällen sind die Feldcodes die gemeinsame Sprache zwischen CRM, Prozess und externen Systemen.

Fazit

Der Feldcode ist ein dauerhafter technischer Bezeichner: Systemcodes sind lesbar (TITLE, OPPORTUNITY), Benutzercodes werden mit dem Präfix UF_CRM_ generiert. Sehen Sie sich die Codes in den CRM-Feldeinstellungen oder über die Methoden *.fields an und stützen Sie sich in der Automatisierung ausschließlich auf sie. Roboter zum Lesen und Schreiben von Feldern anhand von Codes finden Sie im Roboteka-Katalog; fehlt der benötigte — beschreiben Sie die Aufgabe, wir bauen den Roboter kostenlos.