# DOC. SERVICIOS APP - SHALOM CONTROL # Embarques # Control/carguero/listar - (1,2) [indexCooler] ## 🧾 **Descripción** *Este servicio valida un **código de cooler (BINS, COOLER o PALLET)** y retorna la **lista de guías (OSE)** que tienen paquetes dentro del cooler y aún no están embarcadas.* *Realiza consultas combinadas en **CentOS** y **Empresarial**, arma las guías agrupando cantidades y devuelve un resumen estructurado.* --- # 🚀 **Endpoint**
**`POST /index-cooler`**
--- ## 📥 **Request Body**
`{ "cooler": "string", "usuario": "string", "terminal": "string", "cap_id": "string"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
coolerstringSíCódigo escaneado del cooler (debe contener BINS, COOLER o PALLET).
usuariostringSíUsuario que ejecuta el proceso.
terminalstringNoTerminal desde donde opera.
cap\_idstringNoID de capacidad.
--- # 🔐 **Seguridad** Generalmente protegido por token o cabecera de sesión (dependiendo del middleware definido). No se valida en la función directamente. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validaciones iniciales** - Verifica que `cooler` y `usuario` existan. - Valida que `cooler` contenga: `BINS` o `COOLER` o `PALLET`. 2. **Verifica existencia del cooler** Busca en `emp_cooler`:
`SELECT id, codigo_barra, cap_idFROM emp_coolerWHERE codigo_barra = AND estado = 1ORDER BY id DESC`
Si no existe → *“Aún no hay paquetes en el cooler”* 3. **Obtiene paquetes del cooler aún no embarcados**
`SELECT ose_id, codigo_barra AS cooler, numero, usuario, fechaFROM emp_cooler_guiasWHERE codigo_barra = AND estado_embarque = 0 AND estado = 1ORDER BY fecha DESC`
4. **Agrupa paquetes por OSE** - Extrae los primeros dígitos del campo `numero`. - Agrupa cantidades por OSE. 5. **Obtiene datos adicionales de la OSE** Consulta empresarial:
`SELECT osd.osd_osid AS ose_id, os.ose_nroguiacliente AS guia, SUM(osd.osd_unidad) AS cantidadFROM emp_os_detalle osdLEFT JOIN emp_ordenservicio os ON os.ose_id = osd.osd_osidWHERE osd.osd_eliminado = 0 AND osd.osd_osid IN GROUP BY osd.osd_osid`
6. **Construye respuesta final** Por cada OSE: - código del cooler - usuario y fecha del último registro - cantidades únicas encontradas - cantidad total desde la OS - número de guía del cliente --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "lista guias embarcadas.", "data": [ { "ose_id": 12345, "cooler": "COOLER-001", "usuario": "jlopez", "fecha": "2025-01-20 10:15:00", "cantidades": "10,12", "cantidad": 22, "guia": "GUIA-998877" } ]}`
--- # ❗ **Posibles Errores** ### 1. Cooler no enviado
`{ "success": false, "message": "No se encontró el cooler vuelva a intentarlo" }`
### 2. Usuario no enviado
`{ "success": false, "message": "No se encontró el usuario vuelva a intentarlo" }`
### 3. Código de cooler inválido
`{ "success": false, "message": "Cooler inválido. Debe contener la palabra BINS o COOLER"}`
*(Tu código acepta PALLET también, pero el mensaje no lo menciona.)* ### 4. Cooler no tiene registros activos
`{ "success": false, "message": "Aun no hay paquetes en el cooler" }`
### 5. No hay paquetes no embarcados
`{ "success": false, "message": "Aun no hay paquetes en el cooler", "data": []}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_cooler**
`{ "id": "number", "codigo_barra": "string", "cap_id": "number"}`
### **emp\_cooler\_guias**
`{ "ose_id": "number", "cooler": "string", "numero": "string", "usuario": "string", "fecha": "datetime"}`
### **emp\_os\_detalle + emp\_ordenservicio**
`{ "ose_id": "number", "guia": "string", "cantidad": "number"}`
--- # 🗃 **Lógica en pseudo-código**
`if !cooler -> errorif !usuario -> errorif cooler not contains ["BINS", "COOLER", "PALLET"] -> errorcoolerData = SELECT from emp_cooler where codigo=cooler and estado=1if empty -> errorpaquetes = SELECT from emp_cooler_guias where cooler=cooler and estado_embarque=0if empty -> erroragrupar paquetes por ose_id: extract cantidades from numerodetalles = SELECT cantidades y guía por cada ose_idcombinar datos: return lista por cada ose_id con cantidades únicas + total OS`
# control/carguero/obtener - [show] **PATH:** /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/CargueroController.php ## 🧾 **Descripción** Obtiene la **información detallada de un carguero programado** (`cap_id`) incluyendo: - Datos del carguero (fecha, placas, choferes, ruta) - Listado de terminales (para reemplazar IDs por nombres) - Orígenes, destinos y escalas (transformados a formato legible) - Cantidad de guías embarcadas asociadas al carguero - Suma total del monto final de dichas guías Este servicio consolida datos provenientes de varias tablas del sistema Empresarial. --- # 🚀 **Endpoint**
**`POST /carguero/show`**
--- # 📥 **Request Body**
`{ "cap_id": "number", "terminal": "string", "usuario": "string"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
cap\_idnumberSíID del carguero programado.
terminalstringNoTerminal origen (no se usa en la lógica actual).
usuariostringNoUsuario que consulta (no se usa en la lógica actual).
--- # 🔐 **Seguridad** El servicio depende del middleware configurado (token, sesión, etc). No valida autenticación dentro del método. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación inicial** - Si no se envía `cap_id` → retorna error. 2. **Obtiene datos del carguero**
`SELECT fecha, choferes, ruta, placas, origen, destino, cerradoFROM emp_cargprogramadoWHERE cap_id = <cap_id>`
3. **Obtiene lista de terminales**
`SELECT ter_id, ter_nombreFROM emp_terminal`
- Se genera un mapa `ter_id → nombre`. 4. **Convierte origen/destino (JSON) a texto descriptivo** - Decodifica arrays JSON. - Reemplaza cada ID por: `ID + nombre_terminal` - Calcula campos: - `origenes` - `destinos` - `escalas` (unión única de ambos) 5. **Obtiene guías relacionadas al carguero**
`SELECT ose_montofinal, ose_idFROM emp_ordenservicioWHERE ose_ultimo_carprog_embarque = ORDER BY ose_ultima_fecha_embarque DESC`
6. Calcula: - `cantidad`: número de guías - `suma`: suma total de `ose_montofinal` 7. Elimina campos originales `origen` y `destino` del objeto final. 8. **Retorna JSON con todos los datos del carguero.** --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de cargueros", "data": { "fecha": "2025-01-15 10:00:00", "cap_id": 1287, "chofer1": "CHO123", "chofer2": "CHO456", "ruta": "RUTA-09", "placa1": "ABC-123", "placa2": "DEF-456", "cerrado": 0, "origenes": [ "1 Terminal Lima", "3 Terminal Arequipa" ], "destinos": [ "5 Terminal Piura" ], "escalas": [ "1 Terminal Lima", "3 Terminal Arequipa", "5 Terminal Piura" ], "cantidad": 42, "suma": 15789.50 }}`
--- # ❗ **Posibles Errores** ### 1. Falta `cap_id`
`{ "success": false, "message": "Es obligatorio enviar un id"}`
### 2. `cap_id` no existe en la BD *(La función no valida explícitamente este caso, pero retornará `data = null`)* Ejemplo de respuesta:
`{ "success": true, "message": "Lista de cargueros", "data": null}`
*(Opcionalmente podrías corregir esto en backend.)* --- # 📚 **Schemas (estructuras usadas)** ### **emp\_cargprogramado**
`{ "cap_id": "number", "fecha": "datetime", "chofer1": "string", "chofer2": "string", "ruta": "string", "placa1": "string", "placa2": "string", "cerrado": "number", "origen": "json[]", "destino": "json[]"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string"}`
### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_montofinal": "float", "ose_ultimo_carprog_embarque": "number"}`
--- # 🗃 **Lógica en pseudo-código**
`if !cap_id -> errorcarguero = SELECT * FROM emp_cargprogramado WHERE cap_id = cap_idterminales = SELECT ter_id, ter_nombre FROM emp_terminalmapaTerminal = {ter_id: nombre}carguero.origenes = parseJSON(carguero.origen)carguero.destinos = parseJSON(carguero.destino)escalas = union(origenes, destinos)reemplazar cada ID por "ID + nombre_terminal"guias = SELECT ose_id, ose_montofinal FROM emp_ordenservicio WHERE ose_ultimo_carprog_embarque = cap_idcarguero.cantidad = count(guias)carguero.suma = sum(ose_montofinal)return carguero`
# 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**
**`POST /ordenes-embarque`**
--- # 📥 **Request Body**
`{ "cap_id": "number", "pagina": "number", "guia": "string (opcional)"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
cap\_idnumberSíID de carga programación (embarque).
paginanumberSíPágina para paginación.
guiastringNoNúmero de guía del cliente.
--- # 🔐 **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**
`{ "success": true, "message": "Lista de ordenes", "data": [ { "fecha": "2025-02-24 08:15:00", "monto": 150.50, "guia": "GC-2300122", "remitente": "JUAN PÉREZ GARCÍA", "destinatario": "EMPRESA XYZ", "tipo_pago": "CR", "origen": "LIMA", "destino": "AREQUIPA", "usuario": "amendoza", "ose_id": 554433, "estado_pago": "PAGADO", "tipo_entrega": "DELIVERY", "contenido": "3 KG, 2 SB", "ruta": "LIM - AQP", "embarque_guia": "GUIA EMBARCADA", "cant_paq": 5, "cant_total": 5, "embarcados": ["PKG001", "PKG002", "PKG003", "PKG004", "PKG005"] } ]}`
--- # ❗ **Posibles Errores** ### 1. Falta `cap_id`
`{ "success": false, "message": "Es obligatorio enviar un id" }`
### 2. No hay órdenes embarcadas aún
`{ "success": false, "message": "No ha embarcado nada aun" }`
### 3. No hay órdenes coincidentes con la guía filtrada
`{ "success": false, "message": "No ha embarcado nada aun" }`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_nroguiacliente": "string", "ose_remiteempresa": "string (DNI)", "ose_destinaempresa": "string", "ose_servpagotipo": "string", "ose_termorigenatencion": "number", "ose_termdestinoentrega": "number", "ose_montofinal": "number"}`
### **emp\_os\_detalle**
`{ "ose_id": "number", "tipo": "string", "cantidad": "number"}`
### **emp\_embarque\_historial**
`{ "emb_ose_id": "number", "emb_estado_guia": "boolean", "emb_cant_paquetes_embarcados": "string (coma separada)", "emb_cant_paquetes_total": "number"}`
### **emp\_terminal**
`{ "ter_id": "number", "nombre": "string", "alias": "string"}`
### **emp\_persona**
`{ "documento": "string", "nombre": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`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`
# control/carguero/qr - [generateQrMassive] **PATH:** /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/CargueroController.php ## 🧾 **Descripción** Genera un registro QR asociado a un **carguero programado (cap\_id)**. Obtiene automáticamente la **placa** del vehículo asignado y registra: - cap\_id - placa - usuario - terminal - fecha de creación El registro se almacena en la tabla `emp_cargprogramado_qr` en la base de datos **CentOS**. *Nota:* El código contiene una validación de contraseña deshabilitada (comentada). --- # 🚀 **Endpoint**
**`POST /generate-qr-massive`**
--- # 📥 **Request Body**
`{ "password": "string", "usuario": "string", "cap_id": "number", "terminal": "string", "placa": "string (ignorado, se reemplaza con la placa obtenida)"}`
### Reglas - `password`: opcional actualmente (validación comentada). - `usuario`: requerido. - `cap_id`: requerido. - `terminal`: requerido. - `placa`: ignorado, se obtiene desde la BD. --- # 🔐 **Seguridad** La función no fuerza autenticación ni validación de contraseña porque está comentada, pero originalmente pretendía validar:
`Hash::check(strtoupper(password), usr_clave)`
La seguridad dependerá del middleware externo del proyecto. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Recibe parámetros del request:** `password`, `usuario`, `cap_id`, `terminal`, `placa` (pero placa será ignorada). 2. **Obtiene la placa real del carguero** desde Empresarial:
`SELECT cap_cargueroid AS placaFROM emp_cargprogramadoWHERE cap_id = `
3. **Preparar datos para el QR:**
`{ cap_id, car_placa (placa obtenida), user (usuario), ter_id (terminal), fecha_crea (timestamp actual)}`
4. **Inserta registro en CentOS:**
`INSERT INTO emp_cargprogramado_qrRETURNING id`
5. **Si la inserción falla → error** **Si inserta correctamente → éxito** --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Qr Generado con éxito"}`
--- # ❗ **Posibles Errores** ### 1. Error al insertar el registro
`{ "success": false, "message": "Error en el servicio vuelva a intentar"}`
### 2. cap\_id no encontrado (si la consulta no retorna placa) *(El código no valida este error explícitamente, pero sería un caso real posible)*
`{ "success": false, "message": "No se encontró carguero asociado al cap_id"}`
### 3. Error inesperado (excepción del servidor) *(No manejado explícitamente, pero debe considerarse)*
`{ "success": false, "message": "Error interno del servidor"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_cargprogramado**
`{ "cap_id": "number", "cap_cargueroid": "string (placa)"}`
### **emp\_cargprogramado\_qr** Campos insertados:
`{ "cap_id": "number", "car_placa": "string", "user": "string", "ter_id": "string", "fecha_crea": "datetime"}`
--- # 🗃 **Lógica en pseudo-código**
`receive password, usuario, cap_id, terminal, placa// Validar contraseña (actualmente deshabilitado)placaReal = SELECT placa FROM emp_cargprogramado WHERE cap_id = cap_iddata = { cap_id: cap_id, car_placa: placaReal, user: usuario, ter_id: terminal, fecha_crea: now()}id = INSERT INTO emp_cargprogramado_qr(data)if !id: return errorreturn éxito`
# control/embarque/cerrar - [cerrar] PATH: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/EmbarqueController.php ## 🧾 **Descripción** Este servicio realiza el **cierre de embarque** para un carguero (cap\_id). Procesa todas las **órdenes de servicio asociadas al carguero**, registra el embarque individual de cada una, actualiza sus estados y marca el carguero como embarcado. Además: - Actualiza el historial de embarque. - Procesa posibles transbordos. - Actualiza el detalle del carguero. - Registra un reporte de embarque. - Retorna confirmación del cierre. --- # 🚀 **Endpoint**
**`POST /cerrar`**
--- # 📥 **Request Body**
`{ "cap_id": "number", "terminal": "string", "usuario": "string"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
cap\_idnumberSíID del carguero programado a cerrar.
terminalstringSíTerminal donde se realiza el cierre.
usuariostringSíUsuario que ejecuta el proceso.
--- # 🔐 **Seguridad** Controlada por autenticación global (middleware). El servicio no valida tokens directamente. --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. **Obtiene órdenes asociadas al cap\_id** Consulta `emp_ordenservicio`: - No eliminadas - Asignadas al carguero (`ose_ultimo_carprog_embarque = cap_id`) Si: - No hay órdenes, o - Todas ya están cerradas (`ose_estadoembarque = '1'`) → Retorna “Carguero cerrado”. --- ### 2. **Marca historial de embarque como cerrado** Actualiza `emp_embarque_historial`: - Donde status = 1 - Y emb\_estado\_cierre = 0 → Lo cambia a 1. --- ### 3. **Iteración por cada orden** Para cada orden: #### a) Obtiene placa del carguero Desde `emp_cargprogramado`. #### b) Si la orden está en estado de reparto `T`, registra transbordo Actualiza `emp_transbordo`: - tra\_estado = "SI" - registra usuario, fecha y placa del carguero #### c) Registra el embarque en `emp_embarque` Guarda: - ose\_id - cap\_id - terminal - fecha de embarque - usuario creador - observaciones temporales almacenadas en la orden #### d) Actualiza estado de la orden en `emp_ordenservicio`:
`ose_estadoembarque = 1ose_terminalactual = terminalose_estadodesembarque = 0ose_reparto_estado = 0ose_movilidad_reparto = nullose_estado_paquete_embarque = 0ose_estado_guia_embarque = 0estado_os = "Embarque"`
--- ### 4. **Actualiza detalle del carguero (emp\_cargprogramado\_detalle)** Si existe registro: - Agrega el terminal a la lista `id_terminal` - Cambia `cap_estado_embarque` a 1 Si no existe: - Inserta nuevo registro con ese terminal y estado de embarque = 1. --- ### 5. **Calcula monto total embarcado** Suma `ose_montofinal` de todas las OS: - No eliminadas - De ese terminal - Con estado embarque E o 1 - Y asignadas al carguero --- ### 6. **Registra un reporte de embarque** Inserta en `emp_cargprogramado_reporte`: - cap\_id - terminal - usuario - fecha - tipo\_estado = “Embarque” - flete = monto total --- ### 7. **Retorna respuesta** Devuelve:
`{ "success": true, "message": "Se grabó el Embarque correctamente." }`
--- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Se grabó el Embarque correctamente."}`
--- # ❗ **Posibles Errores** ### 1. No hay órdenes para embarcar o ya están cerradas
`{ "success": false, "message": "Carguero cerrado."}`
*Es el único error explícito que retorna el servicio.* --- # 📚 **Schemas (estructuras usadas)** *(Basado exclusivamente en los campos usados en el código)* ### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_ultima_fecha_embarque": "datetime", "ose_reparto_estado": "string", "ose_emb_obs_tipo_temp": "string", "ose_emb_obs_mensaje_temp": "string", "ose_emb_obs_usuario_temp": "string", "ose_emb_obs_fecha_temp": "datetime", "ose_emb_obs_urlimg_temp": "string", "ose_estadoembarque": "string"}`
### **emp\_embarque\_historial**
`{ "emb_carg_id": "number", "status": "number", "emb_estado_cierre": "number"}`
### **emp\_transbordo**
`{ "tra_osid": "number", "tra_estado": "string", "tra_salidaid2": "number", "tra_user2": "string", "tra_fecha2": "datetime", "tra_carguero2": "string"}`
### **emp\_embarque** Campos insertados:
`{ "emb_ordenservicioid": "number", "emb_cargprograid": "number", "emb_horaembarque": "datetime", "emb_terminalembarque": "string", "eliminado": "number", "fhcrea": "datetime", "usercreaid": "string", "emb_obs_tipo": "string", "emb_obs_mensaje": "string", "emb_obs_usuario": "string", "emb_obs_fecha": "datetime", "emb_obs_urlimg": "string"}`
### **emp\_cargprogramado\_detalle**
`{ "cap_id": "number", "id_terminal": "string", "cap_estado_embarque": "number"}`
### **emp\_cargprogramado\_reporte**
`{ "cap_id": "number", "id_terminal": "string", "usuario_reg": "string", "fechareg": "datetime", "tipo_estado": "string", "flete": "number"}`
--- # 🗃 **Lógica en pseudo-código**
`ordenes = SELECT OS where cap_idsi ordenes vacío o todas cerradas: return "Carguero cerrado"actualizar emp_embarque_historial: emb_estado_cierre = 1para cada orden: cargar placa del carguero si reparto_estado == T: actualizar transbordo insertar en emp_embarque (datos de la OS) actualizar emp_ordenservicio: estadoembarque = 1 terminalactual = terminal otros estados...actualizar o insertar emp_cargprogramado_detallemonto = suma montofinal de ordenes embarcadas del terminal y cap_idinsertar reporte en emp_cargprogramado_reportereturn success`
# control/embarque/validar - [validar] PATH: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/EmbarqueController.php ## 🧾 **Descripción** Este servicio valida si una **Orden de Servicio (OSE)** puede ser procesada para embarque, verificando: - Que la guía exista y no esté anulada. - Que corresponda al terminal. - Que cuente con código QR o clave según el tipo de cliente. - Que cumpla validaciones adicionales mediante `validar_grt()`. El servicio evita el embarque de guías que estén incompletas, anuladas o sin documentación obligatoria. --- # 🚀 **Endpoint**
**`POST /validar-guia`**
--- # 📥 **Request Body**
`{ "ose_id": "number", "cantidad": "number", "numero": "string", "usuario": "string", "terminal": "string", "tipo_cierre": "APP | PDA", "cap_id": "string"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
ose\_idnumberSíID de la Orden de Servicio.
cantidadnumberSíCantidad escaneada.
numerostringNo\*Número del paquete escaneado. *(Si no existe, no se valida embarque)*
usuariostringSíUsuario que realiza la validación.
terminalstringSíTerminal donde se realiza el proceso.
tipo\_cierrestringSíTipo de cierre: APP o PDA.
cap\_idstringSíCapacidad asociada.
--- # 🔐 **Seguridad** Depende del middleware del proyecto. La función **no valida seguridad interna**, se asume que ya llega un request autenticado. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validaciones básicas del Request** - Verifica existencia de: - `ose_id` - `cantidad` - `usuario` - `terminal` - `cap_id` - `tipo_cierre` ∈ {APP, PDA} - Si **no existe `numero`**, retorna: > "Embarque de guías no se valida." 2. **Consulta Orden de Servicio**
`SELECT ose_id, ose_estadoPago, ose_nroguiacliente, ose_code_qr, ose_termdestinoentrega, ose_remiteempresa, ose_destinaempresa, ose_termorigenatencion, ose_fhpreferenciapartida, ose_remitecontactomail, ose_remitecontactofonoFROM emp_ordenservicioWHERE ose_id = <ose_id>`
Validaciones: - Si no existe: ❌ "Guía no encontrada." - Si está anulada (`ose_estadoPago = 'AN'`): ❌ "La guía se encuentra anulada." - Si no corresponde al terminal destino: ❌ "La Orden de Servicio ya se encuentra en su destino." 3. **Validaciones por tipo de cliente** - Si tiene información de remitente con reglas especiales: - Si `remitecontactomail == '0'` → ❌ “Primero debe confirmar la guía en empresarial.” - Si cliente es tipo `"CLIENTES"`: - Busca clave en `emp_code_send` - Busca adicionales en `emp_adicionales` - Si no tiene clave ni adicionales → ❌ “La Orden de Servicio no tiene clave Creada.” - Si **no es cliente tipo especial**, verifica QR: - Si no tiene QR → ❌ “La Orden de Servicio no tiene código QR.” 4. **Validación adicional mediante `validar_grt()`** Llama:
`validar_grt(ose_id, cap_id, remiteempresa, destinaempresa)`
- Si falla, retorna error directo. 5. **Si todo es correcto** Retorna:
`{ "success": true, "message": "Orden de servicio validada."}`
--- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Orden de servicio validada."}`
--- # ❗ **Posibles Errores** ### 1. Falta ose\_id
`{ "success": false, "message": "Falta ose_id.", "data": "error"}`
### 2. No se valida porque no se envió número
`{ "success": true, "message": "Embarque de guias no se valida."}`
### 3. Falta algún parámetro obligatorio Ejemplo — falta terminal:
`{ "success": false, "message": "Falta terminal.", "data": "error"}`
### 4. Guía no encontrada
`{ "success": false, "message": "Guia no encontrada.", "data": "error"}`
### 5. Guía anulada
`{ "success": false, "message": "La guía se encuentra anulada.", "data": "error"}`
### 6. Terminal incorrecto
`{ "success": false, "message": "La Orden de Servicio ya se encuentra en su destino.", "data": "error"}`
### 7. Guía sin confirmación
`{ "success": false, "message": "Primero debe confirmar la guía en empresarial.", "data": "error"}`
### 8. No tiene clave creada
`{ "success": false, "message": "La Orden de Servicio no tiene clave Creada.", "data": "error"}`
### 9. No tiene QR
`{ "success": false, "message": "La Orden de Servicio no tiene código QR.", "data": "error"}`
### 10. Error por validar GRT Ejemplo:
`{ "success": false, "message": "Error en validación GRT.", "data": "password"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_ordenservicio** Campos utilizados:
`{ "ose_id": "number", "ose_estadoPago": "string", "ose_nroguiacliente": "string", "ose_code_qr": "string", "ose_termdestinoentrega": "string", "ose_remiteempresa": "string", "ose_destinaempresa": "string", "ose_termorigenatencion": "string", "ose_fhpreferenciapartida": "datetime", "ose_remitecontactomail": "string", "ose_remitecontactofono": "string"}`
### **emp\_code\_send**
`{ "idose": "number", "password": "string"}`
### **emp\_adicionales**
`{ "adc_ordenservicioid": "number", "adc_tipo": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !ose_id -> errorif !numero -> return "Embarque de guías no se valida."if !cantidad or !usuario or !terminal or !cap_id -> errorif tipo_cierre not in ["APP", "PDA"] -> errororden = SELECT FROM emp_ordenservicio WHERE ose_idif !orden -> errorif estadoPago == 'AN' -> errorif orden.destino != terminal -> errorvalidaciones cliente: if remitenteMail == '0' -> error if CLIENTES and no clave y no adicional -> error else if no QR -> errorvalida_grt = validar_grt(...)if !success -> return valida_grtreturn success`
# control/embarque/paquete -[storeQuantities] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/EmbarqueController.php ## 🧾 **Descripción** Este servicio registra el **embarque de paquetes** para una Orden de Servicio (OS). Valida toda la información crítica del embarque, verifica restricciones de rutas, valida si la OS está apta para embarque (QR / clave / no anulada), confirma cantidades, registra procesos históricos, actualiza estados de embarque y permite manejar escenarios: - Embarque normal - Embarque masivo - Embarque aéreo - Embarque desde cooler Es uno de los servicios centrales del módulo logístico. --- # 🚀 **Endpoint**
`POST /store-quantities`
--- # 📥 **Request Body**
`{ "ose_id": 12345, "cantidad": 12, "cantidades": "1,2,3,4", "usuario": "jlopez", "terminal": 7, "tipo_cierre": "APP", "cap_id": 881, "cierre_aereo": null, "cooler": null, "placa": null, "traspaso": 0}`
### Campos requeridos
CampoTipoObligatorioDescripción
ose\_idnumberSíID de la Orden de Servicio a embarcar.
cantidadnumberSíCantidad total declarada a embarcar.
cantidadesstring (CSV)SíPaquetes escaneados para este embarque.
usuariostringSíUsuario que está realizando el proceso.
terminalnumberSíTerminal desde donde se embarca.
tipo\_cierre"APP" | "PDA"SíTipo de registro del embarque.
cap\_idnumberSíCarguero (ruta programada) asignado.
### Campos opcionales
CampoTipoDescripción
cierre\_aereonumberID del cierre a registrar si es embarque aéreo.
coolerstringCódigo del cooler si se embarca desde uno.
placastringPara embarque masivo (opcional).
traspasonumber (0/1)Indica si permite traspaso entre terminales.
--- # 🔐 **Seguridad** Servicio protegido mediante autenticación de API interna del sistema. Requiere usuario autenticado y terminal válida. --- # 🧠 **Flujo del Servicio (resumen real)** A continuación, el flujo real y completo basado en tu código: --- ### 🔹 **1. Validación de parámetros obligatorios** - ose\_id - cantidades - cantidad - usuario - terminal - cap\_id - tipo\_cierre (solo APP o PDA) --- ### 🔹 **2. Obtiene la Orden de Servicio** Consulta: `emp_ordenservicio` Valida: - Existe la OS - No está anulada - Tiene QR o clave (según reglas del contacto) - Terminal de destino coincide para permitir embarque --- ### 🔹 **3. Valida retención de embarque aéreo** Consulta: `emp_retencion_embarque_aereo` Si existe → no permite embarque. --- ### 🔹 **4. Valida terminales, rutas y restricciones del carguero** Consulta: `emp_cargprogramado` Verifica: - Que el origen del carguero incluya la terminal actual (a menos que sea traspaso). - Restricciones de destino. - Que si es destino aéreo, la ruta sea aérea. Si alguna restricción aplica → error. --- ### 🔹 **5. Obtiene cantidades totales de la OS** Consulta: `emp_os_detalle` Calcula unidades totales. --- ### 🔹 **6. Verifica paquetes previamente desembarcados** Consulta: `emp_procesos_historial_app` Si encuentra que todos los paquetes ya están en destino → bloquea embarque. --- ### 🔹 **7. Verifica embarques previos** Consulta: `emp_embarque_historial` Evalúa: - embarque actual - cantidades ya registradas - estado de guía - si ya está 100% embarcada Si ya embarcó todos los paquetes → error. --- ### 🔹 **8. Registra o actualiza el embarque** Dos escenarios: #### a) **Primer registro** Inserta en: `emp_embarque_historial` #### b) **Actualización** Actualiza registro existente. --- ### 🔹 **9. Actualiza el estado de la Orden de Servicio** Actualiza en `emp_ordenservicio`: - estado de paquete - último carguero - estado de embarque general - fecha de embarque - marcas de validación --- ### 🔹 **10. Registra proceso histórico** En: `emp_procesos_historial_app` - Si no existe → inserta - Si existe → actualiza cantidades --- ### 🔹 **11. Procesos adicionales** - Si es embarque aéreo → actualiza `emp_embarque_aereo` - Si embarca desde cooler → marca estado del registro en `emp_cooler_guias` --- ### 🔹 **12. Respuesta final** Devuelve éxito y número de guía. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Paquetes de la OS: 458822 embarcados con éxito."}`
--- # ❗ **Posibles Errores** ### 1. Campos faltantes
`{ "success": false, "message": "Falta cantidad." }`
### 2. OS no encontrada
`{ "success": false, "message": "Guia no encontrada." }`
### 3. OS anulada
`{ "success": false, "message": "La guía se encuentra anulada." }`
### 4. OS sin QR o clave válida
`{ "success": false, "message": "La Orden de Servicio no tiene código QR." }`
### 5. Terminal no permitida
`{ "success": false, "message": "La Orden de Servicio ya se encuentra en su destino." }`
### 6. Restricción de embarque aéreo
`{ "success": false, "message": "La guia tiene una retención de embarque aereo, no se puede embarcar"}`
### 7. Restricción de ruta
`{ "success": false, "message": "En la ruta X no puede embarcar para el destino Y."}`
### 8. Paquetes ya embarcados
`{ "success": false, "message": "Ya fueron embarcados todos los paquetes de la guia."}`
### 9. Error al actualizar embarque aéreo o cooler
`{ "success": false, "message": "Ocurrió un error al embarcar la OS: XXXX"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_nroguiacliente": "string", "ose_estadoPago": "string", "ose_code_qr": "string", "ose_termorigenatencion": "number", "ose_termdestinoentrega": "number", "ose_fhpreferenciapartida": "datetime"}`
### **emp\_embarque\_historial**
`{ "emb_id": "number", "emb_ose_id": "number", "emb_cant_paquetes_embarcados": "string", "emb_cant_paquetes_total": "number", "emb_terminal": "number", "emb_carg_id": "number"}`
### **emp\_procesos\_historial\_app**
`{ "id": "number", "idose": "number", "idcarguero": "number", "proceso": "string", "nombre_metodo": "string", "cant_paquetes": "string"}`
### **emp\_cooler\_guias**
`{ "codigo_barra": "string", "ose_id": "number", "estado_embarque": "0|1"}`
### **emp\_embarque\_aereo**
`{ "ose_id": "number", "estado": "number", "cierre_id": "number|null"}`
--- # 🗃 **Lógica en pseudo-código**
`validar parámetros requeridosorden = obtener OSsi no existe o está anulada -> errorvalidar QR o clavevalidar terminal de destinovalidar retenciones aéreasvalidar rutas, orígenes, restriccionesdetalle = obtener total de paquetes de OSprocesos_previos = obtener historialsi todos los paquetes ya están en destino -> errorembarques_previos = obtener embarquessi ya embarcados todos -> errorsi no existe embarque actual: insertar registro de embarquesino: actualizar registro existenteactualizar estado de OSregistrar proceso históricosi cierre_aereo -> actualizar emp_embarque_aereosi cooler -> actualizar emp_cooler_guiasreturn éxito`
# control/embarque/obtener - [show] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/EmbarqueController.php ## 🧾 **Descripción** Obtiene la información completa de una **Orden de Servicio (OSE)**, incluyendo: - Datos generales de la guía - Datos del remitente, destino y ruta - Contenido (tipos y cantidades de unidades) - Estado de embarque y paquetes embarcados - Atributos del tipo de pago - Usuario creador - Validaciones de estado Es un servicio para **consulta detallada** de una guía antes o durante el proceso de embarque. --- # 🚀 **Endpoint**
**`POST /show`**
--- # 📥 **Request Body**
`{ "ose_id": "number", "cap_id": "number", "terminal": "string"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
ose\_idnumberSíID de la orden de servicio a consultar.
cap\_idnumberSíID de carga (embarque) asociado.
terminalstringNoTerminal desde donde se consulta.
--- # 🔐 **Seguridad** El servicio depende del middleware global (token/sesión del sistema). No hace validación explícita dentro de la función. --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. **Validación inicial** - Verifica obligatorio `ose_id`. - Verifica obligatorio `cap_id`. ### 2. **Obtiene datos de la orden** Consulta principal:
`SELECT fecha, monto, guia, remitente, destinatario, tipo_pago, origen, destino, usuario, ose_id, estado_pago, tipo_entrega, contenido = null, ruta = null, embarque_guia = 'SIN GUIA', cant_paq = 0, cant_total = 0, embarcados = null, cap_id = ''FROM emp_ordenservicioWHERE ose_id = <ose_id>`
Si no existe → *"Orden de servicio no encontrada"* Si está anulada (`estado_pago = 'AN'`) → error. --- ### 3. **Obtiene nombres de terminales** Se reemplazan los IDs de origen/destino por su nombre y alias:
`SELECT nombre, alias FROM emp_terminal WHERE ter_id = origenSELECT nombre, alias FROM emp_terminal WHERE ter_id = destino`
Crea la ruta: `ruta = origen_alias + ' - ' + destino_alias` --- ### 4. **Obtiene contenido de la OSE** Consulta:
`SELECT tipo, cantidadFROM emp_os_detalleWHERE osd_osid = <ose_id> AND osd_eliminado = 0`
Construye: - contenido → `"5 CAJA / 2 SOBRE / ..."` - cant\_total → sumatoria de cantidades --- ### 5. **Obtiene estado de embarque** Consulta:
`SELECT emb_estado_guia, emb_cant_paquetes_embarcadosFROM emp_embarque_historialWHERE emb_ose_id = AND emb_carg_id = AND status = 1`
Calcula: - emb\_guia → `GUIA EMBARCADA` si existe algún registro con valor > 0 - cant\_paq → cantidad de paquetes registrados - embarcados → array de los paquetes embarcados --- ### 6. **Traduce tipo de pago** Consulta atributos:
`SELECT abreviatura, valorFROM emp_atributosWHERE concepto = 'tipospago'AND atr_idpadre = 90`
Aplica la conversión: `orden.tipo_pago = abreviatura del valor recibido` --- ### 7. **Obtiene nombre del remitente**
`SELECT documento, nombre_completoFROM emp_personaWHERE documento = orden.remitente`
--- ### 8. **Obtiene usuario creador**
`SELECT usr_alias FROM emp_usuario WHERE usr_id = orden.usuario`
--- ### 9. **Devuelve respuesta final** Incluye: - datos completos de la OSE - contenido - tipo de pago traducido - cantidades - ruta - paquetes embarcados --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Orden encontrada", "data": { "ose_id": 152233, "fecha": "2025-01-12", "guia": "G-998877", "remitente": "EMPRESA S.A.", "destinatario": "CLIENTE SAC", "tipo_pago": "CR", "origen": "LIMA", "destino": "AREQUIPA", "ruta": "LIM - AQP", "contenido": "5 CAJA / 2 SOBRE", "cant_total": 7, "embarque_guia": "SIN GUIA", "cant_paq": 0, "usuario": "jrojas", "cap_id": 22, "embarcados": [] }}`
--- # ❗ **Posibles Errores** ### 1. Falta ose\_id
`{ "success": false, "message": "Es obligatorio enviar un ose_id" }`
### 2. Falta cap\_id
`{ "success": false, "message": "Es obligatorio enviar un cap_id" }`
### 3. OSE no encontrada
`{ "success": true, "message": "Orden de servicio no encontrada" }`
### 4. Guía anulada
`{ "success": false, "message": "La guía se encuentra anulada."}`
--- # 📚 **Schemas (estructuras usadas)** ### **Orden de Servicio (emp\_ordenservicio)**
`{ "ose_id": "number", "fecha": "datetime", "monto": "number", "guia": "string", "remitente": "string", "destinatario": "string", "tipo_pago": "string", "origen": "number", "destino": "number", "usuario": "number", "estado_pago": "string"}`
### **Detalle OSE (emp\_os\_detalle)**
`{ "tipo": "string", "cantidad": "number"}`
### **Terminal (emp\_terminal)**
`{ "nombre": "string", "alias": "string"}`
### **Embarque Historial**
`{ "emb_estado_guia": "number", "emb_cant_paquetes_embarcados": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !ose_id -> errorif !cap_id -> errororden = SELECT from emp_ordenservicioif not found -> return mensajeif anulada -> errororigen = SELECT terminaldestino = SELECT terminalorden.ruta = origen.alias + " - " + destino.aliasdetalles = SELECT detalle OSEcontenido = concatenar tipo + cantidadcant_total = sum cantidadesembarques = SELECT embarques para ose_id y cap_idcalcular emb_guia, cant_paq, embarcados[]tipo_pago = traducir via emp_atributosremitente = SELECT personausuario = SELECT usuarioreturn orden completa`
# control/embarque/eliminar - [destroy] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/EmbarqueController.php ## 🧾 Descripción *Este servicio elimina el **embarque** asociado a una orden de servicio (**OSE**) y un carguero (**cap\_id**).* *Revierte todos los estados de embarque relacionados y registra el historial de eliminación del proceso.* *Si aplica, también elimina el embarque en **Moova** (integración externa).* Es un servicio crítico dentro del flujo de **desembarque / reversión de embarque**. --- # 🚀 Endpoint
***`POST /embarque/destroy`***
--- # 📥 Request Body
`{ "ose_id": "number", "usuario": "string", "terminal": "string", "cap_id": "number"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
ose\_idnumberSíID de la orden de servicio a revertir.
usuariostringSíUsuario que ejecuta la eliminación del embarque.
terminalstringSíTerminal desde donde se realiza el proceso.
cap\_idnumberSíID del carguero asociado al embarque.
--- # 🔐 Seguridad Protegido por autenticación estándar de la API (middleware Laravel). La función asume que ya hay un usuario validado. --- # 🧠 Flujo del Servicio (resumen real) ### 1. **Validaciones iniciales** Verifica que existan los campos obligatorios: `ose_id`, `usuario`, `terminal`, `cap_id`. Si falta alguno → responde con error inmediato. --- ### 2. **Obtiene información del carguero** Consulta en `emp_cargprogramado` para asegurarse de que el carguero existe.
`SELECT cap_origen, cap_destino, cap_rutacarguero, cap_restricciones, ruta_aereaFROM emp_cargprogramadoLEFT JOIN emp_gruposWHERE cap_id = <cap_id>`
Si no existe → error: *"No se encontró el carguero."* --- ### 3. **Define estructura de reversión de OSE** Se arma un arreglo con todos los campos de embarque en estado inicial:
`{ "ose_usuario_embarque": null, "ose_estadoembarque": 0, "ose_ultimo_carprog_embarque": null, "ose_ultima_fecha_embarque": null, "ose_fecha_paquete_embarque": null, "ose_fecha_guia_embarque": null, "ose_estado_guia_embarque": 0, "ose_usuario_guia_embarque": null, "ose_usuario_paquete_embarque": null, "ose_estado_paquete_embarque": 0}`
--- ### 4. **Valida si la OSE tuvo desembarque anterior** Consulta:
`SELECT des_id FROM emp_desembarque_historialWHERE des_ose_id = <ose_id> AND des_carg_id = <cap_id>`
Si existen → marca `estado_os = "Desembarque"` --- ### 5. **Revierte el embarque en historial empresarial** Actualiza `emp_embarque_historial`:
`WHERE emb_carg_id = cap_id AND emb_ose_id = ose_idUPDATE status = 0`
--- ### 6. **Resetea información de embarque en la OSE**
`UPDATE emp_ordenservicio SET $OS> WHERE ose_id = `
--- ### 7. **Revierte procesos en historial de CentOS** Busca procesos activos en:
`emp_procesos_historial_appWHERE idose = ose_idAND idcarguero = cap_idAND proceso = 'embarque'AND nombre_metodo IN ('embarque_paquete', 'embarque_guia')UPDATE status = 0`
--- ### 8. **Registra un nuevo historial de eliminación** Inserta un registro indicando el proceso "eliminar\_embarque". --- ### 9. **Integración con Moova (si aplica)** Si el carguero contiene destino "523", verifica si el terminal está habilitado para Moova:
`SELECT id FROM emp_ter_moovaWHERE ter_id = terminal AND status = 1`
Si existe → Ejecuta: `MoovaController::destroy($ose_id)` --- ### 10. **Respuesta final** Devuelve mensaje de éxito: `{ "success": true, "message": "Embarque eliminado"}` --- # 📤 Response 200 – Ejemplo
`{ "success": true, "message": "Embarque eliminado"}`
--- # ❗ Posibles Errores ### 1. Falta ose\_id
`{ "success": false, "message": "Falta ose_id." }`
### 2. Falta usuario
`{ "success": false, "message": "Falta usuario." }`
### 3. Falta terminal
`{ "success": false, "message": "Falta terminal." }`
### 4. Falta cap\_id
`{ "success": false, "message": "Falta cap_id." }`
### 5. Carguero no encontrado
`{ "success": false, "message": "No se encontró el carguero." }`
--- # 📚 Schemas (estructuras usadas) ### **emp\_cargprogramado**
`{ "cap_origen": "string", "cap_destino": "json/string", "cap_rutacarguero": "string", "cap_restricciones": "json/string"}`
### **emp\_embarque\_historial**
`{ "emb_ose_id": "number", "emb_carg_id": "number", "status": "number"}`
### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_estadoembarque": "number", "ose_usuario_embarque": "string|null"}`
### **emp\_procesos\_historial\_app**
`{ "idose": "string", "idcarguero": "string", "proceso": "string", "nombre_metodo": "string", "status": "number"}`
--- # 🗃 Lógica en pseudo-código
`validar campos obligatorios: ose_id, usuario, terminal, cap_idcarguero = obtener cargueroif !carguero -> errorOS = campos en estado inicialdesembarque = buscar desembarque previoif existe -> OS.estado_os = 'Desembarque'actualizar emp_embarque_historial SET status = 0actualizar emp_ordenservicio SET OSactualizar procesos_historial_app SET status = 0insertar registro eliminar_embarquesi carguero.cap_destino contiene '523': si terminal tiene configuración moova: llamar MoovaController.destroy(ose_id)return success`
# Desembarques # control/grupo/listar - [index] (1,2) Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Retorna una lista paginada de **grupos de cargueros de desembarque**, filtrados por terminal, nombre y fecha. Cada grupo incluye sus placas asociadas y el nombre legible de la terminal. Realiza consultas en la base **empresarial**, transforma datos y enriquece la respuesta con nombres de terminales y placas de cargueros programados. --- # 🚀 **Endpoint**
`POST /cargueros-desembarque`
--- # 📥 **Request Body**
`{ "terminal": 3, "pagina": 1, "nombre": "TURNO A"}`
### Parámetros
CampoTipoObligatorioDescripción
terminalint✔️ SíID de la terminal.
paginaint✔️ SíNúmero de página (paginación de 15 registros).
nombrestring✖️ OpcionalFiltra por nombre del grupo (activa rango de fecha extendido).
--- # 🔐 **Seguridad** Requiere token o autenticación definida en middleware general (no se valida dentro del método). --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. Validaciones iniciales - Si no envían `terminal` → error obligatorio. - Se toma `pagina` para paginar. - Se define `limit = 15`. - Fecha mínima: - Por defecto: **ayer** - Si se envía `nombre`: se amplía rango **–10 días a +10 días** y se agrega filtro LIKE al nombre. ### 2. Construcción del filtro para la consulta Filtros aplicados: - terminal = enviado - status = 1 - fecha\_creacion > fechaDesde - si existe nombre → LIKE %nombre% y fecha\_creacion < fechaHasta ### 3. Consulta de grupos de desembarque Tabla: `emp_grupo_cargueros_desembarque` Campos retornados: - id - grupo (array JSON de cap\_id) - nombre - terminal - cerrar\_grupo - fecha\_creacion - placas = null (placeholder) Si no hay resultados → “No se encontraron grupos”. ### 4. Obtención del catálogo de terminales Consulta `emp_terminal` y crea un arreglo tipo diccionario:
`[ ter_id => ter_nombre ]`
### 5. Enriquecimiento de la data Para cada grupo: 1. Decodifica `grupo` (lista de cap\_id). 2. Consulta placas desde: - **emp\_cargprogramado (cap)** - **emp\_carguero\_new (carg)** Campos: - placa1 - codigo1 - placa2 3. Construye lista de placas: `"placa1 codigo1"` 4. Reemplaza el id de terminal por su nombre real. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "lista de grupos", "data": [ { "id": 15, "grupo": [123, 124], "nombre": "TURNO A", "terminal": "Terminal Callao", "cerrar": 0, "fecha": "2025-01-26 10:21:00", "placas": [ "B1234 C001", "B2288 C002" ] } ]}`
--- # ❗ **Posibles Errores** ### 1. Terminal obligatorio
`{ "success": false, "message": "Es obligatorio enviar una terminal"}`
### 2. Sin resultados
`{ "success": false, "message": "No se encontraron grupos"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_grupo\_cargueros\_desembarque**
`{ "id": "number", "grupo": "json array of cap_id", "nombre": "string", "terminal": "number", "cerrar_grupo": "number", "fecha_creacion": "datetime"}`
### **emp\_cargprogramado + emp\_carguero\_new**
`{ "placa1": "string", "codigo1": "string", "placa2": "string"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string", "ter_abrebiatura": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !terminal -> errorfechaDesde = yesterdayif nombre: fechaDesde = -10 days fechaHasta = +10 days add filter nombre LIKE %nombre% add filter fecha_creacion < fechaHastaadd filter fecha_creacion > fechaDesdegrupos = SELECT from emp_grupo_cargueros_desembarque where filters, paginatedif empty -> errorterminales = SELECT all terminalesmap[ter_id] = ter_nombrefor each grupo: ids = decode(grupo.grupo) cargueros = SELECT placas info using ids grupo.placas = format placas grupo.terminal = terminales[grupo.terminal]return grupos`
# control/grupo/obtener - [show] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Este servicio obtiene la **información detallada de un grupo de cargueros de desembarque**, incluyendo: - Datos del grupo - Terminal asociada - Cargueros programados (placas/códigos) - Información estructurada lista para visualizar en pantalla El servicio consulta varias tablas del sistema empresarial para reconstruir toda la información relacionada al grupo. --- # 🚀 **Endpoint**
`POST /grupo-desembarque/show`
--- # 📥 **Request Body**
`{ "grp_id": 123}`
### Parámetros
CampoTipoObligatorioDescripción
grp\_idintegerSíID del grupo a consultar.
--- # 🔐 **Seguridad** Requiere autenticación estándar del sistema (middleware). La función no implementa validación de permisos directamente. --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. **Validación del parámetro** - Si no se envía `grp_id`, retorna error. --- ### 2. **Obtiene información del grupo** Consulta:
`SELECT id, grupo, nombre, terminal, cerrar_grupo AS cerrar, fecha_creacion AS fecha, null AS placasFROM emp_grupo_cargueros_desembarqueWHERE id = `
- Si no se encuentra → error *"No se encontró el grupo"*. --- ### 3. **Reemplaza el ID de terminal por su nombre** Consulta:
`SELECT ter_id, ter_nombre, ter_abrebiaturaFROM emp_terminalWHERE ter_id = <grupo.terminal>`
Actualiza: `grupo.terminal = ` --- ### 4. **Convierte el campo grupo a JSON** `grupo.grupo` es un JSON que contiene una lista de `cap_id`. Ejemplo:
`[12, 15, 19]`
--- ### 5. **Obtiene información de cargueros programados** Consulta:
`SELECT cap.cap_cargueroid AS placa1, carg.car_codigo AS codigo1, cap.cap_carguero_id2 AS placa2FROM emp_cargprogramado capLEFT JOIN emp_carguero_new carg ON cap.cap_cargid = carg.idWHERE cap.cap_id IN () AND cap.eliminado = 0`
Luego construye una lista tipo: `["PLACA001 COD001", "PLACA002 COD009", ...]` Asignado a: `grupo.placas = [...]` --- ### 6. **Respuesta final** Retorna toda la estructura ensamblada. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Informacion de grupo", "data": { "id": 12, "grupo": [125, 126], "nombre": "GRUPO 1", "terminal": "Terminal Norte", "cerrar": 0, "fecha": "2025-01-10 10:20:00", "placas": [ "ABC123 COD001", "XYZ998 COD077" ] }}`
--- # ❗ **Posibles Errores** ### 1. Falta de parámetro obligatorio
`{ "success": false, "message": "Es obligatorio enviar grp_id"}`
### 2. Grupo no encontrado
`{ "success": false, "message": "No se encontró el grupo"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_grupo\_cargueros\_desembarque**
`{ "id": "number", "grupo": "json-array", "nombre": "string", "terminal": "number", "cerrar": "number", "fecha": "datetime", "placas": "array"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string", "ter_abrebiatura": "string"}`
### **emp\_cargprogramado + emp\_carguero\_new**
`{ "placa1": "string", "codigo1": "string", "placa2": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !grp_id -> errorgrupo = SELECT ... FROM emp_grupo_cargueros_desembarque WHERE id=grp_idif !grupo -> errorterminal = SELECT ... FROM emp_terminal WHERE ter_id=grupo.terminalgrupo.terminal = terminal.nombreterminales = JSON decode(grupo.grupo)grupo.grupo = terminalesif terminales not empty: cargueros = SELECT cargueros programados WHERE cap_id IN terminales grupo.placas = ["placa1 codigo1", ...]return grupo`
# control/carguero/grupo - [listarPorGrupo] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/CargueroController.php ## 🧾 **Descripción** Este servicio recibe un **ID de grupo de cargueros (`grp_id`)** y retorna la **lista de cargueros asociados al grupo**, incluyendo información enriquecida: - Datos del carguero (placas, choferes, ruta, origen/destino) - Estado de QR generado - Datos de desembarque (paquetes desembarcados y guías desembarcadas) - Escalas generadas dinámicamente según origen y destino El servicio consulta varias tablas del sistema Empresarial y CentOS y consolida la información en una sola respuesta. --- # 🚀 **Endpoint**
`POST /listar-por-grupo`
--- # 📥 **Request Body**
`{ "grp_id": "number"}`
### Parámetros
CampoTipoObligatorioDescripción
grp\_idnumberSíID del grupo registrado en la tabla `emp_grupo_cargueros_desembarque`.
--- # 🔐 **Seguridad** Protegido generalmente por autenticación de la API (token/middleware definido). El método no valida credenciales directamente. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación de entrada** - Verifica que `grp_id` exista; si no, retorna error. - Busca el grupo en `emp_grupo_cargueros_desembarque`. - Verifica que el grupo tenga cargueros registrados. 2. **Obtiene cargueros asociados** Consulta `emp_cargprogramado` para los `cap_id` del grupo:
`SELECT fecha, cap_id, chofer1, chofer2, ruta, origen, destino, placa1, placa2, cerradoFROM emp_cargprogramadoWHERE eliminado = 0 AND cap_id IN ()ORDER BY fecha DESC`
3. **Obtiene catálogo de terminales** - Lista nombres y abreviaturas de todas las terminales. - Se usa para convertir IDs de terminal en texto legible. 4. **Procesamiento por cada carguero** Para cada `cap_id`: - Decodifica JSON de `origen` y `destino`. - Traduce IDs a abreviaturas de terminal:
`ORIGEN → "LIM - CHI - ARE"DESTINO → "ARE - JUL"`
- Verifica si tiene QR generado (consulta en CentOS). - Obtiene información de desembarque por guía: - Paquetes desembarcados - Total de paquetes - Estado de guía (DESEMBARCADA, SIN GUIA, FALTA DESEMBARCAR GUIA) - Calcula: - Total de paquetes desembarcados - Total de guías desembarcadas - Construye lista de **escalas** combinando origen + destino. 5. **Devuelve lista final de cargueros procesados** --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de cargueros", "data": [ { "fecha": "2025-01-10 08:00:00", "cap_id": 98765, "chofer1": 1122, "chofer2": 3344, "ruta": "RUTA-01", "origen": "LIM - ARE", "destino": "ARE - JUL", "placa1": "ABC-123", "placa2": "XYZ-789", "cerrado": 0, "qr_generado": true, "escalas": [ "1 Terminal Lima", "2 Terminal Arequipa", "3 Terminal Juliaca" ], "paquetes": 150, "guias": 12 } ]}`
--- # ❗ **Posibles Errores** ### 1. No se envió `grp_id`
`{ "success": false, "message": "Envie grp_id"}`
### 2. Grupo no existe
`{ "success": false, "message": "No se encontró grupo"}`
### 3. Grupo sin cargueros
`{ "success": false, "message": "Agregue cargueros al grupo"}`
### 4. No hay cargueros coincidentes
`{ "success": false, "message": "Agregue cargueros al grupo"}`
--- # 📚 **Schemas (estructuras utilizadas)** ### **emp\_grupo\_cargueros\_desembarque**
`{ "id": number, "grupo": "string (JSON array)"}`
### **emp\_cargprogramado**
`{ "cap_id": number, "cap_fhsalidaprogramada": datetime, "cap_chofer1id": number, "cap_chofer2id": number|null, "cap_rutacarguero": string, "cap_origen": "JSON array", "cap_destino": "JSON array", "cap_cargueroid": string, "cap_carguero_id2": string|null, "cap_cerrado": number}`
### **emp\_terminal**
`{ "ter_id": number, "ter_nombre": string, "ter_abrebiatura": string}`
### **emp\_desembarque\_historial + emp\_ordenservicio**
`{ "des_ose_id": number, "desembarcados": "comma separated string", "total": number, "estadoguia": "FALTA DESEMBARCAR GUIA | SIN GUIA | GUIA DESEMBARCADA"}`
--- # 🗃 **Lógica en pseudo-código**
`if !grp_id -> errorgrupo = SELECT grupo WHERE id=grp_idif !grupo -> errorcap_ids = json_decode(grupo.grupo)if empty -> errorcargueros = SELECT cargueros WHERE cap_id IN cap_idsif empty -> errorterminales = SELECT ter_id, ter_nombre, abreviaturafor each carguero: origen_ids = json_decode(carguero.origen) destino_ids = json_decode(carguero.destino) traducir ids a abreviaturas verificar QR generado consultar historial de desembarque calcular paquetes desembarcados y guías desembarcadas generar escalas a partir de origen + destinoreturn cargueros procesados`
# control/grupo/guardar - [store] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Crea un nuevo registro en **emp\_grupo\_cargueros\_desembarque**, que representa un grupo de cargueros/desembarque asociado a un terminal. Si el usuario no envía un nombre, el sistema genera uno automáticamente usando el nombre del terminal y la fecha de creación. --- # 🚀 **Endpoint**
`POST /grupo-cargueros-desembarque`
--- # 📥 **Request Body**
`{ "nombre": "string (opcional)", "terminal": "number (requerido)", "usuario": "string (opcional)"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
terminalnumberSíID del terminal donde se creará el grupo.
nombrestringNoNombre personalizado del grupo. Si no se envía, el sistema genera uno.
usuariostringNoUsuario que realiza la operación (no se usa dentro de la función).
--- # 🔐 **Seguridad** El método no define validación propia, pero depende del middleware o autenticación general de la API. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Obtiene los parámetros**: nombre, terminal, usuario, fecha actual. 2. **Valida que terminal sea numérico**. Si no lo es → retorna:
`{ "success": false, "message": "Debe enviar el terminal" }`
3. **Busca datos del terminal** en `emp_terminal`:
`SELECT ter_id, ter_nombre AS nombreFROM emp_terminalWHERE ter_id = {terminal}`
4. **Genera nombre automáticamente** si no se envía: → ` ` 5. **Inserta un nuevo grupo** en `emp_grupo_cargueros_desembarque`:
`INSERT INTO emp_grupo_cargueros_desembarque(nombre, terminal, fecha_creacion)VALUES (...)`
6. **Retorna ID generado** mediante `insertGetId`. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Grupo creado correctamente", "data": 58}`
*(donde `58` es el ID del nuevo grupo)* --- # ❗ **Posibles Errores** ### 1. Terminal no válido
`{ "success": false, "message": "Debe enviar el terminal"}`
*(No existen más validaciones dentro del método.)* --- # 📚 **Schemas (estructuras usadas)** ### **emp\_terminal**
`{ "ter_id": "number", "nombre": "string"}`
### **emp\_grupo\_cargueros\_desembarque**
`{ "id": "number", "nombre": "string", "terminal": "number", "fecha_creacion": "datetime"}`
--- # 🗃 **Lógica en pseudo-código**
`nombre = request.nombreterminal = request.terminalusuario = request.usuariofecha = now()if terminal is not numeric: return errorterminal_data = SELECT nombre FROM emp_terminal WHERE ter_id = terminalif nombre is empty: nombre = terminal_data.nombre + " " + fechagrupo_new = INSERT INTO emp_grupo_cargueros_desembarque (nombre, terminal, fecha_creacion)return success with grupo_new id`
# control/grupo/carguero/agregar - [agregarCarguero] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Agrega un **carguero (cap\_id)** a un **grupo de cargueros de desembarque (grp\_id)**. El servicio valida que: - Exista el grupo. - El grupo tenga su lista de cargueros almacenados en formato JSON. - El carguero no esté ya incluido en el grupo. - Luego actualiza la tabla agregando el carguero al listado. Este servicio modifica directamente la tabla: **emp\_grupo\_cargueros\_desembarque** --- # 🚀 **Endpoint**
`POST /agregar-carguero`
--- # 📥 **Request Body**
`{ "grp_id": "number", "cap_id": "number"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
grp\_idnumberSíID del grupo de cargueros de desembarque.
cap\_idnumberSíID del carguero a agregar.
--- # 🔐 **Seguridad** Protegido por autenticación del sistema (middleware). El servicio no valida permisos dentro de la función. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación inicial de parámetros** - Si falta `grp_id` → retorna error. - Si falta `cap_id` → retorna error. 2. **Obtiene información del grupo**
`SELECT grupoFROM emp_grupo_cargueros_desembarqueWHERE id = grp_id`
- Si no existe → error “Grupo no encontrado”. 3. **Decodifica el campo `grupo`** - Si el campo `grupo` tiene JSON → se convierte en array. - Si está vacío → se crea array vacío. 4. **Verifica si el carguero ya está en el grupo** - Si `cap_id` ya existe → error “El carguero ya se encuentra en el grupo”. 5. **Agrega el nuevo carguero al grupo** - Inserta `cap_id` dentro del array. - Convierte el array nuevamente a JSON. 6. **Actualiza la BD**
`UPDATE emp_grupo_cargueros_desembarqueSET grupo = json_encode(arreglo_actualizado)WHERE id = grp_id`
7. **Retorna éxito**
`"Carguero agregado al grupo"`
--- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Carguero agregado al grupo"}`
--- # ❗ **Posibles Errores** ### 1. Falta `grp_id`
`{ "success": false, "message": "Falta cap_id"}`
*(El mensaje es incorrecto en el código, pero lo dejamos tal cual está implementado.)* --- ### 2. Falta `cap_id`
`{ "success": false, "message": "Falta cap_id"}`
--- ### 3. Grupo no existe
`{ "success": false, "message": "Grupo no encontrado"}`
--- ### 4. Carguero repetido
`{ "success": false, "message": "El carguero ya se encuentra en el grupo"}`
--- # 📚 **Schemas (estructuras usadas)** ### Tabla: `emp_grupo_cargueros_desembarque`
`{ "id": "number", "grupo": "string(JSON array of cap_id)"}`
Ejemplo del campo `grupo`: `["123", "245", "300"]` --- # 🗃 **Lógica en pseudo-código**
`if !grp_id -> error("Falta cap_id")if !cap_id -> error("Falta cap_id")grupo = SELECT grupo FROM tabla WHERE id = grp_idif !grupo -> error("Grupo no encontrado")grupos = decode(grupo.grupo) OR []if cap_id in grupos: error("El carguero ya se encuentra en el grupo")grupos.append(cap_id)UPDATE tabla SET grupo = encode(grupos) WHERE id = grp_idsuccess("Carguero agregado al grupo")`
# control/carguero/obtener - [show] PATH: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/CargueroController.php ## 🧾 **Descripción** Este servicio devuelve **toda la información detallada** de un carguero programado (`cap_id`), incluyendo: - Datos generales del carguero (choferes, placas, ruta, fechas). - Orígenes y destinos estructurados con su nombre de terminal. - Escalas calculadas (orígenes + destinos). - Cantidad de órdenes de servicio asociadas al carguero. - Suma de los montos finales de dichas OS. Lee información combinada de `emp_cargprogramado`, `emp_terminal` y `emp_ordenservicio`. --- # 🚀 **Endpoint**
`POST /carguero/show`
--- # 📥 **Request Body**
`{ "cap_id": "number", "terminal": "string (opcional)", "usuario": "string (opcional)"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
cap\_idnumberSíID del carguero programado.
usuariostringNoUsuario que ejecuta el proceso.
terminalstringNoTerminal de operación.
--- # 🔐 **Seguridad** Requiere sesión o token según la configuración del middleware (no validado en la función). --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación inicial** - Si no se envía `cap_id`, retorna error. 2. **Obtiene datos del carguero**
`SELECT fecha, cap_id, chofer1, chofer2, ruta, placa1, placa2, cerrado, origen, destinoFROM emp_cargprogramadoWHERE cap_id = :cap_id`
3. **Obtiene datos de terminales**
`SELECT ter_id, ter_nombre FROM emp_terminal`
Construye un diccionario:
`listaTerminal[id] = nombre`
4. **Procesa orígenes y destinos** - Decodifica JSON almacenado en BD. - Convierte cada id de terminal a:
`"<id> <nombre>"`
5. **Calcula escalas**
`escalas = origenes ∪ destinos`
6. **Busca órdenes de servicio asociadas al carguero**
`SELECT ose_montofinal, ose_idFROM emp_ordenservicioWHERE ose_ultimo_carprog_embarque = :cap_idORDER BY ose_ultima_fecha_embarque DESC`
7. **Calcula:** - `cantidad` = total de OS encontradas - `suma` = sumatoria de `ose_montofinal` 8. **Retorna el carguero con estructura final.** --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de cargueros", "data": { "fecha": "2025-01-21 14:00:00", "cap_id": 441, "chofer1": "CH00123", "chofer2": "CH00452", "ruta": "NORTE 01", "placa1": "ABC-123", "placa2": "XYZ-987", "cerrado": 0, "cantidad": 12, "suma": 1560.50, "escalas": [ "01 LIMA", "05 CHIMBOTE", "07 TRUJILLO" ], "origenes": [ "01 LIMA", "05 CHIMBOTE" ], "destinos": [ "07 TRUJILLO" ] }}`
--- # ❗ **Posibles Errores** ### 1. cap\_id no enviado
`{ "success": false, "message": "Es obligatorio enviar un id"}`
### 2. No se encuentra carguero (si cap\_id no existe) *(Laravel devolverá null y puede lanzar errores posteriores, según tu implementación)* Puedes documentarlo así:
`{ "success": false, "message": "Carguero no encontrado"}`
*(**Sugerencia:** en tu función no validas esto, pero debería considerarse.)* --- # 📚 **Schemas (estructuras usadas)** ### **emp\_cargprogramado**
`{ "cap_id": "number", "cap_fhsalidaprogramada": "datetime", "cap_chofer1id": "string", "cap_chofer2id": "string", "cap_rutacarguero": "string", "cap_cargueroid": "string", "cap_carguero_id2": "string", "cap_origen": "json[]", "cap_destino": "json[]", "cap_cerrado": "number"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string"}`
### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_montofinal": "float", "ose_ultimo_carprog_embarque": "number", "ose_ultima_fecha_embarque": "datetime"}`
--- # 🗃 **Lógica en pseudo-código**
`if !cap_id -> errorcarguero = SELECT carguero WHERE cap_idterminales = SELECT id, nombre FROM terminalmapaTerminal = map(id => nombre)carguero.origenes = decodeJSON(carguero.origen)carguero.destinos = decodeJSON(carguero.destino)escalas = unique(origenes + destinos)convertir ids a " " usando mapaTerminalordenes = SELECT OS WHERE os.ose_ultimo_carprog_embarque = cap_idcarguero.cantidad = count(ordenes)carguero.suma = sum(ordenes.montofinal)return carguero`
# query/validar_crear_ruta - [funct_validar_crear_ruta_module] Path: /var/www/html/moradex-qa/app/Models/GeneralesApp.php ## 🧾 **Descripción** Servicio que valida si un usuario o un terminal tienen permiso para acceder a un módulo específico. Actualmente, debido a un `return` colocado antes de la validación, **el servicio siempre devuelve acceso permitido**, pero la lógica diseñada incluye listas de usuarios y terminales autorizados. --- # 🚀 **Endpoint**
`POST /validar-crear-ruta-module`
--- # 📥 **Request Body**
`{ "username": "string", "terminalId": "string"}`
### Parámetros
CampoTipoObligatorioDescripción
usernamestringSíDNI o identificador del usuario.
terminalIdstringSíID del terminal desde el cual accede.
--- # 🔐 **Seguridad** Sin validación interna adicional. Generalmente depende del middleware aplicado al endpoint. --- # 🧠 **Flujo del Servicio (resumen real)** > **IMPORTANTE:** El servicio retorna inmediatamente acceso permitido debido al primer `return`. ### Flujo implementado (real): 1. Obtiene: - `username` (usuario) - `terminalId` (terminal) 2. Retorna:
`{ valor: true, msn: "Puede acceder al modulo" }`
Esto interrumpe el método, haciendo que la lógica posterior nunca se ejecute. --- ### Flujo diseñado (pero actualmente inactivo por el return anticipado) 1. Verificar si el usuario está en la lista de usuarios permitidos:
`if (in_array($user, $usuarios_permitidas)) acceso permitido`
2. Verificar si el terminal está en la lista de terminales permitidas:
`if (in_array($terminal, $terminales_permitidas)) acceso permitido`
3. Si no coincide con ninguna lista → acceso denegado (pero el código está incompleto y termina con `retur`). --- # 📤 **Response – Ejemplo (actual)** ### ✔️ Acceso permitido (siempre)
`{ "valor": true, "msn": "Puede acceder al modulo"}`
--- # ❗ **Posibles Errores (según la lógica esperada)** > *Actualmente NO se producen porque la función retorna antes de validar.* ### 1. Usuario NO autorizado
`{ "valor": false, "msn": "Usuario no autorizado"}`
### 2. Terminal NO autorizada
`{ "valor": false, "msn": "Terminal no autorizada"}`
### 3. Petición incompleta
`{ "valor": false, "msn": "Datos insuficientes (username o terminalId faltantes)"}`
--- # 📚 **Schemas (estructuras usadas)** ### Request
`{ "username": "string", "terminalId": "string"}`
### Response
`{ "valor": "boolean", "msn": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`user = POST.usernameterminal = POST.terminalIdreturn { valor: true, msn: "Puede acceder al modulo" } // retorna siempreusuarios_permitidos = [...]terminales_permitidas = [...]if user in usuarios_permitidos: return acceso permitidoif terminal in terminales_permitidas: return acceso permitidoreturn acceso denegado`
# control/desembarque/pendientes - [pendientes] ## 🧾 **Descripción** Este servicio retorna la lista de **órdenes de servicio (OSE)** que **aún tienen paquetes pendientes por desembarcar** en una unidad específica (`cap_id`). Combina información de embarques, desembarques, órdenes de servicio, detalles de OS, atributos, terminales y datos de personas. Permite aplicar **filtro por número de guía** y soporta **paginación**. Es un servicio crítico para la vista de **desembarques pendientes**. --- # 🚀 **Endpoint**
`POST /pendientes`
--- # 📥 **Request Body**
`{ "cap_id": "number", "pagina": "number", "guia": "string (opcional)"}`
### Parámetros
CampoTipoObligatorioDescripción
cap\_idnumber✔ SíID de la unidad de carga programada.
paginanumber✔ SíNúmero de página a listar.
guiastring✘ NoFiltra por número de guía del cliente.
--- # 🔐 **Seguridad** Requiere autenticación estándar usada en los endpoints del backend (middleware Laravel). No se valida explícitamente dentro del método. --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. Validación inicial - `cap_id` es obligatorio. - Define paginación con `limit = 15`. --- ### 2. Obtener embarques asociados al `cap_id` Consulta tabla `emp_embarque_historial`: - Se filtra por: - estado activo (`status = 1`) - paquete habilitado (`emb_estado_paquete = 1`) - carg\_id igual al cap\_id Si no hay embarques: **“Aún no se ha embarcado nada en esta unidad.”** Se arma: - Lista de OSE (`ose_ids`) - Información del embarque por OSE: - estado de guía - cantidad de paquetes embarcados - cantidad total de paquetes --- ### 3. Obtener desembarques del mismo `cap_id` Consulta tabla `emp_desembarque_historial` similares filtros: Se arma: - Lista de desembarques por OSE: - estado de guía - paquetes desembarcados - total de paquetes --- ### 4. Obtener órdenes de servicio relacionadas Consulta:
`SELECT (varios campos)FROM emp_ordenservicioWHERE ose_id IN (ose_ids)AND (opcional) ose_nroguiacliente = guiaOFFSET (pagina - 1) * 15LIMIT 15`
Si no encuentra OS → **“No ha embarcado nada aun”** --- ### 5. Obtener terminales (origen y destino) Convierte IDs a: - nombre - alias (para construir la ruta) --- ### 6. Obtener detalle de OS Consulta `emp_os_detalle`: Agrupa por: - OSE - Tipo Construye por OSE: - contenido: `"cantidad tipo"` - cantidad total sumada --- ### 7. Obtener atributos de tipo de pago Convierte `tipo_pago` → abreviatura usando tabla `emp_atributos`. --- ### 8. Integrar datos (núcleo del servicio) Por cada OS: - Si existe desembarque: - Calcula paquetes pendientes = total – desembarcados - Marca guía como `"GUIA EMBARCADA"` o `"SIN GUIA"` - Si no existe desembarque: - Paquetes pendientes = total del detalle - Si cantidad pendiente es `0` → se omite del resultado final. - Se construye: - contenido - cantidad total - cantidad pendiente - ruta origen → destino - nombre de terminales Si después de filtrar no hay OS pendientes: → **“No hay desembarques pendientes”** --- ### 9. Obtener nombres de remitentes Consulta `emp_persona` usando los DNIs encontrados: Reemplaza el DNI por nombre completo. --- ### ✔ 10. Respuesta Final Devuelve toda la data procesada. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de ordenes", "data": [ { "ose_id": 202525, "fecha": "2025-02-15 10:30:00", "monto": 45.50, "guia": "GUIA-882233", "remitente": "Carlos Gómez", "destinatario": "Empresa ABC", "tipo_pago": "CR", "origen": "LIMA", "destino": "AREQUIPA", "ruta": "LIM - AQP", "cap_id": 33112, "contenido": "10 CAJA, 2 SOBRE", "cant_paq": 5, "cant_total": 12, "desembarque_guia": "SIN GUIA", "usuario": "jperez" } ]}`
--- # ❗ **Posibles Errores** ### 1. No envía `cap_id`
`{ "success": false, "message": "Es obligatorio enviar un cap_id"}`
### 2. No hay embarques
`{ "success": false, "message": "Aun nó se ha embarcado nada en esta unidad."}`
### 3. No hay órdenes
`{ "success": false, "message": "No ha embarcado nada aun"}`
### 4. No hay desembarques pendientes
`{ "success": false, "message": "No hay desembarques pendientes"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_embarque\_historial**
`{ "emb_ose_id": "number", "emb_estado_guia": "string", "emb_cant_paquetes_embarcados": "string", "emb_cant_paquetes_total": "number"}`
### **emp\_desembarque\_historial**
`{ "des_ose_id": "number", "des_estado_guia": "string", "des_cant_paquetes_desembarcados": "string", "des_cant_paquetes_total": "number"}`
### **emp\_ordenservicio** Campos usados:
`{ "ose_id": "number", "ose_fhpreferenciapartida": "datetime", "ose_nroguiacliente": "string", "ose_remiteempresa": "string", "ose_destinaempresa": "string", "ose_servpagotipo": "string", "ose_termorigenatencion": "number", "ose_termdestinoentrega": "number", "ose_estadoPago": "number"}`
### **emp\_os\_detalle**
`{ "osd_osid": "number", "osd_tipopreciomanual": "string", "cantidad": "number"}`
### **emp\_atributos**
`{ "valor": "string", "abreviatura": "string"}`
### **emp\_persona**
`{ "documento": "string", "nombre": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !cap_id -> errorembarques = SELECT embarques WHERE cap_id = inputif empty -> errordesembarques = SELECT desembarques WHERE cap_id = inputose_ids = embarques.ose_idordenes = SELECT OS WHERE ose_id in ose_ids FILTER guia IF EXISTS PAGINACIONif empty -> errordetalles = SELECT SUM(cantidad), tipo FROM emp_os_detalle WHERE ose_id in ose_ids GROUP BY ose_id,tipoatributos = SELECT mapa tipo_pago -> abreviaturaterminales = SELECT terminal_id -> nombre, aliasbuild lista: para cada OS: calcular paquetes pendientes si 0 → excluir traducir tipo_pago generar ruta origen/destino agregar contenido y totalesif lista vacía -> “No hay desembarques pendientes”buscar nombres remitente en emp_personareturn lista final`