Collegare un contratto di un’altra piattaforma Spedisci.online
Questa guida spiega come usare, sulla tua piattaforma, un contratto corriere di un’altra piattaforma Spedisci.online. Dalla versione 2026-09 delle API il collegamento si fa con le credenziali di un’App OAuth2, al posto della chiave API.
Il collegamento con la chiave API resta attivo fino al 28 febbraio 2027. I nuovi collegamenti vanno fatti con la procedura di questa pagina; quelli esistenti vanno migrati entro quella data.
Come funziona
| Piattaforma | Ruolo |
|---|---|
| Master (livello 0) | Ha il contratto diretto con il corriere: Poste, GLS, FedEx, UPS e così via |
| Reseller (livello 1) | Acquista il servizio dal master e lo rivende ai propri clienti |
| La tua piattaforma | Usa il contratto del fornitore, master o reseller, come se fosse un proprio corriere |
Sulla piattaforma del fornitore tu sei un cliente: hai un account, un listino e un credito. Sulla tua piattaforma quel contratto compare tra i corrieri e lo assegni ai tuoi clienti con i tuoi listini.
Catene consentite
- Consentito: Master (A) → Reseller (B) → Piattaforma C.
- Consentito: collegamento via API a un contratto di livello 1, solo con abbonamento attivo sulla piattaforma del fornitore.
- Non supportato: una catena più lunga (A → B → C → D) e il collegamento via API a contratti di livello 2.
Prerequisiti
- Un account cliente attivo sulla piattaforma del fornitore, con il contratto attivo e funzionante: verifica che da quell’account la creazione di una lettera di vettura vada a buon fine.
- La piattaforma del fornitore aggiornata alla versione 2026.23 o successiva.
- Sulle piattaforme Enterprise, l’account sul fornitore deve avere almeno 3 documenti validati per poter creare l’App.
- Per i contratti di livello 1, un abbonamento attivo sulla piattaforma del fornitore.
- L’accesso come amministratore alla tua piattaforma.
Procedura
Crea l’App sulla piattaforma del fornitore
Accedi alla piattaforma del fornitore con il tuo account cliente, apri Impostazioni → API App (OAuth2) e crea l’App. Annota Client ID e Client Secret.
Ogni utente può avere una sola App attiva: se ne hai già una, usa le sue credenziali.
Annota dominio e codice del contratto
Sempre sulla piattaforma del fornitore, apri Impostazioni → Chiave API. Ti servono:
- il Dominio della piattaforma, ad esempio
master.spedisci.online; - il Codice Contratto del contratto da collegare, dalla tabella Contratti Master (L0) o Contratti Secondari (L1).
Copia il codice con il pulsante accanto e usalo esattamente com’è. I codici dei contratti secondari (L1) sono stringhe lunghe e cifrate: non vanno modificate né abbreviate.
Apri il contratto sulla tua piattaforma
Accedi alla tua piattaforma come amministratore, apri Impostazioni → Corrieri e clicca sul logo Spedisci.online.
Compila i dati del collegamento
| Campo | Valore |
|---|---|
| Nome contratto | Un nome a tua scelta, che riconosci tra i corrieri |
| Utente, Password | Lascia vuoti: servono solo per la chiave API precedente |
| Master Domain | Il dominio della piattaforma del fornitore |
| Contract Code | Il codice del contratto copiato al passo precedente |
| API del master | Client API 2026-09 (OAuth2) |
| App Client ID (master) | Il Client ID dell’App |
| App Client Secret (master) | Il Client Secret dell’App |
In Impostazioni Generale indica se il contratto accetta il Multicollo e l’Inserimento ritiri.
Salva
Clicca Salva. Al salvataggio la tua piattaforma:
- verifica il contratto presso il fornitore e ne legge corriere e livello;
- registra il proprio webhook sulla piattaforma del fornitore, per ricevere gli aggiornamenti di tracking e delle giacenze.
Riaprendo il contratto, sotto il Client Secret compare Webhook firmato dal master: registrato.
Dopo il collegamento
- Sincronizza le zone del contratto: in Listini Prezzi → Gestione Zone, nel riquadro del contratto, clicca Sync Zones.
- Imposta i prezzi del contratto nei tuoi listini.
- Assegna il contratto ai clienti che devono usarlo.
- Verifica con una spedizione di prova:
- la lettera di vettura viene creata e l’etichetta si stampa;
- il tracking si aggiorna;
- una giacenza riceve le istruzioni.
Cosa passa dal collegamento
| Operazione | Comportamento |
|---|---|
| Creazione della spedizione | La lettera di vettura viene creata sul contratto del fornitore; l’etichetta viene salvata sulla tua piattaforma |
| Più colli | I colli vengono trasmessi uno per uno, con peso e misure |
| Annullamento | L’annullamento sulla tua piattaforma annulla la spedizione anche presso il fornitore |
| Ritiri | Le richieste di ritiro vengono inoltrate al fornitore |
| Chiusura giornata | La distinta viene chiusa anche sulla piattaforma del fornitore |
| Giacenze | Le giacenze aperte arrivano dal fornitore e le istruzioni di svincolo gli vengono trasmesse |
| Tracking | Gli aggiornamenti di stato arrivano dal fornitore con avvisi firmati |
| Spedizioni extra UE | I dati doganali vengono inoltrati al fornitore e da lì al corriere |
Gli avvisi del fornitore sono firmati: la tua piattaforma accetta solo quelli con una firma valida. Non serve alcuna configurazione: il segreto viene scambiato al salvataggio del contratto.
Migrare un contratto già collegato
Un contratto collegato con la chiave API si porta sulle nuove API senza ricrearlo:
- Sulla piattaforma del fornitore crea l’App in Impostazioni → API App (OAuth2).
- Sulla tua piattaforma apri il contratto in Impostazioni → Corrieri.
- In API del master scegli Client API 2026-09 (OAuth2) e inserisci App Client ID (master) e App Client Secret (master).
- Salva e ripeti la verifica.
Master Domain, Contract Code, listini e clienti assegnati restano invariati. Le spedizioni già create continuano a essere tracciate.
Per tornare indietro, riapri il contratto e scegli di nuovo Chiave API (precedente, fino al 28/02/2027): Utente e Password salvati tornano in uso.
Quando modifichi un contratto già configurato, il campo Client Secret appare vuoto: lascialo vuoto per mantenere il secret salvato, oppure inserisci quello nuovo per sostituirlo.
Risoluzione dei problemi
| Sintomo | Cosa verificare |
|---|---|
| Il salvataggio del contratto fallisce | Dominio e codice del contratto; Client ID e Client Secret; che la piattaforma del fornitore sia alla versione 2026.23 o successiva |
| Le spedizioni vengono rifiutate dopo un periodo di funzionamento | Se l’App è stata revocata sulla piattaforma del fornitore, creane una nuova e aggiorna Client ID e Client Secret nel contratto |
| Errore di abbonamento o di limite del piano | L’abbonamento del tuo account sulla piattaforma del fornitore |
| Errore di credito | Il credito del tuo account sulla piattaforma del fornitore |
| Il tracking non si aggiorna | Che nel contratto compaia Webhook firmato dal master: registrato; in caso contrario salva di nuovo il contratto |
| Le zone non corrispondono a quelle del fornitore | Ripeti Sync Zones in Listini Prezzi → Gestione Zone |
Collegamento con la chiave API (precedente)
Questa modalità funziona fino al 28 febbraio 2027 e non inoltra i dati doganali delle spedizioni extra UE. Usala solo per i contratti già collegati in attesa di migrazione.
- Sulla piattaforma del fornitore apri Impostazioni → Chiave API e annota Api Key, Dominio e Codice Contratto.
- Sulla tua piattaforma apri Impostazioni → Corrieri e clicca sul logo Spedisci.online.
- Compila:
- Nome contratto: un nome a tua scelta;
- Utente: l’e-mail del tuo account sulla piattaforma del fornitore;
- Password: la chiave API;
- Master Domain e Contract Code: dominio e codice del contratto;
- API del master: Chiave API (precedente, fino al 28/02/2027).
- Salva.
Per gli sviluppatori
Il collegamento usa le stesse API a disposizione dei clienti: la guida è nella documentazione delle API .