WooCommerce / Integracions
Errors de la REST API de WooCommerce: com diagnosticar-los
Resposta curta
Llegeix l’estat HTTP i el camp code de la resposta JSON. Un 401 amb woocommerce_rest_cannot_view o un error d’autenticació vol dir que la petició no s’ha autenticat o que la clau no té permís. Un 404 rest_no_route vol dir que la URL o la versió de l’API són incorrectes, o que la REST API no és accessible a /wp-json/. Un 403 sense codi d’error de WooCommerce sol venir d’un plugin de seguretat, un WAF o el hosting. Un 500 és un error PHP a la botiga. Prova la mateixa crida amb curl per separar el client de la botiga.
Símptomes
- Una integració (ERP, CRM, app mòbil, connector de marketplace) rep respostes 401, 403, 404 o 500.
- Funcionava abans d’un canvi de hosting, una migració a HTTPS, una actualització del plugin de seguretat o un canvi d’enllaços permanents.
- Alguns endpoints funcionen i d’altres fallen.
- Les peticions són lentes o superen el temps amb col·leccions grans.
- Les dades que retorna l’API estan desactualitzades.
Causes més habituals
| Resposta | Causa típica |
|---|---|
401 woocommerce_rest_cannot_view |
No autenticada, o l’usuari o el permís de la clau no poden llegir el recurs |
401 woocommerce_rest_authentication_error |
Consumer key no vàlida, signatura no vàlida (OAuth sobre HTTP) o una marca de temps incorrecta |
401 amb claus vàlides que funcionen en un altre lloc |
El servidor elimina la capçalera Authorization abans que arribi a PHP |
403 sense codi de WooCommerce |
Un plugin de seguretat, un WAF, ModSecurity o el hosting bloquegen la petició |
404 rest_no_route |
Ruta, versió o mètode incorrectes; REST API no accessible a /wp-json/ |
500 |
Error fatal de PHP en construir la resposta |
| Timeouts | per_page molt alt, extensions pesades que afegeixen dades, consultes lentes |
Diagnosi
1. Reprodueix-ho amb curl
Treu el client de l’equació. Amb una clau de només lectura, en una còpia de staging si és possible:
$ curl -s -i -u ck_your_key:cs_your_secret "https://example.com/wp-json/wc/v3/orders?per_page=1"Si curl funciona i la integració no, el problema és al client: URL, mètode, capçaleres o la manera com envia les claus. Si curl falla igual, el problema és a la botiga.
2. Llegeix l’estat i el codi d’error
El cos JSON conté un code i un message. Un codi de WooCommerce o de WordPress (woocommerce_rest_…, rest_…) vol dir que la petició ha arribat a WordPress. Un 403 o una pàgina d’error en HTML sense aquest codi vol dir que ha respost alguna cosa que és davant de WordPress.
3. Revisa la clau
A WooCommerce → Paràmetres → Avançat → REST API: existeix la clau, té el permís correcte (Lectura, Escriptura o Lectura/Escriptura), a quin usuari pertany i quan es va fer servir per última vegada? Una clau l’usuari de la qual s’ha esborrat o ha perdut el rol fallarà.
4. Comprova que la capçalera Authorization arriba a PHP
En algunes configuracions d’Apache amb CGI/FastCGI, la capçalera Authorization no es passa a PHP i l’autenticació Basic falla sense avisar. La regla de .htaccess que WordPress sol incloure la deixa passar:
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]5. Revisa el que hi ha davant de WordPress
Els plugins de seguretat, el WAF del hosting, ModSecurity i les CDN poden bloquejar les peticions a /wp-json/, mètodes concrets (PUT, DELETE) o user agents desconeguts. Els seus registres mostren les peticions bloquejades amb el motiu.
Registres i comprovacions tècniques
- La resposta HTTP completa: estat, capçaleres i cos.
- Claus de la REST API de WooCommerce: permís, usuari, últim accés.
- WooCommerce → Estat → Registres (
fatal-errors) i el registre d’errors PHP per a les respostes 500. - Registres del plugin de seguretat, del WAF i de la CDN per a les respostes 403.
- Paràmetres → Enllaços permanents: els enllaços simples desactiven les URL
/wp-json/. - Regles de memòria cau:
/wp-json/no s’ha de desar en memòria cau per a peticions autenticades.
Solucions
- Fes servir HTTPS amb autenticació Basic, claus amb el permís mínim necessari i una clau per integració per poder-les revocar per separat.
- Passa la capçalera Authorization a PHP quan el servidor l’elimina.
- Permet l’API a les capes de seguretat per a les rutes i mètodes concrets que necessita la integració, en lloc de desactivar la protecció.
- Fes servir la ruta i la versió correctes (
/wp-json/wc/v3/…), i?rest_route=només on no hi hagi enllaços permanents amigables. - Pagina amb seny: valors moderats de
per_page, i filtratge de camps quan el client ho permeti. - Arregla els errors PHP darrere de les respostes 500; sovint els causen extensions que afegeixen dades a les respostes de l’API.
- Exclou
/wp-json/de la memòria cau de pàgines i de la CDN per a les peticions autenticades.
Què no s’ha de fer
- No donis a les integracions claus d’administrador amb lectura i escriptura quan n’hi ha prou amb lectura.
- No posis claus en JavaScript del costat del client ni comparteixis una mateixa clau entre sistemes.
- No desactivis del tot el plugin de seguretat perquè funcioni una integració.
- No apugis
per_pageal màxim per «anar més ràpid»; les respostes grans són més lentes i superen el temps més sovint.
Quan recórrer a un expert
Recorre a un enginyer quan la integració mou comandes, estoc o pagaments i les fallades causen dades incoherents, quan el problema és entre el hosting, les capes de seguretat i el client, o quan cal redissenyar la integració amb reintents, registres i webhooks.
Problemes relacionats
- WooCommerce / Integracions Webhooks de WooCommerce que fallen: com diagnosticar-los Registres de lliurament, codis de resposta, signatures i per què WooCommerce desactiva un webhook després de diversos lliuraments fallits seguits.
- 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 / Rendiment Problemes amb Action Scheduler a WooCommerce Accions programades vençudes, fallides i encallades: com funciona la cua, per què s’atura i com arreglar-ho sense perdre feina pendent.
Preguntes freqüents
Per què la REST API de WooCommerce retorna 401 woocommerce_rest_cannot_view?
La petició no s’ha autenticat com un usuari amb permís per llegir aquest recurs. Revisa les claus, el seu permís de lectura o escriptura, l’usuari a qui pertanyen i si la capçalera Authorization arriba a PHP.
Què vol dir rest_no_route?
Cap ruta REST coincideix amb la URL i el mètode. Revisa la versió de l’API a la ruta (com /wp-json/wc/v3/), el mètode HTTP i que la REST API sigui accessible: amb els enllaços permanents simples, /wp-json/ no funciona i cal fer servir ?rest_route=.
He d’enviar les claus de l’API a la URL?
Fes servir l’autenticació HTTP Basic sobre HTTPS sempre que puguis. Les claus a la URL acaben als registres del servidor, als proxies i a l’analítica. El mètode per paràmetres d’URL existeix per als servidors que eliminen la capçalera Authorization.
Per què les respostes de l’API semblen desactualitzades?
Potser una capa de memòria cau (una CDN o una memòria cau de pàgines) està desant les respostes de /wp-json/. Les respostes de l’API a peticions autenticades no s’han de desar mai en memòria cau.