Guida operativa a Poste Delivery Business PRO

1. Installazione e licenza

Requisiti

• WordPress 5.8 o superiore e WooCommerce 6.0 o superiore (per il checkout a blocchi e i Punti di Ritiro serve WooCommerce 8.9 o superiore).
• PHP 7.4 o superiore.
• Un contratto attivo con Poste Delivery Business e le credenziali API fornite da Poste Italiane.

Installare il plugin

1. Vai su Plugin → Aggiungi nuovo → Carica plugin.
2. Seleziona il file eraclito-pdb-pro-X.Y.Z.zip e clicca Installa ora.
3. Clicca Attiva. Nel menu di WordPress compare la voce Poste Delivery Business.

Attivare la licenza

1. Apri Poste Delivery Business → Licenza. Finché la licenza non è attiva, le altre pagine del plugin restano nascoste.
2. Incolla la chiave di licenza ricevuta da Eraclito e clicca Attiva Licenza.
3. Quando la licenza è attiva il campo diventa di sola lettura e compaiono i dettagli (stato, scadenza, versione).

Aggiornare il plugin

Con la licenza attiva gli aggiornamenti compaiono in Plugin → Plugin installati come per qualsiasi altro plugin. Se non vedi un aggiornamento che ti aspetti, vai su Poste Delivery Business → Supporto e usa Forza Controllo Aggiornamenti.

2. Configurazione iniziale

Prima di creare la prima lettera di vettura (LdV) completa questi quattro passaggi. Ti consigliamo di iniziare in ambiente Sandbox e passare a Live solo a prove concluse.

Passo 1 – Impostazioni PDB API

Apri Poste Delivery Business → Impostazioni PDB API.

1. Ambiente: scegli Sandbox (Test) per le prove (le credenziali di test si compilano da sole) oppure Live (Produzione) per le spedizioni reali. Le LdV generate in Sandbox non sono valide per spedire.
2. Credenziali: inserisci Client ID, Client Password (nel portale Poste si chiama Client Secret) e Centro di Costo. Si trovano nel portale My Poste Delivery Business, nella sezione dedicata alle credenziali API del tuo contratto.
3. Clicca Verifica credenziali: il plugin chiede un token a Poste con i dati inseriti (anche non salvati) e risponde “Credenziali corrette!” oppure “Credenziali non accettate”.
4. Prodotti PDB abilitati nel contratto: seleziona (CTRL o CMD per più voci) solo i prodotti inclusi nel tuo contratto. Se un prodotto non è abilitato, la creazione della LdV fallisce.
5. Prodotti predefiniti: scegli il servizio proposto per primo per le spedizioni nazionali e per quelle internazionali. Selezionando Nessun prodotto il box di spedizione non compare sugli ordini di quel tipo.
6. Metodi di spedizione gestiti con Poste Italiane: spunta i metodi di spedizione WooCommerce che spedisci con Poste. Per gli altri ordini nella lista compare “Non gestito da Poste”.
7. Clicca Salva Impostazioni API.

Passo 2 – Impostazioni mittente

Apri Poste Delivery Business → Impostazioni. Sono i dati del magazzino o dell’azienda stampati come mittente su tutte le LdV. I campi con * sono obbligatori.

Clicca Salva Impostazioni Mittente. Il ritiro dei pacchi avviene all’indirizzo qui indicato.

Passo 3 – Gestione pacchi

Apri Poste Delivery Business → Gestione pacchi e crea con Aggiungi Pacco le scatole che usi: Nome, Altezza, Larghezza e Profondità in cm, Peso in grammi.

Passo 4 – Prima prova

Con l’ambiente Sandbox attivo apri un ordine di prova (WooCommerce → Ordini) e genera una LdV come descritto nella sezione 4. Quando tutto funziona, passa a Live inserendo le credenziali di produzione e salva di nuovo.

3. La dashboard

Cliccando su Poste Delivery Business nel menu si apre la dashboard, il punto di partenza di ogni giornata.

Le quattro schede

Clicca su una scheda per aprire la tabella di dettaglio (massimo 10 righe).

Accesso rapido e licenza

Sotto le schede trovi i pulsanti per le pagine del plugin e un riquadro informativo con lo stato della licenza: scadenza e giorni rimasti, chiave (parzialmente nascosta), dominio, ambiente e versione. Se la licenza scade entro 30 giorni compare il pulsante per rinnovarla.

4. Lettera di vettura da un ordine

Richiedere la LdV

1. Apri l’ordine in WooCommerce → Ordini. Nella colonna laterale trovi il box Spedizione PDB. Dalla lista ordini puoi anche usare il pulsante Richiedi LDV nella colonna LDV.
2. Clicca Richiedi LDV: si apre la finestra Richiesta Lettera di Vettura.
3. Controlla o modifica i campi (vedi tabella sotto).
4. Clicca Invia richiesta LDV. Il plugin genera la LdV, salva il codice sull’ordine e aggiunge una nota.

Dopo la generazione

• Scarica LDV: scarica il PDF (o il file .prn per Zebra) nel formato scelto nelle impostazioni.
• Traccia pacco: apre il tracking della spedizione.
• Cancella LDV: annulla la LdV a Poste. Se all’ordine era collegato un ritiro, viene annullato anche quello (un ritiro cumulativo che copre altri ordini resta attivo). Attenzione: lo stato dell’ordine non cambia da solo.

Casi particolari

• LDV esterna o raccomandata: se hai generato la spedizione fuori dal plugin, usa Inserisci codice e riporta il codice: l’ordine lo conserva e puoi tracciarlo.
• Destinazioni non supportate: se il paese non è gestito dal plugin, la finestra lo segnala e ti rimanda al portale My Poste Delivery Business per generare la LdV a mano, da inserire poi con Inserisci codice.
• Contrassegno internazionale: non è compatibile con le spedizioni verso l’estero.
• Paperless: con la modalità attiva non c’è PDF da scaricare, ma solo il codice LdV.
• Prova di consegna (Digipod): compare nel box dell’ordine solo quando il tracking indica la spedizione come consegnata (serve il Tracking automatico attivo). Usa Richiedi (puoi indicare un’e-mail a cui Poste invia il documento) e poi Scarica PDF. Poste prepara il documento in circa 1 ora e solo a spedizione consegnata.

5. LdV Massiva

Genera le lettere di vettura di molti ordini in un solo passaggio.

1. Nella lista ordini seleziona gli ordini da spedire.
2. Dal menu delle Azioni di gruppo scegli Crea lettere di vettura PdB e conferma.
3. Nella finestra Creazione Massiva Lettere di Vettura PdB imposta i parametri validi per tutto il lotto: Pacco, Peso, Contenuto, Merce, Copertura e il Formato.
4. Clicca Avvia Generazione. Il lavoro prosegue in background anche se chiudi la finestra.
5. Controlla l’avanzamento in Poste Delivery Business → LdV Massiva: lo storico mostra data, ordini, stato (In coda, In corso, Completato, Fallito) e si aggiorna da solo.
6. A lotto completato scarica il PDF unico con tutte le LdV (un solo file .prn per il formato ZPL) e, se ci sono stati problemi, il file Errori TXT.

Con Richiesta automatica del ritiro attiva, a fine lotto il plugin richiede a Poste un unico ritiro cumulativo per tutte le LdV create.

6. LdV Libera

Serve per generare una lettera di vettura non collegata a un ordine, per esempio per una spedizione fatta fuori dal negozio. Apri Poste Delivery Business → Ldv Libera.

1. Scegli il Prodotto PDB (Standard o Express nazionale; devono essere abilitati nelle Impostazioni PDB API).
2. Compila i Dati Destinatario: nome o ragione sociale (max 35 caratteri), indirizzo (max 40), civico, città (max 30), provincia (2 lettere), CAP (5 cifre), paese (ISO 2, es. IT), telefono ed e-mail.
3. Compila i Dati Pacco: tipologia di pacco, peso in grammi e contenuto.
4. Clicca Genera Lettera di Vettura e poi Scarica LdV.

7. Ritiri

Il plugin può richiedere a Poste il ritiro dei pacchi all’indirizzo del mittente, senza passare dal portale.

Attivazione

In Impostazioni PDB API → Richiesta di ritiro scegli la modalità:

• Non richiedere: il ritiro resta concordato con il corriere (comportamento di serie).
• Proponi nella generazione LdV: nella finestra di richiesta LdV compare la casella Richiedi il ritiro a Poste Italiane.
• Richiesta automatica: la casella è già spuntata e la LdV Massiva richiede un ritiro cumulativo a fine lotto.

Imposta anche la fascia oraria predefinita (mattina, pomeriggio o entrambe) e, se vuoi, le notifiche sullo stato del ritiro.

Richiedere il ritiro dalla pagina Ritiri

Apri Poste Delivery Business → Ritiri.

1. Nella sezione Ordini con LdV senza ritiro (ultimi 30 giorni) seleziona gli ordini.
2. Scegli il Tipo di richiesta: un ritiro per ogni LdV oppure un ritiro cumulativo (una sola prenotazione per tutti i colli).
3. Indica Data ritiro (da domani in poi: Poste non accetta la data di oggi), Fascia oraria e le eventuali Note per il corriere.
4. Clicca Richiedi ritiro. Con Ignora selezionati nascondi gli ordini per cui non serve il ritiro.

Gestire i ritiri richiesti

La sezione Ritiri richiesti elenca i ritiri di un periodo (massimo 10 giorni) con stato, indirizzo e ordini collegati. Gli stati possibili sono: Inserito, Prenotato, In corso, Effettuato, Non effettuato, Annullato, In lavorazione manuale. Da qui puoi Annullare e, dove Poste lo consente, Modificare data, fascia e note. Gli stessi comandi sono nel box dell’ordine, con Aggiorna stato.

8. Giacenze

Una spedizione va in giacenza quando Poste non riesce a consegnarla (destinatario assente, indirizzo errato…). Da Poste Delivery Business → Gestione Giacenze vedi l’elenco e decidi cosa fare.

Cercare le giacenze

1. Scegli Cerca per: Data di giacenza oppure Data accettazione LdV (in questo caso l’intervallo massimo è di 10 giorni; il calendario lo rispetta).
2. Imposta Data da e Data a, e se vuoi filtra per Stato e per Motivo (rifiuto del destinatario, destinatario non individuabile, indirizzo errato, destinatario assente).
3. Clicca Aggiorna giacenze.

Per ogni spedizione vedi LdV, destinatario, prodotto, motivo, stato, date di inizio e fine giacenza e numero di colli. Gli stati sono: Da svincolare, Svincolo richiesto, Svincolata, Svincolo proattivo e Non svincolabile (giacenza scaduta).

Svincolare una giacenza

Sulle righe Da svincolare clicca Svincola, scegli l’azione e conferma con Conferma svincolo:

9. Tracking e stati d’ordine

Tracking automatico

In Impostazioni PDB API → Tracking automatico scegli Sincronizza il tracking. Ogni ora il plugin legge il tracking delle LdV non ancora consegnate (ordini degli ultimi 60 giorni, escluse le LdV esterne diverse dalle raccomandate) e scrive ogni nuovo evento come nota privata sull’ordine. Di serie la funzione è disattivata.

Raccomandate. Le raccomandate inserite con Inserisci codice sono tracciate in modo più prudente, perché Poste blocca gli accessi troppo frequenti (con richiesta di captcha): a ogni controllo orario ne vengono lette poche (le meno recentemente controllate), solo tra le più recenti e non quelle inserite nello stesso giorno. Per leggerne subito una usa Aggiorna tracking nel box dell’ordine. Se Poste blocca le richieste, il plugin sospende le letture per qualche ora.

Nel box Spedizione PDB vedi l’ultimo stato della spedizione e il pulsante Aggiorna tracking; se il pacco è in giacenza compare un avviso con il link a Gestione Giacenze.

Opzioni facoltative

Il percorso completo è quindi: In lavorazione → In attesa del corriere PdB → In transito PdB → Completato. Con lo stato In transito PdB attivo, il numero LdV non viene più inserito nelle e-mail di Completato, ma in quella di transito.

Cosa vede il cliente

• Pagina pubblica di tracking: i link nelle e-mail portano a una pagina del tuo sito con il nome del negozio, il numero d’ordine e gli eventi della spedizione. Non serve il login, il cliente non lascia il tuo sito e la pagina mostra solo numero ordine, codice LdV ed eventi (nessun dato personale). Il link è univoco e non indovinabile; se la LdV viene rigenerata, il vecchio link smette di funzionare.
• Area “Il mio account”: nell’ordine il cliente trova il tracking aggiornato e, nell’elenco degli ordini completati o in transito, il pulsante Traccia. Gli stati appaiono senza il suffisso “PdB” (In transito, In attesa del corriere). Il tracking letto da Poste resta in memoria 30 minuti per non rallentare il sito.

10. Punti di ritiro al checkout

Permette ai tuoi clienti di scegliere, al posto della consegna a domicilio, un punto di ritiro Poste vicino a loro. Vale solo per le spedizioni nazionali.

Attivazione

1. In Impostazioni PDB API → Punti di Ritiro spunta Mostra opzione Punto di Ritiro al checkout.
2. Scegli i tipi di punto da offrire:
   • Punto Poste: esercizi convenzionati (edicole, tabaccherie, bar) con orari estesi;
   • Locker: armadietti automatici accessibili 24 ore su 24 con un codice;
   • Ufficio Postale: gli uffici tradizionali.
3. Seleziona i metodi di spedizione su cui mostrare il selettore. Se non ne selezioni nessuno, vale per tutti i metodi gestiti con Poste.
4. Salva.

Come funziona per il cliente

Al checkout il cliente attiva Ritira presso un Punto Poste, cerca per indirizzo o CAP e sceglie il punto. La scelta è obbligatoria se l’opzione è attivata. Il punto scelto compare nell’ordine e nel box di spedizione, e il campo Presso usa l’etichetta impostata in Impostazioni.

11. Spedizioni internazionali

Se il tuo contratto lo prevede, il plugin genera le LdV anche per l’estero.

• Abilita nelle Impostazioni PDB API i prodotti Internazionale Standard, Express e/o Plus inclusi nel tuo contratto.
• Il servizio viene proposto in base alla destinazione dell’ordine; puoi cambiarlo nella finestra di richiesta LdV.
• Per la dichiarazione doganale serve il codice TARIC (10 cifre). Puoi impostare quello predefinito nelle Impostazioni PDB API e assegnarne uno specifico a ogni prodotto WooCommerce, nella scheda del prodotto.
• L’elenco dei paesi è letto da Poste e conservato in memoria 24 ore.
• Il contrassegno non è disponibile per l’estero.
• Per International Plus sono disponibili anche i formati etichetta 10×15 e ZXL; questo prodotto non è supportato nella LdV Massiva.

12. Supporto e domande frequenti

La pagina Poste Delivery Business → Supporto raccoglie gli strumenti di diagnostica: stato dell’ambiente (versioni di plugin, WordPress, WooCommerce e PHP, ultimo errore API), test della connessione e del server aggiornamenti, gestione della cache dei paesi e modalità debug, che aggiunge un riquadro tecnico al box di spedizione degli ordini. Tienila spenta in produzione, salvo richiesta dell’assistenza.