Guía del Proceso de Entrega en Warehouse¶

Resumen¶

Este documento describe el flujo completo del proceso de entrega de paquetes en el warehouse destino. Explica cómo los paquetes se verifican, escanean y entregan a los destinatarios finales.

1. Overview¶

El Warehouse Destination Workflow es el proceso que comienza cuando una maleta llega al warehouse de destino y termina cuando todos los paquetes son entregados a sus destinatarios.

Beneficios para Clientes¶

Beneficio	Descripción
Trazabilidad en tiempo real	Cada escaneo actualiza el estado del paquete inmediatamente
Verificación segura	Mínimo 2 fotos por paquete + firma del destinatario
Notificaciones automáticas	El destinatario sabe cuándo su paquete está listo para recojo
Manejo de incidencias	Si falta un paquete, se registra y notifica inmediatamente
Consolidación inteligente	Los paquetes se agrupan por envío para entrega eficiente

Flujo Simplificado¶

sequenceDiagram
    participant C as Courier
    participant B as Bag/Maleta
    participant W as Warehouse Destino
    participant P as Package/Paquete
    participant S as Sistema
    participant R as Destinatario

    C->>B: Llega al warehouse destino
    B->>S: Escanea QR de maleta
    S->>W: Registra llegada

    W->>P: Escanea primer paquete
    P->>S: Registra escaneo courier

    W->>P: Escanea paquete (operador)
    P->>S: Registra escaneo operador
    Note over S: Si operator ≠ courier<br/>ambos deben escanear

    W->>P: Sube 2+ fotos por paquete
    P->>S: Verifica y cambia a FOR_PICKUP

    S->>B: Verifica todos paquetes
    alt todos FOR_PICKUP
        S->>B: Marca DELIVERED
        S->>R: Notificación "listo para recojo"
        S->>S: Notifica al remitente
    else algún paquete falta
        S->>B: Marca INCIDENCE
        S->>W: Registra paquetes faltantes
    end

2. Actores y Roles¶

2.1 Courier (Transportista)¶

El courier es la persona que transporta la maleta desde el origen hasta el destino.

Responsabilidad	Descripción
Transportar la maleta	Lleva la maleta en el vuelo
Escaneo inicial	Escanea el QR de la maleta al llegar al warehouse destino
Escaneo de paquetes	Escanea cada paquete que pertenece a la maleta
Entrega física	Entrega los paquetes al destinatario (opcional según configuración)

2.2 Operador de Warehouse¶

El operador trabaja en el warehouse de destino y es responsable del proceso de verificación.

Responsabilidad	Descripción
Recibir maletas	Confirma la llegada de maletas al warehouse
Escanear paquetes	Escanea los paquetes para confirmar su presencia
Verificar fotos	Confirma que las fotos de verificación son adecuadas
Gestionar incidencias	Registra cuando algún paquete falta o tiene problemas
Consolidar envíos	Confirma cuando un envío está completo y listo

2.3 Sistema (Automático)¶

El sistema gestiona las transiciones automáticas y la lógica de negocio.

Responsabilidad	Descripción
Validar estados	Verifica que las transiciones de estado sean válidas
Marcar OPEN	Cambia el estado de la maleta a OPEN cuando se cumplen las condiciones
Marcar END	Confirma el fin del proceso de escaneo
Marcar DELIVERED/INCIDENCE	Determina el estado final según verificación
Enviar notificaciones	Notifica a destinatarios y remitentes
Registrar historial	Guarda todos los cambios de estado con timestamp

3. Flujo Completo de Entrega¶

sequenceDiagram
    participant O as Origen
    participant C as Courier
    participant F as Flight/Vuelo
    participant W as Warehouse Destino
    participant P as Paquetes
    participant S as Sistema
    participant R as Destinatario
    participant REM as Remitente

    Note over O,REM: FASE 1: Preparación en Origen
    O->>P: Crear paquetes
    P->>S: Status = CREATED
    C->>P: Asignar a maleta
    P->>S: Status = ASSIGNED_TO_BAG
    C->>W: Entregar maleta

    Note over C,REM: FASE 2: Transporte
    C->>F: Registrar maleta en vuelo
    F->>S: Vuelo despega
    S->>P: Status = IN_TRANSIT
    F->>S: Vuelo aterriza
    S->>P: Status = ARRIVED

    Note over C,REM: FASE 3: Recepción en Destino
    C->>W: Llega al warehouse destino
    W->>S: Escanea QR maleta
    alt operator ≠ courier
        C->>W: Escanea primer paquete
        W->>S: Registra escaneo courier
        W->>C: Confirma escaneo
        C->>W: Escanea maleta
        W->>S: Registra escaneo operador
    else operator = courier
        C->>W: Escanea QR maleta o primer paquete
        W->>S: Registra escaneo
    end
    S->>W: Maleta = OPEN

    Note over C,REM: FASE 4: Verificación
    loop Para cada paquete
        W->>P: Escanea paquete
        P->>S: Registra escaneo
        W->>P: Sube 2+ fotos
        P->>S: Verifica fotos
        S->>P: Status = FOR_PICKUP
    end

    Note over C,REM: FASE 5: Consolidación
    S->>W: Verifica todos paquetes
    alt todos FOR_PICKUP
        S->>W: Maleta = DELIVERED
        S->>R: Notificación "listo para recojo"
        S->>REM: Notificación "envío entregado"
        R->>W: Firma por entrega
        W->>S: Confirma entrega
        S->>P: Status = DELIVERED
    else algún paquete falta
        S->>W: Maleta = INCIDENCE
        S->>W: Registra missing_package_ids
    end

4. Guía Paso a Paso¶

4.1 Courier Llega al Warehouse Destino¶

¿Qué sucede? El courier transporta la maleta al warehouse de destino después del vuelo.

Pasos: 1. El courier llega al warehouse con la maleta 2. El sistema registra la llegada de la maleta 3. La maleta cambia su estado a IN_WAREHOUSE

Concepto clave: La maleta no puede ser procesada hasta que llegue físicamente al warehouse destino.

4.2 Abrir la Maleta (OPEN)¶

¿Qué sucede? La maleta cambia de IN_WAREHOUSE a OPEN para iniciar el proceso de escaneo.

Condiciones para marcar OPEN:

Escenario	Condición
Operator ≠ Courier	Operator escaneó ≥1 package Y (Courier escaneó QR de maleta O Courier escaneó ≥1 package)
Operator = Courier	Courier escaneó QR de maleta O Courier escaneó ≥1 package

Pasos: 1. El sistema detecta un escaneo 2. Verifica si se cumplen las condiciones de OPEN 3. Si es así, la maleta cambia a OPEN 4. El warehouse recibe notificación de que la maleta está lista para procesar

Nota importante: El estado OPEN indica que el proceso de verificación ha comenzado. Ambos actores (courier y operador) deben participar en el escaneo cuando son personas distintas.

4.3 Escaneo de Paquetes¶

¿Qué sucede? Cada paquete dentro de la maleta debe ser escaneado y verificado con fotos.

Pasos: 1. El operador escanea cada paquete 2. Si operator ≠ courier, el courier también debe escanear 3. Se sube un mínimo de 2 fotos por paquete 4. El sistema verifica que las fotos cumplan los criterios 5. El paquete cambia a FOR_PICKUP cuando está verificado

Validación de fotos: - Mínimo 2 fotos por paquete - Las fotos deben mostrar el contenido del paquete - Deben ser claras y legibles

4.4 Finalizar Verificación de Maleta (END)¶

¿Qué sucede? El operador confirma que todos los paquetes han sido escaneados o decide finalizar de otra forma.

Pasos: 1. El operador llama al endpoint de "end-bag" 2. El sistema verifica el estado de todos los paquetes en la maleta 3. Si todos están en FOR_PICKUP: la maleta cambia a DELIVERED 4. Si alguno falta: la maleta cambia a INCIDENCE

Tabla de resultados:

Estado de Paquetes	Resultado de Maleta
Todos FOR_PICKUP	DELIVERED
Al menos 1 no FOR_PICKUP	INCIDENCE

4.5 Notificaciones¶

¿Qué sucede? El sistema notifica automáticamente a las partes interesadas.

Notificaciones enviadas:

Cuando	Quién recibe	Mensaje
Todos paquetes FOR_PICKUP	Destinatario	"Tu envío está listo para recojo"
Shipment consolidado	Remitente	"Tu envío ha sido entregado al destinatario"

5. Diagramas de Estados¶

5.1 Estados de la Maleta (Bag)¶

stateDiagram-v2
[*] --> INIT: Creación de maleta

state INIT {
    [*] --> EMPTY: Sin shipments
    EMPTY --> HAS_SHIPMENTS: Primer shipment asignado
}

INIT --> PACKING: Primer package asignado
PACKING --> CLOSE: Operador cierra con 2+ fotos

CLOSE --> TO_AIRPORT: Courier lleva al aeropuerto
TO_AIRPORT --> IN_FLY: Vuelo despega

IN_FLY --> IN_AIRPORT: Vuelo aterriza en destino
IN_AIRPORT --> WITH_COURIER: Courier retira maleta

WITH_COURIER --> IN_WAREHOUSE: Llega al warehouse destino
IN_WAREHOUSE --> OPEN: Condiciones de escaneo cumplidas

state OPEN {
    [*] --> SCANNING: Procesando paquetes
    SCANNING --> COMPLETE: Todos escaneados
}

OPEN --> END: Operador confirma
END --> DELIVERED: Todos paquetes FOR_PICKUP
END --> INCIDENCE: Paquetes faltantes

INCIDENCE --> DELIVERED: Paquetes encontrados
DELIVERED --> [*]

INCIDENCE --> [*]

5.2 Estados del Paquete (Package)¶

stateDiagram-v2
[*] --> CREATED: Shipment creado

CREATED --> SCANNED: QR escaneado por primera vez
SCANNED --> ASSIGNED_TO_BAG: Asignado a maleta

ASSIGNED_TO_BAG --> IN_BAG:放入 maleta
IN_BAG --> FOR_PICKUP: Verificación completada (2+ fotos)

FOR_PICKUP --> DELIVERED: Destinatario firma
DELIVERED --> [*]

FOR_PICKUP --> RETURNED: No entregado
RETURNED --> [*]

5.3 Estados del Envío (Shipment)¶

stateDiagram-v2
[*] --> RECEIVED: Paquetes creados

RECEIVED --> PACKING: Primer package creado
PACKING --> PACKED: Todos packages creados

PACKED --> TO_AIRPORT: Maleta sellada
TO_AIRPORT --> IN_FLY: Vuelo despega

IN_FLY --> IN_AIRPORT: Vuelo aterriza
IN_AIRPORT --> WITH_COURIER: Courier recibe

WITH_COURIER --> IN_WAREHOUSE: Llega al destino
IN_WAREHOUSE --> CONSOLIDATING: Verificación en proceso

CONSOLIDATING --> CONSOLIDATED: Todos FOR_PICKUP
CONSOLIDATED --> DELIVERED: Todos entregados

DELIVERED --> [*]

RECEIVED --> CANCELLED: Cancelado
CANCELLED --> [*]

6. Referencia de API¶

6.1 Abrir Maleta en Warehouse¶

Endpoint: POST /api/v1/warehouse/destination/open-bag

Descripción: Marca una maleta como abierta (OPEN) para iniciar el proceso de verificación en el warehouse destino.

Request:

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440001",
  "courier_id": "550e8400-e29b-41d4-a716-446655440002"
}

Campo	Tipo	Obligatorio	Descripción
operator_id	UUID	Sí	ID del operador que inicia el proceso
courier_id	UUID	Sí	ID del courier que transporta la maleta

Response:

{
  "bag_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "OPEN",
  "packages_in_bag": [
    {
      "package_id": "550e8400-e29b-41d4-a716-446655440003",
      "qr_code": "PKG-839201",
      "status": "IN_BAG"
    },
    {
      "package_id": "550e8400-e29b-41d4-a716-446655440004",
      "qr_code": "PKG-839202",
      "status": "IN_BAG"
    }
  ],
  "opened_at": "2026-05-20T10:30:00Z"
}

6.2 Escanear Paquete¶

Endpoint: POST /api/v1/warehouse/destination/scan-package

Descripción: Registra el escaneo de un paquete por parte del courier u operador.

Request:

{
  "qr_code": "PKG-839201",
  "actor_id": "550e8400-e29b-41d4-a716-446655440002",
  "actor_type": "courier"
}

Campo	Tipo	Obligatorio	Descripción
qr_code	string	Sí	Código QR del paquete
actor_id	UUID	Sí	ID de quien escanea
actor_type	string	Sí	"courier" o "operator"

Response:

{
  "package_id": "550e8400-e29b-41d4-a716-446655440003",
  "qr_code": "PKG-839201",
  "status": "IN_BAG",
  "requires_photos": true,
  "photos_count": 0,
  "both_scanned": false,
  "awaiting_action": "upload_photos"
}

Campo	Tipo	Descripción
requires_photos	boolean	Si necesita subir fotos
both_scanned	boolean	Si courier y operador han escaneado
awaiting_action	string/null	siguiente acción requerida

6.3 Subir Fotos de Verificación¶

Endpoint: POST /api/v1/warehouse/destination/upload-photos

Descripción: Sube las fotos de verificación para un paquete. Requiere mínimo 2 fotos.

Request:

[
  "https://storage.example.com/photo1.jpg",
  "https://storage.example.com/photo2.jpg"
]

Response:

{
  "package_id": "550e8400-e29b-41d4-a716-446655440003",
  "qr_code": "PKG-839201",
  "status": "FOR_PICKUP",
  "photos_uploaded": 2,
  "all_shipment_packages_ready": true,
  "shipment_status": "CONSOLIDATED"
}

6.4 Finalizar Verificación de Maleta¶

Endpoint: POST /api/v1/warehouse/destination/end-bag

Descripción: Finaliza el proceso de verificación de una maleta. El sistema determina si la maleta se marca como DELIVERED o INCIDENCE.

Request:

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440001",
  "courier_id": "550e8400-e29b-41d4-a716-446655440002"
}

Response (éxito):

{
  "bag_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DELIVERED",
  "all_packages_received": true,
  "missing_packages": null,
  "incomplete_packages": null
}

Response (incidencia):

{
  "bag_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "INCIDENCE",
  "all_packages_received": false,
  "missing_packages": ["550e8400-e29b-41d4-a716-446655440005"],
  "incomplete_packages": [
    {
      "package_id": "550e8400-e29b-41d4-a716-446655440005",
      "qr_code": "PKG-839203",
      "current_status": "IN_BAG",
      "missing_action": "awaiting_scan"
    }
  ]
}

6.5 Consolidar Envío¶

Endpoint: POST /api/v1/warehouse/destination/consolidate

Descripción: Consolida un envío verificando que todos sus paquetes están listos para entrega.

Request:

{
  "shipment_id": "550e8400-e29b-41d4-a716-446655440010"
}

Response:

{
  "shipment_id": "550e8400-e29b-41d4-a716-446655440010",
  "status": "CONSOLIDATED",
  "packages_ready": 3,
  "total_packages": 3,
  "notifications_sent": true,
  "recipient_notified": true,
  "sender_notified": true
}

7. Manejo de Incidencias¶

7.1 ¿Cuándo se crea una Incidencia?¶

Una incidencia se crea cuando:

El operador llama al endpoint end-bag
Al menos un paquete en la maleta no está en estado FOR_PICKUP

7.2 Datos Registrados¶

Campo	Descripción
id	Identificador único de la incidencia
bag_id	ID de la maleta con incidencia
missing_package_ids	Lista de IDs de paquetes faltantes
reported_by	ID del operador que reporta
notes	Notas opcionales del operador
created_at	Timestamp de creación

7.3 Flujo de Resolución¶

flowchart TD
    A[Maleta = INCIDENCE] --> B{Paquete encontrado?}
    B -->|Sí| C[Escanear paquete]
    C --> D{País FOR_PICKUP?}
    D -->|Sí| E[Verificar si todos OK]
    E --> F{Todos FOR_PICKUP?}
    F -->|Sí| G[Maleta = DELIVERED]
    F -->|No| A
    B -->|No| H[Registrar pérdida]
    H --> I[Notificar a cliente]

8. Preguntas Frecuentes¶

8.1 ¿Qué sucede si el courier y el operador son la misma persona?¶

Si el courier también opera en el warehouse destino,只需要 que una persona escanee. El sistema detecta que es la misma persona y solo requiere un escaneo (ya sea del QR de la maleta o del primer paquete).

8.2 ¿Qué pasa si un paquete no tiene fotos?¶

El paquete no puede cambiar a estado FOR_PICKUP. Debe ser escaneado nuevamente y subir las fotos requeridas (mínimo 2).

8.3 ¿Se puede revertir una incidencia?¶

Sí. Si el paquete faltante aparece y se verifica con fotos, el sistema cambiará el estado de la maleta de INCIDENCE a DELIVERED.

8.4 ¿Cuántas fotos se requieren por paquete?¶

Mínimo 2 fotos. Se recomienda que las fotos muestren diferentes ángulos del contenido.

8.5 ¿Qué notificaciones se envían?¶

Evento	Destinatario	Notificación
Todos paquetes FOR_PICKUP	Destinatario	"Tu envío está listo para recojo"
Shipment consolidado	Remitente	"Tu envío ha sido entregado"

8.6 ¿Pueden varios paquetes tener diferentes destinatarios?¶

Sí. Cada paquete puede tener su propio destinatario si así se configuró al crear el envío.

9. Resumen de Estados¶

9.1 Maleta (Bag)¶

Estado	Descripción
INIT	Creada, sin shipments
PACKING	Con shipments, recibiendo packages
CLOSE	Cerrada con 2+ fotos
TO_AIRPORT	En camino al aeropuerto
IN_FLY	En vuelo
IN_AIRPORT	Llegó al destino
WITH_COURIER	Con courier
IN_WAREHOUSE	En warehouse destino
OPEN	Siendo procesada
END	Verificación completada
DELIVERED	Todos entregados
INCIDENCE	Paquetes faltantes

9.2 Paquete (Package)¶

Estado	Descripción
CREATED	Creado
SCANNED	QR escaneado
ASSIGNED_TO_BAG	Asignado a maleta
IN_BAG	En maleta
FOR_PICKUP	Listo para recojo
DELIVERED	Entregado
RETURNED	Devuelto

9.3 Envío (Shipment)¶

Estado	Descripción
RECEIVED	Recibido
PACKING	Creando packages
PACKED	Todos creados
TO_AIRPORT	En camino
IN_FLY	En vuelo
IN_AIRPORT	Llegó
WITH_COURIER	Con courier
IN_WAREHOUSE	En warehouse
CONSOLIDATING	Consolidando
CONSOLIDATED	Listo
DELIVERED	Entregado

Documento creado para SaaS Courier - Warehouse Destination Workflow Versión 1.0 - Mayo 2026