Ordini dentro. Percorsi fuori.
Invii lavori dal sistema che già usa e riceva un percorso sequenziato con i suoi identificativi intatti. Tre endpoint, nessun SDK necessario.
Tre chiamate, e la superficie finisce qui
| Verbo | Percorso | Scopo |
|---|---|---|
| POST | /v1/integration-token | Scambiare le credenziali client con un token bearer, valido un’ora |
| POST | /v1/integration-import | Importare un lavoro con le sue fermate, geocodificare gli indirizzi, ottimizzare il percorso e assegnare l’autista — in una sola richiesta |
| GET | /v1/integration-jobs | Stato del lavoro e delle fermate: conteggi di avanzamento, stato per fermata, l’ordine ottimizzato |
Importare, geocodificare, ottimizzare, assegnare
POST /v1/integration-import HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
{
"external_job_id": "WMS-2026-07-30-A",
"driver_email": "driver@fleet.com.au",
"optimize": true,
"stops": [
{ "external_stop_id": "SO-88214",
"address": "3/216 Brunswick St, Fitzroy VIC 3065",
"parcel_count": 2,
"duration_minutes": 4 }
]
}{
"job_id": "job_7Yq2c",
"external_job_id": "WMS-2026-07-30-A",
"assigned_to": "driver@fleet.com.au",
"optimized": true,
"stops_imported": 142,
"stops": [
{ "external_stop_id": "SO-88214",
"stop_id": "stp_9f2",
"sequence": 38,
"status": "pending" }
],
"warnings": []
}I suoi identificativi restano
Ogni identificativo che invia torna in uscita, sul lavoro e su ogni fermata. Non deve mai tenere una tabella di corrispondenza fra i suoi numeri d’ordine e i nostri.
| external_job_id | Il suo riferimento di lotto — torna su ogni fermata, così non le serve una tabella di corrispondenza |
| external_stop_id | Il suo numero d’ordine o di spedizione, portato fino allo stato e alla chiusura |
| address | Una sola riga di indirizzo; geocodificata all’import, gli errori tornano come avvisi |
| parcel_count | Usato per le ipotesi di carico e movimentazione sulla fermata |
| duration_minutes | Tempo di servizio alla porta — consumato nel modello, non dato per scontato |
| driver_email | Assegna il percorso finito a un autista già presente sull’account |
Cosa fa quando qualcosa va storto
Scritture idempotenti
Reimportare lo stesso external_job_id aggiorna il lavoro invece di crearne un secondo. Riprovare dopo un timeout è sicuro.
Successo parziale
Una fermata che non si riesce a geocodificare torna in warnings[] mentre il resto del lavoro viene importato. La richiesta non fallisce per intero perché un indirizzo è sbagliato.
Versionamento
La versione sta nel percorso. Dentro una versione i campi si aggiungono, ma non vengono mai rimossi o riutilizzati per altro, quindi un’integrazione scritta oggi continua a funzionare.
Le chiavi sandbox sono gratuite
Sviluppi contro una sandbox prima di impegnarsi. Ce lo chieda e le manderemo credenziali e un esempio svolto sul suo formato di dati.