Cos'è Carte Cultura?

Carte Cultura è un'iniziativa del governo italiano che fornisce voucher culturali ai diciottenni (precedentemente nota come “18app” e “Bonus Cultura”). Ogni cittadino idoneo riceve un voucher da €500 da spendere in beni e servizi culturali: libri, musica, cinema, teatro, biglietti museali, concerti, corsi di lingua e abbonamenti a giornali.

Per i commercianti Shopify in Italia, accettare Carte Cultura significa aprire il tuo negozio a migliaia di giovani clienti con potere d'acquisto garantito. La sfida? Il governo richiede una validazione del voucher basata su SOAP — un protocollo che Shopify non supporta nativamente.

Come ilGhera Carte Cultura Colma il Divario

La ilGhera Carta Cultura è una soluzione completa che si integra direttamente con il sistema di voucher del Ministero della Cultura italiano. Gestisce l'intero flusso di lavoro: validazione del voucher, applicazione dello sconto e conferma del pagamento — tutto senza richiedere un piano Shopify Plus.

Funzionalità principali

• Estensione UI del Checkout (Shopify Plus) — Un widget nativo integrato direttamente nella pagina di checkout di Shopify dove i clienti inseriscono il codice del loro voucher Carte Cultura. Disponibile sui piani Shopify Plus.
• Widget del Carrello a Tendina — Un widget alternativo per i negozi che utilizzano un carrello a tendina invece della pagina di checkout standard. Funziona con qualsiasi tema.
• Funzione di Sconto Automatico — Uno sconto basato su Shopify Functions che applica automaticamente l'importo del voucher ai prodotti idonei. Lo sconto viene calcolato in tempo reale in base al saldo residuo del voucher.
• Idoneità del Prodotto per Categoria — Mappa le tue collezioni Shopify alle categorie Carte Cultura (Libri, Musica, Teatro, Cinema, ecc.). Solo i prodotti nelle collezioni mappate saranno idonei per lo sconto, garantendo la conformità alle regole governative.
• Validazione SOAP tramite Microservizio PHP — L'app comunica con i servizi web SOAP del Ministero attraverso un microservizio PHP dedicato, gestendo la complessa autenticazione basata su certificati richiesta dall'infrastruttura IBM DataPower del governo italiano.
• Sandbox Mode — Testa l'intero flusso di lavoro con un certificato demo prima di andare in produzione. Perfetta per negozi di sviluppo e ambienti di staging.

Architettura: Progettata per l'Affidabilità

L'app segue un'architettura a strati progettata per l'uso in produzione su Fly.io:

1. Estensione del Checkout (JavaScript) — Raccolglie il codice del voucher dal cliente e lo invia al backend dell'app.
2. Backend Node.js (Remix) — Gestisce autenticazione, fatturazione, gestione delle impostazioni e instrada le richieste al microservizio PHP.
3. Microservizio PHP — Esegue le effettive chiamate SOAP ai servizi web del Ministero della Cultura. Questa separazione è necessaria perché l'implementazione SOAP del governo richiede una gestione specifica dei certificati che funziona meglio con il client SOAP nativo di PHP.
4. Metafields di Shopify — Tutte le impostazioni del commerciante (certificati, mappature delle categorie, stato della fatturazione) sono memorizzate come Metafields di Shopify, garantendo la persistenza dei dati anche in ambienti cloud effimeri.

Flusso di Validazione del Voucher

Ecco come funziona una transazione tipica:

1. Il cliente aggiunge prodotti al carrello e procede al checkout.
2. Nel carrello (o nel checkout su Shopify Plus), inserisce il codice del proprio voucher Carte Cultura nel widget dedicato.
3. L'app invia il codice al servizio SOAP del Ministero per la validazione (operazione CHECK).
4. Se valido, l'app recupera il saldo residuo del voucher e lo applica come sconto tramite Shopify Functions.
5. Il cliente completa il pagamento per l'eventuale importo rimanente.
6. Quando l'ordine viene pagato, l'app invia una richiesta CONFIRM al Ministero per consumare il credito del voucher.

Fatturazione e Prezzi

L'app è disponibile con due piani tariffari:

• Monthly: $19,99/mese
• Annual: $199/anno (risparmio di ~$40)

Entrambi i piani includono una prova gratuita di 7 giorni, test completi in sandbox e accesso al sistema di supporto premium di ilGhera. Nessun costo nascosto — l'unico costo sono le commissioni di transazione Shopify che si applicano a tutte le app.

Per iniziare

1. Installa l'app dallo Shopify App Store.
2. Configura il tuo certificato (o usa la modalità sandbox per i test).
3. Mappa le tue collezioni Shopify alle categorie Carte Cultura.
4. Testa il flusso di lavoro in modalità sandbox.
5. Vai in produzione e inizia ad accettare pagamenti Carte Cultura!

Funziona su Ogni Piano Shopify

Shopify limita l'API di estensibilità del checkout al solo Shopify Plus. L'app ilGhera Carte Cultura supera questa limitazione utilizzando l' Estensione UI del Carrello, che funziona su ogni piano Shopify — Basic, Shopify, Advanced e Plus.

• Widget del carrello (tutti i piani): Il widget del voucher Carte Cultura appare nella pagina del carrello e nel carrello a tendina. I clienti inseriscono il codice del loro voucher prima di procedere al checkout. Questa è l'integrazione standard che funziona su ogni piano senza eccezioni.
• Widget del checkout (solo Shopify Plus): Su Shopify Plus, il widget può apparire anche direttamente nella pagina di checkout per un'esperienza ancora più fluida.

L'approccio basato sul carrello non è una limitazione — è una scelta progettuale deliberata che garantisce che ogni commerciante in Italia possa accettare Carte Cultura, indipendentemente dal proprio piano Shopify. Nessun piano Plus richiesto.