Integrazione API corrieri: come automatizzare le spedizioni del tuo e-commerce

Sopra i 100-150 ordini al giorno, gestire le spedizioni manualmente non è più un'opzione: copi-incolli indirizzi, generi etichette una alla volta, carichi tracking sui CRM. Ore sprecate ogni settimana. L'automazione via API è il salto produttivo che separa gli e-commerce a margine doppia cifra dai 9-to-5 stressati. In questa guida tecnica vediamo come funzionano le API corrieri, cosa fanno (rate, label, track, void), come integrarle nello stack del tuo store e quanto risparmi in tempo e soldi.

Cosa fanno le API dei corrieri?

Le API dei corrieri permettono al tuo sistema di comunicare con il corriere senza passaggi manuali. Le 4 chiamate fondamentali sono Rate Shopping (calcola tariffa per peso/destinazione), Create Shipment + Generate Label (crea spedizione e ottieni PDF etichetta), Track Shipment (interroga lo status), Void Label (annulla un'etichetta non spedita). Le principali corriere espongono REST API con autenticazione via API Key/OAuth: BRT, GLS, DHL, UPS, FedEx, Poste, SDA hanno tutte API pubbliche o partner.

Le 4 chiamate API fondamentali

1. Rate Shopping

Endpoint che ritorna prezzo + tempo per una spedizione data origine, destinazione, peso, dimensioni.

Esempio chiamata DHL: ``` POST /mydhlapi/rates { "origin": {"postalCode": "20100", "country": "IT"}, "destination": {"postalCode": "10115", "country": "DE"}, "package": {"weight": 2.5, "dimensions": {"length": 30, "width": 20, "height": 15}} } ``` Response: array di servizi disponibili (Express 9:00, Express 12:00, Economy) con prezzo per ciascuno.

2. Create Shipment + Generate Label

Crea la spedizione, ritorna AWB (Air Waybill) numero + PDF etichetta base64 da stampare.

Esempio: ``` POST /mydhlapi/shipments { "service": "EXPRESS_WORLDWIDE", "origin": {...}, "destination": {...}, "package": {...}, "customsDeclaration": {...} } ``` Response: `{ "trackingNumber": "12345678901", "labelData": "JVBERi0xLjQK..." }`.

Salvi il tracking number nel tuo DB ordini, salvi PDF nel filesystem o lo stampi direttamente.

3. Track Shipment

Interroga lo status di un AWB. Usato per aggiornare il customer.

Esempio: ``` GET /mydhlapi/tracking?trackingNumber=12345678901 ``` Response: array di eventi con timestamp, location, status (es. "PICKED_UP", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED").

Best practice: invece di interrogare ogni 5 minuti, abbonati a Webhook del corriere — lui ti chiama quando lo status cambia.

4. Void Label

Annulla un'etichetta generata ma non spedita. Importante per non pagare etichette inutilizzate.

Esempio: ``` DELETE /mydhlapi/shipments/12345678901 ```

API dei principali corrieri italiani: panoramica

Ognuna richiede contratto attivo con il corriere. Senza contratto: niente API.

Soluzione comune: API aggregator (multi-corriere)

Costruire integrazioni separate per 6-8 corrieri = 4-12 settimane di sviluppo + manutenzione perenne. La via comune:

API Aggregator = un'unica API che parla con tutti i corrieri. Tu ti integri solo a quella.

Aggregator popolari:

• EasyPost (US-focus) — bestseller globale, supporta 100+ corrieri.
• Shippo — versatile, US/EU.
• ShippyPro — italiana, ottima per BRT/GLS/Poste.
• Sendcloud — europeo, integrazione checkout.
• Spring GDS — focus internazionale.
• Paccofly — italiana, 20+ corrieri locali con tariffe scontate, REST API.

Vantaggi:

• Una API per tutti i corrieri → -80% sviluppo.
• Tariffe già scontate (volume aggregato).
• Webhook unificati per tracking.
• Dashboard di analytics per ottimizzare scelte corriere.

Costo: 49-499€/mese a fasce di volumi.

Architettura tipica e-commerce con API corrieri

``` [E-commerce platform: Shopify/WooCommerce/Magento]

| v [Backend custom / Plugin / Webhook handler]

| v [Aggregator API: Paccofly/EasyPost/ShippyPro]

| v---> BRT API v---> GLS API v---> DHL API v---> UPS API ```

Flusso ordine:

1. Cliente paga → ordine status "Paid" su platform.
2. Webhook al backend → trigger automation.
3. Backend chiama aggregator: rate shopping per peso/destinazione.
4. Backend sceglie corriere (regola: più economico, più veloce, preferito).
5. Backend chiama: create shipment + generate label.
6. Backend salva tracking + URL etichetta in DB.
7. Backend stampa etichetta (Zebra printer) o invia a fulfillment center.
8. Backend aggiorna status ordine a "Shipped" + email cliente con tracking.
9. Webhook tracking dall'aggregator → status cliente aggiornato in real-time.

Tempo per ordine: 2-5 secondi totale. Volume gestibile: 1.000-10.000 ordini/giorno.

Esempio pratico: integrazione Shopify + API

In Shopify, lo step più semplice è una app dedicata dal Shopify App Store.

No-code path (raccomandato 90% merchant):

• Installa Paccofly Connector Shopify (o ShippyPro, Sendcloud).
• Connetti API key del tuo account.
• Configura regole (corriere preferito per peso/destinazione).
• Tariffe scontate appaiono al checkout.
• Etichette generate automaticamente quando ordine "Fulfilled".

Code path (custom development):

• Webhook Shopify "order/paid" → endpoint tuo backend.
• Tuo backend chiama aggregator API → rate + label.
• Tuo backend chiama Shopify API per "fulfillment.create" con tracking.
• Customer riceve email automatica.

Tempo setup no-code: 2-4 ore. Tempo custom: 2-4 settimane.

Webhook tracking: il modo intelligente di gestire status

Polling (interrogare API ogni X minuti) = costoso, lento, rate-limited. Webhook = il corriere TI chiama quando lo status cambia.

Setup webhook:

1. Endpoint pubblico HTTPS del tuo backend (es. `api.tuoshop.it/webhook/dhl`).
2. Registri URL nell'API corriere/aggregator.
3. Quando pacco cambia status, il corriere invia POST con payload (tracking number, status, timestamp, location).
4. Il tuo backend processa il payload e aggiorna DB + invia notifica cliente.

Webhook reduce traffico API del 95% e rende real-time l'esperienza cliente.

ROI box: integrazione API vs gestione manuale

Esempio: shop con 600 ordini/mese, AOV 55€.

Su volumi 500+, ROI dell'integrazione API è 30-50x in 12 mesi.

Errori comuni nell'integrazione API

1. Rate limit non gestito → API risponde 429, tuo flusso si rompe.
2. Webhook senza idempotenza → status duplicati nel DB.
3. Niente fallback → se API down, ordine resta in limbo.
4. Credenziali in code → committate su Git, sicurezza compromessa.
5. Test in production → genera etichette reali e ti fanno pagare anche se non spedite.
6. Niente retry policy → errori transitori diventano errori definitivi.

FAQ — Domande frequenti

Posso integrare API corrieri senza essere sviluppatore?

Sì. Connector dedicati (Paccofly Connector, ShippyPro, Sendcloud) sono no-code: installi l'app sulla tua piattaforma e configuri da pannello. Per integrazioni custom serve dev. La maggior parte dei merchant <1.000 ordini/mese usa connector no-code.

Quanto costano le API dei corrieri?

Le API in sé sono di solito gratuite per i clienti del corriere (devi avere contratto attivo). Costo viene per spedizione (la tariffa concordata) + eventuale fee dell'aggregator (49-499€/mese). Il risparmio tariffe + tempo recupera l'investimento entro 1-3 mesi.

Le API supportano tariffe negoziate con il mio corriere?

Sì, se hai contratto con tariffe negoziate, l'API restituisce automaticamente quelle tariffe (non il listino). Importante quando usi rate shopping: l'aggregator vede le tue tariffe negoziate e le confronta con altri corrieri. Vedi [[contratto-corriere-aziendale-negoziare]].

Cosa succede se un'API corriere è down?

Best practice: implementa fallback su corriere secondario. Esempio: se DHL API down, sposta automaticamente a UPS (configurato in advance). Aggregator (es. Paccofly) gestisce questo automaticamente con regola "se X non risponde entro 3s, prova Y".

Paccofly espone API per chi vuole integrare?

Sì. La nostra REST API espone rate shopping su 20+ corrieri italiani, label generation, tracking webhook, void labels. Documentazione su developer.paccofly.it. Per merchant >200 pacchi/mese forniamo onboarding tecnico dedicato.

Pronto a spedire?

Calcola subito il prezzo della tua spedizione su Paccofly — confronti 20+ corrieri in un click, paghi solo quello che vedi (IVA, ritiro e assicurazione base sempre inclusi). Per il tuo e-commerce, parla con noi: tariffe scontate per volumi e API REST per integrazione diretta. Niente account, niente sorprese.