Documento histórico

Este documento se conserva solo para trazabilidad. Consulte el índice maestro para la fuente vigente.

Documento histórico — no usar como fuente de decisiones actuales

Reemplazado por la versión canónica del 2026-07-11. Conservar solo como trazabilidad histórica.

Diagrama de estados — Envío (Shipment)¶

Diagrama UML de máquina de estados para el ciclo de vida de un Shipment desde la cotización hasta la entrega al destinatario en Cuba.

Diagrama¶

stateDiagram-v2
    [*] --> borrador: crear envío manual

    borrador --> pendiente_kyc: KYC no aprobado
    borrador --> pendiente_destinatario: falta destinatario
    borrador --> pendiente_cotizacion: necesita cotización

    pendiente_kyc --> pendiente_cotizacion: KYC aprobado
    pendiente_kyc --> cancelado: usuario cancela

    pendiente_destinatario --> pendiente_cotizacion: destinatario definido
    pendiente_destinatario --> cancelado

    pendiente_cotizacion --> cotizado: calcular
    pendiente_cotizacion --> cancelado

    cotizado --> pendiente_pago: aceptar cotización
    cotizado --> pendiente_cotizacion: recalcular
    cotizado --> cancelado

    pendiente_pago --> pagado: pago confirmado
    pendiente_pago --> cancelado: usuario cancela
    pendiente_pago --> pendiente_cotizacion: cotización expiró

    pagado --> en_preparacion: operador toma
    en_preparacion --> despachado_desde_almacen: operador despacha
    en_preparacion --> cancelado: cancelación tardía

    despachado_desde_almacen --> en_transito_a_cuba: sale de Miami
    en_transito_a_cuba --> en_aduana: llega a Cuba
    en_transito_a_cuba --> incidencia: problema en tránsito

    en_aduana --> liberado_de_aduana: aduana aprueba
    en_aduana --> incidencia: retenido por aduana

    liberado_de_aduana --> en_reparto: sale a reparto
    en_reparto --> entregado: confirmación
    en_reparto --> incidencia: problema en reparto

    incidencia --> en_reparto: incidencia resuelta
    incidencia --> entregado: incidencia resuelta con entrega
    incidencia --> cancelado: cancelación operativa

    entregado --> [*]
    cancelado --> [*]

Estados (16 oficiales)¶

#	Estado	Descripción
1	`borrador`	Envío creado pero no confirmado
2	`pendiente_kyc`	KYC del usuario no aprobado
3	`pendiente_destinatario`	Falta definir el destinatario
4	`pendiente_cotizacion`	Esperando cálculo de costo
5	`cotizado`	Costo calculado, esperando aprobación
6	`pendiente_pago`	Esperando pago
7	`pagado`	Pago confirmado
8	`en_preparacion`	Preparándose para despacho
9	`despachado_desde_almacen`	Ya salió del almacén
10	`en_transito_a_cuba`	En camino hacia Cuba
11	`en_aduana`	En proceso de aduana en Cuba
12	`liberado_de_aduana`	Pasó aduana, liberado
13	`en_reparto`	En última milla de entrega
14	`entregado`	Entregado al destinatario
15	`incidencia`	Hay un problema que requiere atención
16	`cancelado`	Cancelado antes de entrega

Bloqueos obligatorios¶

KYC (búsqueda por precondición)¶

flowchart TD
    A[Crear envío] --> B{¿KYC aprobado?}
    B -- No --> C[Estado: pendiente_kyc]
    B -- Sí --> D[Continúa flujo]
    C --> E[Usuario completa KYC]
    E --> B

Destinatario¶

flowchart TD
    A[Crear envío] --> B{¿Destinatario definido?}
    B -- No --> C[Estado: pendiente_destinatario]
    B -- Sí --> D[Continúa flujo]
    C --> E[Usuario define destinatario]
    E --> B

Cotización vigente¶

flowchart TD
    A[Estado: pendiente_pago] --> B{¿Cotización vigente?}
    B -- Sí --> C[Continúa]
    B -- No --> D[Estado: pendiente_cotizacion]
    D --> E[Recalcular]
    E --> A

Transiciones válidas¶

Desde	Hacia	Quién	Disparador
`borrador`	`pendiente_kyc`	Sistema	Validación pre-despacho
`borrador`	`pendiente_destinatario`	Sistema	Falta destinatario
`borrador`	`pendiente_cotizacion`	Sistema	Datos OK, falta calcular
`pendiente_kyc`	`pendiente_cotizacion`	Sistema	KYC aprobado
`pendiente_kyc`	`cancelado`	Usuario/Sistema	Cancelación
`pendiente_destinatario`	`pendiente_cotizacion`	Usuario	Define destinatario
`pendiente_destinatario`	`cancelado`	Usuario	Cancelación
`pendiente_cotizacion`	`cotizado`	Sistema	Cálculo exitoso
`cotizado`	`pendiente_pago`	Usuario	Acepta cotización
`cotizado`	`pendiente_cotizacion`	Sistema	Recálculo (cambió peso/vía)
`cotizado`	`cancelado`	Usuario	No acepta
`pendiente_pago`	`pagado`	Sistema/Operador	Pago confirmado
`pendiente_pago`	`pendiente_cotizacion`	Sistema	Cotización expiró
`pendiente_pago`	`cancelado`	Usuario	Cancela
`pagado`	`en_preparacion`	Operador	Toma para preparar
`en_preparacion`	`despachado_desde_almacen`	Operador	Despacho físico
`en_preparacion`	`cancelado`	Admin/Operador	Cancelación tardía
`despachado_desde_almacen`	`en_transito_a_cuba`	Operador	Sale hacia Cuba
`en_transito_a_cuba`	`en_aduana`	Operador/Agencia	Llega a aduana
`en_transito_a_cuba`	`incidencia`	Operador/Agencia	Problema
`en_aduana`	`liberado_de_aduana`	Operador	Aduana aprueba
`en_aduana`	`incidencia`	Operador	Retenido por aduana
`liberado_de_aduana`	`en_reparto`	Operador/Agencia	Sale a reparto
`en_reparto`	`entregado`	Operador/Agencia	Confirmación
`en_reparto`	`incidencia`	Operador/Agencia	Problema
`incidencia`	`en_reparto`	Operador	Resuelto, continúa
`incidencia`	`entregado`	Operador	Resuelto con entrega
`incidencia`	`cancelado`	Admin	Cancelación operativa

Estados terminales¶

entregado → estado final exitoso
cancelado → estado final con cancelación

Notificaciones por transición¶

Transición	Push	Email	Aparece en "Requiere tu atención"
→ `pendiente_kyc`	✅	❌	✅ (KYC pendiente)
→ `pendiente_destinatario`	✅	❌	✅
→ `cotizado`	✅	❌	✅ (Pago pendiente)
→ `pendiente_pago`	✅	❌	✅
→ `pagado`	✅	❌	❌
→ `despachado_desde_almacen`	✅	❌	❌
→ `en_transito_a_cuba`	✅	❌	❌
→ `en_aduana`	✅	❌	❌
→ `liberado_de_aduana`	✅	❌	❌
→ `en_reparto`	✅	❌	❌
→ `entregado`	✅	✅	❌
→ `incidencia`	✅	✅	✅
→ `cancelado`	✅	❌	❌

Códigos de error para transiciones inválidas¶

Código	Significado
`INVALID_TRANSITION`	Transición no permitida por la máquina de estados
`KYC_NOT_APPROVED`	Intentar despachar sin KYC
`NO_RECIPIENT`	Intentar despachar sin destinatario
`QUOTE_EXPIRED`	Intentar pagar con cotización vencida
`PAYMENT_NOT_CONFIRMED`	Intentar despachar sin pago
`ALREADY_DELIVERED`	Modificar un envío ya entregado
`SHIPMENT_CANCELLED`	Modificar un envío cancelado
`MISSING_INCIDENT_REASON`	Cambio a `incidencia` sin motivo

Diferencia con el estado de paquete¶

Aspecto	Paquete físico	Envío (shipment)
Unidad	Caja individual	Despacho (1 o muchos paquetes)
Consolidación	1 paquete = 1 (o varios en consolidación)	1 envío = 1 consolidación o 1 paquete individual
Estados	16	16 (distintos)
Bloqueos	KYC no bloquea	KYC sí bloquea (despachar)
Notificaciones	Algunas	Siempre en cada cambio