Rutas

Modelo de ruta

interface Route {
  id: string;
  route_number: string;       // "RUTA-2026-0001"
  name: string;               // "Ruta Barcelona Norte"
  date: string;              // Fecha de la ruta
  vehicle_id: string;
  driver_id: string;         // ID del empleado conductor
  status: 'planned' | 'in_progress' | 'completed' | 'cancelled';
  estimated_start_time: string;
  estimated_end_time: string;
  actual_start_time?: string;
  actual_end_time?: string;
  shipment_ids: string[];     // IDs de envios en esta ruta
  staging_area_id?: string;
  waypoints: Waypoint[];
  total_distance_km?: number;
  estimated_duration_minutes?: number;
  notes?: string;
  created_by: string;
  created_at: string;
}

interface Waypoint {
  order: number;
  shipment_id: string;
  address: Address;
  estimated_arrival?: string;
  actual_arrival?: string;
  sequence_verified?: boolean;  // El conductor confirma el orden
}

---

Endpoints

Método	Ruta	Descripción
GET	/api/logistics/routes	Listar rutas
POST	/api/logistics/routes	Crear ruta
GET	/api/logistics/routes/:id	Ver ruta
PATCH	/api/logistics/routes/:id	Actualizar ruta
POST	/api/logistics/routes/:id/start	Iniciar ruta
POST	/api/logistics/routes/:id/complete	Completar ruta
DELETE	/api/logistics/routes/:id	Eliminar ruta

Crear ruta

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

{
  "name": "Ruta Barcelona Norte - 8 mayo",
  "date": "2026-05-08",
  "vehicle_id": "veh_001",
  "driver_id": "emp_010",
  "shipment_ids": ["ship_001", "ship_002", "ship_003"],
  "staging_area_id": "sa_001",
  "estimated_start_time": "08:00",
  "estimated_duration_minutes": 360
}

El sistema calcula automáticamente:

• Waypoints ordenados por proximidad (geocodificación)
• Tiempo estimado de llegada a cada punto
• Distancia total de la ruta

Ver ruta con envíos

GET /api/logistics/routes/:id

{
  "data": {
    "id": "route_001",
    "vehicle": { "license_plate": "1234ABC", "type": "furgon" },
    "driver": { "name": "Carlos Conductor", "phone": "+34612345678" },
    "waypoints": [
      { "order": 1, "shipment": { "number": "ENV-2026-0001", "recipient": "Acme S.L.", "address": "C/ Industrial 45, Barcelona" } },
      { "order": 2, "shipment": { "number": "ENV-2026-0002", "recipient": "Beta S.A.", "address": "C/ Mayor 12, Barcelona" } }
    ],
    "total_shipments": 2,
    "staging_area": { "name": "Area A - Salida Norte" }
  }
}

---

Mapas y geocodificación

Keirost geocodifica automáticamente las direcciones de los envíos para:

• Calcular la ruta optima
• Mostrar el mapa en el driver app
• Rastrear la ubicación en tiempo real

Geocodificar dirección

POST /api/logistics/geocode
Content-Type: application/json

{
  "street": "Avenida Industrial 45",
  "city": "Barcelona",
  "postal_code": "08001",
  "country": "ES"
}

Respuesta:

{
  "lat": 41.3851,
  "lng": 2.1734,
  "formatted_address": "Avinguda Industrial, 45, 08001 Barcelona, Spain"
}

---

Resumen de endpoints

Método	Ruta	Descripción
GET	/api/logistics/routes	Listar rutas
POST	/api/logistics/routes	Crear ruta
GET	/api/logistics/routes/:id	Ver ruta con waypoints
PATCH	/api/logistics/routes/:id	Actualizar ruta
POST	/api/logistics/routes/:id/start	Iniciar ruta
POST	/api/logistics/routes/:id/complete	Completar ruta
POST	/api/logistics/routes/:id/reorder	Reordenar waypoints
DELETE	/api/logistics/routes/:id	Eliminar ruta
POST	/api/logistics/geocode	Geocodificar dirección