Accesso agli endpoint per ruolo
Se non riesci ad accedere, un'azione è bloccata o il POS ti chiede di aggiornare, cerca il codice nel messaggio dell'app e trova qui la soluzione:
- AUTH101: accedi di nuovo
- AUTH201: chiedi a un amministratore di controllare il ruolo
- SYNC341: aggiorna l'app
Diagnosi degli errori
Accedi di nuovo (AUTH101)
L'app mostra «Richiesta ancora non autorizzata dopo il rinnovo del token - accedi di nuovo».
- WCPOS apre automaticamente la finestra di accesso a WordPress. Accedi con lo stesso account cassiere.
- Se hai chiuso la finestra, l'app mostra «Accedi per continuare». Premi Accedi nel messaggio per riaprire la finestra.
- Una volta effettuato di nuovo l'accesso, le vendite in attesa di invio vengono inviate automaticamente.
Se il messaggio ricompare subito, chiedi aiuto all'amministratore del sito e inviagli la pagina AUTH101.
Dettagli dell'errore di accesso
L'app ha ricevuto un 401, ha rinnovato il token e anche il nuovo tentativo ha restituito un 401. Il problema riguarda l'autenticazione, non il ruolo: un 403 non attiva mai un rinnovo. Qualcosa tra l'app e WordPress rimuove o rifiuta il token, spesso un plugin di sicurezza o autenticazione (AUTH301).
Chiedi a un amministratore di controllare il ruolo (AUTH201)
Hai effettuato l'accesso, ma il tuo ruolo non consente questa azione. Chiedi all'amministratore del sito di verificare i tuoi permessi in Accesso del personale. Può seguire le indicazioni di AUTH201 per individuare la causa.
Dettagli dei permessi del ruolo
Il server ha risposto 403 a un utente autenticato. All'utente manca access_woocommerce_pos, oppure la rotta richiede manage_woocommerce_pos o install_plugins. Cerca l'endpoint negli elenchi qui sotto. Se indicano che il ruolo dell'utente dovrebbe potervi accedere, molto probabilmente il ruolo è stato modificato rispetto ai valori predefiniti: nella schermata Accesso, dove compare Modificato rispetto ai valori predefiniti di WCPOS, tramite un plugin di modifica dei ruoli o con codice personalizzato. Anche un ruolo aggiuntivo assegnato all'utente può negare una capacità.
Se l'endpoint non è negli elenchi, i test su cui si basano non lo coprono: leggi il controllo dei permessi specifico di quella rotta. WCPOS Pro può anche rifiutare l'accesso a un utente per un negozio per il quale non è autorizzato, ad esempio con 403 wcpos_display_store_forbidden («Non sei autorizzato ad accedere a questo negozio.»).
Aggiorna l'app (SYNC341)
L'app mostra «Aggiorna l'app POS su questo dispositivo.» Il plugin sul sito è più recente dell'app. Aggiorna l'app, poi riaprila:
- Web: ricarica la scheda del browser. Se il messaggio ricompare: su un computer, tieni premuto Maiusc mentre ricarichi; su un telefono o tablet, chiedi aiuto all'amministratore del sito e inviagli la pagina SYNC341.
- Desktop: installa l'aggiornamento proposto dall'app, poi riaprila. Se non viene proposto alcun aggiornamento, scarica l'ultima versione desktop per Windows, Mac (Intel o Apple silicon) o Linux.
- iPhone e iPad: aggiorna WCPOS dalla sua beta su TestFlight.
- Android: aggiorna WCPOS dalla sua beta su Google Play.
SYNC341 contiene le altre informazioni, comprese le azioni a disposizione dell'amministratore del sito quando non esiste ancora una versione più recente dell'app.
Dettagli sulla versione dell'app
Il server ha risposto 426 su una rotta v2, perché l'app è meno recente del protocollo di sincronizzazione del plugin.
Errore di permessi o errore del token
AUTH201 indica che l'utente è autenticato ma non autorizzato: chiedi a un amministratore di verificare il ruolo. AUTH101 indica che è l'autenticazione stessa a essere fallita: accedi di nuovo.
Come distinguerli
403(AUTH201): l'utente è autenticato ma non ha il permesso di eseguire questa azione. Controlla le capacità del ruolo e i requisiti dell'endpoint negli elenchi qui sotto.401(AUTH101, «Richiesta ancora non autorizzata dopo il rinnovo del token»): il server non è riuscito ad autenticare la richiesta dell'app e nessun utente è autenticato. Accedi di nuovo; se il problema continua a ripresentarsi, controlla il token e qualsiasi elemento tra l'app e WordPress che lo rimuova o lo rifiuti.
Leggi la risposta di rifiuto nel pannello di rete del browser o in un log lato server. Anche WP Admin > POS > Impostazioni > Strumenti > Log registra ogni 401 il cui token era malformato o rifiutato per un motivo diverso dalla semplice scadenza. Lo stato e il codice di errore si trovano nel corpo della risposta. L'utente autenticato no: verificalo sul server, ad esempio con get_current_user_id() in un log di debug durante l'esecuzione della richiesta.
Errore di ruolo o capacità:
- Stato:
403 - Codice:
woocommerce_pos_rest_forbidden, oppure quello specifico della rotta, comerest_forbidden - Utente autenticato (lato server): l'ID utente WordPress del cassiere
Errore del token o di accesso:
- Stato:
401 - Codice:
woocommerce_pos_rest_unauthorized data.reason: l'errore del token, comewoocommerce_pos_auth_token_expired- Utente autenticato (lato server):
0(nessun utente autenticato)
Un ID utente diverso da zero indica un problema di capacità. Un utente con ID 0 indica un problema del token o di qualcosa tra l'app e WordPress.
Documentazione correlata
Per amministratori e sviluppatori
I cassieri possono fermarsi qui. Il resto della pagina è destinato agli amministratori del sito e agli sviluppatori che devono capire se la causa è l'autenticazione, il ruolo dell'utente o la versione dell'app. Elenca gli endpoint REST di WCPOS accessibili a ciascun ruolo predefinito e le risposte del server quando nega l'accesso. Per modificare le azioni consentite a un ruolo, usa Accesso del personale.
A cosa può accedere ciascun ruolo predefinito
Un cassiere può eseguire tutte le operazioni necessarie a una vendita, inclusi i rimborsi, e può leggere le stampanti Cloud Print per inviare le ricevute. Tutte le altre impostazioni, i log e la gestione dei negozi richiedono un amministratore o un gestore del negozio.
Accesso consentito a ciascun ruolo predefinito
administrator: tutti gli endpoint di questa pagina.shop_manager: tutti gli endpoint tranne l'azione di installazione e aggiornamento delle estensioni di Pro, che richiede la capacitàinstall_pluginsdi WordPress.cashier: tutto ciò che viene usato nel flusso di vendita, inclusi i rimborsi. Nessun accesso alle schermate delle impostazioni, ai log, alle estensioni o alla gestione dei negozi. Le uniche impostazioni che può leggere sono le stampanti Cloud Print, così il POS può inviare loro le ricevute.
Come sono stati verificati questi elenchi
Gli elenchi derivano dai test di integrazione del plugin. Ogni test effettua l'accesso con un token di accesso WCPOS, come fa l'app, e chiama l'endpoint con ciascun ruolo. Nei test della versione gratuita, un endpoint consentito deve rispondere con uno stato inferiore a 400. I test Pro accettano anche 400 o 404, perché i dati di test sono minimi: entrambe le risposte dimostrano comunque che l'utente ha superato il controllo dei permessi. Un endpoint non consentito deve rispondere 403 con l'utente ancora autenticato.
Come il server controlla una richiesta
Ogni richiesta al POS passa attraverso un massimo di quattro controlli: la versione dell'app, l'autenticazione, l'accesso al POS e infine la regola specifica della rotta. Il primo controllo che fallisce determina la risposta.
I quattro controlli, in ordine
Una richiesta a /wcpos/v1/ o /wcpos/v2/ passa attraverso questi controlli in ordine. Le rotte pubbliche di autenticazione e il polling delle stampanti saltano i controlli 2 e 3. Tre rotte di manutenzione della sincronizzazione saltano il controllo 3 per un utente con manage_woocommerce di WooCommerce e richiedono invece quella capacità.
- Protocollo dell'app (la maggior parte delle rotte v2). In caso di errore restituisce
426, codicewcpos_update_required. L'app mostra SYNC341: aggiorna l'app. - Token di accesso. In caso di errore restituisce
401, codicewoocommerce_pos_rest_unauthorized, senza alcun utente autenticato. L'app rinnova il token una volta e riprova; se fallisce anche il nuovo tentativo, mostra AUTH101: Sessione scaduta. - Accesso al POS. Un utente autenticato senza
access_woocommerce_posriceve403, codicewoocommerce_pos_rest_forbidden. L'app mostra AUTH201: Ruolo insufficiente. - Controllo specifico della rotta. In caso di errore restituisce
403, ad esempiorest_forbidden. Anche in questo caso l'app mostra AUTH201.
Le tre capacità e i ruoli che le possiedono
All'attivazione, il plugin concede le proprie due capacità ai ruoli predefiniti. Un aggiornamento concede solo le capacità introdotte in quella versione, quindi una capacità rimossa nella schermata Accesso rimane rimossa. install_plugins è una capacità di WordPress.
access_woocommerce_pos: amministratore, gestore del negozio e cassiere. È richiesta per ogni endpoint POS tranne le rotte pubbliche di autenticazione, il polling delle stampanti e tre rotte di manutenzione della sincronizzazione (/wcpos/v2/uuid/backfill,/orders/index/backfill,/integrity/rebuild), che richiedono invecemanage_woocommercedi WooCommerce; alcuni endpoint richiedono anche una delle due capacità seguenti.manage_woocommerce_pos: amministratore e gestore del negozio. Consente l'accesso a impostazioni, log, elenco delle estensioni e gestione dei negozi di Pro.install_plugins(WordPress): solo amministratore. Consente l'installazione e l'aggiornamento delle estensioni di Pro.
Endpoint di sincronizzazione (v2)
L'app 2.0 si sincronizza tramite /wcpos/v2/. Ogni ruolo predefinito può accedere a tutte le rotte di sincronizzazione usate dall'app.
Tutti i ruoli: le rotte di sincronizzazione v2
- Stato:
GET /wcpos/v2/status - Catalogo:
GET /wcpos/v2/products,/variations,/products/categories,/products/tags,/products/brands - Clienti, coupon, imposte:
GET /wcpos/v2/customers,/coupons,/taxes - Ordini:
GET /wcpos/v2/orders,/orders/pull - Flusso delle modifiche:
GET /wcpos/v2/changes/sequence-log,/changes/revision-hash,/changes/range-checksum,/changes/config-fingerprint,/changes/tick - Controlli di integrità:
GET /wcpos/v2/digests,/integrity/scan,/integrity/bucket - Ricerca del codice a barre:
GET /wcpos/v2/resolve/barcode - Invio di un nuovo ordine:
POST /wcpos/v2/push/orders
Matrice di accesso agli endpoint del plugin gratuito
Queste rotte /wcpos/v1/ servono per l'autenticazione, il pagamento, le ricevute e le schermate delle impostazioni. Ogni ruolo può accedere alle rotte usate per una vendita. Le schermate delle impostazioni, i log e l'elenco delle estensioni richiedono un amministratore o un gestore del negozio.
Tutti i ruoli (amministratore, gestore del negozio, cassiere): 27 endpoint
GET /wcpos/v1/stores: negozi che l'app può aprireGET /wcpos/v1/cashier/{id}: il cassiere autenticatoGET /wcpos/v1/cashier/{id}/stores: negozi che questo cassiere può usareGET /wcpos/v1/products,/products/variations: catalogoGET /wcpos/v1/products/categories,/tags,/brands: filtri del catalogoGET /wcpos/v1/coupons: ricerca dei couponGET /wcpos/v1/orders: cronologia degli ordiniPOST /wcpos/v1/orders: venditaPATCH /wcpos/v1/orders/{id}: completamento di un ordineGETePOST /wcpos/v1/orders/{id}/checkout: riscossione del pagamentoGET /wcpos/v1/receipts/{order_id}: rendering della ricevutaGET /wcpos/v1/data/order_statuses: nomi degli statiGET /wcpos/v1/customers: ricerca dei clientiPOST /wcpos/v1/customers: aggiunta di un clientePATCH /wcpos/v1/customers/{id}: modifica di un clienteGET /wcpos/v1/taxes,/taxes/classes: aliquote e classi fiscaliGET /wcpos/v1/shipping_methods: righe di spedizioneGET /wcpos/v1/payment-gateways: opzioni di pagamentoPOST /wcpos/v1/payment-gateways/{id}/bootstrap: configurazione del pagamentoGET /wcpos/v1/templates,/templates/active,/templates/gallery: template delle ricevute
Ogni ruolo può anche leggere GET /wcpos/v1/settings/cloud-print, ovvero le stampanti Cloud Print, così il POS può inviare loro le ricevute. È richiesta solo access_woocommerce_pos. Non è uno dei 27: un test dedicato verifica un utente che possiede quella capacità ma non ha accesso alle impostazioni.
Solo amministratore e gestore del negozio: 6 endpoint
Questi richiedono manage_woocommerce_pos; un cassiere riceve 403.
GET /wcpos/v1/settings/general: schermata delle impostazioni generaliGET /wcpos/v1/settings/checkout: schermata delle impostazioni CassaGET /wcpos/v1/settings/tax_ids: schermata delle impostazioni degli identificativi fiscaliGET /wcpos/v1/settings/payment-gateways: schermata delle impostazioni dei gateway di pagamentoGET /wcpos/v1/extensions: elenco delle estensioniGET /wcpos/v1/logs: schermata Log
/wcpos/v1/settings non ha un indice leggibile: leggi invece una sezione come /settings/general.
Matrice di accesso agli endpoint del plugin Pro
WCPOS Pro aggiunge queste rotte. Ogni ruolo può rimborsare un ordine. La gestione dei negozi e la chiave di licenza richiedono un amministratore o un gestore del negozio, mentre l'installazione di un'estensione richiede un amministratore.
Le rotte Pro, per ruolo
Tutti i ruoli:
POST /wcpos/v1/orders/{id}/refunds: rimborso di un ordine
Solo amministratore e gestore del negozio (richiede manage_woocommerce_pos):
GET /wcpos/v1/stores/{id}/edit: apertura di un negozio per la modificaPOST /wcpos/v1/stores: aggiunta di un negozioPATCH /wcpos/v1/stores/{id}: salvataggio di un negozioPOST /wcpos/v1/settings/license: salvataggio della chiave di licenza
Solo amministratore (richiede la capacità install_plugins di WordPress):
POST /wcpos/v1/extensions/action: installazione o aggiornamento di un'estensione
Copertura dei casi di scadenza dei token
Per impostazione predefinita, l'accesso all'app dura 30 minuti e si rinnova automaticamente per un massimo di 30 giorni dal momento in cui il cassiere ha effettuato l'accesso. Dopo questo periodo, il cassiere accede di nuovo (AUTH101). Un token scaduto restituisce sempre un 401, mai un 403, quindi non viene mai confuso con un problema di ruolo.
Durata dei token e risposta restituita in ciascun caso
L'app si autentica con un token di accesso della durata di 30 minuti e un token di rinnovo della durata di 30 giorni. Entrambe le durate possono essere modificate via codice con i filtri wcpos_jwt_access_token_expire e wcpos_jwt_refresh_token_expire. Gli stessi test coprono ciò che accade alla scadenza di ciascun token, per tutti e tre i ruoli:
- Token di accesso valido: l'endpoint risponde normalmente.
- Token di accesso scaduto, mancante o malformato:
401, codicewoocommerce_pos_rest_unauthorized, nessun utente autenticato. L'app rinnova il token una volta e riprova. - Token di accesso scaduto, token di rinnovo valido: il rinnovo restituisce un nuovo token di accesso e il nuovo tentativo riesce.
- Token di rinnovo scaduto: il rinnovo viene rifiutato con
woocommerce_pos_auth_token_expirede il cassiere accede di nuovo (AUTH101).
Un token di accesso scaduto non autentica mai un utente, quindi non arriva mai a un controllo del ruolo: restituisce sempre un 401, mai un 403. I test dimostrano lo stesso comportamento sulle rotte v2 per il ruolo cassiere.