Classificare il fallimento prima di intervenire
Un errore di validazione locale deve essere mostrato vicino al campo e portare il focus sul primo valore da correggere. Una risposta 400 del carrier richiede invece lettura del codice e del messaggio normalizzato. Un timeout non dimostra che la richiesta sia fallita: il provider potrebbe averla elaborata senza restituire la risposta. Una risposta 500 indica un problema diverso e non va trasformata in “indirizzo non valido”.
La classificazione determina il retry. Gli errori deterministici di input non si ripetono automaticamente; i timeout possono essere verificati con una chiave idempotente o una ricerca dello stato; i problemi temporanei usano backoff e limite. Ogni tentativo conserva correlation ID e fase, evitando di esporre al cliente payload o segreti tecnici.
Numeri validi per l'utente e per l'API
Peso e dimensioni sono una fonte comune di rifiuti. L'utente italiano può inserire 0,5, mentre il payload JSON rappresenta 0.5 come numero. Il parser deve accettare entrambi i separatori in interfaccia, rifiutare forme ambigue e trasmettere un valore numerico positivo. Non deve convertire 0,5 in 5 né inviare una stringa se il carrier richiede un numero.
Anche limiti minimi e massimi dipendono dal provider. Un valore tecnicamente maggiore di zero può essere fuori dal prodotto selezionato. VECTOR valida prima le regole note e lascia al carrier la decisione finale, mostrando un messaggio comprensibile. I decimali originari vengono conservati per spiegare la richiesta e per evitare che una correzione automatica invisibile cambi il prezzo.
Indirizzi e opzioni devono appartenere allo stesso carrier
L'autocompletamento Google aiuta a selezionare un luogo, ma non sostituisce la struttura richiesta da Swiss Post, UPS o FedEx. L'adapter mappa il modello comune nei campi del carrier; se manca un civico o il codice postale non corrisponde al paese, il sistema deve bloccare prima della tariffa. Non si risolve inviando campi di un provider all'altro.
Lo stesso vale per pickup, firma, assicurazione e merci pericolose. Le feature compaiono nel blocco del carrier e vengono aggiunte soltanto al relativo payload quando supportate. Un'opzione globale selezionabile e poi ignorata è un errore di integrità. I gate di produzione restano disattivati finché sandbox e contratto non confermano la capacità.
Tariffa assente: nessun fallback deve fingere di essere reale
Se nessun carrier restituisce un'offerta idonea, l'interfaccia deve spiegare quali dati verificare e consentire di tornare allo step corretto. Mostrare una tariffa statica come se provenisse dall'API produce un prezzo non acquistabile e altera la fiducia. Le simulazioni sono ammesse soltanto in ambienti o account chiaramente identificati, senza addebito e senza confonderle con una spedizione reale.
Il sistema di quote protegge anche le API esterne: debounce, cache coerente, deduplicazione e limiti per utente evitano chiamate ripetute durante la digitazione. La cache deve includere tutti i campi che cambiano idoneità e prezzo. Riutilizzare una risposta dopo avere modificato peso o modalità di affidamento è peggio che richiedere una nuova tariffa.
Pagamento riuscito, fulfillment in attesa
Dopo il checkout, il webhook del provider di pagamento registra l'esito in modo idempotente. Solo allora il fulfillment crea o recupera la spedizione carrier. Se il carrier rifiuta il payload, il pagamento non scompare e non va ripetuto automaticamente. VECTOR informa il cliente che l'importo è registrato e che label e conferma seguiranno dopo il ripristino o la correzione operativa.
Il recupero usa lo stesso ordine e controlla se esiste già un tracking prima di creare un nuovo invio. Questo impedisce label duplicate e costi carrier non necessari. Quando serve correggere un dato sostanziale, si valuta annullamento o rimborso secondo lo stato reale, mantenendo audit della decisione. La soluzione non è modificare silenziosamente il mittente su una label già emessa.
Cosa deve vedere il cliente
Il risultato professionale non è l'assenza assoluta di errori esterni. È un flusso che impedisce danni economici, conserva lo stato e porta l'utente all'azione corretta. VECTOR usa test contrattuali e browser per verificare questo comportamento prima del deploy, lasciando fuori dalle prove live qualsiasi operazione che generi costi o label non necessarie.
- Focus e bordo evidente sul primo campo locale obbligatorio o incoerente.
- Messaggio umano distinto per dati non validi, servizio non disponibile e provider temporaneamente irraggiungibile.
- Nessun secondo pagamento se l'ordine risulta già pagato.
- Conferma esplicita quando la label è in recupero e invio email appena disponibile.
- Tracking, mittente, destinatario e servizi aggiuntivi verificabili nello Step 5 e nei documenti.
- Correlation ID disponibile per il supporto senza mostrare segreti o payload sensibili.
Metodo ufficiale per dichiarare autore, processo e finalità del contenuto.
Costruire una prova che non generi costi
Un test affidabile usa dati sintetici consentiti, account autorizzati e ambienti sandbox quando disponibili. Verifica validazione, costruzione del payload, risposta, visualizzazione e recupero, ma si ferma prima di un'azione irreversibile se il provider non offre modalità di prova. L'obiettivo non è ottenere una schermata verde a qualunque costo: è dimostrare quale parte del contratto applicativo funziona senza creare label o pickup fatturabili.
Prima del deploy, i casi minimi includono peso con punto e virgola, indirizzo incompleto, mittente uguale al destinatario, servizio non supportato, timeout e webhook duplicato. Dopo il deploy, un canary controlla salute e risposta senza acquistare. Le metriche devono separare errori dell'utente, rifiuti del carrier e problemi interni; soltanto così un aumento degli HTTP 400 porta alla correzione del campo giusto invece che a retry indiscriminati.