WooCommerce spedizioni multi-corriere: zone, tariffe e tracking automatizzato

Quando un negozio passa dal corriere unico al multi-corriere, di solito è perché il primo non copre più tutte le destinazioni o perché i costi sono diventati insostenibili sui colli pesanti. Il problema è che WooCommerce non nasce con il multi-corriere in mente: nasce con le shipping zones, che sono un'astrazione geografica, non logistica. Mescolare le due cose è il primo errore ricorrente.

Le shipping zone raggruppano nazioni o regioni e a ogni zona si associano i metodi di spedizione. Il multi-corriere si costruisce sopra le zone, non al posto loro: a ogni zona corrisponde il corriere che la serve meglio, e dentro la zona si gestiscono le tariffe. Se provi a mettere tre corrieri nella stessa zona con tariffe sovrapposte, il cliente al checkout vede una lista confusa di opzioni tutte nominate 'Spedizione' — e sceglie la più economica anche se è la più lenta.

Strutturare le zone prima dei plugin

Il primo lavoro è di mappatura, non di codice. Si parte dalla domanda: quali corrieri coprono quali zone, a quale costo e con quali tempi. Una zona Italia con corriere espresso, una zona Europa con corriere internazionale, una zona USA con un corriere dedicato. Solo dopo si configura WooCommerce. Le zone si creano in WooCommerce → Impostazioni → Spedizione, e a ciascuna si assegnano i metodi.

Per le tariffe a peso, il metodo 'Spedizione basata sulla tariffa' (Flat Rate) non basta quasi mai: serve un plugin di calcolo tariffe o, meglio, l'integrazione diretta con l'API del corriere. Il calcolo lato server è più affidabile del calcolo lato plugin perché usa le tariffe reali aggiornate, non una tabella statica che invecchia.

// Esempio: aggiungere un metodo di spedizione custom che chiama
// l'API del corriere per calcolare la tariffa reale a peso.

add_filter( 'woocommerce_shipping_methods', function( $methods ) {
    $methods['corriere_express'] = 'WC_Shipping_Corriere_Express';
    return $methods;
} );

class WC_Shipping_Corriere_Express extends WC_Shipping_Method {
    public function calculate_shipping( $package = [] ) {
        $peso = 0;
        foreach ( $package['contents'] as $item ) {
            $peso += (float) $item['data']->get_weight() * $item['quantity'];
        }
        $rate = $this->chiama_api_corriere( $peso, $package['destination'] );
        if ( $rate ) {
            $this->add_rate( [
                'id'    => $this->id,
                'label' => 'Corriere Express (' . $rate['giorni'] . ' gg)',
                'cost'  => $rate['costo'],
            ] );
        }
    }

    private function chiama_api_corriere( $peso, $destinazione ) {
        $resp = wp_remote_post( 'https://api.corriere.example/tariffa', [
            'headers' => [ 'Authorization' => 'Bearer ' . getenv( 'CORRIERE_API_TOKEN' ) ],
            'body'    => wp_json_encode( [
                'peso'   => $peso,
                'nazione' => $destinazione['country'],
            ] ),
            'timeout' => 8,
        ] );
        if ( is_wp_error( $resp ) ) return false;
        return json_decode( wp_remote_retrieve_body( $resp ), true );
    }
}

Tracking automatizzato: chiudere il cerchio

Il tracking è la parte che il cliente sente di più. Se ordina e non riceve aggiornamenti, pensa che il pacco sia perso — e apre una controversia o scrive un'email. L'automazione corretta fa l'opposto: quando il corriere genera la lettera di vettura, WooCommerce invia automaticamente l'email con il tracking number, e quando lo stato cambia in transito/consegnato, lo aggiorna.

Il webhook dal corriere verso WordPress è il pattern migliore: il corriere chiama un endpoint REST di WordPress quando lo stato cambia, e WordPress aggiorna l'ordine e invia la notifica. Niente polling, niente cron che interroga il corriere ogni 10 minuti.

// Webhook: il corriere notifica il cambio di stato a WordPress
add_action( 'rest_api_init', function() {
    register_rest_route( 'wp-planet/v1', '/corriere/tracking', [
        'methods'  => 'POST',
        'callback' => function( $request ) {
            $data = $request->get_json_params();
            // Verifica la firma del corriere (HMAC) per evitare spoofing
            $firma = $request->get_header( 'x-corriere-signature' );
            $attesa = hash_hmac( 'sha256', $request->get_body(), getenv( 'CORRIERE_WEBHOOK_SECRET' ) );
            if ( ! hash_equals( $attesa, $firma ) ) {
                return new WP_Error( 'firma_non_valida', 'Firma non valida', [ 'status' => 401 ] );
            }
            $ordine = wc_get_order( $data['order_id'] );
            if ( ! $ordine ) return new WP_Error( 'no_order', 'Ordine non trovato', [ 'status' => 404 ] );
            $ordine->update_status( $data['stato'], 'Tracking: ' . $data['tracking_url'] );
            return rest_ensure_response( [ 'ok' => true ] );
        },
        'permission_callback' => '__return_true', // protetto da firma HMAC
    ] );
} );

Il multi-corriere ben gestito è invisibile al cliente: al checkout vede opzioni chiare con prezzo e tempi, dopo l'ordine riceve il tracking e gli aggiornamenti automatici. Male gestito, è una fonte continua di email di supporto e controversie. La differenza non è il plugin, è l'architettura: zone pulite, tariffe calcolate lato server, tracking via webhook. Un audit del checkout e della logistica è il modo più rapido di capire se la tua configurazione sta reggendo o sta creando problemi nascosti.