Aggiornamenti

Esportare dati alloggiati: guida pratica per gestori italiani

Esporta i dati degli ospiti per Alloggiati Web con facilità: crea un .txt da 168 caratteri in UTF-8, verifica e conserva la ricevuta firmata.

Esportare dati alloggiati: guida pratica per gestori italiani

Per esportare e inviare correttamente i dati degli ospiti a Alloggiati Web crea un file .txt a lunghezza fissa da 168 caratteri per riga, in codifica UTF-8, verifica con la funzione «Elabora» sul portale e trasmetti le schedine valide entro le tempistiche richieste dalla normativa vigente. Scarica sempre la ricevuta firmata e cancella i dati temporanei una volta confermato l’invio.

In breve:

  • Per rispettare le scadenze di trasmissione, è fondamentale verificare che il file .txt abbia esattamente 168 caratteri per riga e sia in codifica UTF-8 senza BOM.
  • I campi obbligatori, come tipo di alloggiato, dati anagrafici e documentali, devono essere completati rispettando il formato ufficiale e il padding con spazi, soprattutto per capofamiglia e gruppi.
  • Prima di caricare i dati, bisogna controllare che il file non contenga caratteri accentati fuori standard, che le date siano correttamente formattate e che tutte le righe siano prive di errori di struttura.
  • L’uso di Web Service ufficiali semplifica l’automazione, consentendo un controllo più accurato ed eliminando i rischi di errori di formattazione o perdita di tracciabilità.
  • Le ricevute di invio sono valide cinque anni e devono essere scaricate subito dopo l’invio, conservandole in più copie per garantire la conformità in caso di controlli.

Indice

Come generare ed esportare il file .txt compatibile con Alloggiati Web

Molti gestionali per affitti brevi e hotel generano il file di trasmissione in automatico durante il check-in. Quando il software non lo fa, o quando gestisci pochi alloggi, puoi creare il file manualmente seguendo le specifiche pubblicate nel manuale alberghi del portale Alloggiati Web, che prevede una riga per ogni ospite e una lunghezza fissa di 168 caratteri per riga.

La procedura tipica segue questi passaggi:

  1. Raccogli i dati di ogni ospite (documento, cittadinanza, date di soggiorno) prima di iniziare la compilazione.
  2. Compila un record per ogni alloggiato rispettando l’ordine dei campi indicato nel tracciato ufficiale.
  3. Applica il padding richiesto sui campi a lunghezza fissa, come cognome e nome, riempiendo gli spazi vuoti con caratteri spazio fino a raggiungere la lunghezza prevista.
  4. Salva il file in formato .txt con codifica UTF-8, verificando secondo le istruzioni CREAFILE che l’ultimo record non termini con CR+LF.
  5. Controlla il file con un editor di testo semplice prima di caricarlo, evitando programmi che alterano automaticamente la codifica.

Il punto più delicato riguarda proprio l’editor usato per creare o modificare il file. Il manuale CREAFILE segnala che alcuni editor introducono caratteri invisibili o modificano la sequenza di fine riga senza che il gestore se ne accorga, generando errori di validazione difficili da individuare a occhio. Un editor di testo puro, senza formattazione automatica, riduce questo rischio; per chi lavora su più prenotazioni ogni giorno, un piccolo script di esportazione dal proprio gestionale evita del tutto la digitazione manuale.

Prima di caricare il file sul portale, vale la pena eseguire alcuni controlli locali: verifica che non compaiano caratteri accentati fuori standard, che le date seguano il formato richiesto e che ogni riga abbia esattamente 168 caratteri, né uno di più né uno di meno.

Un consiglio: tieni un file modello già formattato correttamente e limitati a sostituire i dati degli ospiti: riduce drasticamente gli errori di struttura.

Campi obbligatori e differenze tra ospite singolo, capofamiglia e capogruppo

Il tracciato del file richiede alcuni blocchi di informazioni sempre presenti per ogni alloggiato, e altri campi aggiuntivi solo per chi è indicato come capofamiglia o capogruppo. Conoscere questa distinzione evita uno degli errori più comuni: compilare tutti gli ospiti con lo stesso livello di dettaglio, quando in realtà i familiari o i membri del gruppo richiedono un tracciato semplificato.

I campi sempre obbligatori, secondo il manuale alberghi Alloggiati Web, comprendono:

  • Tipo di alloggiato, che indica se la persona è singola, capofamiglia, capogruppo, familiare o membro del gruppo.
  • Data di arrivo e durata del soggiorno, espresse nel formato previsto dal tracciato.
  • Cognome e nome, con il padding a spazi fino alla lunghezza fissa prevista dal campo.
  • Data di nascita, luogo di nascita e cittadinanza, tramite i codici numerici ufficiali.
  • Tipo e numero del documento di identità, insieme al codice del luogo di rilascio.

Per capofamiglia e capogruppo il tracciato richiede in più il numero di familiari o componenti del gruppo dichiarati sotto la stessa schedina, mentre i familiari e i membri del gruppo compilano solo i dati anagrafici essenziali, senza ripetere le informazioni sul documento già fornite dal capofamiglia.

I codici numerici per comuni italiani, stati estranei e tipologie di documento non si inventano: vanno recuperati dalle tabelle ufficiali scaricabili dal portale, e vanno tenuti aggiornati perché eventuali variazioni amministrative (fusioni di comuni, nuovi stati) modificano periodicamente questi elenchi.

Un esempio pratico di padding: un cognome come «Rossi», se il campo prevede 50 caratteri, va scritto come «Rossi» seguito da 45 spazi vuoti, mai troncato né lasciato senza riempimento, altrimenti l’intera riga perde l’allineamento e il record successivo viene letto in modo errato dal portale.

Caricare il file sul portale e correggere le schedine respinte

Una volta pronto il file, la trasmissione avviene attraverso la sezione dedicata del portale Alloggiati Web. La sequenza operativa è sempre la stessa, indipendentemente dal numero di ospiti da comunicare:

  1. Accedi alla sezione di caricamento e seleziona il file .txt preparato.
  2. Avvia la funzione «Elabora», che analizza il file e restituisce un conteggio delle schedine corrette e di quelle respinte.
  3. Consulta l’esito riga per riga: il sistema segnala il tipo di errore per ciascuna schedina non accettata, che va isolata e corretta separatamente dal resto del file.
  4. Prosegui con l’invio delle schedine valide, senza attendere la correzione di quelle errate se i tempi di trasmissione stanno per scadere.
  5. Scarica subito la ricevuta e annota l’identificativo della trasmissione, utile in caso di controlli o contestazioni successive.

Come segnala la Questura di Modena, il portale mostra quante schedine sono state acquisite correttamente e quante no, ma la sola schermata di conferma non basta: bisogna sempre scaricare la ricevuta, perché è quella a fare fede in caso di verifica. Se l’invio è parziale, il portale acquisisce solo le righe corrette e il gestore deve correggere e ritrasmettere separatamente quelle respinte, sempre nel rispetto delle finestre temporali previste.

Nei casi in cui il portale risulti temporaneamente non disponibile, restano attive modalità alternative come la trasmissione via PEC o fax alla Questura competente, da usare solo in via eccezionale e documentando il problema tecnico riscontrato: la Questura di Bari chiarisce che un disservizio tecnico non giustifica automaticamente un invio tardivo, quindi conviene attivarsi per tempo piuttosto che aspettare l’ultimo momento utile.

Integrare l’esportazione con i Web Service ufficiali del portale

Per chi gestisce molte prenotazioni, automatizzare l’invio tramite i Web Service ufficiali elimina gran parte del lavoro manuale descritto finora. Il manuale dei servizi web di Alloggiati Web descrive un servizio di cooperazione applicativa pensato proprio per collegare un gestionale esterno al portale.

L’attivazione richiede alcuni passaggi tecnici:

  • Abilitare il servizio Web Service dalla propria area sul portale Alloggiati Web.
  • Generare la WSKEY, la chiave che identifica in modo univoco la struttura verso il sistema.
  • Integrare nel proprio gestionale il metodo GenerateToken, che produce un token temporaneo necessario per ogni chiamata successiva.
  • Usare i metodi di invio e controllo (tra cui Send) per trasmettere le schedine e verificarne l’esito prima della conferma definitiva.
  • Scaricare la ricevuta tramite il metodo dedicato, così da chiudere il ciclo senza tornare sull’interfaccia web.

Il vantaggio principale di questo approccio non è solo la velocità, ma il controllo: ogni chiamata al servizio produce una risposta verificabile, quindi è possibile registrare un log di ogni invio e intercettare subito un errore di formato prima che diventi un problema di conformità.

Un consiglio: testa sempre l’integrazione in un ambiente non definitivo prima di collegarla al flusso reale di prenotazioni: un errore nel formato del token o nella struttura della chiamata può bloccare l’invio di più giorni di schedine insieme.

Non basta esportare correttamente il file: senza una gestione solida di WSKEY, token temporanei e risposte dei metodi Send e GenerateToken, il rischio è perdere traccia dello stato reale di ogni schedina trasmessa.

Flusso di integrazione con token e risposte

Scaricare e conservare le ricevute per i cinque anni previsti

Ogni trasmissione accettata dal portale genera una ricevuta scaricabile dalla sezione dedicata, che riporta l’identificativo della trasmissione, la data, la Questura di riferimento e il numero di schedine incluse. Il documento è firmato digitalmente con un codice di controllo della Polizia di Stato, che ne garantisce l’autenticità secondo quanto descritto nella documentazione sulla ricevuta digitale.

Le ricevute restano scaricabili dal portale per soli 30 giorni dalla data di invio, mentre l’obbligo di conservazione si estende a cinque anni: questa differenza tra disponibilità online e durata dell’obbligo è il motivo per cui molti gestori perdono documenti utili in caso di controllo.

Alcune pratiche riducono questo rischio:

  • Scarica la ricevuta subito dopo ogni invio, senza rimandarla a un momento successivo.
  • Nomina i file in modo coerente, per esempio con data e numero di schedine, così da ritrovarli rapidamente.
  • Conserva le ricevute in almeno due posizioni diverse, ad esempio un archivio locale e uno in cloud.
  • Verifica periodicamente che l’archivio sia completo, confrontando il numero di ricevute con il numero di soggiorni registrati.

Sul fronte della protezione dei dati, la conservazione va gestita in coerenza con il GDPR: i dati anagrafici e i documenti raccolti servono esclusivamente all’adempimento verso la Questura, e vanno trattati con le stesse cautele previste per qualsiasi altro dato personale sensibile, comprese misure di accesso limitato e distruzione una volta scaduti i termini previsti.

Errori comuni nell’esportazione e checklist pre-invio

Gli errori più frequenti nella preparazione del file non riguardano quasi mai il contenuto dei dati, ma la struttura del file stesso. I casi più ricorrenti sono:

  1. Codifica del file diversa da UTF-8, spesso introdotta da un editor che salva automaticamente in un formato diverso.
  2. Padding mancante o errato su campi come cognome e nome, che sposta tutti i caratteri successivi della riga.
  3. Presenza di CR+LF sull’ultimo record del file, quando il tracciato richiede che manchi.
  4. Codici di comune, stato o tipo di documento non aggiornati o inseriti a mano in modo errato.

Alcuni strumenti semplici aiutano a individuare questi problemi prima del caricamento: un editor di testo che mostra i caratteri di fine riga, o un piccolo script che conta i caratteri per riga e segnala eventuali scostamenti dai 168 previsti.

Una checklist pre-invio utile, da ripetere a ogni caricamento:

  1. Il file è salvato in formato .txt con codifica UTF-8 senza BOM.
  2. Ogni riga ha esattamente 168 caratteri.
  3. L’ultimo record non termina con CR+LF.
  4. Tutti i campi a lunghezza fissa hanno il padding corretto.
  5. I codici di comune e stato sono aggiornati alle tabelle ufficiali più recenti.
  6. Le date di arrivo e durata del soggiorno sono coerenti con la prenotazione reale.
  7. Ogni capofamiglia o capogruppo ha il numero corretto di componenti dichiarati.
  8. Il file è stato aperto e controllato visivamente prima del caricamento.

Un consiglio: quando un invio fallisce per motivi tecnici del portale, conserva uno screenshot dell’errore con data e ora: è la prova che serve per giustificare un eventuale ritardo rispetto alle 24 o 6 ore previste.

Quando conviene automatizzare l’esportazione con EuroCheckin

Gestire manualmente l’esportazione funziona bene con pochi ospiti al mese, ma diventa fragile quando le prenotazioni arrivano da più portali contemporaneamente e ogni check-in richiede di raccogliere e riformattare gli stessi dati. EuroCheckin automatizza la registrazione legale degli ospiti sincronizzando i dati raccolti durante il check-in online con Alloggiati Web, riducendo il rischio di errori di formato e duplicati che abbiamo descritto nelle sezioni precedenti.

La soglia in cui vale la pena valutare l’automazione non è tanto il numero assoluto di ospiti, quanto la complessità: più canali di prenotazione attivi (Airbnb, Booking, Vrbo) significano più occasioni di errore manuale nel trascrivere gli stessi dati più volte. Sincronizzare calendario e prenotazioni da un’unica piattaforma elimina questo passaggio ripetitivo, lasciando al gestore solo la verifica finale prima dell’invio.

Per un property manager con più alloggi, o per un host che gestisce il servizio insieme ad altre attività, il tempo risparmiato sulla compilazione manuale del file si traduce in meno margine di errore nelle scadenze di 24 o 6 ore, e in una gestione più semplice delle ricevute da conservare per i cinque anni previsti dalla normativa.

Cosa sottovalutano davvero i gestori su Alloggiati Web

La parte più fraintesa di questo adempimento non è il formato del file, ma la gestione del tempo. Molti gestori si concentrano sulla correttezza tecnica della schedina e trascurano che la finestra di 6 ore per i soggiorni brevi lascia pochissimo margine di errore quando il check-in avviene a orari serali o notturni, un momento in cui la disponibilità del portale stesso può essere meno stabile.

La convinzione diffusa che basti «avere il file pronto» per essere in regola è incompleta: senza un controllo sistematico dell’esito di ogni invio, e senza un archivio ordinato delle ricevute, il gestore resta esposto anche quando ha rispettato la procedura tecnica. La conformità reale si misura nella capacità di dimostrare, mesi o anni dopo, che ogni ospite è stato comunicato nei tempi corretti.

Chi gestisce più di due o tre alloggi dovrebbe smettere di trattare l’esportazione come un’attività isolata per ogni prenotazione, e iniziare a pensarla come un processo continuo da monitorare, con controlli periodici sull’archivio delle ricevute tanto quanto sulla qualità dei file inviati.

— Sofía Herrera

Scopri EuroCheckin: prova, assistenza e contatti

Se gestisci uno o più alloggi e vuoi togliere dalla lista delle cose da controllare ogni giorno la compilazione manuale del file per Alloggiati Web, EuroCheckin sincronizza automaticamente i dati raccolti durante il check-in online con il portale della Polizia di Stato, con un prezzo mensile accessibile per alloggio.

Eurocheckin

La piattaforma è pensata per chi gestisce affitti brevi su Airbnb, Booking e Vrbo, ma anche per strutture alberghiere che gestiscono più prenotazioni contemporaneamente attraverso EuroCheckin per hotel, disponibile a 3 € al mese per alloggio.

Tra le funzionalità utili per l’esportazione e l’invio automatico:

  • Sincronizzazione automatica delle prenotazioni da più canali OTA, senza inserimento manuale ripetuto.
  • Check-in online multilingua che raccoglie i dati direttamente dall’ospite prima dell’arrivo.
  • Configurazione assistita per l’attivazione dei Web Service e della generazione della WSKEY.
  • Conservazione dei dati conforme al GDPR, con gestione centralizzata delle ricevute.

Per chi vuole una mano nella configurazione iniziale, il team offre assistenza dedicata per la registrazione e la configurazione. Chi vuole partire subito può scoprire i piani su EuroCheckin e valutare quale soluzione si adatta meglio alla propria struttura.

Per verificare o approfondire quanto descritto in questa guida, la documentazione ufficiale della Polizia di Stato resta il riferimento più affidabile. Il manuale alberghi del portale Alloggiati Web descrive il tracciato completo dei campi obbligatori, mentre le istruzioni CREAFILE spiegano nel dettaglio la creazione del file precompilato.

Per chi vuole integrare l’invio tramite software gestionale, il manuale dei servizi web copre l’attivazione della WSKEY e i metodi disponibili. Le FAQ ufficiali sulle ricevute chiariscono infine i tempi di disponibilità online e conservazione.

Domande frequenti

È obbligatorio registrare gli ospiti in Italia?

Sì, la comunicazione dei dati degli alloggiati alla Questura è un obbligo di legge previsto dall’articolo 109 del TULPS e si applica a hotel, B&B, case vacanza e a qualsiasi struttura che ospiti persone a pagamento. L’obbligo riguarda chi gestisce la struttura, non l’ospite, e comprende la verifica del documento di identità al momento dell’arrivo.

Come si comunicano i dati degli alloggiati alla Questura?

I dati vanno trasmessi tramite il portale Alloggiati Web, caricando un file .txt conforme al tracciato ufficiale oppure integrando il proprio gestionale con i Web Service dedicati. La trasmissione va completata entro 24 ore dall’arrivo, o entro 6 ore per soggiorni inferiori alle 24 ore.

Come si scarica il certificato per Alloggiati Web?

Le credenziali di accesso e la documentazione tecnica per operare sul portale si ottengono registrando la struttura presso la Questura competente, che abilita l’account sul sistema Alloggiati Web. Le tabelle codici e i manuali tecnici sono invece scaricabili direttamente dalle pagine ufficiali del portale.

Come si scaricano le ricevute di Alloggiati Web?

Dopo ogni invio andato a buon fine, la ricevuta è disponibile nella sezione dedicata del portale e riporta l’identificativo della trasmissione insieme al numero di schedine acquisite. Le ricevute restano scaricabili online per soli 30 giorni, quindi vanno salvate e conservate autonomamente per il periodo di cinque anni richiesto dalla normativa.

Raccomandati

Articoli simili