El checkout de WooCommerce no funciona: com diagnosticar la causa arrel

Símptomes

• L’indicador de càrrega del checkout no s’atura després de prémer Fes la comanda.
• Prémer Fes la comanda no fa res.
• Apareix un error genèric: Hi ha hagut un error en processar la comanda, No hem pogut processar la comanda, torna-ho a provar, o un avís vermell buit.
• El checkout funciona per a uns clients i no per a uns altres: convidats, un mètode de pagament, un país, només mòbil.
• La comanda es crea com a Pagament pendent o Fallida, però el client no arriba mai a la pàgina de pagament ni a la d’agraïment.

Causes més habituals

1. Un error fatal de PHP en un hook del checkout: codi de càrrecs, camps, enviaments o validació a mida que falla amb la versió actual de WooCommerce o de PHP.
2. Avisos o notices de PHP impresos a la resposta, que corrompen el JSON que espera l’script del checkout.
3. Un error de JavaScript que atura l’script del checkout abans d’enviar la petició: scripts del tema, plugins d’optimització que difereixen o combinen scripts, eines de consentiment que bloquegen els scripts de pagament.
4. El checkout en memòria cau, que serveix nonces caducats o dades de sessió d’una altra persona.
5. Una capa de seguretat que bloqueja la petició: plugins de seguretat, regles de ModSecurity, una regla de CDN o WAF, o restriccions de la REST API (que afecten el bloc de Checkout).
6. Errors de la passarel·la retornats en processar la comanda: claus incorrectes, barreja de mode de proves i real, validacions de moneda o d’import.
7. Límits del servidor: temps d’execució o memòria de PHP, o processos de PHP-FPM esgotats amb càrrega.

Diagnosi

1. Identifica quin checkout fa servir la botiga

El checkout clàssic (shortcode [woocommerce_checkout]) actualitza els totals amb ?wc-ajax=update_order_review i crea la comanda amb ?wc-ajax=checkout. El bloc de Checkout crea les comandes mitjançant la Store API, amb un POST a /wp-json/wc/store/v1/checkout. Saber quin tens et diu quina petició has de buscar, i per què una regla que bloqueja la REST API només trenca el bloc.

2. Reprodueix la fallada amb el panell de xarxa obert

Obre les eines de desenvolupament del navegador a la pestanya Xarxa, conserva el registre i fes una comanda de prova: en una còpia de staging si pots o, si no, amb un producte barat o un mètode de pagament de prova.

3. Llegeix l’error a l’hora exacta de la fallada

Apunta l’hora de la comanda de prova fallida i revisa:

• WooCommerce → Estat → Registres: l’origen fatal-errors i el registre propi de la passarel·la de pagament.
• El registre d’errors PHP del tauler del hosting, o wp-content/debug.log si el registre de depuració de WordPress és actiu.
• La consola del navegador per buscar errors de JavaScript quan no s’envia cap petició.

4. Relaciona-ho amb els canvis recents

Fes una llista de tot el que va canviar abans que comencés el problema: actualitzacions de WooCommerce, extensions i tema, versió de PHP, plugins nous, paràmetres de memòria cau o CDN, regles de seguretat, paràmetres de la passarel·la de pagament. La majoria de fallades del checkout comencen just després d’un canvi.

5. Aïlla a staging, no a producció

Si les evidències apunten a una interacció i no a un sol error, reprodueix-ho en una còpia de staging i aïlla-ho allà: canvia a un tema per defecte com Storefront i desactiva plugins per meitats fins que la fallada desaparegui. El mode de resolució de problemes del plugin Health Check & Troubleshooting ho fa només per a la teva sessió del navegador, sense afectar els clients.

Registres i comprovacions tècniques

• WooCommerce → Estat → Estat del sistema: versió de WooCommerce, versió i límits de PHP, i la llista de plantilles sobreescrites marcades com a desactualitzades.
• Registres: fatal-errors, l’origen de registre de la passarel·la, el registre d’errors PHP i el registre d’errors del servidor web per a les respostes 403 i 5xx.
• Memòria cau: confirma que /carreto/, /finalitza-la-compra/ i /el-meu-compte/ (o els slugs de la teva botiga) estan excloses de la memòria cau de pàgines, de la CDN i de qualsevol optimització de l’HTML.
• Seguretat: registres del plugin de seguretat, esdeveniments del WAF o bloquejos de ModSecurity sobre wc-ajax=checkout o /wp-json/wc/store/.
• Cos de la resposta de la petició que falla: copia’l sencer. Una sola línia Warning: abans del JSON n’hi ha prou per trencar el checkout clàssic.

Solucions

• Arregla el codi que falla, no el símptoma: una funció de càrrecs o de validació que llança un TypeError a PHP 8 necessita una correcció de tipus, no més memòria.
• Reverteix l’actualització concreta que ha introduït la fallada mentre es prepara la correcció real a staging.
• Exclou el checkout de la memòria cau i de l’optimització, inclosos la combinació i el diferiment dels scripts de pagament.
• Permet els endpoints del checkout al plugin de seguretat o al WAF, limitat a aquestes rutes, en lloc de desactivar la protecció.
• Actualitza les plantilles sobreescrites desactualitzades del tema, o elimina les que ja no calguin.
• Treu les crides externes lentes (tarifes d’enviament, serveis d’impostos, consultes a l’ERP) de la petició del checkout, o desa-les en memòria cau.

// Una funció de càrrecs que no peta amb valors inesperats a PHP 8.
add_action( 'woocommerce_cart_calculate_fees', function ( WC_Cart $cart ) {
    $rate = (float) get_option( 'my_handling_rate', 0 ); // abans: TypeError string + float
    if ( $rate <= 0 ) {
        return;
    }
    $cart->add_fee( __( 'Despeses de gestió', 'my-store' ), $cart->get_subtotal() * $rate );
} );

Què no s’ha de fer

• No desactivis plugins un per un a la botiga en producció en horari comercial: trenca altres fluxos i perd comandes en curs.
• No activis WP_DEBUG_DISPLAY a producció. Registra els errors; no els mostris mai als clients.
• No editis fitxers del nucli de WooCommerce ni copiïs plantilles del nucli al tema per «arreglar» el checkout.
• No apugis a cegues els límits de memòria i temps. Si una petició del checkout necessita 60 segons, alguna cosa de dins no va bé.
• No canviïs de passarel·la ni reinstal·lis WooCommerce abans de conèixer la causa.

Quan recórrer a un expert

Recorre a un enginyer quan l’error apunta a codi a mida que no pots canviar amb seguretat, quan el checkout falla de manera intermitent sense un error clar, quan es cobren pagaments però les comandes fallen, o quan la botiga està perdent comandes ara mateix i cada minut compta.

Problemes relacionats

• WooCommerce / Pagaments WooCommerce: el pagament falla però al client se li ha cobrat Quan la passarel·la cobra el pagament però la comanda queda pendent o fallida, revisa el traspàs de callbacks i webhooks abans de tocar la comanda. →
• WooCommerce / Errors Error fatal a WooCommerce: guia pràctica per resoldre’l Llegeix bé l’error fatal (fitxer, línia, traça) i relaciona’l amb el canvi que el va provocar. →
• WooCommerce / Errors Conflicte de plugins a WooCommerce: com trobar la causa Parteix de les evidències (l’error, el moment, la petició) i aïlla a staging per meitats, no plugin a plugin a producció. →
• WooCommerce / Rendiment Checkout lent a WooCommerce: què cal revisar Separa el temps de PHP, les consultes a la base de dades i les crides a APIs externes abans de canviar la memòria cau o el hosting. →

Preguntes freqüents