L’invio massivo degli alloggiati si fa caricando un file TXT precompilato oppure tramite servizi web con chiave WSKEY sul Portale Alloggiati Web della Polizia di Stato. La comunicazione va completata entro 24 ore dall’arrivo dell’ospite, o in tempi molto brevi per soggiorni inferiori a un giorno. La prova dell’adempimento è la ricevuta digitale generata dal sistema dopo l’invio, da scaricare e conservare.
In breve:
- L’invio massivo tramite file TXT richiede righe di 168 caratteri in codifica ASCII con terminatori CR+LF e un formato preciso per evitare errori di elaborazione.
- La gestione tramite servizi web con WSKEY automatizza e velocizza il processo, eliminando quasi del tutto l’intervento manuale e riducendo gli errori di formattazione.
- Le cause più frequenti di rifiuto dei file sono errori di lunghezza, caratteri non ASCII o formati di data incoerenti, facilmente correggibili con adeguata normalizzazione.
- La conservazione corretta della ricevuta digitale, generata dopo ogni invio, costituisce prova legale essenziale in caso di controlli.
- Per strutture con più di due o tre unità, l’automazione attraverso software come EuroCheckin rappresenta un investimento che risparmia tempo e garantisce la tracciabilità dei dati.
Indice
- Quali modalità esistono per l’invio massivo alloggiati?
- Come deve essere strutturato il file TXT per l’invio massivo?
- Come si ottiene la WSKEY per integrare il gestionale?
- Come si crea e si carica un file per l’invio massivo?
- Perché il portale rifiuta il mio file di invio massivo?
- Cosa prevedono la normativa e il Garante sulla privacy?
- Cosa fare con la ricevuta digitale dopo l’invio
- Perché automatizzare l’invio conviene davvero
- EuroCheckin: automatizzare l’invio massivo senza rincorrere ogni schedina
- Fonti
- Domande frequenti
Quali modalità esistono per l’invio massivo alloggiati?
Il Portale Alloggiati Web offre tre strade per comunicare le generalità degli ospiti, e la scelta cambia parecchio in base a quante persone gestisci ogni settimana. Chi ha una sola stanza può ancora permettersi l’inserimento manuale scheda per scheda. Chi gestisce dieci appartamenti no.
Inserimento online diretto. Si compila una schedina alla volta dall’interfaccia web del portale. Funziona bene per chi ospita pochi arrivi al mese, ma diventa insostenibile con più di tre o quattro check-in al giorno: ogni schedina richiede diversi campi obbligatori e il rischio di errori di digitazione cresce con la stanchezza operativa più che con il volume in sé.
Invio massivo tramite file TXT. Si costruisce un file di testo con una riga per ogni alloggiato e si carica sul portale in un’unica operazione. Il sistema elabora il file, segnala quante righe sono corrette e quante contengono errori, e permette un invio parziale delle sole schedine valide mentre si corregge il resto. È la soluzione più pratica per chi lavora con più unità o riceve gruppi numerosi, come documentato nella guida ufficiale del servizio.
Servizi web tramite WSKEY. È il livello più avanzato: il gestionale della struttura dialoga direttamente con Alloggiati Web tramite chiamate SOAP, senza che nessuno debba manualmente scaricare, compilare o caricare file. Richiede una configurazione tecnica iniziale, ma elimina quasi del tutto l’intervento umano nel processo quotidiano.
Le tre modalità non si escludono a vicenda. Molte strutture usano il file TXT come base e passano ai servizi web quando il volume di prenotazioni giustifica l’investimento in un’integrazione automatica. In tutti i casi, l’accesso al sistema richiede credenziali rilasciate dalla questura territorialmente competente, e da qualche anno il portale applica l’autenticazione a due fattori per proteggere l’accesso a dati sensibili come documenti d’identità e generalità degli ospiti.
Le differenze pratiche tra le tre opzioni si riassumono così:
- L’inserimento online è gratuito e immediato ma richiede tempo proporzionale al numero di ospiti.
- Il file TXT accelera drasticamente gli invii multipli ma richiede attenzione al formato.
- I servizi web eliminano il lavoro manuale ma richiedono una configurazione tecnica o un software che la gestisca per te.
- Tutte e tre le vie producono la stessa ricevuta digitale come prova dell’invio.
Come deve essere strutturato il file TXT per l’invio massivo?
Ogni riga del file deve avere esattamente 168 caratteri, né uno di più né uno di meno. È la regola più rigida del tracciato record descritto nel manuale CreaFile, e la sua violazione è la causa più comune di rifiuto in fase di elaborazione. Ogni riga corrisponde a un alloggiato: se una famiglia di quattro persone soggiorna insieme, il file conterrà quattro righe distinte, con la prima dedicata al capofamiglia o capogruppo e le successive ai componenti.
La codifica deve essere ASCII, e al termine di ogni riga, eccetto l’ultima, vanno inseriti i caratteri CR+LF (Carriage return più line feed). Dimenticare questo terminatore, o aggiungerlo anche dopo l’ultima riga, genera errori di elaborazione che bloccano l’intero file anche se una sola riga è fuori formato. I caratteri accentati o simboli non previsti dalla tabella ASCII sono un’altra fonte frequente di rifiuto, motivo per cui vale la pena normalizzare nomi e cognomi prima di generare il file.
I campi obbligatori includono tipo di alloggiato, data di arrivo, numero di giorni di permanenza, generalità complete, tipo e numero del documento, comune o stato di nascita e cittadinanza. I campi vuoti non si eliminano: vanno riempiti con spazi fino a raggiungere la lunghezza prevista per quel campo, mantenendo intatta la struttura a posizioni fisse della riga.
| Elemento del tracciato | Regola |
|---|---|
| Lunghezza riga | Esattamente 168 caratteri |
| Terminatore riga | CR+LF su ogni riga tranne l’ultima |
| Codifica caratteri | ASCII, niente accenti o simboli estesi |
| Campi vuoti | Riempiti con spazi, non omessi |
| Ordine righe | Capofamiglia/capogruppo prima, componenti a seguire |
| Tabelle di riferimento | Comuni, stati estivi, tipi documento con codici numerici standard |
I codici di comuni, stati estranei e tipologie di documento seguono tabelle numeriche standard fornite dal portale stesso, e vanno consultate ogni volta che si aggiorna il file, perché un codice comune errato produce uno scarto della riga tanto quanto un errore di lunghezza.
Come si ottiene la WSKEY per integrare il gestionale?
La WSKEY si richiede alla questura competente, insieme alle credenziali di accesso ordinarie al Portale Alloggiati Web. Una volta ottenuta, la chiave permette al proprio gestionale, o a un software esterno, di generare un token di autenticazione temporaneo che autorizza le chiamate ai servizi web senza bisogno di login manuale ogni volta.
Il manuale tecnico dei servizi web descrive l’endpoint unico del sistema, service.asmx, e i metodi SOAP disponibili per l’invio delle schedine. Un esempio concreto è il metodo GestioneAppartamenti_FileUnico_Send, pensato proprio per chi gestisce più unità abitative e deve trasmettere in un’unica chiamata i dati relativi a diversi alloggi. Altri metodi gestiscono l’autenticazione, il rinnovo del token e la verifica dell’esito di elaborazione.
I vantaggi dell’integrazione via web service si vedono soprattutto nel tempo. Chi collega il proprio software di gestione prenotazioni direttamente al portale elimina il passaggio manuale di esportazione e caricamento del file, e riduce drasticamente gli errori di formattazione che nascono dalla digitazione o dalla conversione manuale dei dati, come confermano le indicazioni tecniche del manuale WS. La sincronizzazione con i calendari delle piattaforme OTA diventa quasi automatica quando il gestionale riceve già i dati dell’ospite al momento della prenotazione.
Sul fronte della sicurezza, alcune attenzioni sono imprescindibili:
- Il token generato dalla WSKEY ha una durata limitata e va rinnovato periodicamente, non conservato a tempo indeterminato.
- Tutte le chiamate devono avvenire su connessione HTTPS, mai in chiaro.
- I dati trasmessi vanno cifrati durante il transito, non solo protetti da password.
- Il ciclo di vita del token richiede un sistema di log e retro per gestire gli esiti restituiti dal servizio in caso di errore temporaneo.
Chi non ha competenze tecniche interne per gestire questa integrazione può affidarsi a software specializzati che dialogano già con l’API del portale, evitando di dover scrivere da zero le chiamate SOAP.
Come si crea e si carica un file per l’invio massivo?
Seguire un ordine preciso evita la maggior parte degli errori di elaborazione, soprattutto quando si gestiscono decine di schedine contemporaneamente.
- Estrai i dati dal gestionale o dal foglio di lavoro. Raccogli generalità, documento, date di arrivo e permanenza per ogni ospite in un formato tabellare pulito, senza celle vuote nei campi obbligatori.
- Mappa ogni campo sulla posizione corretta del tracciato. Costruisci ogni riga rispettando l’ordine dei campi previsto dal manuale, aggiungendo spazi di padding dove un campo non raggiunge la lunghezza richiesta.
- Verifica codifica e terminatori di riga. Controlla che il file sia salvato in ASCII puro e che ogni riga, tranne l’ultima, termini con CR+LF; un editor di testo semplice o uno script di validazione locale individua rapidamente eventuali anomalie.
- Carica il file su Alloggiati Web. Nella sezione dedicata, seleziona il file e avvia la funzione Elabora: il sistema mostra quante schedine sono corrette e quante contengono errori.
- Analizza l’esito e scegli tra invio parziale o totale. Se alcune righe risultano errate, puoi inviare subito quelle valide e correggere le altre separatamente, evitando di bloccare l’intero adempimento per un singolo errore.
- Scarica la ricevuta. Dopo l’invio, il portale genera un documento PDF che attesta l’operazione: conservalo come prova legale.
Un consiglio: prima di caricare un file con cinquanta o cento schedine, testa la procedura con tre o quattro record fittizi ma formalmente corretti. Se il sistema li accetta, il problema di eventuali errori successivi sarà nei dati, non nel formato del file.
Costruire il file a mano con un editor di testo funziona per volumi piccoli, ma diventa rischioso sopra le venti o trenta righe giornaliere: un errore di conteggio caratteri in una riga si propaga silenziosamente a tutte le successive se si usa un editor senza controllo automatico della lunghezza.
Perché il portale rifiuta il mio file di invio massivo?
Il messaggio di errore che compare dopo l’elaborazione indica quasi sempre il numero della riga non conforme, ed è il primo posto dove guardare. Risalire dalla riga al record originale nel proprio archivio permette di isolare il problema senza dover ricontrollare l’intero file.
Le cause più frequenti di scarto sono poche e ricorrenti:
- Lunghezza riga errata. Anche un solo carattere in più o in meno sposta tutti i campi successivi e fa fallire la validazione, come indicato nelle specifiche tecniche del tracciato.
- Caratteri non ASCII. Lettere accentate, apostrofi tipografici o simboli speciali nei nomi provenienti da copia e incolla da documenti Word sono una causa comune e facile da correggere con una normalizzazione automatica.
- Date di arrivo incoerenti. Una data di arrivo posteriore alla data di generazione del file, o una relazione errata tra capofamiglia e componenti del gruppo, genera un rifiuto logico anche quando il formato è corretto.
- Terminatori di riga mancanti o duplicati. L’assenza di CR+LF su una riga intermedia, o la sua presenza sull’ultima riga, sono errori invisibili a occhio nudo ma bloccanti per il sistema.
Se il Portale Alloggiati Web risulta temporaneamente non disponibile, il decreto del 2013 prevede una via alternativa: comunicare i dati alla questura competente tramite fax o PEC, segnalando contestualmente l’impedimento tecnico che ha reso impossibile l’invio telematico. Chi non dispone ancora della WSKEY o delle credenziali del portale deve comunque procedere con l’inserimento manuale o contattare la questura per attivare l’accesso prima della scadenza del termine legale.
Cosa prevedono la normativa e il Garante sulla privacy?
L’obbligo di comunicazione nasce dall’articolo 109 del TULPS e trova le sue modalità operative nel D.M. 07/01/2013, che fissa i termini di 24 e 6 ore e descrive le procedure ammesse, incluse quelle alternative in caso di malfunzionamento del portale.
Sul fronte della privacy, il Garante per la protezione dei dati personali ha chiarito un punto che molti gestori ignorano: conservare copie dei documenti d’identità degli ospiti oltre il tempo strettamente necessario alla comunicazione al portale non è consentito. L’unico elemento che va conservato è la ricevuta digitale dell’invio, non la fotografia o la scansione della carta d’identità.
Alcune indicazioni pratiche derivano direttamente da questi principi:
- Separa i dati raccolti per finalità di pubblica sicurezza da quelli eventualmente raccolti per finalità fiscali o contrattuali.
- Evita canali non sicuri come le app di messaggistica per ricevere immagini di documenti dagli ospiti.
- Pianifica la cancellazione sistematica delle copie dei documenti subito dopo l’invio della schedina.
- Forma il personale che gestisce il check-in sulle regole di conservazione e cancellazione dei dati.
Cosa fare con la ricevuta digitale dopo l’invio
La ricevuta si scarica direttamente dal Portale Alloggiati Web al termine della sessione di invio, sia che si tratti di una singola schedina sia di un file massivo con centinaia di righe. Il documento, in formato PDF, riporta il numero di schedine trasmesse per ciascuna data e costituisce la prova formale dell’adempimento richiesto dalla legge.
Conservare questa ricevuta non è una formalità opzionale: in caso di controllo da parte della questura, è il documento che dimostra che la comunicazione è stata effettuata nei termini previsti. Alcune buone pratiche di archiviazione aiutano a evitare problemi futuri:
- Organizza le ricevute per data e struttura in una cartella digitale accessibile e con backup.
- Verifica che ogni ricevuta corrisponda al numero effettivo di ospiti registrati quel giorno.
- Se l’invio riguarda più unità abitative, mantieni una ricevuta distinta per ciascuna struttura.
- Se la ricevuta non viene generata o il download fallisce, comunica subito l’anomalia alla questura competente, indicando data e orario del tentativo di invio.
Perché automatizzare l’invio conviene davvero
Chi gestisce più di due o tre unità abitative arriva presto a un punto in cui il tempo speso a costruire manualmente file TXT o a inserire schedine una a una supera quello dedicato all’accoglienza vera e propria. L’automazione non è un lusso per grandi catene hotel: è una necessità operativa per chi affitta anche solo cinque appartamenti su più portali OTA.
Il vantaggio principale non è solo la velocità. È la riduzione degli errori che si accumulano quando si copiano manualmente dati da una prenotazione Airbnb a un file di testo con posizioni fisse a 168 caratteri. Un sistema che sincronizza automaticamente le prenotazioni con l’invio delle schedine elimina anche il rischio, tutt’altro che teorico, di dimenticare un ospite o di sbagliare una data di arrivo durante una settimana con dieci check-in.
C’è poi il tema della tracciabilità: un archivio digitale organizzato delle ricevute, generato automaticamente a ogni invio, vale molto più di una cartella di PDF scaricati a mano e forse dimenticati su un computer diverso ogni volta.
— Sofía Herrera
EuroCheckin: automatizzare l’invio massivo senza rincorrere ogni schedina
Esistono software che automatizzano la sincronizzazione delle prenotazioni da diverse piattaforme e inviano direttamente i dati degli ospiti ad Alloggiati Web senza dover costruire manualmente file TXT.
Alcune piattaforme offrono il check-in online multilingua per gli ospiti, permettendo che le generalità arrivino già pronte prima dell’arrivo fisico in struttura, riducendo il lavoro amministrativo e il rischio di errori di trascrizione. Per chi gestisce più appartamenti, questo significa passare da ore di inserimento dati a pochi minuti di verifica. Chi ha bisogno di attivare la chiave WSKEY o di configurare l’integrazione con il proprio gestionale può contare sull’assistenza dedicata offerta dalla piattaforma.
Il piano EuroCheckin parte da 5 € al mese per alloggio, mentre chi gestisce hotel o strutture di dimensioni maggiori trova un’opzione dedicata con EuroCheckin per hotel a partire da 3 € al mese per alloggio. Attiva la prova per verificare quanto tempo puoi recuperare dalla prossima ondata di check-in.
Fonti
Per verificare direttamente le regole descritte in questo articolo, conviene partire dai documenti ufficiali: il manuale del servizio Alloggiati Web spiega l’intero processo di elaborazione e invio, mentre le specifiche del tracciato record restano il riferimento per chi costruisce file TXT in autonomia. Chi integra un gestionale tramite servizi web trova la documentazione completa nel manuale tecnico dei servizi web. Sul fronte privacy, i chiarimenti del Garante sulla gestione dei documenti d’identità restano il punto di riferimento più aggiornato.
Questo articolo fornisce informazioni generali e non sostituisce il parere di un avvocato qualificato. Consulta un professionista legale qualificato riguardo al tuo caso specifico prima di agire in base a questo contenuto.
- CreaFile — specifiche per invio file precompilati
- Parere del Garante sulla gestione dei documenti d’identità nelle strutture ricettive (2026)
Domande frequenti
È obbligatorio registrare gli ospiti in Italia?
Sì, per legge tutte le strutture ricettive, incluse quelle di affitto breve e i B&B, devono comunicare le generalità degli ospiti al Portale Alloggiati Web. L’obbligo nasce dall’articolo 109 del TULPS e dal D.M. 07/01/2013, con termine di 24 ore dall’arrivo o 6 ore per soggiorni più brevi.
Come posso inviare le schedine degli alloggiati su Alloggiati Web?
Puoi inserirle manualmente una a una, caricare un file TXT con più schedine in un’unica operazione, oppure integrare il gestionale tramite servizi web con la chiave WSKEY. Per volumi elevati, l’invio massivo tramite file o l’integrazione automatica riducono drasticamente il tempo e gli errori rispetto all’inserimento manuale.
Chi controlla le schedine alloggiate?
Le schedine trasmesse arrivano alla questura territorialmente competente, che le utilizza per finalità di pubblica sicurezza. La ricevuta digitale generata dal portale dopo ogni invio è il documento che il gestore deve conservare come prova in caso di controllo.
Come devo comunicare i miei ospiti alla questura come B&B?
Un B&B segue esattamente le stesse regole di un hotel: comunicazione entro 24 ore (o 6 ore per soggiorni brevi) tramite il Portale Alloggiati Web, con credenziali richieste alla questura competente. Chi gestisce più camere o unità simultaneamente può usare l’invio massivo tramite file TXT invece dell’inserimento manuale singolo.
Quanto costa automatizzare l’invio con EuroCheckin?
Il piano EuroCheckin per affitti brevi parte da 5 € al mese per alloggio, mentre EuroCheckin per hotel parte da 3 € al mese per alloggio. Entrambi i piani includono la sincronizzazione con Alloggiati Web e il check-in online per gli ospiti.
