Limitaciones del Servicio

Crítico Planificación Requerida

Rate Limiting - Límite Crítico

La limitación más importante del servicio Facturatech es el rate limiting estricto que impone el API.

Impacto en el Procesamiento

Cálculo de Capacidad

Cada nómina requiere mínimo 2 peticiones:

uploadDocument - Enviar XML
documentStatus - Verificar estado (puede requerir múltiples llamadas)

Capacidad Teórica

10 nóminas cada 10 segundos

20 peticiones ÷ 2 operaciones = 10 nóminas

3,600 nóminas/hora (teórico)

Capacidad Real

8 nóminas cada 10 segundos

Considerando:

Reintentos por errores
Polling múltiple de status
Margen de seguridad

~2,400 nóminas/hora (real)

Tiempo para 3000 Empleados

50-75 minutos

3000 nóminas ÷ 10 cada 10s = 300 ciclos

300 × 10 segundos = 3000s ≈ 50 min

Escalamiento Limitado

NO es posible paralelizar

El límite es por cuenta/credencial

No hay forma de aumentar la velocidad

Escenarios de Procesamiento

Empresa Pequeña (100 empleados)

Tiempo estimado: 1-2 minutos
Ciclos necesarios: 10
Complejidad: BAJA

Estrategia:

Procesamiento secuencial simple
Sin necesidad de optimizaciones
Cola básica suficiente

Empresa Mediana (500 empleados)

Tiempo estimado: 8-10 minutos
Ciclos necesarios: 50
Complejidad: MEDIA

Estrategia:

Sistema de cola con monitoreo
Manejo de errores robusto
Notificaciones de progreso

Empresa Grande (1500 empleados)

Tiempo estimado: 25-30 minutos
Ciclos necesarios: 150
Complejidad: ALTA

Estrategia:

Cola distribuida
Procesamiento por lotes
Dashboard en tiempo real
Alertas automáticas

Empresa Muy Grande (3000+ empleados)

Tiempo estimado: 50-75 minutos
Ciclos necesarios: 300+
Complejidad: MUY ALTA

Estrategia:

Sistema de cola avanzado
Procesamiento nocturno
Múltiples ventanas de emisión
Monitoreo 24/7
Plan de contingencia

Otras Limitaciones Importantes

1. Sin Webhooks o Notificaciones Push

Problema: El API no envía notificaciones cuando un documento es autorizado.

Implicación: Se requiere polling activo para consultar el estado.

Solución: Implementar sistema de polling inteligente con backoff progresivo.

// Polling cada 3-5 segundos hasta obtener respuesta
while ($intento < $maxIntentos) {
    $status = $client->documentStatus($transactionID);
    if ($status['codigo'] == 200) break;
    sleep($intervalo);
}

2. Tiempo de Procesamiento Variable

Problema: El tiempo de autorización no es predecible.

Rangos observados:

Sandbox: 5-30 segundos
Producción: xx segundos
Alta demanda: Hasta xx minutos

Solución: Timeout configurable con límite máximo de 10 minutos.

3. Tamaño de XML Limitado

Límite: Aunque no está documentado oficialmente, XMLs muy grandes (>5MB) pueden fallar.

Recomendación: Mantener XMLs bajo 2MB.

Consideración: Una nómina con muchos devengados y deducciones puede crecer significativamente.

4. Sin Procesamiento por Lotes

Problema: No existe endpoint para enviar múltiples nóminas en una sola petición.

Implicación: Cada nómina debe enviarse individualmente.

Solución: Sistema de cola local que simule procesamiento por lotes.

5. Plantilla PDF No Personalizable

Limitación: El PDF usa plantilla genérica de Facturatech.

Personalización disponible: Solo 2 colores principales.

No se puede cambiar:

Layout del documento
Tipografía
Logo (solo Facturatech)
Orden de secciones

Alternativa: Generar PDF propio adicional para uso interno si asi se llega a requerir en el futuro.

Estrategias de Mitigación

1. Sistema de Cola Inteligente

class SmartQueueManager {
    private $maxBatchSize = 10;
    private $batchInterval = 10;
    private $maxRetries = 3;

    public function process() {
        $pendientes = $this->getPendingNominas($this->maxBatchSize);

        foreach ($pendientes as $nomina) {
            try {
                $this->processNomina($nomina);
            } catch (RateLimitException $e) {
                // Esperar y reintentar
                sleep($this->batchInterval);
                $this->retry($nomina);
            }
        }

        sleep($this->batchInterval);
    }
}

2. Procesamiento en Horarios Valle

Procesamiento Nocturno

Ventaja: Menos congestión del servicio

Programar emisión a las 2-4 AM para grandes volúmenes

Ventanas Múltiples

Ventaja: Distribuir la carga

Dividir emisión en 2-3 días para empresas muy grandes

3. Priorización de Nóminas

// Procesar por prioridad
$query = "
    SELECT * FROM nomina_electronica
    WHERE estado = 'PENDIENTE_ENVIO'
    ORDER BY
        CASE
            WHEN prioridad = 'ALTA' THEN 1
            WHEN prioridad = 'MEDIA' THEN 2
            WHEN prioridad = 'BAJA' THEN 3
        END,
        fecha_liquidacion ASC
    LIMIT 10
";

Criterios de prioridad:

ALTA: Nómina complementaria, correcciones urgentes
MEDIA: Nómina regular del mes
BAJA: Re-emisiones, documentos de respaldo

4. Monitoreo y Alertas

// Métricas críticas a monitorear
$metricas = [
    'nominas_pendientes' => countPending(),
    'tasa_exito' => calculateSuccessRate(),
    'tiempo_promedio' => getAverageTime(),
    'errors_last_hour' => countRecentErrors(),
    'rate_limit_hits' => getRateLimitHits()
];

// Alertas
if ($metricas['nominas_pendientes'] > 100) {
    alertar('Cola muy grande');
}

if ($metricas['tasa_exito'] < 0.95) {
    alertar('Tasa de éxito baja');
}

Tabla Comparativa de Tiempos

Empleados	Ciclos	Tiempo Mínimo	Tiempo Esperado	Tiempo Máximo
50	5	50s	1 min	2 min
100	10	1.5 min	2 min	3 min
250	25	4 min	5 min	7 min
500	50	8 min	10 min	15 min
1000	100	16 min	20 min	30 min
1500	150	25 min	30 min	45 min
3000	300	50 min	60 min	90 min
5000	500	83 min	100 min	150 min

Recomendaciones Finales

Planificación

Calcular tiempo necesario con anticipación
Considerar el día de emisión (evitar fines de mes)
Tener plan B para volúmenes grandes

Automatización

Sistema de cola robusto
Reintentos automáticos
Monitoreo continuo
Alertas configuradas

Monitoreo

Dashboard en tiempo real
Métricas de performance
Logs detallados
Reportes diarios

Contingencia

Plan de recuperación
Procedimientos de emergencia
Contactos de soporte
Documentación actualizada

Escalamiento con Facturatech

Si su organización requiere procesar más de 5000 nóminas por día, considere:

Negociar límites especiales con Facturatech
Múltiples credenciales (C3) si es posible
Procesamiento distribuido en varios días
Servicios enterprise con SLA dedicado

Referencias

Implementación - Sistema de cola completo
Pruebas Sandbox - Métricas observadas