«Actualizar un campo del negocio» suena a tarea de una línea — hasta que el campo se niega en silencio a cambiar: la petición devuelve éxito y la ficha muestra el valor antiguo. La causa es casi siempre una de tres: la generación equivocada del método, el formato equivocado del nombre del campo o la forma equivocada del valor. Así funciona de verdad la actualización de campos del negocio en Bitrix24 (Alaio): desde la llamada REST en crudo hasta la regla de automatización sin código.

¿Qué método actualiza un campo del negocio?

La respuesta actual es el método universal crm.item.update: pase entityTypeId 2 (negocio), el id del negocio y un objeto fields que contenga solo los campos a cambiar — todo lo omitido queda intacto.

{"entityTypeId": 2, "id": 351, "fields": {"stageId": "C1:WON", "opportunity": 50000}}

El método antiguo por entidad crm.deal.update sigue funcionando y aparece en la mayoría de tutoriales, pero pertenece a la generación legacy: mismos campos, distinta nomenclatura. Las integraciones nuevas deberían usar por defecto crm.item.update — cubre negocios, prospectos, contactos, compañías y procesos inteligentes con un solo contrato.

¿Por qué el campo no se actualiza?

El primer sospechoso es la caja de las letras. La API legacy y el diseñador de procesos escriben los códigos de campo en mayúsculas: TITLE, OPPORTUNITY, UF_CRM_1721244707107. La API universal escribe los mismos campos en camelCase: title, opportunity, ufCrm_1721244707107. Envíe TITLE a crm.item.update y será ignorado como clave desconocida — con mensaje de éxito. Si quiere que el método universal acepte los nombres originales UF_CRM_*, pase useOriginalUfNames con valor Y. El segundo sospechoso es la forma del valor: un campo de lista espera el id del elemento y no su etiqueta, un campo de fecha espera un formato de fecha correcto, y un valor inválido devuelve CRM_FIELD_ERROR_VALUE_NOT_VALID nombrando el campo. Dónde consultar los códigos de campo lo muestra el artículo sobre los ID de campos en Bitrix24.

¿Cómo actualizo teléfono, correo y otros multicampos?

Los teléfonos y correos viven en el array de multicampos fm, y con su semántica de actualización todo el mundo tropieza al menos una vez: las filas existentes se direccionan por su id — una fila con id cambia la entrada en su sitio —, mientras que las filas sin id conocido se añaden como entradas nuevas. Enviar un juego «fresco» de valores sin ids no reemplaza los antiguos: los anexa, y el contacto del negocio acumula en silencio teléfonos duplicados. Lea primero las filas fm actuales y luego actualice por id.

¿Cómo actualizo un campo desde un webhook?

Para una integración de un solo portal no hace falta una aplicación OAuth: un webhook entrante entrega una URL que lleva la autorización en sí misma. Créelo con el scope crm y recuerde que el webhook actúa con los permisos del empleado que lo creó — si esa persona no ve el embudo, la llamada falla con un error de acceso aunque el token sea válido. Método, id y fields van en la petición exactamente como arriba. La configuración paso a paso está en la guía de webhooks; si en vez de un resultado vuelve un código de error, este nombra directamente el campo o el problema de permisos — registre el código, no solo la descripción.

¿Cómo actualizar campos del negocio sin código?

Dentro del portal, la mayoría de las actualizaciones de campos no necesitan REST en absoluto: una regla de automatización en la etapa lo resuelve. La regla estándar «Editar elemento» cubre un campo con un valor estático. Cuando cambian varios campos a la vez, o los valores vienen de pasos anteriores, la regla Actualizar negocio por ID del catálogo de Roboteka toma un objeto JSON en el mismo formato camelCase que crm.item.update y lo escribe todo en una sola acción. Vaciar un campo es un caso aparte — una cadena vacía no limpia listas, fechas ni multicampos, para eso existe la regla Vaciar campo, que anula correctamente cualquier tipo. Para mover un valor entre entidades — por ejemplo, copiar la ciudad del contacto al negocio — sirve Escribir campo de la entidad vinculada, y contra campos críticos vacíos antes de un cambio de etapa, Comprobar campo no vacío devuelve Y/N para ramificar con una condición. Una acción dentro del proceso es además la respuesta barata a «¿monto un escenario externo para esto?»: sin tokens que renovar, sin límites de peticiones que presupuestar — la actualización corre donde vive el negocio.

Qué sigue

Empiece por el fallo que realmente tiene: caja equivocada — pase a camelCase o active useOriginalUfNames; teléfonos duplicados — actualice las filas fm por id; errores de acceso — revise los permisos del creador del webhook. Todo lo que deba reaccionar a eventos del negocio en lugar de a llamadas externas, constrúyalo como reglas de automatización en Bitrix24 — las reglas de actualización de arriba son piezas corrientes allí. Y si falta la pieza que necesita, describa la tarea: Roboteka construye gratis las reglas de automatización que faltan y las publica en la biblioteca común.