Importazioni CSV

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

• 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) e, 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 è possibile avviarne un'altra per la stessa organizzazione.

Limiti del file

Vincolo	Valore
Righe dati (esclusa l'intestazione)	max 10.000
Dimensione file	max 10 MB
Codifica	UTF-8 (o UTF-8 con BOM)
Separatore	virgola (,)
Valuta	EUR (unica supportata)

File più grandi vanno suddivisi in più importazioni.

Formato dell'intestazione

Le intestazioni sono minuscole, con le parole separate da spazi (non snake case, non Title Case). Esempio: first name, supporter external ref, payment date. Il confronto ignora maiuscole/minuscole e gli spazi esterni; spazi interni multipli vengono normalizzati a uno solo. È la stessa convenzione che usano le esportazioni: un file esportato si corregge in Excel e si ricarica senza rinominare niente.

Due eccezioni:

• le colonne dei campi personalizzati mantengono il prefisso custom_ con underscore (vedi Campi personalizzati);
• le colonne con l'identificativo del record (id, supporter id, donation id) vengono ignorate invece che rifiutate. Un'esportazione le scrive sempre, e un'importazione non deve mai consumarle: gli id sono nostri, un file non può imporli. Qualsiasi altra colonna sconosciuta resta un errore, così un refuso viene comunque intercettato.

Valori: regole di formato

Queste regole valgono per entrambi gli importatori.

• Importi (amount): formato fisso x.xx - cifre intere, punto come separatore decimale, esattamente due decimali (regex ^\d{1,10}\.\d{2}$). Non sono 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): 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.

• Valori booleani (consensi marketing e campi personalizzati BOOLEAN): sono ammesse solo queste coppie (case-insensitive): t/f, true/false, 0/1. Cella vuota = valore non impostato. Qualsiasi altro valore (yes, si, x, ...) 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:

  ...,altro,"x,y,z",altro,...

  La cella "x,y,z" produce tre tag: x, y, z.

Deduplica

Sostenitore - catena di chiavi, la prima che trova vince e si ferma:

supporter external ref → email → ssn → vat

Se nessuna chiave è valorizzata, viene sempre creato un nuovo sostenitore (anonimo). Quando una chiave secondaria (email/ssn/vat) individua più sostenitori, vince quello con id più basso (regola deterministica).

Donazione - chiave donation external ref. Righe con lo stesso donation external ref confluiscono in una sola donazione con più pagamenti. Senza donation external ref ogni riga diventa una donazione one-off separata.

Pagamento - chiave (donazione, data pagamento, importo): evita di contare due volte lo stesso pagamento quando si reimporta il file.

Campi personalizzati

I campi personalizzati si importano con colonne dedicate custom_<key>, dove <key> è la chiave stabile di una definizione di campo personalizzato dell'organizzazione (es. custom_numero_tessera).

• La definizione deve già esistere: l'importazione non crea nuovi campi personalizzati. Una <key> inesistente è un errore di intestazione.
• La colonna viene assegnata all'entità della sua definizione: un custom_<key> di tipo sostenitore va sul sostenitore, uno di tipo donazione va sulla donazione (anche nel file donazioni denormalizzato).
• Nell'importatore sostenitori sono ammesse solo <key> di tipo sostenitore.
• Coerenza dei valori: BOOLEAN segue la regola booleana sopra; SELECT deve essere tra le opzioni della definizione; TEXT senza vincoli.

Report ed esito

Al termine, in Impostazioni → Importazioni trovi:

• stato dell'importazione (In attesa, In corso, Completata, Fallita);
• conteggi dei record creati (sostenitori, donazioni, pagamenti) e delle righe scartate;
• l'elenco delle righe scartate con motivo, ed esportazione CSV del solo sottoinsieme scartato, da correggere e ricaricare.

Un errore a livello di file (CSV illeggibile, intestazioni non valide, file troppo grande, pre-flight 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.

Vedi le pagine dedicate per l'elenco completo delle colonne:

• Importazione sostenitori
• Importazione donazioni