El ID de un campo —también llamado código o identificador simbólico— es el nombre por el que Bitrix24 reconoce un campo en los robots, los procesos de negocio, la API REST y los webhooks. Los campos del sistema tienen códigos legibles y fijos —TITLE, OPPORTUNITY—; los personalizados reciben un código del tipo UF_CRM_ con un número. En el artículo veremos dónde ver el código de un campo, por qué un mismo campo se escribe de forma distinta en diferentes API y cómo usar los códigos en la automatización.

¿Qué es el ID de un campo y en qué se diferencia del nombre?

Cada campo tiene dos nombres. El nombre —«Importe», «Fuente»— lo ven los usuarios; se puede cambiar en cualquier momento y no afecta al funcionamiento del sistema. El código —OPPORTUNITY, SOURCE_ID— es un identificador de servicio: por él encuentran el campo los robots, los procesos de negocio, las consultas a la API y las plantillas de documentos. El código se fija al crear el campo y ya no cambia. De ahí una regla práctica: en la automatización, apóyate en el código, no en el nombre. Renombrar un campo romperá todo lo que dependa del texto del nombre, y no tocará lo que dependa del código; por eso las integraciones y los procesos montados sobre códigos sobreviven a cualquier retoque cosmético de la ficha.

¿Cómo conocer el ID de un campo en la configuración del CRM?

El camino más corto es la configuración de campos: abre CRM → Configuración, elige la entidad y el campo deseado; el código se muestra en la ficha del campo. Los códigos del sistema son significativos: TITLE, el nombre; OPPORTUNITY, el importe; ASSIGNED_BY_ID, el responsable; COMMENTS, el comentario. Los campos personalizados reciben un código automático del tipo UF_CRM_ más un número largo; no se puede asignarlo manualmente al crear el campo desde la interfaz, así que un código «ilegible» es lo normal. En las tareas los campos personalizados llevan el prefijo UF_; en los procesos inteligentes los códigos se construyen con el mismo principio. Si un campo se creó hace tiempo y nadie recuerda para qué, el código ayuda a encontrar todos los lugares donde se usa, desde los procesos de negocio hasta los webhooks.

¿Cómo obtener la lista completa de campos a través de la API?

Cuando hay decenas de campos, es más cómodo pedir toda la lista de una vez: los métodos REST del tipo crm.deal.fields y crm.contact.fields (o el universal crm.item.fields) devuelven un JSON con todos los campos de la entidad: el código, el tipo y el nombre de cada uno. Basta con un webhook entrante con permisos sobre el CRM: pega la URL del método en el navegador y obtendrás el catálogo completo de campos de tu portal. Este mismo truco resuelve la tarea inversa —encontrar el código por el nombre cuando no tienes a mano la configuración del CRM—. La lista de campos también sirve al insertar valores en las variables de un proceso de negocio: antes de construir el proceso, conviene anotar los códigos de todos los campos que lee y escribe.

¿Por qué TITLE y title son el mismo campo?

En Bitrix24 hay dos generaciones de API REST, y los códigos se escriben de forma distinta en cada una. Los métodos antiguos (crm.deal.update) y el diseñador de procesos de negocio usan mayúsculas: TITLE, OPPORTUNITY, UF_CRM_…. La API universal crm.item.* usa camelCase: title, opportunity, assignedById. Es el mismo campo en dos escrituras, y la confusión entre ellas es una causa frecuente de la situación «el robot funcionó, pero el valor no se guardó». La regla: el formato del código míralo en la documentación del método concreto o en la pista del robot. Por ejemplo, el robot «Actualizar negociación por ID» trabaja a través de la API universal y recibe un JSON en camelCase: {"title":"Nueva negociación","stageId":"C1:WON","opportunity":50000}.

¿Cómo usar los ID de los campos en los robots?

Tres operaciones típicas. Leer un valor por el código: el robot «Obtener valor de un campo de la entidad relacionada»: el tipo de entidad, su ID y el código del campo (TITLE, ASSIGNED_BY_ID o UF_CRM_…); a la salida, el valor y el indicador «encontrado» Y/N. Escribir varios campos a la vez: «Actualizar negociación por ID»: el ID de la negociación y un JSON cuyas claves son esos mismos códigos de campo. Analizar la respuesta de un sistema externo: «Extraer valor de un JSON por ruta»: obtiene el valor por una ruta separada por puntos (por ejemplo, data.user.email) del JSON que devolvió un webhook o un servicio externo, y lo devuelve como cadena más el indicador «ruta encontrada» Y/N. En los tres casos, los códigos de los campos son el idioma común entre el CRM, el proceso y los sistemas externos.

Conclusión

El código de un campo es un identificador de servicio permanente: los códigos del sistema son legibles (TITLE, OPPORTUNITY), los personalizados se generan con el prefijo UF_CRM_. Mira los códigos en la configuración de campos del CRM o mediante los métodos *.fields, y en la automatización apóyate solo en ellos. Los robots para leer y escribir campos por sus códigos están en el catálogo de Roboteka; si falta el que necesitas, describe la tarea y haremos el robot gratis.