Envios

Estados del envio

Un envio pasa por un ciclo de vida completo desde que se crea hasta que se entrega:

pending → picked → in_transit → delivered → POD_signed
                                     ↘ returned

Estado	Descripcion
pending	Pendiente de preparacion. Sin asignar a ruta.
picked	Mercancia recogida del almacen, lista para envio.
in_transit	En camino hacia el destino.
delivered	Entregado al destinatario. Esperando firma de POD.
POD_signed	Pod de entrega firmado. Envio completado.
returned	Devuelto (por rechazo, direccion incorrecta, etc.)

---

Modelo de envio

interface Shipment {
  id: string;
  shipment_number: string;       // Numero de envio (ej: ENV-2026-0001)
  route_id?: string;
  vehicle_id?: string;
  driver_id?: string;
  status: ShipmentStatus;
  sender: {
    company_name: string;
    address: Address;
    contact: Contact;
  };
  recipient: {
    company_name: string;
    address: Address;
    contact: Contact;
    recipient_name?: string;     // Quien recibe fisicamente
  };
  packages: ShipmentPackage[];
  total_weight?: number;         // Peso total en kg
  total_volume?: number;         // Volumen total en m3
  shipping_date?: string;
  estimated_delivery_date?: string;
  actual_delivery_date?: string;
  carrier_id?: string;
  tracking_number?: string;
  notes?: string;
  POD_url?: string;              // URL del PDF de prueba de entrega
  created_by: string;
  created_at: string;
}

interface ShipmentPackage {
  package_id: string;
  barcode: string;
  description: string;
  weight: number;
  dimensions?: { width: number; height: number; depth: number };
  quantity: number;
}

---

Endpoints

Listar envios

GET /api/logistics/shipments
GET /api/logistics/shipments?status=pending
GET /api/logistics/shipments?route_id=route_001
GET /api/logistics/shipments?date_from=2026-05-01&date_to=2026-05-31
Authorization: Bearer <token>

Crear envio

POST /api/logistics/shipments
Authorization: Bearer <token>
Content-Type: application/json

{
  "route_id": "route_001",
  "sender": {
    "company_name": "Almacen central",
    "address": { "street": "Calle仓储 12", "city": "Madrid", "postal_code": "28001", "country": "ES" },
    "contact": { "name": "Juan Almacenero", "phone": "+34612345678" }
  },
  "recipient": {
    "company_name": "Acme S.L.",
    "address": { "street": "Avenida Industrial 45", "city": "Barcelona", "postal_code": "08001", "country": "ES" },
    "contact": { "name": "Maria Reception", "phone": "+34698765432", "email": "recepcion@acme.com" }
  },
  "packages": [
    { "barcode": "PKG-001", "description": "Pedido 1234", "weight": 2.5 }
  ],
  "shipping_date": "2026-05-08",
  "estimated_delivery_date": "2026-05-09"
}

Ver envio

GET /api/logistics/shipments/:id

Cambiar estado

POST /api/logistics/shipments/:id/status
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "in_transit",
  "timestamp": "2026-05-08T10:00:00Z",
  "location": "Autopista A-2 km 45",
  "notes": "Salida a las 10:00"
}

Asignar a ruta

PATCH /api/logistics/shipments/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "route_id": "route_001",
  "vehicle_id": "veh_001",
  "driver_id": "emp_010"
}

Prueba de entrega (POD)

POST /api/logistics/shipments/:id/pod
Content-Type: application/json

{
  "recipient_name": "Carlos Perez",
  "recipient_dni": "12345678B",
  "signature_data": "data:image/png;base64,...",
  "photo_url": "/storage/pod/POD-001.jpg",
  "notes": "Dejado en recepcion"
}

Genera el PDF del POD (prueba de entrega) y lo adjunta al envio.

---

Resumen de endpoints

Metodo	Ruta	Descripcion
GET	/api/logistics/shipments	Listar envios
POST	/api/logistics/shipments	Crear envio
GET	/api/logistics/shipments/:id	Ver envio
PATCH	/api/logistics/shipments/:id	Actualizar envio
POST	/api/logistics/shipments/:id/status	Cambiar estado
POST	/api/logistics/shipments/:id/pod	Registrar POD
GET	/api/logistics/shipments/:id/pdf	Descargar POD PDF