API Spedisci.online – versione 2026-09
Le API permettono di collegare il tuo gestionale, il tuo e-commerce o qualsiasi altro software alla piattaforma: tutto ciò che fai dal pannello per spedire lo puoi fare da codice.
La versione 2026-09 è la versione attuale. Usa l’autenticazione OAuth2 con credenziali dedicate (una App) e token temporanei, al posto della chiave API delle versioni precedenti.
Cosa puoi fare
| Area | Operazioni |
|---|---|
| Preventivi e spedizioni | Preventivo su tutti i contratti, creazione della spedizione con etichetta PDF o ZPL, elenco, dettaglio, annullamento |
| Spedizioni extra UE | Dichiarazione doganale completa e ricerca dei codici HS/TARIC |
| Tracking | Stato ed eventi di una spedizione, per numero di spedizione o per BDA |
| Invio ordini | Invio degli ordini dal gestionale, da spedire poi dal pannello |
| Ritiri e chiusura giornata | Prenotazione dei ritiri e creazione delle distinte (borderò) |
| Giacenze | Elenco delle giacenze e invio delle istruzioni di svincolo |
| Punti di consegna | Ricerca dei punti BRT e dei punti Poste (Punto Poste, Locker, Ufficio Postale) |
| Fatture, credito e contrassegni | Fatture con PDF, saldo e movimenti del credito, distinte contrassegni, distinte resi |
| Webhook | Registrazione, test e storico degli avvisi inviati ai tuoi sistemi |
Indirizzo di base
Ogni piattaforma ha il proprio sottodominio. Tutte le chiamate partono da:
https://<sottodominio>.spedisci.online/api/2026-09/Ad esempio, per la piattaforma demo.spedisci.online il saldo del credito si
legge da https://demo.spedisci.online/api/2026-09/credit.
Requisiti di accesso
- Un utente con ruolo cliente, attivo, di un cliente attivo.
- Sulle piattaforme Enterprise (non self-service): almeno 3 documenti validati sull’anagrafica del cliente, la stessa regola della pagina Chiave API.
- Un’App creata in Impostazioni → API App (OAuth2): vedi Autenticazione.
Gli endpoint che generano un costo (creazione di spedizioni e ritiri) richiedono inoltre un abbonamento attivo, quando la piattaforma lo prevede.
Primi passi
- Crea la tua App in Impostazioni → API App (OAuth2).
- Richiedi un token con
client_ideclient_secret. - Chiama
POST /ratesper ottenere il preventivo e il codice del contratto. - Chiama
POST /shipmentsper creare la spedizione e ricevere l’etichetta.
# 1. token (valido 1 ora)
curl -X POST https://demo.spedisci.online/oauth/token \
-d "grant_type=client_credentials" \
-d "client_id=<client_id>" \
-d "client_secret=<client_secret>" \
-d "scope=client-api"
# 2. prima chiamata
curl https://demo.spedisci.online/api/2026-09/credit \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"Gli esempi di questa guida sono abbreviati e i loro valori (codici, importi, nomi dei contratti) sono indicativi: i codici reali sono quelli restituiti dalla tua piattaforma.
Versionamento
Il prefisso della versione è una data (2026-09).
- Le modifiche compatibili (nuovi campi, nuovi endpoint) entrano nella stessa versione: la tua integrazione deve ignorare i campi che non conosce.
- Una modifica incompatibile apre un nuovo prefisso; il precedente resta servito per almeno 12 mesi.
Le API precedenti (chiave API e Basic auth) restano attive fino al 28 febbraio 2027. Le nuove integrazioni devono usare la versione 2026-09; quelle esistenti vanno migrate entro quella data. Vedi Migrazione dalle API precedenti.
Riferimento completo
Questa sezione è una guida all’uso. Il riferimento di ogni endpoint, con tutti i campi di richiesta e risposta, è pubblicato su apidocs.spedisci.online .