Sì, puoi automatizzare l’invio delle schedine alla Polizia di Stato. Il Portale Alloggiati Web espone un Web Service SOAP ufficiale che permette di sostituire il caricamento manuale con chiamate automatiche dal tuo gestionale o dal software di property management.
Il percorso pratico è sempre lo stesso:
- richiedi le credenziali alla Questura competente;
- abilita la WSKEY (chiave web service) dal tuo profilo sul portale;
- usa l’operazione GenerateToken per autenticarti;
- invia i dati con Send o FileUnico.
Rispettare questo flusso significa restare in regola con l’art. 109 del TULPS, che impone la comunicazione degli ospiti entro 24 ore dall’arrivo, o immediatamente per soggiorni inferiori alle 24 ore, ed eliminare gran parte del lavoro manuale di digitazione.
Punti chiave
Automatizzare l’invio delle schedine richiede WSKEY, GenerateToken e una gestione XML conforme al WSDL ufficiale del Portale Alloggiati Web.
| Punto | Dettagli |
|---|---|
| Prima l’amministrazione | Richiedi le credenziali alla Questura e attiva la WSKEY prima di iniziare lo sviluppo tecnico. |
| Protocollo SOAP, non REST | Usa un client SOAP e genera il proxy dal WSDL per evitare errori di serializzazione XML. |
| Rispetta i tempi di legge | Invia i dati entro 24 ore dall’arrivo, o subito per soggiorni inferiori a un giorno. |
| Proteggi le credenziali | Conserva WSKEY e token in un vault dedicato e ruotali periodicamente per limitare i rischi. |
| Alternativa gestita | EuroCheckin sincronizza automaticamente le prenotazioni OTA con Alloggiati Web, con un tasso di successo del 99,9% tra oltre 3.000 host. |
Indice
- Requisiti legali e amministrativi prima di integrare l’API
- Come funziona l’architettura tecnica dell’API Alloggiati Web
- Come abilitare la WSKEY e generare il token di accesso
- Quali operazioni servono per inviare le schedine
- Perché le chiamate API vengono rifiutate
- Sicurezza dei dati e conformità al GDPR nell’integrazione
- Come EuroCheckin semplifica l’integrazione con Alloggiati Web
- Cosa conta davvero in questa integrazione
- Richiedi assistenza per l’integrazione Alloggiati Web
- Fonti
Requisiti legali e amministrativi prima di integrare l’API
Prima di toccare una riga di codice, devi passare dalla parte amministrativa. La legge non lascia margini di interpretazione: ogni struttura ricettiva, dall’appartamento singolo all’hotel con cento camere, deve trasmettere le generalità degli ospiti entro le 24 ore dall’arrivo, o subito se il soggiorno dura meno di un giorno.
Per ottenere l’accesso al sistema devi seguire questi passaggi:
- presentare richiesta di credenziali alla Questura di competenza territoriale (il metodo varia: alcune Questure richiedono il ritiro di persona, altre accettano una PEC);
- attendere l’assegnazione di utente e password per il portale;
- abilitare, una volta dentro il portale, il servizio di cooperazione applicativa che genera la WSKEY necessaria per le chiamate API.
Senza questo passaggio amministrativo, nessuna integrazione tecnica può partire: la Questura resta il gatekeeper di tutto il processo.
Come funziona l’architettura tecnica dell’API Alloggiati Web
L’endpoint ufficiale è service.asmx, raggiungibile aggiungendo il parametro ?wsdl all’URL per scaricare la definizione completa del servizio. Questo dettaglio cambia tutto l’approccio di sviluppo: Alloggiati Web non è un’API REST. Non troverai risposte JSON né endpoint in stile /api/v1/guests. Il servizio è basato su protocollo SOAP, con messaggi XML strutturati secondo namespace e schemi definiti nel WSDL stesso.
Per un tecnico abituato a REST, questo significa tre cose pratiche:
- Serve un client SOAP, non una semplice libreria HTTP: in .NET puoi generare il proxy direttamente da Visual Studio puntando al WSDL, in Java strumenti come wsimport fanno lo stesso lavoro, in Python librerie come Zeep gestiscono la serializzazione XML senza doverla scrivere a mano.
- Ogni richiesta deve rispettare rigorosamente lo schema XML previsto: un tag fuori posto o un encoding sbagliato genera un rigetto immediato.
- La gestione degli errori richiede di leggere le ricevute restituite dal servizio, non semplici codici HTTP.
Un consiglio: prima di scrivere codice di produzione, scarica il WSDL e genera il client con gli strumenti della tua piattaforma. Risparmi ore di debug su problemi di serializzazione che non hanno nulla a che fare con la logica di business.
Come abilitare la WSKEY e generare il token di accesso
Abilitare il servizio richiede pochi passaggi, ma vanno seguiti nell’ordine giusto.
- Accedi al portale con le credenziali fornite dalla Questura e vai al menu Accesso → Codici (o all’area personale, secondo la versione dell’interfaccia).
- Individua la sezione dedicata alla chiave web service: da qui generi la WSKEY per la prima volta.
- Salva la chiave in un posto sicuro: puoi rigenerarla in caso di compromissione, ma la rigenerazione invalida immediatamente quella precedente.
- Nel tuo codice, chiama l’operazione GenerateToken passando utente, password e WSKEY: il servizio restituisce un token temporaneo da usare nelle chiamate successive.
Alcuni punti da tenere a mente durante questa fase:
- il token ha una validità limitata nel tempo, quindi il tuo sistema deve rigenerarlo periodicamente, non salvarlo come credenziale permanente;
- se la WSKEY viene rigenerata, tutte le integrazioni che usano quella vecchia iniziano a fallire senza preavviso;
- conviene testare il flusso con un client SOAP generico (come SoapUI) prima di integrarlo nel codice definitivo.
Quali operazioni servono per inviare le schedine
Il Web Service espone diverse operazioni pensate per casi d’uso specifici, e sceglierla giusta evita parecchi mal di testa.
- Send invia le schedine standard per una singola struttura.
- GestioneAppartamenti_Send serve a chi gestisce più unità sotto lo stesso account: in questo caso ogni chiamata deve includere l’IdAppartamento, un identificativo che il portale assegna a ciascun appartamento registrato.
- FileUnico_Send permette di raggruppare più schedine in un solo invio, utile quando arrivano prenotazioni multiple nello stesso giorno.
- Ricevuta recupera l’esito dell’invio: è l’unico modo per sapere se i dati sono stati accettati o rigettati.
Ogni schedina richiede campi obbligatori precisi: dati anagrafici completi dell’ospite, tipo e numero del documento d’identità, nazionalità, data di arrivo e durata prevista del soggiorno. Un campo mancante o formattato male blocca l’intera trasmissione, non solo la riga interessata.
Un consiglio: se gestisci più appartamenti, verifica l’IdAppartamento corretto prima di ogni batch di invio. È l’errore più comune tra chi passa da una singola struttura a un portfolio di unità multiple.
Perché le chiamate API vengono rifiutate
La maggior parte dei problemi di integrazione ricade in tre categorie, e conoscerle in anticipo fa risparmiare ore di debug.
- Autenticazione fallita: token scaduto, WSKEY errata o rigenerata di recente, oppure permessi non ancora attivi sull’account. Controlla sempre l’orario di sistema del server: uno sfasamento con quello del portale può invalidare il token.
- XML non valido: caratteri speciali non gestiti nell’encoding UTF-8, tag fuori sequenza rispetto allo schema del WSDL, o campi obbligatori vuoti. Validare l’XML contro lo schema prima dell’invio, come suggerisce il manuale ufficiale, riduce drasticamente i rigetti in produzione.
- Ricevute non interpretate correttamente: il sistema restituisce un esito che va letto e loggato, non solo scartato. Un rigetto silenzioso oggi diventa una violazione dell’art. 109 TULPS domani.
Quando i controlli di base non risolvono il problema, il canale di supporto della Questura resta il riferimento per casi non documentati nel manuale.
Sicurezza dei dati e conformità al GDPR nell’integrazione
I dati che transitano in queste chiamate sono dati personali sensibili: documenti d’identità, nazionalità, date di soggiorno. Trattarli con leggerezza è un rischio legale, non solo tecnico.
- Conserva WSKEY e credenziali in un secret manager o vault dedicato, mai in file di configurazione versionati su repository condivisi.
- Usa sempre HTTPS per ogni chiamata, mantieni un logging minimo (giusto quanto basta per il debug) e definisci una policy di conservazione delle ricevute coerente con i tempi richiesti dalla normativa.
- Ruota periodicamente la WSKEY e limita l’accesso alle credenziali solo a chi gestisce effettivamente l’integrazione.
Un consiglio: documenta chi ha accesso alle credenziali Alloggiati Web nella tua azienda. In caso di audit o di richiesta della Questura, dover ricostruire questa informazione a memoria è un problema evitabile. Per un approfondimento sulle pratiche di protezione dati in ambienti cloud, la guida di Rioton sulla sicurezza e conformità dei dati offre un quadro utile applicabile anche a questo contesto.
Come EuroCheckin semplifica l’integrazione con Alloggiati Web
Non tutti i gestori hanno un tecnico interno pronto a lavorare con SOAP e WSDL. EuroCheckin nasce esattamente per questo scenario: la piattaforma sincronizza automaticamente i dati degli ospiti con Alloggiati Web, gestendo l’intera comunicazione con la Questura senza richiedere competenze di programmazione da parte del gestore.
- La sincronizzazione automatica riduce il rischio di errori manuali e di duplicati nelle schedine, uno dei problemi più frequenti tra chi lavora ancora a mano.
- Più di 3.000 host si affidano già alla piattaforma, con un tasso di successo del 99,9% nelle registrazioni trasmesse.
- Il servizio include assistenza per l’attivazione della WSKEY, import automatico delle prenotazioni da Airbnb, Booking e altre piattaforme OTA, e gestione centralizzata delle ricevute.
Per chi affitta su più portali contemporaneamente, la sincronizzazione dei calendari evita anche il problema separato del doppio booking, che spesso si accompagna alla gestione manuale delle schedine.
Cosa conta davvero in questa integrazione
L’ordine delle priorità qui è quasi sempre invertito rispetto a quello che i tecnici vorrebbero seguire. La parte amministrativa, la richiesta alla Questura, i tempi di attesa per le credenziali, va risolta prima di aprire l’IDE. Ho visto troppi sviluppatori perdere settimane a costruire un’integrazione perfetta contro un WSDL, per poi scoprire che l’account non era ancora abilitato al servizio di cooperazione applicativa.
Se in azienda non c’è nessuno che vuole occuparsi di SOAP e gestione token, non è una sconfitta scegliere una soluzione gestita: è una scelta razionale che limita il rischio di non conformità. E per chi decide di integrare in autonomia, testare il flusso con poche schedine reali prima di automatizzare tutto il volume delle prenotazioni resta il modo più sicuro per individuare errori prima che diventino un problema con la Questura.
Richiedi assistenza per l’integrazione Alloggiati Web
Se preferisci non gestire in casa WSKEY, token e validazione XML, EuroCheckin ti fa risparmiare le settimane che servirebbero a costruire e testare tutto da zero: un tecnico configura l’integrazione con Alloggiati Web al posto tuo, mentre tu resti concentrato sulla gestione degli ospiti.
Con EuroCheckin ottieni la sincronizzazione automatica delle prenotazioni da Airbnb, Booking e Vrbo, l’invio delle schedine senza intervento manuale e un archivio ordinato delle ricevute pronto per eventuali controlli. È la stessa logica del Web Service ufficiale, ma senza dover scrivere o mantenere codice SOAP internamente.
Richiedi oggi l’assistenza per la configurazione dell’integrazione e verifica in pochi giorni quanto tempo puoi recuperare ogni settimana sulla gestione amministrativa degli ospiti.
Fonti
- Portale Alloggiati Web - Polizia di Stato
