iCarryUP Routing System — Documentación API

Documentación pública / partner Esta versión está pensada para clientes y socios que integran las API. Algunas secciones reservadas a administradores (gestión de usuarios, planes, detalles de infraestructura) no están incluidas.

URL Base y entornos

Los endpoints están versionados bajo /api/v1. Use siempre HTTPS.

Entorno	URL Base	Notas
Producción	`https://flow.icarry.it`	Conectado a la flota real y trabajos programados por iCarryUP.

En esta versión para socios no se muestran enlaces a Swagger ni ReDoc. El acceso a /api/docs, /api/redoc y /openapi.json está restringido solo a superadministradores (el resto recibe 403). Para socios, la referencia es el listado de endpoints de esta página.

Autenticación

La API utiliza tokens JWT con esquema Bearer. Obtenga el token enviando credenciales al endpoint OAuth2.

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=OPS_USER&password=********

El token devuelto debe enviarse en el header:

Authorization: Bearer <ACCESS_TOKEN>

⚠️ Configure rotación de token server-side cada 24h o use refresh programados. Para integraciones server-to-server, cree usuarios técnicos dedicados (rol: system).

Flujo de trabajo recomendado

Cargue datos logísticos (conductores + entregas) en el formato esperado por RoutingOptimizationRequest.
Envíe POST /api/v1/routing/optimize con async_processing=true; reciba un job_id.
Monitoree el estado vía GET /api/v1/routing/jobs/{job_id} (polling 5-10s) o vía WebSocket /ws/jobs.
Cuando status=completed lea result, exporte archivos o genere mapas con los endpoints dedicados.
Opcional: configure webhook_url en la solicitud para recibir callbacks push (payload idéntico a result).

Endpoints críticos

POST /api/v1/routing/optimize

Envía una nueva optimización. Soporta payloads modernos y legacy (conversión automática de lat/lng a start_lat, etc.).

{
  "async_processing": true,
  "session_id": "tms-session-example-001",
  "webhook_url": "https://your-tms.example.com/webhooks/routing",
  "delivery_points": [
    {
      "tracking_number": "SHIP-EXAMPLE-0001",
      "delivery_company": "Example SpA",
      "address": "Via Esempio 1, Milano",
      "lat": 45.4642,
      "lng": 9.1900,
      "tot_items": 4,
      "priority": 1
    }
  ],
  "drivers": [
    {
      "name": "Driver example 01",
      "start_lat": 45.5342,
      "start_lng": 9.3265,
      "end_lat": 45.5342,
      "end_lng": 9.3265,
      "capacity": 90,
      "vehicle_type": "van_standard",
      "max_distance_km": 220
    }
  ],
  "algorithms": ["standard"],
  "optimization_objective": "time",
  "optimization_params": {
    "max_iterations": 120,
    "time_limit_seconds": 420,
    
    "distance_weight": 0.5,
    "time_weight": 0.3,
    "balance_weight": 0.2
    
  },
  "constraints": {
    "max_route_distance": 250,
    "max_route_duration": 480,
    "max_stops_per_route": 45
  }
}

Respuesta inmediata:

{
  "job_id": "6b758bee-65e5-473e-add8-8cecc36f6fda",
  "status": "queued",
  "estimated_completion": "2025-11-26T09:11:37.123Z",
  "result_url": "/api/v1/routing/jobs/6b758bee-65e5-473e-add8-8cecc36f6fda"
}

GEL (recogida en locker): si el usuario no tiene la feature de plan gel_proximity (tenant con GEL en mapa + flag en tier/perfil), el backend elimina en silencio pickup_point_id de las entregas y gel_cost_to_time_equivalent_minutes_per_eur de optimization_params antes de optimizar.

Qué objetivo enviar

Los mismos cuatro valores del asistente de la consola. El campo es optimization_objective en POST /api/v1/routing/optimize. El predeterminado es time. Un valor desconocido se trata como time. Existen porque un solo número no puede ser a la vez el recorrido más corto, el más puntual y el más barato.

Menos tiempo `time`

Por quéSin este objetivo, un recorrido corto en km puede hacer esperar a los destinatarios. Penaliza la espera y llena las franjas horarias.

CuándoÚselo con SLA, ventanas estrechas o horas prometidas.

Menos km `distance`

Por quéCuando cuentan los kilómetros, no el reloj. La espera no se penaliza.

CuándoÚselo si dominan combustible y peajes, las paradas están dispersas o hay pocas franjas.

Equilibrado `balanced`

Por quéCompromiso entre tiempo y kilómetros, sin forzar un extremo.

CuándoÚselo con flota mixta o un día normal.

Menos costes `cost`

Por quéConvierte kilómetros y horas en euros con los campos del conductor: hourly_cost, fuel_consumption, prezzo_litro y costo_pedaggio_km.

CuándoÚselo para un presupuesto de flota o una comparación económica. budget_max_eur en optimization_params es el tope, no este objetivo.

No es balance_options: eso reparte la carga entre conductores (número de paradas, km o minutos parecidos). Los pesos distance_weight, time_weight y balance_weight en optimization_params son un ajuste fino; para la integración basta optimization_objective.

{
  "optimization_objective": "time"
}

Sustituya time por distance, balanced o cost. El resto de la petición optimize sigue como en el ejemplo.

GET /api/v1/routing/jobs/{job_id}

Devuelve estado, progreso y, si completado, el RoutingResultResponse completo (rutas, geometrías, métricas globales). Los resultados se persisten en caché compartida y se eliminan durante el mantenimiento programado.

En el resultado completado puede aparecer savings_report: ahorro estimado (km/tiempo/coste) frente a una baseline nearest-neighbor del mismo job.

GET /api/v1/routing/jobs

Lista los últimos jobs del usuario. Acepta ?limit=50 y ?status=processing/completed... para dashboards operativos.

DELETE /api/v1/routing/jobs/{job_id}

Cancela jobs en cola o en ejecución. Devuelve 400 si el job ya está completado.

GET /api/v1/routing/eta

Estima la duración wall-clock de la optimización (segundos) a partir de runs históricos similares (P50/OLS) o del presupuesto TSP. Query típicas: deliveries, drivers, algorithm, routing_provider, has_time_windows, pickup_count, optimization_objective.

GET /api/v1/routing/history

Historial persistente de optimizaciones del usuario/tenant (excluye simulaciones si se solicita). Admite q= para buscar por nombre o job_id. Útil para dashboards y auditoría.

GET /api/v1/routing/calendar

Eventos de calendario (runs planificados y borradores) para un intervalo de fechas. Alimenta la vista calendario de la consola.

GET /api/v1/routing/status

Health-check enriquecido (jobs activos, versión, uptime). Puede usarse para sistemas de monitoreo o readiness probes.

El campo algorithms_available está reservado a cuentas administrativas; para el resto es siempre un array vacío.

POST /api/v1/routing/simulate

Inicia una simulación what-if (Control Tower) a partir de un job baseline. Devuelve un simulation_id; el resultado es un job de optimización con is_simulation=true.

{
  "baseline_job_id": "6b758bee-65e5-473e-add8-8cecc36f6fda",
  "baseline_scope": "PLANNED",
  "simulation_mode": "reoptimize",
  "patches": [
    {
      "type": "add_delivery",
      "point_type": "delivery",
      "lat": 41.9028,
      "lng": 12.4964,
      "tracking_number": "NEW-001",
      "pickup_point_id": "HUB-1"
    },
    { "type": "remove_delivery", "tracking_number": "OLD-042" }
  ]
}

Parches soportados: add_delivery (también recogidas con point_type=pickup y pickup_point_id), remove_delivery, add_driver, remove_driver, delivery_time_window, balance_options, invalidate_matrices. baseline_scope=PLANNED (LIVE no soportado en v1).

GET /api/v1/routing/simulations/{simulation_id}

Devuelve metadatos y comparación de la simulación (baseline vs resultado what-if).

POST /api/v1/routing/estimate-workload

Estima la carga de trabajo (minutos/conductores) antes de elegir la flota. mode=quick (heurística rápida) o precise (solver con flota virtual).

GET /api/v1/routing/delivery-execution/summary

KPI de ejecución de entregas (p. ej. puntualidad %) agregado sobre los últimos jobs del usuario.

GET /api/v1/routing/jobs/{job_id}/delivery-execution

Detalle de ejecución de entregas y prueba de entrega (POD) para un job concreto.

POST /api/v1/routing/manual-assignments

Permite fijar entregas → conductor antes de lanzar la optimización. Los endpoints GET/DELETE /manual-assignments permiten leer/reiniciar preferencias.

POST /api/v1/routing/jobs/{job_id}/generate-real-map

Crea mapas HTML persistentes (carpeta web/static/maps) listos para distribución a conductores. GET .../download-map y GET .../export generan mapas y Excel respectivamente.

POST /api/v1/routing/jobs/{job_id}/generate-geometries

Genera geometrías de carretera para un job completado (JWT obligatorio). Header opcional If-Match con routes_version_hash; mismatch → 409 routes_version_mismatch — reintentar sin header (las geometrías vienen del job guardado).

GET /api/v1/routing/driver-maps

Lista mapas de conductores del tenant actual (JWT obligatorio; 401 sin token). Superusuario sin impersonación puede ver todos los tenants.

Geocoding (autenticado)

JWT obligatorio. POST /optimize no geocodifica: lat/lng numéricos en el JSON siguen siendo obligatorios. Llame antes a estos endpoints. source es una etiqueta de diagnóstico, no un contrato.

POST /api/v1/geocoding/lookup

Solo caché, máximo 500 direcciones. hit false = no está en caché (use forward). No inicia una resolución externa.

{
  "addresses": ["Via Roma 1, Milano", "Piazza Duomo, Firenze"]
}

{
  "results": [
    { "index": 0, "hit": true, "lat": 45.46, "lng": 9.19, "source": "…", "low_confidence": false, "cache_id": 12 },
    { "index": 1, "hit": false, "lat": null, "lng": null, "source": null, "low_confidence": null, "cache_id": null }
  ]
}

POST /api/v1/geocoding/forward

Resuelve hasta 10 direcciones (raw + query). origin: api (por defecto), wizard, mobile, one_driver, simulator, rubrica. Presupuesto de unos 25 segundos. status: ok, not_found, pending (repita la misma llamada), error.

{
  "origin": "api",
  "items": [{ "raw": "Via Roma 1, Milano", "query": "Via Roma 1, Milano" }]
}

{
  "results": [
    {
      "status": "ok",
      "lat": 45.46,
      "lng": 9.19,
      "confidence": 90,
      "matched": true,
      "low_confidence": false,
      "source": "…",
      "cache_id": 12
    }
  ]
}

GET /api/geocode_address?address=

Una sola dirección, el mismo resolver que forward. 200 con lat/lng; 400 si falta address; 404 si no hay resultado; 503 si la resolución sigue pending.

GET /api/reverse_geocode?lat=&lng=

De coordenadas a dirección. 200 { address, source }; 400 si falta lat o lng; 404 si no hay resultado.

Pines de coordenadas Enterprise

Plan Enterprise: guarda direcciones y coordenadas. Los pines del tenant tienen prioridad en lookup/forward. Captura opcional desde POST /optimize.

POST /api/v1/geocoding/pins

Upsert de hasta 500 pines. Mismo rol que DELETE y PUT settings: owner, admin o superuser, además de la feature geocode_pins. Un member recibe 403 owner_or_admin_required. Cada elemento de results tiene index, status, pin_id, address_key, error.

status: created (nuevo), updated (misma dirección, coordenadas movidas al menos 5 m), unchanged (movimiento inferior a 5 m), rejected (error: invalid_address, invalid_coordinates, zero_coordinates, swapped_lat_lng, out_of_area), limit_reached (tope de pines del tenant). summary usa los mismos conteos.

address_key usa la misma normalización que lookup y forward: Unicode NFKC, minúsculas, espacios comprimidos, comas como «, », espacios y comas de los extremos eliminados, máximo 500 caracteres. La misma cadena en POST y en lookup encuentra el pin: use el valor devuelto. Cambian la clave el número, el código postal o palabras extra; no la cambian mayúsculas ni espacios dobles.

{
  "items": [
    { "address": "Via Roma 1, 20121 Milano MI", "lat": 45.46, "lng": 9.19, "external_id": "CLI-1" }
  ]
}

{
  "results": [
    { "index": 0, "status": "created", "pin_id": 12, "address_key": "via roma 1, 20121 milano mi", "error": null }
  ],
  "summary": { "created": 1, "updated": 0, "unchanged": 0, "rejected": 0, "limit_reached": 0 }
}

GET /api/v1/geocoding/pins

Lista de pines para quien tenga la feature (q desde 3 caracteres, external_id, limit, after_id).

DELETE /api/v1/geocoding/pins/{pin_id}

Elimina un pin del propio tenant. Solo owner, admin o superuser. El pin de otro tenant responde 404.

GET / PUT /api/v1/geocoding/pins/settings

GET (feature): enabled, auto_capture, count, max_pins. PUT (owner/admin): cuerpo obligatorio { "auto_capture": true|false }. Respuesta PUT: enabled, auto_capture, max_pins.

{ "auto_capture": true }