Mantener este documento como fuente única de estados

Cualquier otro archivo (incluido datos/equivalencias-estados.md) debe referenciar estos nombres. Los enums en código no deben aparecer en UI; el mapeo de traducción vive en equivalencias-estados.md.

Estados oficiales del sistema¶

Documento central

Este documento define los estados oficiales de cada entidad del sistema. Todos los demás documentos deben referirse a estos estados. Ningún desarrollo debe inventar estados fuera de esta lista.

Estados de prealerta (compra reportada por el usuario)¶

El usuario reporta una compra antes de que el paquete llegue al almacén.

Estado	Descripción
`borrador`	El usuario empezó a reportar pero no lo completó
`reportada`	Reporte creado, completo, esperando llegada del paquete
`reportada_sin_tracking`	Reporte creado pero sin número de tracking (caso normal en Amazon/SHEIN/Temu al principio)
`tracking_actualizado`	El usuario agregó el tracking después de creado el reporte
`vinculada_a_paquete`	El paquete físico llegó y fue asociado a este reporte
`cancelada_por_usuario`	El usuario canceló el reporte
`cancelada_por_operador`	Un operador canceló el reporte (por error, duplicado, etc.)
`requiere_correccion`	Falta información o es incorrecta; el usuario debe corregir

Regla importante

Una prealerta puede existir sin tracking. El sistema debe permitir crear el reporte aunque el usuario todavía no tenga el tracking. El campo tracking es opcional en este estado.

Estados del paquete físico¶

El paquete que llega físicamente al almacén.

Estado	Descripción
`prealertado`	Hay una prealerta asociada y el paquete está en camino
`en_camino_al_almacen`	El transportista está transportando hacia el almacén
`recibido_sin_identificar`	Llegó al almacén, no se pudo identificar aún
`recibido_identificado`	Llegó y se asoció a un usuario
`pendiente_conciliacion`	Llegó pero no coincide con ninguna prealerta; requiere revisión manual
`en_almacen`	Almacenado, esperando instrucciones del usuario
`esperando_instrucciones`	El usuario aún no decidió qué hacer (enviar, consolidar, devolver)
`en_servicio_adicional`	Tiene un servicio activo (inspección, prueba, reempaque) en proceso
`listo_para_consolidar`	Puede ser incluido en una consolidación
`reservado_para_consolidacion`	Ya fue seleccionado para una consolidación, esperando que se complete
`consolidado`	Ya agrupado dentro de una consolidación
`en_transito`	Enviado hacia Cuba
`entregado`	Entregado al destinatario final
`retenido_por_incidencia`	Retenido por algún problema que requiere resolución
`devuelto_a_tienda`	En proceso de devolución al vendedor
`descartado_o_cerrado`	Cerrado por cierre de caso, abandono o decisión operativa

Estados de la consolidación¶

Agrupación de varios paquetes para un mismo envío.

Estado	Descripción
`borrador`	Se empezó a armar la consolidación pero no se confirmó
`completa`	Todos los paquetes reservados y listos para cotizar
`cotizada`	Se calculó el costo de la consolidación
`pendiente_pago`	Esperando que el usuario pague la consolidación
`pagada`	Pago confirmado
`en_preparacion`	Siendo preparada para despacho
`despachada`	Ya enviada hacia Cuba
`cancelada`	Cancelada antes de despacho

Estados del envío (despacho hacia Cuba)¶

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

Estados del pago¶

Estado	Descripción
`pendiente`	Pago iniciado pero no confirmado
`pago_reportado`	Comprobante manual informado; pendiente de validación del operador
`completado`	Pago exitoso
`fallido`	Pago rechazado o falló
`reembolsado`	Dinero devuelto al usuario
`parcial`	Pago parcial (crédito + dinero real) — se desglosa en el pago

Sobre el estado parcial

parcial no es un estado standalone del pago, sino una composición del pago. El pago puede combinar dinero real + crédito + tarjeta. El campo payment_method_mix registra qué se usó. El estado del pago como tal es completado cuando se confirma.

Estados del KYC (verificación de identidad)¶

Estado	Descripción
`sin_iniciar`	El usuario no empezó el proceso de verificación
`borrador`	Empezó a cargar datos pero no lo completó
`enviado`	Documentos cargados, enviado a revisión
`en_revision`	Equipo revisando los documentos
`aprobado`	Verificación aprobada
`rechazado`	Documentos rechazados; puede reenviar
`requiere_mas_informacion`	Se necesita más información o corrección
`vencido`	La verificación expiró (por tiempo o por decisión)
`bloqueado_manual`	Bloqueado manualmente por un operador

Reglas de KYC por estado¶

Estado KYC	¿Puede prealertar?	¿Puede despachar?	¿Puede consolidar?	¿Puede pagar?
`sin_iniciar`	✅ Sí	❌ No	❌ No	❌ No
`borrador`	✅ Sí	❌ No	❌ No	❌ No
`enviado`	✅ Sí	❌ No	❌ No	❌ No
`en_revision`	✅ Sí	❌ No	❌ No	❌ No
`aprobado`	✅ Sí	✅ Sí	✅ Sí	✅ Sí
`rechazado`	✅ Sí	❌ No	❌ No	❌ No
`requiere_mas_informacion`	✅ Sí	❌ No	❌ No	❌ No
`vencido`	✅ Sí	❌ No	❌ No	❌ No
`bloqueado_manual`	❌ No	❌ No	❌ No	❌ No

Principio

El KYC bloquea el despacho, no la prealerta. El usuario puede reportar compras aunque no tenga KYC aprobado. Esto evita paquetes sin prealerta que llegan al almacén.

Estados de servicios adicionales¶

Cada servicio adicional sigue su propio ciclo.

Inspección visual / Prueba funcional¶

Estado	Descripción
`no_solicitado`	No se pidió este servicio
`solicitado`	Usuario lo solicitó
`pendiente_cotizacion`	Esperando definir el costo
`cotizado`	Costo definido, esperando aprobación
`pendiente_pago`	Esperando pago
`en_proceso`	Operador realizando la revisión
`completado`	Servicio completado
`completado_con_evidencia`	Servicio completado con fotos/videos como evidencia
`rechazado`	No se pudo realizar
`cancelado`	Usuario canceló el servicio

Reempaque¶

Estado	Descripción
`no_solicitado`	No se pidió
`solicitado`	Usuario lo pidió
`cotizado`	Costo definido
`pendiente_pago`	Esperando pago
`en_proceso`	Operador reembalando
`completado`	Reempaque terminado

Devolución¶

Estado	Descripción
`no_solicitado`	No se pidió
`solicitado`	Usuario solicitó devolución
`pendiente_cotizacion`	Costos de devolución por definir
`cotizado`	Costo definido
`pendiente_pago`	Usuario debe pagar costos de envío de retorno
`en_proceso`	Devolución en camino al vendedor
`completado`	Devolución completada, dinero reembolsado si aplica
`rechazado`	El vendedor rechazó la devolución
`cancelado`	Cancelada

Estados de devolución (producto/devolución a tienda)¶

Estado	Descripción
`no_solicitado`	No se gestiona devolución
`solicitada`	Usuario solicitó devolución
`pendiente_revision`	Operador revisando si aplica
`aprobada`	Se aprueba la devolución
`rechazada`	No aplica o no se acepta
`en_transito_retorno`	Paquete regresando al vendedor
`recibido_por_vendedor`	El vendedor recibió el paquete
`reembolso_iniciado`	Dinero en proceso de devolución
`reembolso_completado`	Reembolso realizado
`cerrada`	Caso cerrado

Estados de aduana¶

Estado	Descripción
`pendiente`	Aún no presentada a aduana
`en_revision`	Aduana revisando el envío
`retenida`	Retenida por alguna razón
`documentacion_requerida`	Se requiere documentación adicional
`pendiente_pago_aduana`	Pendiente de pago de aranceles
`aduana_pagada`	Aranceles pagados
`decomisada`	Mercancía decomisada por aduana
`no_autorizada`	Envío no autorizado
`libre`	Liberada, sin cargos extra
`con_cargos`	Liberada con pago de aranceles/impuestos
`reclasificada`	Aduana cambió la categoría del producto
`incidencia`	Problema que requiere gestión adicional

Estados de almacenaje¶

Estado	Descripción
`dentro_del_periodo_gratuito`	Dentro de los días incluidos sin costo
`por_vencer`	Próximo a vencer (alerta activa)
`vencido`	Ya superó el período gratuito, aplicando cargos
`maximo_alcanzado`	Alcanzó el máximo de días permitidos antes de acciones drásticas

Estados de incidencias¶

Estado	Descripción
`abierta`	Incidencia creada, requiere atención
`en_revision`	Operador revisando la incidencia
`requiere_accion_usuario`	El usuario debe hacer algo
`resuelta`	Solucionada
`cerrada`	Caso cerrado sin resolución
`escalada`	Escalada a supervisor

Tipos de incidencia¶

Tipo	Descripción
`paquete_sin_identificar`	Paquete llegó sin identificador legible
`tracking_no_coincide`	El tracking del paquete no coincide con el reporte
`falta_factura`	No se encontró factura ni comprobante
`producto_restringido`	Producto no permitido o restringido
`peso_valor_inconsistente`	El peso o valor declarado no coincide con lo recibido
`dano_visible`	Embalaje o producto dañado
`direccion_mal_escrita`	La dirección tiene errores
`kyc_rechazado`	KYC fue rechazado
`pago_fallido`	El pago no se pudo procesar
`aduana_requiere_revision`	Aduana solicita información adicional
`usuario_sin_acceso`	Usuario bloqueado o suspendido

Estados del identificador del casillero¶

Estado	Descripción	¿Recibe paquetes?	¿Puede despachar?
`activo`	En uso normal	✅ Sí	✅ Sí
`suspendido`	Temporalmente pausado	✅ Sí	❌ No
`desactivado`	Inactivo	❌ No	❌ No
`bloqueado`	Bloqueado por alguna razón	✅ Paquetes retenidos	❌ No
`cerrado`	Cuenta cerrada	❌ No	❌ No

Transiciones válidas y reglas¶

Prealerta → Paquete¶

reportada / reportada_sin_tracking / tracking_actualizado
    → vinculada_a_paquete (cuando el paquete físico se identifica)
    → cancelada_por_usuario (usuario cancela)
    → cancelada_por_operador (operador cancela)
    → requiere_correccion (faltan datos)

Paquete físico¶

prealertado
    → en_camino_al_almacen
    → recibido_sin_identificar (no se encontró usuario)
    → recibido_identificado (se encontró usuario por identificador o tracking)

recibido_sin_identificar / recibido_identificado
    → pendiente_conciliacion (si no coincide con prealerta)
    → en_almacen (si se identificó correctamente)

en_almacen
    → esperando_instrucciones
    → en_servicio_adicional
    → listo_para_consolidar
    → en_transito
    → retenido_por_incidencia

esperando_instrucciones
    → listo_para_consolidar
    → en_servicio_adicional
    → en_transito
    → retenido_por_incidencia

en_servicio_adicional
    → listo_para_consolidar
    → retenido_por_incidencia

listo_para_consolidar
    → reservado_para_consolidacion

reservado_para_consolidacion
    → consolidado

consolidado
    → en_transito
    → retenido_por_incidencia

en_transito
    → entregado
    → retenido_por_incidencia

Matriz de acciones por estado (vista del cliente)¶

Paquete desde la perspectiva del usuario¶

Estado del paquete	Visible al cliente?	Qué ve el cliente	Qué puede hacer
`prealertado`	No (interno)	—	—
`en_camino_al_almacen`	No (interno)	—	—
`recibido_sin_identificar`	No (interno)	—	—
`recibido_identificado`	Sí	"Paquete recibido en almacén"	Ver fotos, solicitar acción
`pendiente_conciliacion`	Sí	"Tu paquete llegó pero no lo reconocemos"	Completar datos para identificarlo
`en_almacen`	Sí	"Paquete en almacén"	Enviar, consolidar, pedir inspección, devolver
`esperando_instrucciones`	Sí	"Sin instrucciones aún"	Enviar, consolidar, pedir servicio
`en_servicio_adicional`	Sí	"Servicio en proceso"	Ver estado del servicio
`listo_para_consolidar`	Sí	"Listo para agrupar"	Agregar a una consolidación
`reservado_para_consolidacion`	Sí	"Incluido en consolidación"	Ver consolidación
`consolidado`	Sí	"Incluido en envío"	Ver consolidación
`en_transito`	Sí	"En camino a Cuba"	Seguir tracking
`entregado`	Sí	"Entregado"	Ver confirmación
`retenido_por_incidencia`	Sí	"Hay un problema con tu paquete"	Ver motivo, resolver
`devuelto_a_tienda`	Sí	"En devolución"	Ver estado de la devolución

Estados internos

prealertado, en_camino_al_almacen y recibido_sin_identificar son estados operativos internos. El cliente no los ve porque el paquete aún no ha llegado o no está identificado.

Reglas generales de estados¶

Ningún paquete avanza sin usuario asociado. Si no se identifica, va a pendiente_conciliacion.
Todo paquete recibido debe tener prealerta asociada o crear una. Si no hay prealerta, se crea automáticamente y se notifica al usuario.
Los estados son mutuamente excluyentes. Un paquete no puede estar en dos estados al mismo tiempo.
Las transiciones deben quedar registradas. Cada cambio de estado genera un evento en package_events.
Los estados visibles al usuario pueden diferir de los internos. El cliente ve estados simplificados; el operador ve los estados completos.
El KYC no bloquea la prealerta, pero sí bloquea el despacho, la consolidación para envío y el pago.