Arquitectura
Integraciones de Bitrix24: colas, reintentos y prevención de duplicados
Qué prever en el intercambio de datos cuando una solicitud externa agota el tiempo de espera, se pierde la respuesta o llega varias veces el mismo evento.
Si una solicitud agota el tiempo de espera, todavía no sabemos si la operación externa se ejecutó. El servicio pudo guardar los datos y perder la respuesta. Repetir la creación sin comprobarlo puede generar un duplicado. Para un intercambio fiable, primero hay que definir cómo identificar las operaciones y recuperar un resultado incierto.
Lo que sigue es un enfoque de diseño para integrar sistemas empresariales. No describe una garantía incorporada de Bitrix24: la implementación depende de las API de ambas partes.
Definir primero quién controla los datos
Para cada entidad hay que definir qué sistema guarda la versión válida de los datos y qué campos puede modificar la otra parte. Sin esta regla, dos automatizaciones de un intercambio bidireccional pueden sobrescribir los cambios entre sí.
Conviene mantener la correspondencia entre fuente, ID externo e ID local. Cada operación necesita además una clave estable que se conserve en las entregas repetidas. Generar una clave aleatoria nueva en cada intento no ayuda a reconocer una repetición.
Qué significa idempotencia
El procesamiento idempotente de una operación no produce efectos adicionales indeseados al repetirse. Por ejemplo, un evento repetido de registro de solicitud debe referirse a la tarea ya creada y no crear otra.
Comprobar que un registro no existe antes de crearlo es insuficiente con procesamiento paralelo: dos procesos pueden comprobarlo a la vez. Hace falta protección coordinada en el almacenamiento o un mecanismo de idempotencia de la API receptora.
Si el sistema externo no admite una clave de operación, se diseña otro método de conciliación. Puede requerir buscar por un identificador externo acordado o revisar manualmente un resultado incierto. No se puede prometer una entrega universal «exactamente una vez» entre sistemas arbitrarios.
Para qué sirve la cola
La cola separa la acción del usuario del intento de intercambio y conserva su estado. Debe sobrevivir al reinicio del proceso y permitir saber qué queda pendiente.
Un registro puede incluir identificador de operación, tipo de evento, referencia a la entidad, versión de los datos, estado, número de intentos, próxima ejecución y código del último error. Los datos dependen de los requisitos de recuperación; no se incluyen secretos de acceso ni datos personales innecesarios.
| Estado | Significado |
|---|---|
| Pendiente | Operación aceptada para su procesamiento |
| En ejecución | Un proceso concreto ha tomado el intento |
| Reintento necesario | Error temporal confirmado |
| Completada | Resultado esperado recibido y guardado |
| Revisión necesaria | Reintento automático inseguro o agotado |
Cuando un proceso toma un registro, otro no debe poder ejecutarlo al mismo tiempo. Si el proceso termina de forma inesperada, debe ser posible recuperar el trabajo. Volver a tomar el registro solo es seguro si se evita repetir sus efectos.
Distinguir tipos de error
Ante indisponibilidad temporal se puede programar otro intento con demora creciente y una pequeña variación aleatoria. Así se reduce el riesgo de que todos los procesos vuelvan a saturar el servicio al mismo tiempo.
Un formato de datos incorrecto, la falta de permisos y los conflictos de negocio requieren corregir la causa. Repetir sin cambios no sirve. Tras un tiempo de espera agotado después del envío, puede faltar información para distinguir entre fallo y operación correcta sin respuesta.
Con la REST API de Bitrix24 hay que considerar los errores y límites documentados. Los límites de la nube no se trasladan automáticamente a una instalación autohospedada: importan la configuración del servidor y del módulo. Las cifras deben contrastarse con la documentación vigente y el entorno concreto.
Consistencia y orden de eventos
Si el cambio se guarda en la base de datos pero se pierde el registro de la cola, el intercambio no empezará. Si ambos registros están en la misma base transaccional, se puede guardar el trabajo y el cambio en una única transacción: el patrón outbox. Con almacenamientos diferentes hace falta otra estrategia de recuperación y conciliación.
Otra cuestión son los eventos tardíos. Un cambio antiguo no debe sobrescribir uno reciente solo por llegar después. Se utiliza una versión acordada de la entidad u otro orden compatible con ambas partes.
Comprobaciones mínimas
- Entregar una operación dos veces: no aparece un duplicado indeseado.
- Ejecutar dos procesos: no trabajan sobre el mismo registro simultáneamente.
- Interrumpir la respuesta después del guardado externo: el reintento no crea otro objeto.
- Reiniciar el proceso: se detecta y recupera el trabajo pendiente.
- Entregar un cambio antiguo después del nuevo: se conserva el estado actual.
- Enviar datos incorrectos: el trabajo registra un error comprensible y no se repite indefinidamente.
Para supervisar el intercambio, consulte también la antigüedad del trabajo pendiente más antiguo, el número de errores y los estados de la cola. Relacione cada registro de diagnóstico con su operación. Tener un proceso en marcha no demuestra que el intercambio funcione.