Importazione Donazioni e Sostenitori su RiseAct

Motivo revisione

La pagina è stata generata da un'email con esito "parse_error" nel processo automatico. Il contenuto è stato recuperato dal corpo email (nessun PDF allegato) e riorganizzato manualmente. Richiede verifica umana per controllare: correttezza dei link esterni citati, coerenza tra le tre sezioni e conferma che nessuna informazione sia andata persa nel parsing originale.

Scopo

Documentare le regole di importazione CSV di sostenitori e donazioni su RiseAct: formato file, regole di validazione dei valori, logica di deduplica, elenco colonne supportate ed esito dell'importazione. Contenuto rivolto a chi deve preparare o caricare file di importazione.

Contenuto ripulito

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

Vincolo	Valore
Righe dati (esclusa 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 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

Colonna	Descrizione