Importazione Donazioni e Sostenitori su RiseAct

1. Importazioni – info generali

RiseAct permette di importare sostenitori e donazioni da file CSV. Gli importatori sono pensati come strumento di onboarding: servono a caricare i dati iniziali di un'organizzazione, non a mantenere una sincronizzazione continua con un CRM esterno.

Principi generali

• Nessun aggiornamento dei record esistenti. Se un record corrispondente esiste già (in base alle chiavi di deduplica), viene mantenuto così com'è: i dati presenti non vengono mai sovrascritti.
• Idempotenza. Reimportare lo stesso file non crea duplicati. La deduplica avviene tramite i riferimenti esterni (external ref) o, per le righe senza chiave, tramite un marcatore interno di riga.
• Report in app. Ogni importazione genera un evento consultabile in Impostazioni → Importazioni, con stato, conteggi e righe scartate. Al termine viene inviata anche un'email di riepilogo.
• Un'importazione per organizzazione alla volta. Finché un'importazione è in corso, non se ne può avviare un'altra per la stessa organizzazione.

Limiti del file

File più grandi vanno suddivisi in più importazioni.

Formato dell'intestazione

Le intestazioni sono minuscole, con parole separate da spazi (non snake_case, non Title Case). Esempio: first name, supporter external ref, payment date. Il confronto ignora maiuscole/minuscole e spazi esterni; spazi interni multipli vengono normalizzati a uno solo.

Unica eccezione: le colonne dei campi personalizzati, che mantengono il prefisso custom_ con underscore.

Regole di formato dei valori

Valgono per entrambi gli importatori (sostenitori e donazioni).

• Importi (amount): formato fisso x.xx — cifre intere, punto come separatore decimale, esattamente due decimali (regex ^\d{1,10}\.\d{2}$). Non ammessi: virgola decimale (12,34), separatore delle migliaia (1.234,56), zero o un solo decimale (12, 12.3), valori ≤ 0.
• Date e timestamp (payment date): ISO 8601 stretto. Formati accettati: 2026-12-31, 2026-06-25 13:29:57, 2026-06-25T13:29:57.566Z. Formati ambigui come 31/12/2026 non sono accettati. Se manca il fuso orario si assume UTC; se manca l'ora si assume 00:00.
• Data di nascita (date of birth): formato YYYY-MM-DD.
• Codice paese (country code): ISO 3166-1 alpha-2 (2 lettere, es. IT).
• Codice fiscale / partita IVA: solo validazione formale (caratteri alfanumerici, entro la lunghezza massima); nessun controllo di esistenza reale.
• Valori booleani (consensi marketing e campi personalizzati BOOLEAN): ammesse solo queste coppie (case-insensitive): t/f, true/false, 0/1. Cella vuota = valore non impostato. Qualsiasi altro valore (yes, si, x, ecc.) fa fallire la riga.
• Tag multivalore: più valori separati da virgola nella stessa cella. Poiché la virgola è anche il separatore CSV, la cella va racchiusa tra virgolette, es. "x,y,z" → produce tre tag: x, y, z.

Regole di deduplica

• Sostenitore: catena di chiavi, la prima valorizzata vince: supporter external ref → email → ssn → vat. Se nessuna chiave è valorizzata, viene sempre creato un nuovo sostenitore anonimo. Se una chiave secondaria (email/ssn/vat) individua più sostenitori esistenti, vince quello con id più basso.
• Donazione: chiave donation external ref. Righe con lo stesso riferimento confluiscono in un'unica donazione con più pagamenti. Senza questo riferimento, ogni riga diventa una donazione one-off separata.
• Pagamento: chiave (donazione, data pagamento, importo) — evita di contare due volte lo stesso pagamento in caso di reimportazione.

Campi personalizzati

• Si importano con colonne dedicate custom_<key>, dove <key> è la chiave stabile di una definizione di campo personalizzato già esistente nell'organizzazione (es. custom_numero_tessera).
• La definizione deve esistere già: l'importazione non crea nuovi campi personalizzati. Una <key> inesistente genera un errore di intestazione.
• La colonna viene assegnata all'entità della sua definizione: un campo di tipo sostenitore va sul sostenitore, uno di tipo donazione va sulla donazione (anche nel file donazioni denormalizzato).
• Nell'importatore sostenitori sono ammesse solo chiavi di tipo sostenitore.
• Coerenza valori: BOOLEAN segue la regola booleana sopra; SELECT deve essere tra le opzioni della definizione; TEXT senza vincoli.

Report ed esito dell'importazione

Al termine, in Impostazioni → Importazioni si trovano:

• stato dell'importazione: In attesa, In corso, Completata, Fallita;
• conteggi dei record creati (sostenitori, donazioni, pagamenti) e delle righe scartate;
• elenco delle righe scartate con motivo, con possibilità di esportare in CSV il solo sottoinsieme scartato, per correggerlo e ricaricarlo.

Un errore a livello di file (CSV illeggibile, intestazioni non valide, file troppo grande, controllo preliminare fallito) fa fallire l'intera importazione senza creare alcun record. Un errore su una singola riga non blocca l'importazione: la riga finisce tra quelle scartate e l'importazione resta Completata.

2. Importazione Sostenitori

Carica i sostenitori da un file CSV. Vedi le regole generali sopra (formato file, date, booleani, tag, deduplica) prima di preparare il file.

Nessuna colonna è obbligatoria per riga: un sostenitore anonimo (tutte le celle vuote) è valido e viene ignorato senza errore. La deduplica usa la catena supporter external ref → email → ssn → vat.

Colonne disponibili