iCarryUP Routing System — API-Dokumentation

Öffentliche / Partner-Dokumentation Diese Version richtet sich an Kunden und Partner zur API-Integration. Einige Abschnitte für Administratoren (Benutzerverwaltung, Tarife, Infrastrukturdetails) sind nicht enthalten.

Basis-URL und Umgebungen

Endpunkte sind versioniert unter /api/v1. Immer HTTPS verwenden.

Umgebung	Basis-URL	Hinweise
Produktion	`https://flow.icarry.it`	Verbunden mit echter Flotte und von iCarryUP geplanten Jobs.

In dieser Partner-Version werden keine Links zu Swagger/ReDoc angezeigt. Der Zugriff auf /api/docs, /api/redoc und /openapi.json ist nur Superadmins vorbehalten (andere Konten erhalten 403). Für Partner ist die Endpoint-Liste auf dieser Seite die Referenz.

Authentifizierung

Die API verwendet JWT-Tokens mit Bearer. Erhalten Sie das Token durch Senden von Anmeldedaten an den OAuth2-Token-Endpunkt.

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

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

Das zurückgegebene Token muss im Header gesendet werden:

Authorization: Bearer <ACCESS_TOKEN>

⚠️ Setzen Sie server-seitige Token-Rotation alle 24h oder geplantes Refresh. Für Server-zu-Server-Integrationen erstellen Sie dedizierte technische Benutzer (Rolle: system).

Empfohlener Workflow

Laden Sie Logistikdaten (Fahrer + Lieferungen) im erwarteten Format von RoutingOptimizationRequest.
Senden Sie POST /api/v1/routing/optimize mit async_processing=true; erhalten Sie eine job_id.
Überwachen Sie den Status via GET /api/v1/routing/jobs/{job_id} (Polling 5-10s) oder via WebSocket /ws/jobs.
Bei status=completed lesen Sie result, exportieren Sie Dateien oder generieren Sie Karten mit dedizierten Endpunkten.
Optional: Setzen Sie webhook_url in der Anfrage für Push-Callbacks (Payload identisch mit result).

Kritische Endpunkte

POST /api/v1/routing/optimize

Übermittelt eine neue Optimierung. Unterstützt moderne und Legacy-Payloads (automatische Konvertierung von lat/lng zu 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
  }
}

Sofortige Antwort:

{
  "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 (Locker-Abholung): Hat der Benutzer nicht die Plan-Feature gel_proximity (Tenant mit GEL auf Karte + Flag in Tier/Profil), entfernt das Backend still pickup_point_id aus Lieferungen und gel_cost_to_time_equivalent_minutes_per_eur aus optimization_params vor der Optimierung.

Welches Ziel senden

Dieselben vier Werte wie im Konsolen-Assistenten. Das Feld ist optimization_objective bei POST /api/v1/routing/optimize. Standard ist time. Ein unbekannter Wert wird als time behandelt. Sie existieren, weil eine einzige Zahl nicht zugleich die kürzeste, die pünktlichste und die günstigste Tour sein kann.

Weniger Zeit `time`

WarumOhne dieses Ziel kann eine kilometerkurze Tour Empfänger warten lassen. Wartezeit wird bestraft und Zeitfenster werden gefüllt.

WannNutzen bei SLA, engen Zeitfenstern oder zugesagten Ankunftszeiten.

Weniger km `distance`

WarumWenn Kilometer zählen, nicht die Uhr. Wartezeit wird nicht bestraft.

WannNutzen wenn Kraftstoff und Maut dominieren, Stopps weit auseinander liegen oder Zeitfenster selten sind.

Ausgewogen `balanced`

WarumKompromiss zwischen Zeit und Kilometern, ohne ein Extrem zu erzwingen.

WannNutzen bei gemischter Flotte oder einem normalen Tag.

Weniger Kosten `cost`

WarumRechnet Kilometer und Stunden in Euro um, mit den Fahrerfeldern hourly_cost, fuel_consumption, prezzo_litro und costo_pedaggio_km.

WannNutzen für ein Flottenbudget oder einen Kostenvergleich. budget_max_eur in optimization_params ist die Obergrenze, nicht dieses Ziel.

Das ist nicht balance_options: das verteilt die Last auf die Fahrer (ähnliche Stoppzahl, km oder Minuten). Die Gewichte distance_weight, time_weight und balance_weight in optimization_params sind Feintuning; für die Integration reicht optimization_objective.

{
  "optimization_objective": "time"
}

Ersetzen Sie time durch distance, balanced oder cost. Die übrigen Felder der Optimize-Anfrage bleiben wie im Beispiel.

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

Gibt Status, Fortschritt und bei Abschluss die vollständige RoutingResultResponse (Routen, Geometrien, globale Metriken) zurück. Ergebnisse werden in gemeinsamem Cache persistiert und während geplanter Wartung gelöscht.

Im abgeschlossenen Ergebnis kann savings_report enthalten sein: geschätzte Einsparung (km/Zeit/Kosten) gegenüber einer Nearest-Neighbor-Baseline desselben Jobs.

GET /api/v1/routing/jobs

Listet die letzten Jobs des Benutzers. Akzeptiert ?limit=50 und ?status=processing/completed... für operative Dashboards.

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

Bricht Jobs in Warteschlange oder Ausführung ab. Gibt 400 zurück wenn Job bereits abgeschlossen.

GET /api/v1/routing/eta

Schätzt die Wall-Clock-Dauer der Optimierung (Sekunden) aus ähnlichen historischen Runs (P50/OLS) oder dem TSP-Budget. Typische Query-Parameter: deliveries, drivers, algorithm, routing_provider, has_time_windows, pickup_count, optimization_objective.

GET /api/v1/routing/history

Persistente Optimierungshistorie für Benutzer/Tenant (Simulationen optional ausgeschlossen). Unterstützt q= zur Suche nach Name oder job_id. Nützlich für Dashboards und Audit.

GET /api/v1/routing/calendar

Kalenderereignisse (geplante Runs und Entwürfe) für einen Datumsbereich. Speist die Kalenderansicht der Konsole.

GET /api/v1/routing/status

Angereicherter Health-Check (aktive Jobs, Version, Uptime). Kann für Monitoring-Systeme oder Readiness-Probes verwendet werden.

Das Feld algorithms_available ist Administratorkonten vorbehalten; für alle anderen ist es immer ein leeres Array.

POST /api/v1/routing/simulate

Startet eine What-if-Simulation (Control Tower) aus einem Baseline-Job. Gibt eine simulation_id zurück; das Ergebnis ist ein Optimierungsjob mit 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" }
  ]
}

Unterstützte Patches: add_delivery (auch Abholung mit point_type=pickup und pickup_point_id), remove_delivery, add_driver, remove_driver, delivery_time_window, balance_options, invalidate_matrices. baseline_scope=PLANNED (LIVE in v1 nicht unterstützt).

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

Gibt Metadaten und Vergleich der Simulation zurück (Baseline vs What-if-Ergebnis).

POST /api/v1/routing/estimate-workload

Schätzt den Arbeitsbedarf (Minuten/Fahrer) vor der Flottenwahl. mode=quick (schnelle Heuristik) oder precise (Solver mit virtueller Flotte).

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

KPI zur Lieferausführung (z. B. Pünktlichkeit %) aggregiert über die letzten Jobs des Benutzers.

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

Detail der Lieferausführung und Proof of Delivery (POD) für einen einzelnen Job.

POST /api/v1/routing/manual-assignments

Ermöglicht Lieferungen → Fahrer vor dem Start der Optimierung festzulegen. GET/DELETE /manual-assignments Endpunkte ermöglichen Lesen/Zurücksetzen von Präferenzen.

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

Erstellt persistente HTML-Karten (Ordner web/static/maps) bereit für die Verteilung an Fahrer. GET .../download-map und GET .../export generieren Karten bzw. Excel.

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

Erzeugt Straßen-Geometrien für einen abgeschlossenen Job (JWT erforderlich). Optionaler If-Match-Header mit routes_version_hash; Abweichung → 409 routes_version_mismatch — ohne Header erneut versuchen (Geometrien kommen aus dem gespeicherten Job).

GET /api/v1/routing/driver-maps

Listet Fahrerkarten des aktuellen Tenants (JWT erforderlich; 401 ohne Token). Superuser ohne Impersonation kann alle Tenants sehen.

Geocoding (authentifiziert)

JWT erforderlich. POST /optimize geokodiert nicht: numerische lat/lng im JSON bleiben Pflicht. Diese Endpunkte zuerst aufrufen. source ist ein Diagnose-Label, kein Vertrag.

POST /api/v1/geocoding/lookup

Nur Cache, höchstens 500 Adressen. hit false = nicht im Cache (forward nutzen). Startet keine externe Auflösung.

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

Löst bis zu 10 Adressen (raw + query). origin: api (Standard), wizard, mobile, one_driver, simulator, rubrica. Budget etwa 25 Sekunden. status: ok, not_found, pending (denselben Aufruf wiederholen), 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=

Eine Adresse, derselbe Resolver wie forward. 200 mit lat/lng; 400 wenn address fehlt; 404 ohne Treffer; 503 wenn die Auflösung noch pending ist.

GET /api/reverse_geocode?lat=&lng=

Koordinaten zu Adresse. 200 { address, source }; 400 wenn lat oder lng fehlt; 404 ohne Treffer.

Koordinaten-Pins Enterprise

Enterprise: Adressen und Koordinaten speichern. Tenant-Pins haben Vorrang bei Lookup/Forward. Optionale Auto-Erfassung aus POST /optimize.

POST /api/v1/geocoding/pins

Upsert bis 500 Pins. Gleiche Rolle wie DELETE und PUT settings: Owner, Admin oder Superuser, plus Feature geocode_pins. Ein Member erhält 403 owner_or_admin_required. Jedes results-Element hat index, status, pin_id, address_key, error.

status: created (neu), updated (gleiche Adresse, Koordinaten um mindestens 5 m verschoben), unchanged (Verschiebung unter 5 m), rejected (error: invalid_address, invalid_coordinates, zero_coordinates, swapped_lat_lng, out_of_area), limit_reached (Pin-Limit des Tenants). summary zählt dieselben Werte.

address_key nutzt dieselbe Normalisierung wie Lookup und Forward: Unicode NFKC, Kleinbuchstaben, zusammengezogene Leerzeichen, Kommas als „, “, führende und nachgestellte Leerzeichen und Kommas entfernt, maximal 500 Zeichen. Dieselbe Zeichenkette bei POST und Lookup findet den Pin: den zurückgegebenen Wert verwenden. Hausnummer, PLZ oder zusätzliche Wörter ändern den Schlüssel; Großschreibung und doppelte Leerzeichen nicht.

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

Pin-Liste für alle mit dem Feature (q ab 3 Zeichen, external_id, limit, after_id).

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

Pin im eigenen Tenant löschen. Nur Owner, Admin oder Superuser. Der Pin eines anderen Tenants liefert 404.

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

GET (Feature): enabled, auto_capture, count, max_pins. PUT (Owner/Admin): Pflichtkörper { "auto_capture": true|false }. PUT-Antwort: enabled, auto_capture, max_pins.

{ "auto_capture": true }