iCarryUP Routing System — Documentation API

Documentation publique / partenaires Cette version est destinée aux clients et partenaires qui intègrent les API. Certaines sections réservées aux administrateurs (gestion des utilisateurs, tiers, détails d'infrastructure) ne sont pas incluses.

Base URL et environnements

Les endpoints sont versionnés sous /api/v1. Utilisez toujours HTTPS.

Environnement	Base URL	Notes
Production	`https://flow.icarry.it`	Connecté à la flotte réelle et aux jobs planifiés par iCarryUP.

Dans cette version (partenaires), les liens vers Swagger et ReDoc ne sont pas affichés. L'accès à /api/docs, /api/redoc et /openapi.json est réservé aux seuls superadmins (les autres comptes reçoivent un 403). Pour les partenaires, la liste des endpoints de cette page fait foi.

Authentification

L'API utilise des jetons JWT avec le schéma Bearer. Obtenez le jeton en envoyant les identifiants à l'endpoint token OAuth2.

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

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

Le jeton renvoyé doit être envoyé dans l'en-tête :

Authorization: Bearer <ACCESS_TOKEN>

⚠️ Mettez en place une rotation des jetons côté serveur toutes les 24 h ou utilisez des rafraîchissements programmés. Pour les intégrations serveur à serveur, il est recommandé de créer des utilisateurs techniques dédiés (rôle : system).

Workflow recommandé

Chargez les données logistiques (drivers + livraisons) au format prévu par RoutingOptimizationRequest.
Envoyez POST /api/v1/routing/optimize avec async_processing=true ; vous recevez un job_id.
Surveillez l'état via GET /api/v1/routing/jobs/{job_id} (polling 5-10 s) ou via WebSocket /ws/jobs.
Lorsque status=completed, lisez result, exportez les fichiers ou générez des cartes avec les endpoints dédiés.
Optionnel : définissez webhook_url dans la requête pour recevoir un callback push (payload identique à result).

Endpoints critiques

POST /api/v1/routing/optimize

Soumet une nouvelle optimisation. Prend en charge les payloads modernes et legacy (conversion automatique de lat/lng en 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
  }
}

Réponse immédiate :

{
  "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 (pickup locker) : si l'utilisateur n'a pas la fonctionnalité de plan gel_proximity (tenant avec GEL sur carte + flag sur le tier/profil), le backend retire silencieusement pickup_point_id des livraisons et gel_cost_to_time_equivalent_minutes_per_eur de optimization_params avant l'optimisation.

Quel objectif choisir

Les quatre mêmes valeurs que dans l'assistant de la console. Le champ est optimization_objective sur POST /api/v1/routing/optimize. La valeur par défaut est time. Une valeur inconnue est traitée comme time. Ils existent parce qu'un seul chiffre ne peut pas être à la fois la tournée la plus courte, la plus ponctuelle et la plus économique.

Moins de temps `time`

PourquoiSans cet objectif, une tournée courte en km peut faire attendre les destinataires. Pénalise l'attente et remplit les créneaux horaires.

QuandUtilisez-le avec des SLA, des fenêtres serrées ou des promesses horaires.

Moins de km `distance`

PourquoiUtile lorsque le kilométrage compte, pas l'horloge. L'attente n'est pas pénalisée.

QuandUtilisez-le si carburant et péages dominent, zones dispersées ou peu de créneaux horaires.

Équilibré `balanced`

PourquoiCompromis entre temps et kilomètres, sans pousser un extrême.

QuandUtilisez-le pour une flotte mixte ou une journée normale.

Moins de coûts `cost`

PourquoiConvertit kilomètres et heures en euros avec les champs du driver : hourly_cost, fuel_consumption, prezzo_litro, costo_pedaggio_km.

QuandUtilisez-le pour un budget de flotte ou une comparaison économique. budget_max_eur dans optimization_params est le plafond, pas cet objectif.

Ce n'est pas balance_options : celui-ci répartit la charge entre les livreurs (même nombre d'arrêts, km ou minutes). Les poids distance_weight, time_weight et balance_weight dans optimization_params sont un réglage fin ; pour l'intégration, optimization_objective suffit.

{
  "optimization_objective": "time"
}

Remplacez time par distance, balanced ou cost. Les autres champs de la requête restent ceux de l'exemple optimize.

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

Renvoie l'état, la progression et, s'il est terminé, l'ensemble du RoutingResultResponse (itinéraires, géométries, métriques globales). Les résultats sont persistés en cache partagé et supprimés lors de la maintenance programmée.

Dans le résultat terminé, le champ savings_report peut être présent : estimation d'économie (km/temps/coût) par rapport à une baseline nearest-neighbor sur le même job.

GET /api/v1/routing/jobs

Liste les derniers jobs de l'utilisateur courant. Accepte ?limit=50 et ?status=processing/completed... pour mettre en place des tableaux de bord opérationnels.

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

Annule un job en file d'attente ou en cours d'exécution. Si le travail est déjà terminé, renvoie une erreur 400.

GET /api/v1/routing/eta

Estime la durée wall-clock de l'optimisation (secondes) à partir de runs historiques similaires (P50/OLS) ou du budget TSP. Requêtes typiques : deliveries, drivers, algorithm, routing_provider, has_time_windows, pickup_count, optimization_objective.

GET /api/v1/routing/history

Historique des optimisations persistantes de l'utilisateur/tenant (exclut les simulations si demandé). Prend en charge q= pour rechercher par nom ou job_id. Utile pour les tableaux de bord et l'audit.

GET /api/v1/routing/calendar

Événements calendrier (runs planifiés et brouillons) pour un intervalle de dates. Alimente la vue calendrier de la console.

GET /api/v1/routing/status

Health-check enrichi (jobs actifs, version, uptime). Peut être utilisé pour les systèmes de monitoring ou les readiness probes.

Le champ algorithms_available est réservé aux comptes administratifs ; pour les autres, c'est toujours un tableau vide.

POST /api/v1/routing/simulate

Lance une simulation what-if (Control Tower) à partir d'un job baseline. Renvoie un simulation_id ; le résultat est un job d'optimisation marqué 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" }
  ]
}

Patches pris en charge : add_delivery (aussi retrait avec point_type=pickup et pickup_point_id), remove_delivery, add_driver, remove_driver, delivery_time_window, balance_options, invalidate_matrices. baseline_scope=PLANNED (LIVE non pris en charge en v1).

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

Renvoie les métadonnées et la comparaison de la simulation (baseline vs résultat what-if).

POST /api/v1/routing/estimate-workload

Estime le besoin de travail (minutes/driver) avant de choisir la flotte. mode=quick (heuristique rapide) ou precise (solveur avec flotte virtuelle).

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

KPI d'exécution des livraisons (ex. ponctualité %) agrégé sur les derniers jobs de l'utilisateur.

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

Détail d'exécution des livraisons et preuves de livraison (POD) pour un job unique.

POST /api/v1/routing/manual-assignments

Permet de fixer livraisons → driver avant de lancer l'optimisation. Les autres endpoints GET/DELETE /manual-assignments permettent la lecture/réinitialisation des préférences.

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

Crée des cartes HTML persistantes (dossier web/static/maps) prêtes à être distribuées aux drivers. GET .../download-map et GET .../export génèrent respectivement les cartes et Excel.

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

Génère les géométries routières pour un job terminé (JWT obligatoire). En-tête optionnel If-Match avec routes_version_hash ; mismatch → 409 routes_version_mismatch — réessayer sans en-tête (les géométries proviennent du job enregistré).

GET /api/v1/routing/driver-maps

Liste des cartes driver du tenant courant (JWT obligatoire ; 401 sans jeton). Un superuser sans impersonation peut voir tous les tenants.

Geocoding (authentifié)

JWT obligatoire. POST /optimize ne géocode pas : lat/lng numériques dans le JSON restent obligatoires. Appelez d’abord ces endpoints. source est une étiquette de diagnostic, pas un contrat.

POST /api/v1/geocoding/lookup

Cache uniquement, 500 adresses maximum. hit false = absent du cache (utilisez forward). Ne lance pas de résolution externe.

{
  "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

Résout jusqu’à 10 adresses (raw + query). origin : api (défaut), wizard, mobile, one_driver, simulator, rubrica. Budget d’environ 25 secondes. status : ok, not_found, pending (répétez le même appel), 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=

Une seule adresse, même résolveur que forward. 200 avec lat/lng ; 400 si address manque ; 404 sans résultat ; 503 si la résolution est encore pending.

GET /api/reverse_geocode?lat=&lng=

Coordonnées vers adresse. 200 { address, source } ; 400 si lat ou lng manque ; 404 sans résultat.

Pins coordonnées Enterprise

Plan Enterprise : stocker adresses et coordonnées. Les pins du tenant priment sur lookup/forward. Capture optionnelle depuis POST /optimize.

POST /api/v1/geocoding/pins

Upsert jusqu’à 500 pins. Même rôle que DELETE et PUT settings : owner, admin ou superuser, plus la feature geocode_pins. Un member reçoit 403 owner_or_admin_required. Chaque élément de results a index, status, pin_id, address_key, error.

status : created (nouveau), updated (même adresse, coordonnées déplacées d’au moins 5 m), unchanged (déplacement sous 5 m), rejected (error : invalid_address, invalid_coordinates, zero_coordinates, swapped_lat_lng, out_of_area), limit_reached (plafond de pins du tenant). summary reprend les mêmes compteurs.

address_key utilise la même normalisation que lookup et forward : Unicode NFKC, minuscules, espaces compressés, virgules rendues « , », espaces et virgules de bord retirés, 500 caractères max. La même chaîne en POST et en lookup trouve le pin : utilisez la valeur renvoyée. Le numéro, le code postal ou des mots en plus changent la clé ; pas la casse ni les espaces doubles.

{
  "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

Liste des pins pour qui a la feature (q à partir de 3 caractères, external_id, limit, after_id).

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

Supprime un pin du tenant. Owner, admin ou superuser uniquement. Le pin d’un autre tenant renvoie 404.

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

GET (feature) : enabled, auto_capture, count, max_pins. PUT (owner/admin) : corps obligatoire { "auto_capture": true|false }. Réponse PUT : enabled, auto_capture, max_pins.

{ "auto_capture": true }