Manual de Validaciones - BitrixOrderManager
Descripción General
El sistema BitrixOrderManager realiza la sincronización de pedidos entre Bitrix24 y SAP Business One v10 HANA. Este manual documenta todas las validaciones que se ejecutan durante el proceso de sincronización para garantizar la integridad de los datos.
Flujo de Validación
El proceso de validación sigue este orden:
- Validación de Comprobante de Pago
- Validación de Productos
- Validación de Código de Cliente SAP
- Validación de Cliente en SAP
- Validación de Forma de Pago vs Método de Pago (incluye excepción FT)
- Validaciones de Datos del Cliente
Si alguna validación falla, el pedido se mueve al estado de ERROR (STAGE_ID = "2") y se registra el mensaje de error.
⚠️ Caso Especial - Servicio FT (Factura para Trámite de Pago)
El servicio FT - Factura para Trámite de Pago tiene un tratamiento especial en la validación de compatibilidad entre método de pago y forma de pago:
- Compatibilidad con CONTADO y forma pago 99: Los clientes con método de pago CONTADO pueden usar forma de pago 99 cuando seleccionan el servicio FT con entregas C, L o F.
Nota: En el código actual, FT con formas de pago 01-98 SÍ requiere comprobante adjunto (no hay excepción implementada para este caso en la validación de comprobante).
✅ Validaciones Detalladas
1. Validación de Comprobante de Pago
Regla General
Los pedidos con formas de pago específicas (códigos 01-98) requieren un comprobante de pago adjunto.
Excepciones donde NO se requiere comprobante:
| Excepción | Condición | Descripción |
|---|---|---|
| Forma de pago sin definir | Forma de pago = "00" o "99" | No requiere comprobante por defecto |
| Cliente recoge | Forma de pago = 01-98 Y Tipo de entrega = "C" | El cliente recoge en tienda, no requiere comprobante |
| Pago contra entrega | Forma de pago = 01-98 Y Tipo entrega = "L" Y Tipo servicio = "PCE" | Se paga al momento de la entrega local |
⚠️ NOTA IMPORTANTE: Aunque el servicio FT (Factura para trámite) conceptualmente no requeriría comprobante, esta excepción NO está implementada en el código actual para formas de pago 01-98.
Mensaje de Error
"El pedido con forma de pago [código] requiere comprobante de pago adjunto. Por favor, anexe el comprobante antes de procesar el pedido."
2. Validación de Productos
Validaciones Aplicadas:
| Validación | Condición de Error | Mensaje de Error |
|---|---|---|
| Productos vacíos | El pedido no tiene productos | "El pedido debe contener al menos un producto" |
| Precio inválido | Precio ≤ 0 | "El producto [nombre] tiene un precio no válido" |
| Cantidad inválida | Cantidad ≤ 0 | "El producto [nombre] tiene una cantidad no válida" |
3. Validación de Código de Cliente SAP
Validación:
- El campo
UF_SAPCODECOMdebe estar configurado en la empresa de Bitrix
Mensaje de Error:
"El código de cliente no está asignado al cliente"
4. Validación de Cliente en SAP
Validaciones en SAP Business One:
| Validación | Campo SAP | Condición de Error | Mensaje de Error |
|---|---|---|---|
| Cliente activo | Valid | Valid ≠ "tYES" | "El cliente se encuentra inactivo, favor de contactar a crédito y cobranza" |
| Domicilio facturación | BilltoDefault | Campo vacío | "El cliente no tiene domicilio de facturación definido" |
5. Validación Forma de Pago vs Método de Pago
Escenario Principal:
Cuando un cliente tiene método de pago CONTADO y selecciona forma de pago 99 (Por definir).
Excepciones Permitidas:
| Excepción | Método Pago | Forma Pago | Tipo Entrega | Tipo Servicio | Descripción |
|---|---|---|---|---|---|
| PCE | CONTADO | 99 | L (Local) | PCE | Pago contra entrega |
| FT | CONTADO | 99 | C, L o F | FT | Factura para trámite de pago |
Tipos de Entrega válidos para FT:
- C: Cliente Aquí (recoge en tienda)
- L: Local
- F: Foráneo
Mensaje de Error (cuando no cumple excepciones):
"El cliente tiene método de pago CONTADO ([descripción]) y no puede usar forma de pago 99 (Por definir). Debe seleccionar una forma de pago específica o usar las opciones servicio de Pago Contra Entrega (PCE) o Factura para trámite de pago (FT)."
6. Validaciones de Datos del Cliente
Campos Requeridos en la Empresa (Bitrix):
| Campo | Descripción | Mensaje de Error |
|---|---|---|
| UF_CFDI | Uso de CFDI | "El uso de CFDI no está configurado en el cliente" |
| UF_FORMA_PAGO | Forma de pago del cliente | "La forma de pago no está configurada en el cliente" |
| UF_METODO_PAGO | Método de pago del cliente | "El método de pago no está configurado en el cliente" |
| ASSIGNED_BY_ID | Responsable asignado | "No hay responsable asignado al cliente" |
| UF_REGIMENFISCAL | Régimen fiscal | "El régimen fiscal no está configurado en el cliente" |
? Matriz de Decisión - Comprobante de Pago
Reglas de Validación de Comprobante:
| Forma de Pago | Tipo Entrega | Tipo Servicio | ¿Requiere Comprobante? | Razón |
|---|---|---|---|---|
| 00 | Cualquiera | Cualquiera | ❌ No | Forma de pago no definida |
| 99 | Cualquiera | Cualquiera | ❌ No | Por definir |
| 01-98 | C | Cualquiera | ❌ No | Cliente recoge en tienda |
| 01-98 | L | PCE | ❌ No | Pago contra entrega |
| 01-98 | Otros | Otros | ✅ Sí | Requiere comprobante |
Matriz de Compatibilidad - Método CONTADO con Forma de Pago 99:
| Método Pago | Forma Pago | Tipo Entrega | Tipo Servicio | ¿Permitido? | Razón |
|---|---|---|---|---|---|
| CONTADO | 99 | L | PCE | ✅ Sí | Pago contra entrega |
| CONTADO | 99 | C, L o F | FT | ✅ Sí | Factura para trámite de pago |
| CONTADO | 99 | Otros | Otros | ❌ No | Debe usar forma de pago específica |
| Otros | 99 | Cualquiera | Cualquiera | ✅ Sí | Sin restricción |
Códigos y Catálogos
Formas de Pago
- 00: Sin definir (no requiere comprobante)
- 01-98: Formas de pago específicas (requieren comprobante con excepciones)
- 99: Por definir (no requiere comprobante)
Tipos de Entrega
- C: Cliente Aquí (recoge en tienda)
- L: Local
- F: Foráneo
Tipos de Servicio
- PCE: Pago Contra Entrega
- FT: Factura para Trámite de Pago
Estados del Pedido
- PREPARATION: Pedidos pendientes de procesar
- 2: Estado de error
Mensajes de Error y Soluciones
| Error | Causa | Solución |
|---|---|---|
| "El pedido debe contener al menos un producto" | Pedido sin productos | Agregar productos al pedido |
| "El producto tiene un precio no válido" | Precio ≤ 0 | Corregir el precio del producto |
| "El código de cliente no está asignado" | Falta UF_SAPCODECOM | Configurar código SAP en el cliente |
| "El cliente se encuentra inactivo" | Cliente inactivo en SAP | Contactar a crédito y cobranza |
| "No tiene domicilio de facturación" | Falta BilltoDefault en SAP | Configurar domicilio en SAP |
| "Requiere comprobante de pago" | Falta adjuntar comprobante | Anexar comprobante al pedido |
| "CONTADO no puede usar forma pago 99" | Incompatibilidad método/forma | Cambiar forma de pago o usar PCE/FT |
| "El uso de CFDI no está configurado" | Falta UF_CFDI | Configurar CFDI en el cliente |
| "La forma de pago no está configurada" | Falta UF_FORMA_PAGO | Configurar forma de pago |
| "El método de pago no está configurado" | Falta UF_METODO_PAGO | Configurar método de pago |
| "No hay responsable asignado" | Falta ASSIGNED_BY_ID | Asignar responsable al cliente |
| "El régimen fiscal no está configurado" | Falta UF_REGIMENFISCAL | Configurar régimen fiscal |
Notas Importantes
Orden de Validación: Las validaciones se ejecutan en orden secuencial. Si falla una validación temprana (ej. comprobante de pago), las validaciones posteriores no se ejecutan.
Logs de Debugging: El sistema genera logs detallados durante el proceso de validación para facilitar el diagnóstico de problemas.
Integración SAP: La validación del cliente requiere conexión activa con SAP Business One mediante Service Layer.
Campos Personalizados: Los campos UF_* son campos personalizados configurados en Bitrix24.
Manejo de Errores: Todos los errores se registran en el campo UF_SAPSDKERROR del deal en Bitrix.
Configuración Requerida
En Bitrix24:
- Campos personalizados (UF_*) configurados en Deals y Companies
- Estados de pedido configurados (PREPARATION, 2)
- Catálogos de forma de pago, tipo de entrega y tipo de servicio
En SAP Business One:
- Service Layer activo y accesible
- Clientes con información completa (BilltoDefault, PayTermsGrpCode)
- PaymentTermsTypes configurados
En el ETL (Talend):
- Conexión configurada a Bitrix24 API
- Conexión configurada a SAP Service Layer
- Clase BitrixOrderManager implementada
Historial de Cambios
| Fecha | Versión | Descripción |
|---|---|---|
| 2025 | 2.2 | Corrección: FT solo aplica para validación CONTADO+99, no para exención de comprobante |
| 2025 | 2.1 | Documentación completa del escenario FT en validación CONTADO |
| 2025 | 2.0 | Agregada excepción FT para clientes CONTADO con forma pago 99 |
| 2025 | 1.1 | Agregada excepción PCE para pago contra entrega |
| 2025 | 1.0 | Versión inicial con validaciones base |
Este documento debe actualizarse cada vez que se modifiquen las reglas de validación en el sistema.