6.9.1. Flujo actualiza despacho

Este documento migra el endpoint legacy:

POST /recoleccion_movil/ActualizaEstatusDespacho/update

Request (legacy):

{
  "CollActualizaEstatus": {
    "ActualizaEstatus": [
      {
        "p_control_interno": "",
        "p_employee_number": "119242",
        "p_evento": "En Transito",
        "p_latitud": "37.4219983",
        "p_longitud": "-122.084",
        "p_transferencia": "160105102"
      }
    ]
  }
}

Response (legacy):

{
  "CollTipoSalida": {
    "control_interno": "",
    "estatus": "OK"
  }
}

---

1) Nuevo servicio equivalente

Servicio: Dispatch Control Service (v1)
Base URL: https://api.alpura.mx/dispatch/v1
Endpoint: POST /dispatches/_update-status

1.1 Request (nuevo — compatible con el legacy)

POST /dispatch/v1/dispatches/_update-status
Content-Type: application/json

{
  "CollActualizaEstatus": {
    "ActualizaEstatus": [
      {
        "p_control_interno": "",
        "p_employee_number": "119242",
        "p_evento": "En Transito",
        "p_latitud": "37.4219983",
        "p_longitud": "-122.084",
        "p_transferencia": "160105102"
      }
    ]
  }
}

1.2 Response (nuevo — equivalente)

{
  "CollTipoSalida": {
    "control_interno": "",
    "estatus": "OK"
  }
}

El nuevo endpoint mantiene la estructura CollActualizaEstatus/ActualizaEstatus[] para facilitar la migración 1:1 desde el legacy.

---

2) Mapeo a Base de Datos

Tabla principal: ALP_RECOLECCION_VIAJES

Campo (request/response)	Columna BD	Comentario
p_control_interno	CONTROL_INTERNO	Clave del viaje a actualizar
p_evento	EVENTO	Nuevo estatus del despacho (ej. En Transito)
—	FECHA_EVENTO	Timestamp del cambio (servidor)
p_latitud / p_longitud	LATITUD / LONGITUD	Posición reportada
p_transferencia	ID_TRANSFERENCIA	Vincula con ALP_RECOLECCION_TRANSFERENCIAS si aplica
p_employee_number	LAST_UPDATED_BY (o columna auditoría equivalente)	Usuario/empleado que ejecuta el cambio
control_interno (resp)	CONTROL_INTERNO	Echo del control interno
estatus (resp)	—	Resultado de la operación de API

Si existe una tabla de bitácora (por ejemplo ALP_RECOLECCION_VIAJES_HIST), se recomienda insertar un renglón por cada actualización de estatus con EVENTO_ANTERIOR, EVENTO_NUEVO, COORDENADAS, USUARIO, FECHA.

---

3) SQL de referencia (Oracle/PostgreSQL)

-- Actualiza el estatus y coordenadas del viaje por control interno
UPDATE ALP_RECOLECCION_VIAJES
   SET EVENTO          = :p_evento,
       FECHA_EVENTO    = CURRENT_TIMESTAMP,       -- SYSDATE en Oracle
       LATITUD         = NULLIF(:p_latitud, ''),
       LONGITUD        = NULLIF(:p_longitud, ''),
       ID_TRANSFERENCIA= NULLIF(:p_transferencia, ''),
       LAST_UPDATE_DATE= CURRENT_TIMESTAMP,
       LAST_UPDATED_BY = :p_employee_number
 WHERE CONTROL_INTERNO = :p_control_interno;

-- (Opcional) Insert en bitácora/histórico de estatus
INSERT INTO ALP_RECOLECCION_VIAJES_HIST
  (CONTROL_INTERNO, EVENTO, FECHA_EVENTO, LATITUD, LONGITUD, ID_TRANSFERENCIA, EMPLOYEE_NUMBER, CREATED_AT)
VALUES
  (:p_control_interno, :p_evento, CURRENT_TIMESTAMP,
   NULLIF(:p_latitud, ''), NULLIF(:p_longitud, ''),
   NULLIF(:p_transferencia, ''), :p_employee_number, CURRENT_TIMESTAMP);

Ajusta CURRENT_TIMESTAMP a SYSDATE en Oracle o a la función de fecha de tu motor. Usa NULLIF para no sobreescribir con cadenas vacías.

---

4) Diagrama de Secuencia

---

5) Reglas y validaciones recomendadas

• Enum de p_evento: validar contra catálogo permitido (ej. Pendiente, En Transito, Arribó, Entregado, Cancelado).
• Coordenadas: validar rango (lat -90..90, lon -180..180).
• Transferencia: si se envía p_transferencia, validar existencia en ALP_RECOLECCION_TRANSFERENCIAS.
• Idempotencia: usar Idempotency-Key para evitar dobles updates por reintentos.
• Auditoría: registrar p_employee_number, X-Trace-Id y timestamp.

---