Richiedi assistenza

Gestire i resi in WooCommerce: API, limiti e workflow operativo

Staff
Pacco reso, documento checklist e carta pagamento su tavolo neutro

Panoramica: cosa offre il core e quali gap aspettarsi

Questa guida riassume le primitive tecniche fornite dal core di WooCommerce per ricevere, calcolare e registrare rimborsi, i limiti operativi e tecnici più rilevanti e quali processi o integrazioni servono per avere un workflow di reso completo e tracciabile.

Sintesi immediata:

  • La collection globale “refunds” è di sola lettura e serve per elenchi; per creare o modificare un refund su un ordine si usa l’Order Refunds API (orders/<id>/refunds).
  • WooCommerce 11.1 introduce compute_totals e un endpoint di preview per calcolare lato server i totali di rimborso; attenzione: compute_totals funziona correttamente solo su store con WooCommerce 11.1+ — inviarlo a store con versioni precedenti può produrre rimborsi a 0.00.
  • La nuova form di “order withdrawal” (11.1) permette ai clienti di inviare richieste di recesso dalla pagina My Account; la richiesta viene registrata e notifica il merchant, ma il rimborso e la logistica restano operazioni manuali a meno di integrazioni o procedure operative aggiuntive.

(Continua con i dettagli tecnici, i rischi e una checklist operativa.)

Cosa fornisce il core WooCommerce: API, preview e order withdrawal (11.1)

Endpoint e feature principali da conoscere:

  • Collection “refunds” (read-only): elenca refund a livello di store ma non permette la creazione o la modifica dei refund su uno specifico ordine; non usarla per operazioni operative di rimborso sugli ordini.
  • Order Refunds API: endpoint dedicato per operare sui refund associati a un ordine (POST /wp-json/wc/v3/orders/<id>/refunds). Supporta create/retrieve/delete e accetta parametri chiave come amount, line_items, api_refund, api_restock e compute_totals.
  • Refunds preview: POST /wp-json/wc/v3/orders/<id>/refunds/preview calcola i totali senza creare il refund, restituendo un breakdown per products, shipping, fees e max_refundable; è utile per validare importi prima della creazione.
  • Order withdrawal (WooCommerce 11.1): aggiunge una schermata in My Account per l’invio di richieste di recesso; la richiesta viene loggata e il merchant riceve notifica, ma non automatizza il rimborso né la gestione logistica del reso. Nota: la feature è introdotta in 11.1 e può risultare disabilitata di default nelle impostazioni della release.

Esempio operativo consigliato (flusso rapido):

  1. Il cliente invia la richiesta di withdrawal (My Account) o contatta il supporto; la richiesta viene registrata.
  2. Il merchant esegue la preview via API (orders/<id>/refunds/preview) per ottenere il max_refundable e il breakdown.
  3. Se tutto è corretto, il merchant crea il refund tramite Order Refunds API (orders/<id>/refunds) con i parametri adeguati; usare compute_totals solo su store 11.1+.

Order Refunds API: parametri chiave, compute_totals e preview

Parametri principali e raccomandazioni pratiche:

  • Parametri importanti: amount, line_items (quantità, totali per riga), api_refund (se si vuole che l’API provi a eseguire anche il rimborso sul gateway), api_restock (per riaccreditare lo stock) e compute_totals (server-side calculation).
  • Preview first: chiamare sempre POST /wp-json/wc/v3/orders/<id>/refunds/preview per ottenere breakdown e max_refundable prima di creare il refund. Questo riduce errori e consente validazioni sia lato utente sia lato operatore.
  • Attenzione a compute_totals: il flag permette al server di calcolare gli importi in base a quantità e prezzi salvati; è disponibile correttamente a partire da WooCommerce 11.1. In store con versioni precedenti il flag viene ignorato: una richiesta che invia solo quantità può creare rimborsi con importo 0.00. Evitare di inviare compute_totals su store non compatibili.
  • Gestione errori: l’API può restituire errori di validazione — esempi noti: woocommerce_rest_invalid_refund_amount o woocommerce_rest_refund_exceeds_remaining — quando il rimborso richiesto eccede l’importo rimborsabile. Gestire queste risposte e fornire messaggi chiari a team e clienti.

Esempi descrittivi di chiamate:

Preview:

POST /wp-json/wc/v3/orders/<id>/refunds/preview
Body: { line_items: [ { id: <line_id>, quantity: 1 } ], refund_shipping: true }

(Risposta: breakdown products/shipping/fees e max_refundable).

Creazione refund:

POST /wp-json/wc/v3/orders/<id>/refunds
Body: { amount: 12.50, reason: "Recesso cliente", line_items: [ ... ], api_refund: true }

(Usare compute_totals=true solo su store 11.1+).

Tracciabilità e notifiche: usare i webhook e i log

Per integrare notifiche esterne e migliorare la tracciabilità:

  • Sottoscrivere eventi utili: order.updated, refund.created, order.status.updated o altri eventi rilevanti del flusso reso. I webhook consentono di notificare sistemi esterni (CRM, WMS, ticketing) e di mantenere log centralizzati.
  • Monitoraggio: WooCommerce salva log delle consegne webhook per il troubleshooting; attenzione: i webhook vengono automaticamente disabilitati dopo più di cinque consegne consecutive fallite (valore configurabile via filtro). Serve alerting/monitoring per riattivarli e investigare i fallimenti.
  • Raccomandazione operativa: centralizzare i log dei webhook (es. una destinazione che registra tutte le consegne con esito) e creare alert su consegne fallite oltre una soglia per evitare perdita di notifiche e disabilitazioni non rilevate.

Stati ordine e plugin per modellare il workflow di reso (RMA)

Per strutturare fasi e autorizzazioni del reso spesso conviene introdurre stati ordine dedicati:

  • Perché aggiungerli: gli stati personalizzati consentono di rappresentare fasi distinte (es. “Return requested”, “Return authorized”, “Item received”, “Refund issued”), inviare email automatiche al cambio di stato e includerli nei report.
  • Strumenti: estensioni come Order Status Manager permettono di creare stati custom, definire azioni associate e impostare email al cambio di stato; sono una soluzione comune per modellare flussi RMA.
  • Rischi: i plugin di terze parti possono introdurre comportamenti imprevisti (cambi di stato non voluti o side-effect) che impattano fulfillment e tracciabilità. Testare in staging e definire regole chiare per transizioni e automazioni prima di metterli in produzione.

Rischi pratici e checklist di test (staging) prima di andare in produzione

Controlli da eseguire in staging per mitigare rischi tecnici e operativi:

  1. Verifica versione: controllare che lo store usi WooCommerce 11.1+ se si intende usare compute_totals; altrimenti evitare il flag.
  2. Preview + Create: testare sempre la chiamata di preview e la successiva create refund per i casi: rimborso parziale, rimborso totale, rimborso di spedizione, rimborsi con fee.
  3. Simulare error codes: provocare errori di validazione (es. importo > max_refundable) per verificare la gestione e i messaggi.
  4. Webhook resilience: simulare consegne webhook fallite e verificare che il log mostri errori; verificare la funzionalità di disabilitazione automatica e testare il processo di riattivazione/alert.
  5. Plugin status QA: installare e testare plugin per stati ordine in staging, osservare side-effect (cambi automatici, email generate) e definire policy per rollback.
  6. Procedura di recesso: verificare il flusso amministrativo legato all’order withdrawal (ricezione richiesta, notifica, registrazione) e documentare chi è responsabile dei passi successivi.
  7. Compliance legale: assicurarsi che la procedura preveda il rimborso entro 14 giorni dall’informazione di recesso per le vendite a distanza (verificare processi interni).

Procedura operativa consigliata (RMA) e template minimali per il team

Workflow operativo minimo (ruoli e azioni):

  1. Ricezione richiesta:
    • Fonte: order withdrawal form (My Account) o ticket/mail.
    • Azione: creare ticket RMA con ID ordine, timestamp e motivo.
  2. Validazione iniziale:
    • Operatore: customer care verifica eleggibilità (periodo di recesso, condizioni del prodotto) e lancia la preview refunds per calcolare il max_refundable.
  3. Autorizzazione e istruzioni al cliente:
    • Se autorizzato: inviare istruzioni di reso (indirizzo, modalità, responsabilità sui costi) — documentare la responsabilità dei costi nella policy dello store (nota: per legge le spese di restituzione spettano al consumatore salvo diverso accordo).
  4. Ricezione merce e check logistico:
    • Warehouse: confermare ricezione, fotografare la merce, aggiornare il ticket con le evidenze; segnare lo stato ordine interno (es. “Item received”) se si usano stati custom.
  5. Creazione refund:
    • Dopo le verifiche, usare l’Order Refunds API per creare il rimborso. Prima chiamare preview, poi create; decidere se usare api_refund per tentare il rimborso sul gateway.
  6. Notifica cliente e chiusura:
    • Inviare conferma di rimborso e dettagli (importo, tempistica) e chiudere il ticket. Documentare tutto per audit.

Nota: la feature order withdrawal registra e notifica ma non automatizza la logistica o il rimborso; il merchant resta responsabile dell’esecuzione dei passi operativi sopra descritti.

Domande frequenti (FAQ) tecniche e operative

  • WooCommerce ha un modulo nativo per le richieste di recesso?

    Sì: dalla 11.1 c’è una schermata “order withdrawal” in My Account che permette l’invio della richiesta; la richiesta viene loggata e il merchant notificato, ma il rimborso non è automatico e va eseguito tramite le procedure o le integrazioni del negozio.

  • Qual è la differenza tra l’endpoint “refunds” e l’Order Refunds API?

    La collection “refunds” è di sola lettura e fornisce una lista di refund a livello di store; l’Order Refunds API (orders/<id>/refunds) è l’endpoint per creare, visualizzare e cancellare refund associati a un ordine specifico.

  • Come evitare rimborsi “0.00” quando uso compute_totals?

    Usare compute_totals solo su store con WooCommerce 11.1 o superiore: il flag calcola i totali lato server partendo da quantità e prezzi memorizzati ed è disponibile correttamente in 11.1+. Su versioni precedenti il flag viene ignorato e una richiesta inviata solo con quantità può generare refund 0.00. Procedura consigliata: chiamare prima /orders/<id>/refunds/preview, verificare il breakdown e poi creare il refund.

  • I webhook sono affidabili per tracciare le richieste di reso?

    I webhook sono utili per notifiche e integrazione, ma vanno monitorati: WooCommerce salva log e disabilita automaticamente un webhook dopo più di cinque consegne consecutive fallite (valore configurabile). Implementare logging centralizzato e alerting per evitare perdita di tracciabilità.

Risorse utili e prossimi passi

  • Order Refunds API docs, refunds endpoint docs, refunds preview.
  • Release notes WooCommerce 11.1 per dettagli su compute_totals e order withdrawal.
  • Webhooks docs per configurare logging e gestione degli errori.
  • Se valutate estensioni per stati ordine, consultate Order Status Manager nel marketplace.

Se volete valutare soluzioni commerciali per orchestrare il workflow resi in modo più completo, potete esplorare opzioni come Retiora nella nostra pagina strumenti: Retiora – gestione resi (link informativo, non una dichiarazione di funzionalità verificate nel pacchetto di ricerca).

Checklist rapida prima di andare in produzione:

  • Verifica versione WooCommerce >= 11.1 se prevedete di usare compute_totals.
  • Implementare preview + create refund nella logica di processo.
  • Testare error codes e gestione degli edge-case.
  • Configurare logging centralizzato per webhook e alert su consegne fallite.
  • QA su plugin di stati ordine in staging per evitare side-effect.
  • Definire procedura RMA documentata (chi fa cosa) e tempi per rispettare obblighi di legge (rimborso entro 14 giorni dall’informazione di recesso).