# control/embarque/listar - [index]

## 🧾 **Descripción**

Este servicio retorna la **lista de órdenes de servicio embarcadas** asociadas a un **cargoprogramación (cap\_id)**.  
Además, incluye:

- Datos de origen/destino
- Estado de embarque
- Contenido detallado de las unidades (KG, sobres, bultos, etc.)
- Cantidades totales
- Nombre del remitente
- Guía de cliente
- Ruta generada (origen - destino)

Adicionalmente, permite filtrar por número de guía del cliente.

---

# 🚀 **Endpoint**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-post-%2Fordenes-embarq"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr"><span style="color: rgb(224, 62, 45);">**`POST /ordenes-embarque`**</span></div></div>---

# 📥 **Request Body**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22cap_id%22%3A-%22number%22"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"cap_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"pagina"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"guia"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string (opcional)"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### Parámetros requeridos

<div class="_tableContainer_1rjym_1" id="bkmrk-campo-tipo-obligator"><div class="group _tableWrapper_1rjym_13 flex w-fit flex-col-reverse" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="1066" data-start="809"><thead data-end="853" data-start="809"><tr data-end="853" data-start="809"><th data-col-size="sm" data-end="817" data-start="809">Campo</th><th data-col-size="sm" data-end="824" data-start="817">Tipo</th><th data-col-size="sm" data-end="838" data-start="824">Obligatorio</th><th data-col-size="sm" data-end="853" data-start="838">Descripción</th></tr></thead><tbody data-end="1066" data-start="899"><tr data-end="962" data-start="899"><td data-col-size="sm" data-end="908" data-start="899">cap\_id</td><td data-col-size="sm" data-end="917" data-start="908">number</td><td data-col-size="sm" data-end="922" data-start="917">Sí</td><td data-col-size="sm" data-end="962" data-start="922">ID de carga programación (embarque).</td></tr><tr data-end="1013" data-start="963"><td data-col-size="sm" data-end="972" data-start="963">pagina</td><td data-col-size="sm" data-end="981" data-start="972">number</td><td data-col-size="sm" data-end="986" data-start="981">Sí</td><td data-col-size="sm" data-end="1013" data-start="986">Página para paginación.</td></tr><tr data-end="1066" data-start="1014"><td data-col-size="sm" data-end="1021" data-start="1014">guia</td><td data-col-size="sm" data-end="1030" data-start="1021">string</td><td data-col-size="sm" data-end="1035" data-start="1030">No</td><td data-col-size="sm" data-end="1066" data-start="1035">Número de guía del cliente.</td></tr></tbody></table>

</div></div>---

# 🔐 **Seguridad**

Autenticación estándar del sistema (token/cabecera middleware). No validado directamente en la función.

---

# 🧠 **Flujo del Servicio (resumen real)**

1. **Valida que `cap_id` exista**.  
    Si no → *“Es obligatorio enviar un id”*
2. **Construye filtros**
    
    
    - Siempre por: `ose_ultimo_carprog_embarque = cap_id`
    - Opcional: `ose_nroguiacliente = guia`
3. **Obtiene las órdenes de servicio** (`emp_ordenservicio`), paginadas (15 registros por página).  
    Incluye campos como:
    
    
    - fecha de preferencia de partida
    - monto final
    - remitente/destinatario
    - tipo de pago
    - origen / destino
    - usuario creador
    - estado de pago
    - etc.
4. **Carga los terminales** (`emp_terminal`) para convertir IDs → nombres y alias.
5. **Si no existen órdenes**  
    → *“No ha embarcado nada aun”*
6. **Obtiene detalles de contenido** (`emp_os_detalle`) por OSE:
    
    
    - Agrupa por tipo de precio
    - Suma cantidades
    - Genera estructura como: `"5 KG, 2 SB"`
7. **Obtiene historial de embarque** (`emp_embarque_historial`)
    
    
    - Determina si la guía está embarcada o no
    - Paquetes embarcados
    - Total de paquetes
8. **Obtiene abreviaturas de tipos de pago** (`emp_atributos`)
    
    
    - Convierte código → abreviatura
9. **Integra la información para cada OSE**
    
    
    - contenido
    - cantidad total
    - estado de guía (“GUIA EMBARCADA” / “SIN GUIA”)
    - paquetes embarcados
    - origen y destino por nombre
    - ruta generada (alias-origen → alias-destino)
10. **Obtiene nombres de remitentes** (`emp_persona`)  
    Convierte DNI → nombre completo.
11. **Reemplaza remitente DNI → nombre**.
12. **Retorna lista final** con toda la información enriquecida.

---

# 📤 **Response 200 – Ejemplo**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22success%22%3A-true%2C-%22"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"success"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Lista de ordenes"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>    <span class="hljs-punctuation">{</span>      <span class="hljs-attr">"fecha"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"2025-02-24 08:15:00"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"monto"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">150.50</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"guia"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"GC-2300122"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"remitente"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"JUAN PÉREZ GARCÍA"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"destinatario"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"EMPRESA XYZ"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"tipo_pago"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"CR"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"origen"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"LIMA"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"destino"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"AREQUIPA"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"usuario"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"amendoza"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"ose_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">554433</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"estado_pago"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"PAGADO"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"tipo_entrega"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"DELIVERY"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"contenido"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"3 KG, 2 SB"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"ruta"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"LIM - AQP"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"embarque_guia"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"GUIA EMBARCADA"</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"cant_paq"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">5</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"cant_total"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">5</span><span class="hljs-punctuation">,</span>      <span class="hljs-attr">"embarcados"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"PKG001"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"PKG002"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"PKG003"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"PKG004"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"PKG005"</span><span class="hljs-punctuation">]</span>    <span class="hljs-punctuation">}</span>  <span class="hljs-punctuation">]</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

# ❗ **Posibles Errores**

### 1. Falta `cap_id`

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22success%22%3A-false%2C-"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span> <span class="hljs-attr">"success"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Es obligatorio enviar un id"</span> <span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### 2. No hay órdenes embarcadas aún

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22success%22%3A-false%2C--1"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span> <span class="hljs-attr">"success"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"No ha embarcado nada aun"</span> <span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### 3. No hay órdenes coincidentes con la guía filtrada

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22success%22%3A-false%2C--2"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span> <span class="hljs-attr">"success"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"No ha embarcado nada aun"</span> <span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

# 📚 **Schemas (estructuras usadas)**

### **emp\_ordenservicio**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22ose_id%22%3A-%22number%22"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%; height: 29.6px;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr style="height: 29.6px;"><td style="height: 29.6px;">`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"ose_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_nroguiacliente"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_remiteempresa"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string (DNI)"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_destinaempresa"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_servpagotipo"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_termorigenatencion"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_termdestinoentrega"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"ose_montofinal"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### **emp\_os\_detalle**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22ose_id%22%3A-%22number%22-1"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"ose_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"tipo"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"cantidad"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### **emp\_embarque\_historial**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22emb_ose_id%22%3A-%22num"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"emb_ose_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"emb_estado_guia"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"boolean"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"emb_cant_paquetes_embarcados"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string (coma separada)"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"emb_cant_paquetes_total"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### **emp\_terminal**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22ter_id%22%3A-%22number%22"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"ter_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"number"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"nombre"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"alias"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### **emp\_persona**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22documento%22%3A-%22stri"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"documento"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"nombre"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

# 🗃 **Lógica en pseudo-código**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-if-%21cap_id--%3E-error-"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`if !cap_id -> errorwhere = { ose_ultimo_carprog_embarque = cap_id }if guia -> add filter guiaordenes = get OS with paginationif empty -> errorose_ids = extract idsdetalles = query emp_os_detalle grouped by tipo and ose_idarmar contenido y cantidad totalembarques = query emp_embarque_historial for cap_idarmar estado de guía y paquetes embarcadosatributos = abreviaturas de tipo de pagoterminales = mapear origen/destinofor each orden:    combinar detalles + embarques + terminales + atributos    construir ruta    guardar remitente DNIpersonas = query emp_persona for remitentesreemplazar DNI → nombrereturn lista enriquecida`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>