Español
English
Català
Deutsch
Français
Português
Nederlands
Polski
Abbiamo pubblicato connettori per MRW, SEUR, Correos Express, DHL, GLS, UPS e CTT per Odoo, e abbiamo integrato corrieri in siti che non hanno Odoo alle spalle, come eclipseando.com. Le API cambiano nome e formato, ma il lavoro è sempre lo stesso: quattro chiamate, tre o quattro errori che si ripetono e una decisione di architettura da prendere prima di scrivere la prima riga. Questo articolo è la versione per un sito proprio; se il tuo negozio usa Odoo, buona parte è già risolta nei connettori per corrieri.
Idea chiave: l'integrazione non finisce quando esce l'etichetta. Finisce quando il cliente riceve l'avviso che il suo pacco è in viaggio, o fermo in un punto di ritiro, senza che nessuno del tuo team abbia copiato nulla. Se progetti solo l'etichetta, il resto lo farai a mano.
Prima di programmare: l'attivazione e l'ambiente di test
Nessun corriere ti dà accesso alla sua API per aver compilato un modulo sul sito. Serve un contratto di trasporto con un commerciale, e da lì arrivano le credenziali: un codice cliente o abbonato, un utente e una password o chiave, e a volte un codice di franchising o di agenzia. Chiedile fin dal primo giorno e chiedi anche l'ambiente di test, che non tutti hanno e non tutti si comportano come la produzione. Alcune API sono ancora SOAP con XML (è il caso storico di vari corrieri spagnoli); altre sono REST con JSON. Non cambia ciò che va fatto, cambia quanta fatica costa leggere la documentazione.
Le quattro chiamate
| Chiamata | Cosa invii | Cosa restituisce | Dove si rompe |
|---|---|---|---|
| Creare la spedizione | Mittente, destinatario, colli, peso, servizio, riferimento dell'ordine. | Numero di spedizione e, quasi sempre, l'etichetta nella stessa risposta. | Indirizzi non normalizzati, CAP delle Canarie o delle Baleari, telefoni con spazi, caratteri fuori da ASCII. |
| Etichetta | Numero di spedizione e formato (PDF, ZPL, dimensione). | Il file, normalmente in base64. | Richiederla due volte e generare due spedizioni; stampare in A4 ciò che era 10×15. |
| Tracking | Numero di spedizione. | Elenco di eventi con data, codice e testo. | Interrogare ogni minuto e farsi bloccare; non tradurre i codici in stati propri. |
| Manifesto / chiusura | Data e spedizioni del giorno. | Conferma o documento di ritiro. | Dimenticarlo: il corriere non ritira ciò che non è stato manifestato. |
Creare la spedizione: metà del lavoro è ripulire l'indirizzo
La chiamata di creazione è dove si concentrano i rifiuti. Ogni corriere ha la sua idea di indirizzo valido: lunghezza massima della via, CAP di cinque cifre esatte, provincia come codice e non come testo, telefono obbligatorio e senza prefisso, e in diversi nulla fuori da ASCII nel nome. Ciò che funziona è normalizzare prima di chiamare: separare via e numero, tagliare i campi al massimo ammesso da ciascuna API, sostituire gli accenti quando l'API non li accetta e verificare che il CAP esista per quel paese. E salvare sempre richiesta e risposta complete, in XML o JSON, insieme all'ordine. Quando un pacco si perde tre settimane dopo, quella traccia è l'unica prova di ciò che è stato inviato.
Tracking: polling fatto con criterio, o webhook se c'è
Pochi corrieri avvisano via webhook; alla maggior parte bisogna chiedere. Il modo corretto è un'azione pianificata che interroga solo le spedizioni aperte, con un intervallo ragionevole (di solito basta ogni ora, più spesso il giorno della consegna), che si ferma quando lo stato è finale e che rispetta i limiti dell'API. I codici evento si traducono in un piccolo insieme di stati propri: accettato, in transito, in consegna, consegnato, problema, reso. Cinque o sei, non quaranta. E ogni cambio di stato fa partire l'avviso al cliente, che è lo scopo di tutto questo.
Quando non hai l'API perché a spedire è il tuo fornitore
È più frequente di quanto sembri: vendi tu, ma il pacco lo prepara e lo spedisce un fornitore con il suo contratto di trasporto. Non hai credenziali, non puoi creare la spedizione né consultarla. Quello che hai quasi sempre sono le e-mail che il corriere manda all'indirizzo di contatto a ogni movimento. Su eclipseando.com l'abbiamo risolto così con GLS: un'attività legge la casella ogni dieci minuti, riconosce i quattro tipi di e-mail (in viaggio, in consegna, in punto di ritiro con data limite, destinatario assente), estrae il numero di spedizione e l'ordine a cui appartiene, e trasforma ognuna in uno stato e in un avviso all'acquirente. Le ultime due sono le urgenti: un pacco in un punto di ritiro torna al mittente se nessuno va a prenderlo, e un cliente che non sa che è lì non ci va.
Gli errori che vediamo in produzione
- Provare solo sul sandbox. Diversi corrieri hanno un ambiente di test che accetta ciò che la produzione rifiuta. Il test che conta è una spedizione reale verso il tuo ufficio.
- Creare la spedizione alla conferma dell'ordine sul sito. Si crea quando si prepara il pacco. Se si crea prima, ogni annullamento è una spedizione fantasma che a volte viene fatturata.
- Non salvare richiesta e risposta. Senza XML o JSON completi insieme all'ordine, un reclamo è la tua parola contro quella del corriere.
- Un solo numero di tracking per ordine. Funziona fino al primo ordine con due colli o due fornitori. Il tracking si modella per spedizione.
- Certificati e cifrature vecchi. Alcune API sono ancora su TLS con cifrature che le librerie moderne rifiutano di default. Lo si scopre il primo giorno, non quello della messa in produzione.
Con Odoo alle spalle, quasi nulla di tutto questo si programma
Se il negozio usa Odoo, le quattro chiamate sono già scritte nei connettori che pubblichiamo sull'App Store di Odoo, testati su Odoo 19, 18 e 17 su Odoo.sh reale: l'etichetta esce alla convalida del prelievo, il tracking viene interrogato da un'azione pianificata e scritto sul prelievo, il manifesto si chiude da Odoo stesso e l'avviso al cliente parte via e-mail o SMS con il modello che preferisci. Il sito deve solo leggere lo stato del prelievo. Per questo, quando qualcuno ci chiede di integrare un corriere in un sito e ha già Odoo, la risposta di solito è collegare il sito all'ERP, non riscrivere l'integrazione.
Domande frequenti
Quanto tempo ci vuole per integrare un corriere?
Dipende soprattutto da due cose che non controlli: quanto ci mette il corriere a darti credenziali e ambiente di test, e se la sua API è REST con documentazione aggiornata o SOAP con un PDF di anni fa. Le quattro chiamate in sé sono un lavoro circoscritto; ciò che allunga i tempi sono le attese e i test con spedizioni reali.
Si possono integrare più corrieri insieme?
Sì, ed è meglio progettarlo così fin dall'inizio: uno strato proprio con le quattro operazioni (creare, etichetta, tracking, manifesto) e un adattatore per corriere sotto. Aggiungere il secondo costa una frazione del primo, se il primo è stato fatto con quella separazione.
E se il mio fornitore spedisce con il suo corriere e io non ho accesso?
Si lavora con ciò che arriva: le e-mail del corriere o i file che il fornitore restituisce. Leggerli in automatico e trasformarli in stati e avvisi non è pulito come un'API, ma elimina la copia manuale e, soprattutto, evita che un cliente non sappia che il suo pacco è in attesa in un punto di ritiro.
Link utili dentro FlexigoTech
Cosa facciamo in merito
Devi collegare un corriere e non sai da dove cominciare?
Dicci quale, se hai già le credenziali e se c'è Odoo alle spalle. Ti diciamo cosa si programma, cosa esiste già e cosa chiedere al corriere prima di iniziare. Scrivi a comercial@flexigobe.com o chiama il +34 616 809 504.