=== Qapla' Punti di ritiro ===
Contributors: qaplawoocommerce
Tags: punti di ritiro, pudo, spedizione, woocommerce, corriere
Requires at least: 6.3
Tested up to: 6.9
Stable tag: 2.03
Requires PHP: 8.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Punti di ritiro per WooCommerce. Offri ai tuoi clienti la flessibilità di scegliere quando e dove ritirare i loro ordini.

== Descrizione ==

**Pickup Points per WooCommerce – Offri ai tuoi clienti la flessibilità che richiedono**

Trasforma il tuo checkout aggiungendo un nuovo metodo di spedizione: i punti di ritiro. Con Qapla' Pudo, i tuoi clienti scelgono quando e dove ritirare i loro ordini, senza aspettare a casa il corriere.

= Una soluzione completa che cresce con il tuo business =

Questo plugin si integra perfettamente in WooCommerce (via Qapla' o GLS) e ti mette alla pari con i grandi player del mercato. I tuoi clienti ottengono una modalità di consegna affidabile e pratica, tu riduci i costi logistici e il rischio di giacenze.

**Cosa puoi fare:**

* Attiva i pickup point durante il checkout con una configurazione semplice
* Personalizza il costo di spedizione per questa modalità (o rendila gratuita oltre una soglia)
* Scegli tra mappa interattiva (Google Maps o OpenStreetMap) o elenco: desktop e mobile si adattano automaticamente
* Accedi a migliaia di punti di ritiro in tutta Europa – Qapla' integra oltre 20 corrieri (UPS, DHL, GLS, FedEx, TNT, InPost, e molti altri)

**Compatibile con:**

* **Piattaforma Qapla'** – accedi a una rete di corrieri europei con copertura capillare
* **Piattaforma GLS** – utilizzi esclusivamente la rete di ritiro GLS

Il plugin è gratuito. Hai bisogno di un contratto attivo con Qapla' o GLS per utilizzarlo.

== Installazione ==

= Parte 1: Installazione del plugin =

**Metodo 1: Dalla directory plugin di WordPress (consigliato)**

1. Accedi al tuo WordPress admin
2. Vai su **Plugin → Aggiungi nuovo plugin**
3. Cerca "Qapla' Punti di ritiro" oppure "Qapla' Pudo"
4. Clicca su **Installa**, poi su **Attiva**

**Metodo 2: Caricamento manuale**

1. Scarica il file .zip da https://wordpress.org/plugins/qapla-pudo/
2. Vai su **Plugin → Aggiungi nuovo plugin → Carica plugin**
3. Carica il file .zip e clicca **Installa**
4. Clicca **Attiva**

= Parte 2: Verifica contratto e credenziali API =

Il plugin richiede un contratto attivo con **Qapla'** o **GLS** per recuperare i punti di ritiro. Senza credenziali API valide il plugin non può mostrare nessun punto.

**Se sei cliente Qapla':**

1. Accedi al tuo account Qapla' su https://app.qapla.it
2. Vai alla sezione **Canale**
3. Copia la tua **Chiave Pubblica API** e la **Chiave Privata API**
4. Verifica che il servizio PUDO sia attivo — dovresti vedere una voce "Punti di ritiro" nella configurazione corrieri
5. Se non la vedi, contatta il tuo referente Qapla'

**Se sei cliente GLS con Sell&Send:**

1. Accedi al tuo account GLS Sell&Send su https://sellsend2.gls-italy.com
2. Vai alla sezione **Canale** e individua la tua API key
3. Se il servizio PUDO non è attivo, contatta il tuo referente GLS di zona

**Se sei cliente GLS senza Sell&Send:**

1. Contatta il tuo referente GLS di zona
2. Spiega che vuoi usare il plugin WordPress "Qapla' Pudo" per i pickup point
3. Richiedi l'API key GLS per l'integrazione PUDO
4. Una volta ricevuta, salvala — ti servirà nel passo successivo

= Parte 3: Configurazione del plugin =

1. Nel menu WordPress a sinistra, clicca su **Qapla' Pudo** (voce separata, non sotto Plugin)
2. Scegli il tab della tua piattaforma: **Qapla'** o **GLS**
3. Inserisci le credenziali API nei campi corrispondenti e testa la connessione

**Visualizzazione mappa — scegli una opzione:**

* **Google Maps** – più riconoscibile dai clienti; richiede una Google Maps API Key
  * Ottieni la tua chiave su https://console.cloud.google.com → API e Servizi → Credenziali → Crea chiave API
  * Abilita **Maps JavaScript API** per la chiave
  * Incolla la chiave nel campo "Google Maps API Key" nelle impostazioni del plugin
* **OpenStreetMap** – gratuito, nessuna API key necessaria; scegli tra 4 stili (Voyager, Positron, Dark Matter, Standard)
* **Vista elenco** – nessuna mappa; mostra i punti ordinati per distanza; ideale per mobile

**Parametri di ricerca:**

* *Raggio di ricerca predefinito* (km) – consigliato: 15–20 km
* *Numero massimo di PUDO da visualizzare* – consigliato: 8–12

**Tracciamento (opzionale):** scegli tra Link, Widget o Entrambi per mostrare il tracking nella pagina ordine del cliente.

4. Clicca su **Salva impostazioni**

= Parte 4: Aggiungere il metodo di spedizione in WooCommerce =

1. Vai su **WooCommerce → Impostazioni → Spedizione**
2. Seleziona una zona di spedizione esistente (es. "Italia") o creane una nuova
3. Clicca su **Aggiungi metodo di spedizione** e seleziona **Qapla' Pudo**
4. Configura il metodo:
   * **Titolo** – il nome che vedranno i clienti al checkout (es. "Ritiro presso punto convenzione")
   * **Costo** – lascia vuoto per gratuito, oppure inserisci un importo (es. 2.50)
   * **Soglia spedizione gratuita** – opzionale; importo ordine sopra il quale questo metodo diventa gratuito
5. Clicca **Salva**

= Checklist di configurazione =

Prima di andare live, verifica:

* Plugin installato e attivato
* Contratto attivo con Qapla' o GLS confermato (servizio PUDO abilitato)
* API key inserita e test connessione superato
* Tipo di mappa o vista elenco selezionato
* Google Maps API key inserita (se usi Google Maps)
* Raggio di ricerca e numero massimo PUDO configurati
* Opzione tracciamento selezionata
* Impostazioni salvate
* Metodo di spedizione "Qapla' Pudo" aggiunto alla zona WooCommerce corretta
* Titolo, costo e soglia di gratuità configurati in WooCommerce
* Checkout testato su desktop e mobile — i punti di ritiro compaiono e sono selezionabili

= Supporto =

* **Problemi con Qapla'**: support@qapla.it — https://www.qapla.it
* **Problemi con GLS**: contatta il tuo referente GLS di zona — https://www.gls-group.com
* **Problemi con il plugin**: https://wordpress.org/plugins/qapla-pudo/ → tab Support

== Domande frequenti ==

= Quali sono le differenze tra Qapla' e GLS? =

Qapla' e GLS sono due piattaforme diverse con coperture diverse:

* **Qapla'**: Ti dà accesso a una rete di oltre 20 corrieri europei (UPS, DHL, GLS, FedEx, TNT, InPost, BRT, Correos, SEUR, e molti altri). Ideale se vuoi offrire ai tuoi clienti massima scelta di punti di ritiro. La rete è capillare in Italia, Spagna e tutta Europa.
* **GLS**: Offre esclusivamente i punti di ritiro della rete GLS. Se hai già un contratto con GLS per le consegne, questa è la scelta più diretta. La copertura è buona in Italia e Europa, ma limitata alla sola rete GLS.

In sintesi: scegli Qapla' per massima flessibilità e rete ampia; scegli GLS per una soluzione semplice e dedicata.

= Ho bisogno di un contratto con Qapla' o GLS per usare il plugin? =

Sì, è obbligatorio. Il plugin è gratuito, ma per funzionare ha bisogno di credenziali API fornite da un contratto attivo con Qapla' o GLS. Senza queste credenziali il plugin non può connettersi ai server per recuperare i punti di ritiro.

Se non hai ancora un contratto, contatta Qapla' o GLS direttamente. Se hai già un contratto con uno di loro (anche per altre soluzioni logistiche), puoi riutilizzare le stesse credenziali API.

= Come appare il plugin nel checkout e quali informazioni vedono i clienti? =

Dipende da come lo configuri. Il plugin offre due modalità di visualizzazione:

**Mappa interattiva (Google Maps o OpenStreetMap):**

* I clienti vedono una mappa con i punti di ritiro segnati
* Possono sfogliare e selezionare il punto preferito
* Ogni punto mostra orari di apertura, telefono, note, nome del corriere e distanza
* Desktop: mappa grande e leggibile | Mobile: vista ottimizzata

**Vista elenco:**

* Una lista di punti di ritiro ordinati per distanza
* Stessi dettagli: orari, telefono, corriere, distanza
* Leggera e ottimale su mobile

In entrambe le modalità, dopo aver selezionato il punto il cliente conferma la scelta e procede al pagamento. Indirizzo e orari del punto selezionato compaiono nella thank you page e nell'email di conferma ordine.

= Quali e-commerce sono ideali per questo plugin? =

Il plugin funziona meglio con negozi che vendono prodotti di piccole-medie dimensioni, perché i punti di ritiro hanno limiti di dimensioni.

**Ideale per:** abbigliamento e accessori, libri e media, cosmetica e beauty, elettronica consumer (auricolari, caricabatterie, ecc.), piccoli articoli da casa, giocattoli, food and beverage.

**Meno adatto per:** mobili e arredi grandi, elettrodomestici ingombranti, attrezzature sportive di grandi dimensioni, merci che richiedono consegna specializzata.

Nota: i limiti di dimensione variano per corriere e per punto di ritiro. Puoi comunque attivare questa modalità per tutti i prodotti — dipenderà dal tuo flusso logistico gestire eventuali incompatibilità con il corriere.

= Non vedo nessun punto di ritiro nel checkout — cosa devo fare? =

Cause più probabili:

1. **API key non corretta** – vai nelle impostazioni di Qapla' Pudo, verifica la chiave e lancia il test connessione
2. **Servizio PUDO non attivo nel contratto** – contatta il tuo referente Qapla' o GLS per verificare
3. **Raggio di ricerca troppo piccolo** – aumenta il raggio predefinito nelle impostazioni del plugin (prova 25 km)
4. **Metodo di spedizione non nella zona giusta** – vai in WooCommerce → Impostazioni → Spedizione e verifica che il metodo sia assegnato alla zona che corrisponde all'indirizzo del cliente

= Google Maps non si carica — cosa devo fare? =

1. Verifica di aver inserito una Google Maps API key nelle impostazioni del plugin
2. Nella Google Cloud Console (https://console.cloud.google.com), controlla che **Maps JavaScript API** sia abilitata per la tua chiave
3. Se hai raggiunto il limite di utilizzo gratuito, aggiungi un metodo di pagamento al tuo account Google Cloud

= Il metodo di spedizione "Qapla' Pudo" non appare nel checkout — cosa devo fare? =

1. Verifica di aver aggiunto "Qapla' Pudo" come metodo di spedizione in WooCommerce → Impostazioni → Spedizione per la zona corretta
2. Controlla che l'indirizzo del cliente ricada nella zona di spedizione in cui il metodo è configurato
3. Vai su Plugin e verifica che "Qapla' Punti di ritiro" sia nella lista e risulti Attivo

== Changelog ==

= 2.03 =
* Fix: il REST endpoint /pudos verifica ora il nonce WP REST (header X-WP-Nonce) invece di usare __return_true — protegge la chiave API privata da accessi esterni non autenticati

= 2.02 =
* Readme: sezione Source Code aggiornata per documentare esplicitamente i sorgenti TypeScript di js/src/google-markerclusterer/ inclusi nel pacchetto del plugin

= 2.01 =
* Fix: icona stato "re-entering ship" nel widget di tracking ora servita localmente (img/status/6-2.svg) invece di cdn.qapla.it
* Fix: URL del plugin passato al widget di tracking tramite qplpuTrackingData.pluginUrl

= 2.00 =
* Prima release stabile con compatibilità HPOS completa, internazionalizzazione corretta e supporto multi-corriere

= 1.99 =
* Fix: dati PUDO persi sull'ordine quando WooCommerce aggiorna il checkout (listener updated_checkout)
* Fix: compatibilità HPOS — sostituiti update_post_meta/get_post_meta con WooCommerce Order API
