MARKETING AUTOMATION – Creazione di un messaggio di invio con l’automazione

INTRODUZIONE

La visualizzazione della pagina di tutti i messaggi con possibilità di creazione, si trova sotto la voce di menù “Automazione” -> “Compositore messaggi” disponibile solo se è attivo il modulo commerciale “Automazione”.

Questa maschera contiene i messaggi che verranno utilizzati dal modulo di automazione (vedi documentazione).

La maschera contiene le seguenti informazioni, suddivise in schede:

• Email – contiene il template del messaggio email da inviare
• App – contiene il corpo del messaggio della notifica app da inviare
• Sms – contiene il corpo del messaggio SMS da inviare
• Placeholder- contiene la lista di tutti i segnaposto che possono essere inseriti nei  messaggi (Es. Inserendo “Spettabile {Soggetto.Descrizione}” nel messaggio all’utente verrà scritto “Spettabile Mario Rossi” ). I placeholder cambiano in base al contesto (vedi documentazione).
• Link – contiene l’elenco dei link che possono essere inseriti all’interno della email (i link generati in questa sezione vengono tracciati dal sistema (apertura, eventuali tag associati ai link)).

---

CONFIGURAZIONE E UTILIZZO

Di seguito viene mostrato un esempio di creazione del messaggio.

1. Cliccare sul  tasto “Nuovo” per creare un nuovo messaggio, compilare tutti i campi richiesti e al termine premere “Salva” o “Salva e continua”.
2. Per inserire il corpo del messaggio vengono messi a disposizione i tre tab “Email”, “App” e “Sms”:
   1. 1. Nel tab “Email” è stato inserito un componente che consente di creare il template di una email partendo da zero (1), partendo da un template scelto tra un set già esistente (2) oppure partendo da uno dei template creati da noi 2Bit (3). Il componente di editing della email offre un grande numero di personalizzazioni e di funzionalità da poter inserire all’interno dell’ email come ad esempio testi, bottoni, link ai principali social network, etc..  All’interno del tab è stato inserito anche un tasto “Invia email” che consente di inviare una email di test al proprio account con cui si è fatto log in su Zefiro.
      2. Nel tab “App” è possibile inserire il corpo del messaggio per le notifiche tramite app e anche in questo caso come per la email viene data la possibilità di vedere un’anteprima del testo inviato cliccando su “Anteprima”. Nel caso di messaggio con tipo di contesto diverso da “Info destinatario”, prima di vedere un’anteprima del messaggio, viene richiesto di compilare dei campi per poter creare poi un’anteprima da mostrare cliccando sul tasto “Carica dati” (2.2.1).
      3. Nel tab “Sms” è possibile inserire il corpo del messaggio per i messaggi sms e cliccando su “Anteprima” è possibile vedere un’anteprima del testo inviato. Anche in questo tab, come per il messaggio via notifica app, nel caso di messaggio con tipo di contesto diverso da “Info destinatario”, prima di vedere un’anteprima del messaggio, viene richiesto di compilare dei campi per poter creare poi un’anteprima da mostrare cliccando sul tasto “Carica dati”.

Nel tab “Placeholder” vengono messi a disposizione dell’utente tutti i possibili segnaposto da inserire all’interno del corpo dei vari tipi di messaggio. La tipologia di segnaposto varia a seconda del campo “Tipo di contesto” presente in testata della pagina e la griglia con i segnaposto si aggiornerà automaticamente ogni qualvolta viene modificato il valore del campo citato in precedenza. Di seguito viene riportato un esempio di inserimento di un placeholder all’interno del corpo del messaggio email, la stessa procedura è equivalente anche per i messaggi tramite notifiche e sms.

Incollare il testo appena copiato nel messaggio email. In alternativa per inserire i tag è possibile anche seguire questa procedura:

• Mettere il focus sullo spazio interessa e appariranno una serie di opzioni così come in figura
• Cliccando su “Personalizzazione” è possibile accedere a tutti i tag disponibili, raggruppati per categoria, ed è possibile selezionare quello interessato

Nel tab “Link” vengono visualizzati tutti i link disponibili da poter inserire all’interno del messaggio email. Per ogni link viene inoltre data la possibilità di verificare la correttezza di questo selezionando la riga interessata e cliccando sul tasto in griglia “Verifica link”. Così facendo verrà aperta una pagina del browser che visualizzerà la pagina a cui porta il link.

Di seguito viene riportato un esempio di inserimento di un link all’interno del corpo del messaggio email.

Selezionare la riga con l’url da copiare e cliccare sul tasto in griglia “Copia negli appunti (sel.)” indicato.

Inserire il link nell’apposito spazio e clicca “Salva”.

LINK CON TRACCIAMENTO PREFERENZE UTENTE (MARKETING)

Ogni link (vedi punto precedente) può essere associato ad un tag precedentemente creato (anagrafica tag).

Il tag verrà poi riportato nell’anagrafica del cliente (tab “Altri dati”) in base ai link cliccati da quest’ultimo. In questo modo si possono tracciare le preferenze dell’utente.

 

CONFIGURAZIONE BLOCCO PRODOTTO

Nel componente di creazione delle email è stato aggiunto il blocco “Prodotto (2Bit)” tramite il quale è possibile inserire all’interno delle proprie email delle liste ricorsive che contengono dei dati. In particolare in quei casi in cui all’interno delle email si vuole creare delle liste con dei dettagli dei prodotti venduti. Affinchè funzioni tutto correttamente, devono essere creati dei dati ulteriori nel Due associati all’articolo e inserire dei valori dall’anagrafica articolo in modo che poi Zefiro posso metterli all’interno della email da inviare. Di seguito verrà illustrato un esempio di utilizzo del blocco.

1. Trascinare il blocco “Prodotto (2Bit)” nell’area di personalizzazione email
2. Sostituire “Nome prodotto” con il tag del dato ulteriore utilizzato per la descrizione del prodotto che poi verrà sostituito dal sistema nella email.
3. Nelle proprietà del tasto, inserire nel campo “Collegamento” il link presente con il tag per inserire il link che poi verrà sostituito dal sistema con il link vero e proprio.
4. Salvare le modifiche.

N.B.: non modificare e/o rimuovere i delimitatori STARTPRODUCT e ENDPRODUCT dato che sono usati dal sistema per effettuare delle operazioni su quel blocco email. I tag per i dati ulteriori sono scritti seguendo la sintassi [DatoUlterioreGruppo].[DatoUlterioreDescrizione]

---

Indice

1. Accesso alla funzionalità
2. Struttura della maschera
3. Creazione di un nuovo messaggio
4. Configurazione del corpo email
5. Catalogo placeholder
   1. Testata documento (post-vendita)
   2. Riga prodotto (loop per ogni articolo)
   3. Soggetto destinatario
   4. Coupon e Fidelity
   5. Formattazione automatica di numeri e date
6. Sintassi avanzata
   1. Loop sui prodotti — `STARTPRODUCT` / `ENDPRODUCT`
   2. Blocchi condizionali — `{IF:X}…{ENDIF}`
7. Esempio: template “fac-simile scontrino”
8. Generare un template con Claude AI
   1. Workflow consigliato (Importa template)
   2. Prompt pronto da copiare
   3. Modalità d’uso
   4. Suggerimenti per affinare
9. Errori comuni e come risolverli

1. Accesso alla funzionalità

La pagina è accessibile tramite il menu **Automazione → Compositore messaggi**, disponibile solo se è attivo il modulo commerciale *”Automazione”*.

2. Struttura della maschera

Il compositore messaggi è organizzato in **cinque schede principali**:

1. Email — Template per i messaggi di posta elettronica
2. App — Corpo della notifica da inviare via applicazione mobile
3. SMS — Contenuto del messaggio SMS
4. Placeholder — Lista dei segnaposti personalizzabili
5. Link — Elenco dei link tracciabili con analytics

A monte della maschera ci sono i campi **Descrizione** e **Tipo di contesto**: quest’ultimo determina quali placeholder saranno effettivamente risolti al momento dell’invio.

I contesti principali sono:

**Documenti di vendita** — messaggio inviato dopo l’emissione di scontrino/fattura/ricevuta/preconto/scontrino non fiscale. Sono disponibili sia i dati del documento (totali, numero, data) sia i dati delle singole righe prodotto. –

**Destinatario** — invio “a freddo” o per ricorrenza (es. compleanno, riattivazione cliente). Disponibili solo i dati del Soggetto. –

**Comanda** — collegato alla mini-comanda.

**Coupon** — collegato all’emissione di un coupon.

3. Creazione di un nuovo messaggio

1. Cliccare il pulsante **Nuovo** per avviare la creazione.
2. Compilare: – **Descrizione** (es. “Videoguida prodotti acquistati”) – **Tipo di contesto** (es. “Documenti di vendita”) – **Stato** (Attivo)
3. Andare nella scheda **Email** e compilare l’**Oggetto email**.
4. Costruire il **corpo email** (vedi §4).
5. Premere **Salva** o **Salva e continua**. —

4. Configurazione del corpo email

La scheda **Email** offre tre modalità di partenza:

**Iniziare da modello predefinito** — Sceglie un template Zefiro già pronto.

**Design da zero** – Apre l’editor con un canvas vuoto.

**Importa template** — Carica un file `.json` esistente (utile per riusare template forniti dal consulente o generati con l’AI — vedi §8).

L’editor email (basato su **E-mail editor 3.0** / Topol) include un pannello laterale con i blocchi disponibili: Testo, Immagine, GIF, Pulsante, Divisore, Distanziatore, Social, Video, HTML,

**Prodotto**

ℹ️ Il blocco **Prodotto** è un blocco *custom 2Bit* che inserisce automaticamente i marker `STARTPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA)` e `ENDPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA)` — vedi §6.1.

È inoltre disponibile il pulsante

**Invia email**

per spedire un’anteprima di prova all’indirizzo email associato all’utente Zefiro loggato. —

5. Catalogo placeholder

I placeholder sono testo nel formato `{Entita.Campo}` che il sistema sostituisce con il dato reale al momento dell’invio dell’email.

La scheda **Placeholder** del compositore elenca quelli disponibili per il contesto scelto e permette di copiarli con un click.

**Importante**: i placeholder usabili nella **testata** dell’email sono diversi da quelli usabili **dentro il loop prodotti** (`STARTPRODUCT…ENDPRODUCT`).

Vedi le tabelle qui sotto.

5.1 Testata documento (contesto Documenti di vendita)

Per la testata dell’email, usa il placeholder generico **`{DocumentoVendita.X}`**: funziona per tutti i tipi di documento (scontrino/fattura/ricevuta/preconto/scontrino non fiscale). | Placeholder | Esempio rendering | |—|—| | `{DocumentoVendita.NumeroDocumento}` | `9` | | `{DocumentoVendita.DataOraDocumento}` | `20/05/2026 18:05` | | `{DocumentoVendita.TotaleBaseImponibile}` | `18,36` | | `{DocumentoVendita.TotaleImposta}` | `4,04` | | `{DocumentoVendita.TotaleDocumento}` | `22,40` | | `{DocumentoVendita.TotaleNonImponibile}` | `0,00` | | `{DocumentoVendita.TotaleEsente}` | `0,00` | | `{DocumentoVendita.Soggetto.Descrizione}` | `Mario Rossi` | | `{DocumentoVendita.StoricoSoggetto_RagioneSociale}` | `ACME S.p.A.` (ragione sociale del **cliente** storicizzata sul documento — NON del negozio emittente) |

Se hai certezza che l’automazione spedirà solo scontrini, puoi usare anche i placeholder specifici di tipo come `{Scontrino.NumeroDocumento}` o `{Scontrino.RtNumeroScontrino}`.

**Sconsigliato per portabilità**: se domani vuoi usare lo stesso template anche per le fatture, dovrai rinominare i placeholder.

5.2 Riga prodotto (dentro `STARTPRODUCT…ENDPRODUCT`)

Questi placeholder vengono valutati **una volta per ogni prodotto** del documento.

Vanno scritti **dentro** il blocco `STARTPRODUCT…ENDPRODUCT` (vedi §6.1).

**Alias commerciali** (formato monetario default: **lordo con IVA**): | Placeholder | Significato | Esempio |

|—|—|—|

| `{Riga.Quantita}` | Quantità riga | `2` o `2,5` |

| `{Riga.PrezzoUnitario}` | Prezzo unitario lordo (con IVA) | `9,18` |

| `{Riga.PrezzoTotale}` | Prezzo totale di riga lordo | `18,36` |

| `{Riga.PrezzoUnitarioNetto}` | Prezzo unitario netto (senza IVA) | `7,52` |

| `{Riga.PrezzoTotaleNetto}` | Prezzo totale di riga netto | `15,05` |

| `{Riga.Imposta}` | Importo imposta della riga | `3,31` |

**Alias intelligente con fallback automatico**: | Placeholder | Cascata |

|—|—|

| `{Riga.NomeProdotto}` | (1) Dato Ulteriore *”Nomeprodotto”* del prodotto, se valorizzato → (2) Descrizione storicizzata della riga (`DescrizioneArticolo`) → (3) stringa vuota |

Usa `{Riga.NomeProdotto}` quando hai un custom field con il nome commerciale del prodotto: per gli articoli che non l’hanno, sarà automaticamente sostituito dalla descrizione standard.

**Campi diretti della riga**: | Placeholder | Significato |

|—|—|

| `{Riga.DescrizioneArticolo}` | Testo riga storicizzato (es. `2 ETICHETTE JULIUS-K9 a STRAPPO L`) |

| `{Riga.Sconto}` | Sconto applicato (es. `10%` o `5,00`) |

| `{Riga.Note}` | Note libere sulla riga |

**Anagrafica articolo collegata**: | Placeholder | Significato |

|—|—|

| `{Prodotto.Codice}` | Codice anagrafica articolo (es. `ART001`) — alias che il backend risolve in `Articolo.Codice` |

| `{Prodotto.Seriale}` | Numero seriale del prodotto, se gestito |

| `{Prodotto.ArticoloFornitoreCodice}` | Codice fornitore predefinito dell’articolo | >

⚠️ **Non esiste** un placeholder `{Prodotto.Descrizione}` diretto: per la descrizione del prodotto usa `{Riga.NomeProdotto}` (cascata DatoUlteriore → DescrizioneArticolo) oppure `{Riga.DescrizioneArticolo}` (testo storicizzato sulla riga del documento).

**Custom field configurabili** (definiti in *Anagrafiche → Dati Ulteriori* sull’entità Articolo): | Placeholder | Esempio |

|—|—|

| `{DatoUlteriore.<NomeCampo>}` | `{DatoUlteriore.LINKVIDEO}`, `{DatoUlteriore.MisuraCollare}`, ecc. |

Il nome dopo `DatoUlteriore.` è la *Descrizione* del Dato Ulteriore in tabella (case-sensitive).

5.3 Soggetto destinatario

Sempre disponibile (la lista destinatari popola il Soggetto per ogni email): | Placeholder | Esempio |

|—|—|

| `{Soggetto.Descrizione}` | `Mario Rossi` |

| `{Soggetto.Nome}` | `Mario` |

| `{Soggetto.Cognome}` | `Rossi` |

| `{Soggetto.Email}` | `mario@example.com` |

| `{Soggetto.Telefono}` | `+393334567890` |

| `{Soggetto.DataDiNascita}` | `15/03/1985` (formato `dd/MM/yyyy`) |

| `{Soggetto.CodiceFiscale}` | `RSSMRA85C15F205Z` |

| `{Soggetto.PartitaIva}` | `01234567890` |

| `{Soggetto.Pec}` | `mario.rossi.pec@pec.it` |

Indirizzo (se associato al soggetto): | Placeholder | Esempio |

|—|—|

| `{SoggettoIndirizzo.Indirizzo}` | `Via Roma` |

| `{SoggettoIndirizzo.NumeroCivico}` | `12` |

| `{SoggettoIndirizzo.CAP}` | `35100` |

| `{SoggettoIndirizzo.Comune.Descrizione}` | `Padova` |

| `{SoggettoIndirizzo.Provincia.Descrizione}` | `PD` |

| `{SoggettoIndirizzo.Stato.Descrizione}` | `Italia` |

5.4 Coupon e Fidelity

**Coupon** (se il messaggio è agganciato all’emissione di un coupon): | Placeholder | Note |

|—|—|

| `{Coupon.Codice}` | Codice univoco del coupon |

| `{Coupon.ScontoAValore}` | Importo sconto |

| `{Coupon.ScontoPercentuale}` | Percentuale sconto |

| `{Coupon.DataInizioValidita}` | Data inizio validità |

| `{Coupon.DataFineValidita}` | Data fine validità |

**Fidelity** (se cliente con tessera fidelity): | Placeholder | Significato |

|—|—|

| `{DocumentoVendita.Fidelity.SaldoPunti}` | Saldo punti per ciascuna iniziativa attiva |

| `{DocumentoVendita.Fidelity.PremiRitirabili}` | Premi disponibili al ritiro |

| `{DocumentoVendita.Fidelity.ProssimiPremi}` | Premi successivi nella scala fidelity | > Attenzione: i nomi hanno **un punto in mezzo** (`Fidelity.SaldoPunti`), non sono concatenati. Funzionano solo se il documento di vendita ha una tessera fidelity associata al cliente.

5.5 Formattazione automatica di numeri e date

**Non aggiungere mai format manuali nel template** (es. `{X:F2}`). Il sistema formatta automaticamente in **cultura italiana**: | Tipo dato | Quando | Output |

|—|—|—|

| Importo monetario (Prezzo*/Totale*/Importo*/Imposta/Imponibile) | Sempre | `0,00` (2 decimali, virgola) — es. `22,40` |

| Quantità (`Quantita`) | Sempre | `0,###` (intero o fino a 3 decimali) — es. `2`, `2,5` |

| Data e ora generiche | Sempre | `dd/MM/yyyy HH:mm` — es. `20/05/2026 18:05` |

| Data di nascita | Sempre | `dd/MM/yyyy` (senza ora) — es. `15/03/1985` |

Per anteporre il simbolo €, scrivi nel template `€ {Riga.PrezzoTotale}` (con uno spazio): il rendering finale sarà `€ 22,40`.

6. Sintassi avanzata

6.1 Loop sui prodotti

— `STARTPRODUCT` / `ENDPRODUCT` Per ripetere automaticamente una sezione del template per ogni prodotto del documento di vendita: “` STARTPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA) …contenuto template che si ripete per ogni prodotto… es.: {Prodotto.Codice} – {Riga.NomeProdotto} – Q.tà: {Riga.Quantita} – {Riga.PrezzoTotale} € ENDPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA) “`

**Regole importanti**:

– Esattamente **una sola coppia** STARTPRODUCT/ENDPRODUCT per template.

– Se nel compositore usi il blocco custom **Prodotto (2Bit)**, i marker vengono inseriti automaticamente nel posto giusto.

– Solo i placeholder `{Prodotto.X}`, `{Riga.X}` e `{DatoUlteriore.X}` vengono valutati per-riga. Gli altri (es. `{Soggetto.Email}`) mostrano sempre lo stesso valore (= dato della testata).

6.2 Blocchi condizionali

— `{IF:X}…{ENDIF}` Quando un dato potrebbe non essere valorizzato per certi prodotti (es. il link al video tutorial manca per alcuni articoli), e vuoi che **tutta la parte HTML intorno** sparisca insieme al dato vuoto, usa: “` {IF:<token>} contenuto HTML da mostrare solo se <token> ha valore {ENDIF} “`

**Esempio** — nascondi il box “Link tutorial → guarda il video” per gli articoli senza video: “`html <strong>{Riga.NomeProdotto}</strong> {IF:DatoUlteriore.LINKVIDEO} <br> <span style=”font-size:11px;”> Link tutorial → <a href=”{DatoUlteriore.LINKVIDEO}”>guarda il video</a> </span> {ENDIF} “`

Per un articolo **con** `LINKVIDEO` valorizzato → il box viene mantenuto.

Per un articolo **senza** `LINKVIDEO` → l’intero box (incluso `<br>` e `<span>`) sparisce, resta solo il nome prodotto.

**Limiti**: – Funziona solo **dentro** il blocco `STARTPRODUCT…ENDPRODUCT` (non in testata).

Token validi nell’IF: `DatoUlteriore.X`, `Riga.X`, `Prodotto.X`.

**Non annidare** `{IF}` dentro `{IF}`. – “Vuoto” significa: dato assente, `null`, stringa vuota o solo spazi.

7. Esempio: template “fac-simile scontrino”

Per dare un’idea concreta, ecco il blocco riga prodotto del template *”Videoguida”* (un’email “fac-simile scontrino” che si invia dopo l’acquisto):

“`html <table cellpadding=”4″ cellspacing=”0″ border=”0″ style=”width:100%;”> <tr> <td style=”width:60px;”>{Prodotto.Codice}</td> <td> <strong>{Riga.NomeProdotto}</strong>{IF:DatoUlteriore.LINKVIDEO}<br> <span style=”font-size:11px;”> Link tutorial → <a href=”{DatoUlteriore.LINKVIDEO}”>guarda il video</a> </span>{ENDIF} </td> <td style=”text-align:right;”>{Riga.Quantita}</td> <td style=”text-align:right;”>{Riga.PrezzoUnitario}</td> <td style=”text-align:right;”>{Riga.PrezzoTotale}</td> </tr> </table> “` E i totali documento (fuori dal blocco STARTPRODUCT/ENDPRODUCT): “`html <table> <tr><td>Totale imponibile</td><td>€ {DocumentoVendita.TotaleBaseImponibile}</td></tr> <tr><td>IVA</td> <td>€ {DocumentoVendita.TotaleImposta}</td></tr> <tr><td>TOTALE</td> <td>€ {DocumentoVendita.TotaleDocumento}</td></tr> </table> “` Rendering finale (per uno scontrino con 4 prodotti, di cui uno senza link video): “` Cod. Descrizione Q.tà Prezzo Totale TRXTX01 2 ETICHETTE JULIUS-K9 a STRAPPO L 1 5,00 5,00 Link tutorial → guarda il video PPL12889 PRO PLAN GATTO DELICATE TACCHINO 10Kg 1 57,70 57,70 Link tutorial → guarda il video ANI03 GIOCO PET 1 4,00 4,00 ↑ niente box video (articolo senza LINKVIDEO) FORZA10 FORZA10 CANE DIET AGNELLO RISO UMIDO 1 … Link tutorial → guarda il video Totale imponibile € 54,67 IVA € 12,03 TOTALE € 66,70 “`

8. Generare un template con Claude AI

Se non vuoi costruire il template da zero, puoi farti aiutare da **Claude AI** (sia il chat di claude.ai sia ChatGPT con un modello equivalente). Il flusso è completamente *zero-code*: ricevi un file `.json` pronto e lo importi col pulsante **Importa template** del compositore.

8.1 Workflow consigliato (Importa template)

1. **Apri una chat** con Claude AI.
2. **Allega** uno tra questi input: – una **foto/screenshot** del layout email desiderato (mockup, screenshot Whatsapp di un’email che vuoi replicare, screenshot Figma/PowerPoint, ecc.) – un **file HTML** di un’email esistente da adattare – una **descrizione testuale** dettagliata di cosa vuoi
3. **Incolla il prompt** del §8.2 sotto (modificando i dati statici del negozio coi tuoi valori).
4. Claude risponderà con un blocco di codice contenente un singolo JSON.
5. **Salva quel JSON** in un file `.json` sul tuo PC (es. `MioTemplate.json`).
6. **Compositore messaggi → Nuovo messaggio → tab Email → Importa template** → seleziona il file.
7. Topol carica il template nel canvas: vedi l’anteprima.
8. **Personalizza** se serve (dati negozio, colori, testi) direttamente nell’editor.
9. **Salva**: l’HTML viene rigenerato automaticamente da Topol e Zefiro persiste tutto. > ✅ Verificato funzionante: il template `Videoguida` di esempio è stato importato con successo in `zefirodemo` con questo workflow.

8.2 Prompt pronto da copiare

““text Sei un esperto del motore di marketing automation di Zefiro. Devo creare un nuovo template “MessaggioAutomatico” da importare nel compositore email tramite il pulsante “Importa template” (workflow zero-code: l’editor carica il file via TopolPlugin.load(), al Save viene rigenerato HTML coerente e Zefiro persiste tutto).

INPUT: [allega foto/screenshot del layout desiderato, oppure HTML esistente, oppure descrizione testuale dettagliata] CONTESTO AUTOMAZIONE: [scegli uno]

• Documenti: spedito post-vendita (scontrino/fattura/ricevuta/preconto/ scontrino non fiscale) — abilita placeholder DocumentoVendita.X + loop prodotti STARTPRODUCT/ENDPRODUCT
• Destinatario: spedito a freddo o per ricorrenza (es. compleanno) — NO loop prodotti, solo dati Soggetto
• Coupon: per email di emissione coupon — abilita placeholder Coupon.X DATI STATICI DA INSERIRE NEL TEMPLATE (sostituisci con i miei valori):
• Ragione sociale negozio: <Mio Negozio Srl> – Indirizzo negozio: <Via Roma 12, 35100 Padova (PD)> – P.IVA + Telefono: <P.IVA 01234567890 — Tel. 049 1234567> – Sito web negozio: <https://www.mionegozio.it> – Anno copyright: <2026>

VINCOLI TECNICI (NON DEROGABILI):

1. Placeholder ammessi: – TESTATA (fuori dal loop): {DocumentoVendita.NumeroDocumento}, .DataOraDocumento, .TotaleBaseImponibile, .TotaleImposta, .TotaleDocumento, .TotaleNonImponibile, .TotaleEsente, .Soggetto.Descrizione, .StoricoSoggetto_RagioneSociale {Soggetto.Nome|Cognome|Descrizione|Email|Telefono|DataDiNascita| CodiceFiscale|PartitaIva|Pec} {SoggettoIndirizzo.Indirizzo|NumeroCivico|CAP|Comune.Descrizione| Provincia.Descrizione|Stato.Descrizione} {Coupon.Codice|ScontoAValore|ScontoPercentuale| DataInizioValidita|DataFineValidita} – LOOP RIGA (DENTRO STARTPRODUCT/ENDPRODUCT, solo contesto Documenti): {Prodotto.Codice} -> alias che il BE risolve in Articolo.Codice {Prodotto.Seriale}, {Prodotto.ArticoloFornitoreCodice} {Riga.NomeProdotto} -> cascata DatoUlteriore “Nomeprodotto” -> DescrizioneArticolo {Riga.DescrizioneArticolo} {Riga.Quantita} -> formato 0,### (es. “2” o “2,5”) {Riga.PrezzoUnitario} -> formato 0,00 it-IT (default LORDO con IVA) {Riga.PrezzoTotale} -> formato 0,00 it-IT (default LORDO con IVA) {Riga.PrezzoUnitarioNetto}, {Riga.PrezzoTotaleNetto}, {Riga.Imposta} {Riga.Sconto}, {Riga.Note} {DatoUlteriore.<NomeCampoCustom>} -> es. {DatoUlteriore.LINKVIDEO}

2. Loop sui prodotti (SOLO contesto Documenti): STARTPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA) …template riga ripetuto per ogni prodotto… ENDPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA) – Esattamente UNA coppia. – I marker devono stare in <p> dentro <tr> fratelli nello stesso <tbody>. – Concretamente nell’AST: STARTPRODUCT e ENDPRODUCT vanno ciascuno in un mj-text dedicato (content “<p>STARTPRODUCT_…</p>”), il template riga in un mj-text intermedio.

3. Blocchi condizionali per nascondere parti opzionali: {IF:DatoUlteriore.LINKVIDEO}<contenuto>{ENDIF} – Solo dentro il loop riga (NON in testata). – Token valutabili: DatoUlteriore.X, Riga.X, Prodotto.X. – NON annidare {IF} dentro {IF}.

4. Formattazione: il backend formatta automaticamente decimali e date in cultura it-IT. NON aggiungere format custom tipo {X:F2} (non supportati).

5. Vincoli editor Topol Plugin 3 per il JSON (CRITICO): – Struttura: mj-global-style -> mj-body -> mj-section -> mj-column -> children:[mj-text|mj-button|mj-image|mj-divider|mj-spacer|mj-html] – NIENTE mj-table al root della colonna (il canvas dell’editor resta vuoto).

Le tabelle HTML vanno nel “content” di un mj-text come HTML raw. – uid univoci ~10 char alfanumerici (es. “abcDe12345”). – JSON minificato su UNA SOLA RIGA (no indentazione/newline). OUTPUT RICHIESTO: UN SOLO FILE TemplateEmail.json – JSON minificato su una sola riga (verificato JSON.parse OK). – AST conforme allo schema sopra. – Pronto per il pulsante “Importa template” del compositore Zefiro.

NON generare: HTML separato, script SQL, file .md. Non servono nel workflow “Importa template” — Topol rigenera HTML al Save dell’editor e Zefiro persiste tutto via API standard del compositore.

VERIFICHE OBBLIGATORIE PRIMA DI CONSEGNARE: – JSON.parse(TemplateEmail) -> nessun errore di sintassi – Tutti i placeholder usati sono nella lista ammessa sopra – Solo contesto Documenti: conta STARTPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA) = esattamente 1, conta ENDPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA) = esattamente 1 – Per ogni {IF:X}{ENDIF}: X è un token valutabile (DatoUlteriore.* / Riga.* / Prodotto.*) e c’è esattamente un {ENDIF} di chiusura – Nessun mj-table figlio diretto di mj-column CONVENZIONI: – Italiano per testi UI nell’email – Per gli importi: anteponi “€ ” (con spazio) al placeholder se serve € – Lunghezza target JSON: 3-10 KB Procedi e generami il file TemplateEmail.json. ““

8.3 Modalità d’uso

1. da foto/mockup**: Whatsapp/Figma/screenshot. Specifica nel prompt se i prezzi nel mock sono LORDI o NETTI (dalla foto non si capisce).
2. da HTML esistente**: la più rapida. Claude riusa CSS e struttura, sostituisce solo i valori “dummy” con i placeholder dinamici.
3. da descrizione testuale**: “voglio header logo + lista 3 prodotti con cod/descr/qta/prezzo/totale + link video per prodotto + totali in fondo + footer privacy”.

8.4 Suggerimenti per affinare

Dopo aver importato il template e visto l’anteprima, se vuoi modifiche puoi:

1. Modificarlo direttamente nell’editor Topol (più rapido per cambi minori: colori, testi, spaziature).
2. Tornare nella chat con Claude e chiedere ad esempio: *”Modifica il JSON: aggiungi un mj-divider sotto il titolo, cambia colore disclaimer da #b00020 a #cc0000, aggiungi nel blocco riga `{IF:DatoUlteriore.LINKSCHEDA}…{ENDIF}` con un secondo link «vai alla scheda prodotto». Mantieni il resto invariato.”* Poi reimporti. **Anti-pattern da evitare nel prompt**: – *”Usa MJML standard”* → Claude potrebbe usare `<mj-table>` direttamente nel JSON, che Topol Plugin 3 **non renderizza** (canvas vuoto). – *”Decimali con 2 cifre”* → ridondante: il backend lo fa già automaticamente. Specificarlo costringe Claude ad aggiungere format custom (`{X:F2}`) che il motore non supporta.

9. Errori comuni e come risolverli

| Sintomo | Causa | Soluzione |

|—|—|—|

| Nell’email arriva il testo letterale `STARTPRODUCT_(NON_RIMUOVERE_QUESTA_RIGA)` o `ENDPRODUCT_…` | Più di una coppia STARTPRODUCT/ENDPRODUCT nel template | Tieni esattamente una sola coppia. Se l’editor ha duplicato il blocco “Prodotto (2Bit)” rimuovi i duplicati. |

| Un placeholder resta letterale `{X.Y}` nell’email | Nome entità o campo errato | Controlla che `X` sia nelle tabelle del §5 e `Y` sia un campo valido. I nomi sono case-sensitive. |

| Una colonna risulta vuota (es. quantità, prezzo) | Hai usato un placeholder non valido nel contesto loop | Solo `{Prodotto.X}`, `{Riga.X}` e `{DatoUlteriore.X}` vengono valutati per ciascuna riga. `{Scontrino.TotaleDocumento}` dentro al blocco mostra il totale del documento, non il totale di riga. |

| Importi con 4-5 cifre dopo la virgola (`22,40000`) | Versione vecchia del backend | Aggiornare a versione ≥ 2026-05-21. |

| Il box condizionale `{IF:…}{ENDIF}` non sparisce mai | Il token IF è uno non valutabile nel loop, oppure backend vecchio | Usa solo `DatoUlteriore.X` / `Riga.X` / `Prodotto.X` come token. Verifica versione backend. |

| Canvas dell’editor vuoto dopo Importa template | Il JSON contiene un `mj-table` come blocco diretto della colonna (Topol non lo renderizza) | Rigenera il JSON con Claude assicurandoti che il prompt non chieda “MJML standard” e che le tabelle HTML siano dentro il `content` di un `mj-text`. |