Bitrix24 es el CRM más común entre nuestros clientes y llevamos años trabajando con él. Pero su API REST tiene carácter: cosas que parecen obvias se comportan de forma no obvia — y sueles descubrirlo en producción. Estas son las cinco rarezas que más horas de debugging nos comieron.
Las cinco rarezas
Cada fila es comportamiento real del API, no un bug de un portal concreto. Recopilado de integraciones en producción de nuestros agentes con Bitrix24.
| Rareza | Síntoma | Solución |
|---|---|---|
| Descarte silencioso de valores inválidos | crm.deal.update devuelve success, pero el campo enum no cambió: los valores fuera de la lista se ignoran en silencio | Escribir IDs de valor, no etiquetas; tras escrituras críticas, relectura de control |
| Webhooks sin garantías | Los eventos ONCRMDEALUPDATE llegan agrupados, con retraso y fuera de orden | El webhook es solo una señal de «algo cambió»: releemos el estado por API, nunca confiamos en el payload |
| Límite de ~2 peticiones/seg | En la demo todo vuela; con tráfico real, QUERY_LIMIT_EXCEEDED | batch de hasta 50 comandos por llamada + cola con reintentos y pausa exponencial |
| Paginación con COUNT oculto | Las listas se ralentizan con cada página en portales grandes: cada petición recuenta el total | start=-1 desactiva el conteo; paginamos con cursor de ID en el filtro, no con start |
| UF_* contra ufCrm* | El mismo campo custom es UF_CRM_… en crm.deal.* y ufCrm… en camelCase en los smart processes (crm.item.*) | Mapeo de campos en un solo módulo; nada de nombres de campo «crudos» en la lógica de negocio |
Por qué importa
Un agente de IA que escribe en el CRM es una integración bajo carga. Cada fallo silencioso cuesta confianza: si un deal no se actualizó y nadie lo vio, el gestor deja de creer en el agente. Y la confianza del equipo es la métrica principal del piloto: un segundo fallo silencioso ya no se perdona.
Cómo lo montamos ahora
Escrituras idempotentes con relectura tras operaciones críticas. Reconciliación de estado cada pocos minutos en vez de fe ciega en los webhooks. batch para todo lo masivo. Mapeo de campos en un único módulo. Y una pasada del eval-set de integración antes de cada deploy — en un portal de pruebas, no en el del cliente.
Qué haríamos distinto
La primera semana de cualquier integración: solo lectura. El agente lee, analiza, propone — pero no escribe. Son siete días más lento y meses de limpieza más barato: la mitad de las rarezas de la tabla las habríamos cazado antes de que tocaran deals reales.
Nuestra checklist para integrar un agente con Bitrix24, bajo petición: andrew@grow2.ai.