Comunicare gli ospiti alle autorità in Italia e Spagna, in automatico

L'obbligo, in breve

Se ospiti persone paganti in Italia o in Spagna devi comunicarle alle autorità: in Italia tramite Alloggiati Web, in Spagna tramite SES.Hospedajes. Entrambi fissano un termine misurato in ore dall'arrivo, non in giorni dalla partenza. Entrambi valgono per ospite, non per prenotazione: una famiglia di quattro persone sono quattro record.

Questa guida parla di cosa comporta tutto ciò per il software. Non è consulenza legale, e i requisiti operativi cambiano: verifica le regole vigenti con l'autorità o con il tuo consulente prima di affidarti a qualsiasi implementazione.

Perché la scadenza cambia l'architettura

Ventiquattro ore sembrano generose finché non noti cosa escludono.

Escludono la comunicazione come effetto collaterale di un batch notturno, perché un ospite arrivato alle 18:00 di venerdì non può aspettare quello che gira lunedì. Escludono la comunicazione in linea con il check-in sperando che vada bene, perché se in quel momento l'endpoint dell'autorità è irraggiungibile il record è semplicemente perso e nessuno riproverà. Ed escludono di trattare un invio fallito come un errore da mostrare a schermo, perché la persona che avrebbe visto quell'errore è andata a casa.

Quello che serve, invece, è una coda con ritentativi che gira almeno ogni ora, e una traccia di cosa è stato comunicato, quando e con quale protocollo. In Boris il passo di comunicazione è una delle quattro aree di esecuzione contrassegnate come obbligatorie, proprio perché il suo fallimento è silenzioso e la sua conseguenza è una sanzione.

I due sistemi falliscono in modi diversi

Non sono varianti di un'unica integrazione. Hanno forme davvero diverse, e un sistema che le astrae troppo presto le sbaglia entrambe.

SES.Hospedajes è un servizio SOAP, e il payload non è XML semplice: i dati veri viaggiano come archivio compresso incorporato dentro la busta SOAP. Questo singolo dettaglio manda in crisi quasi tutte le implementazioni ingenue, perché sembra una normale chiamata a un web service finché non scopri che il corpo va prima zippato.

Alloggiati Web vuole record di testo a larghezza fissa: ogni ospite una riga di esattamente 168 caratteri, ogni campo a un offset definito, riempito con spazi anziché delimitato. Quel formato non perdona. Un campo corto di un carattere sposta tutto ciò che segue, e il record viene rifiutato per intero con un errore che punta alla riga, non al tuo bug.

Ciò che hanno in comune è che entrambi pretendono valori codificati, non testo libero. Nazionalità, tipo di documento e comune sono elenchi mantenuti dall'autorità, e un ospite che scrive "Italia" in una casella produce un record che verrà respinto. Qualunque cosa veda l'ospite, il sistema deve risolverla nel codice ufficiale prima dell'invio.

Raccogli una volta, comunica per autorità

Il progetto che funziona è tenere una sola rappresentazione interna dell'ospite — i campi che servono a entrambe le autorità, nel tuo vocabolario — e lasciare che ogni provider la traduca nel proprio formato al momento dell'invio. Mantiene il modulo di check-in indipendente dal paese, e fa sì che aggiungere un terzo stato sia un nuovo traduttore, non un nuovo modello dati.

Conserva il protocollo restituito dall'autorità. È quel riferimento a trasformare "l'abbiamo inviato" in "è stato accettato", ed è l'unica cosa che puoi mostrare a un'ispezione. In Boris un passo con la prova dell'autorità allegata viene marcato come verificato, distintamente dall'essere semplicemente riuscito.

Poi cancella quello che non ti serve più

La comunicazione è anche ciò che esaurisce la tua base giuridica per conservare la fotografia del documento dell'ospite. Una volta comunicato il soggiorno, l'immagine ha esaurito il suo scopo. Boris distrugge quelle fotografie in quel momento, e comunque a fine giornata di arrivo — sul perché questo non sia volutamente configurabile, vedi la guida sul check-in con QR.

Cosa verificare in qualsiasi sistema che dica di farlo

• La comunicazione riprova da sola, almeno ogni ora, senza che nessuno si accorga del fallimento?
• Un soggiorno mai comunicato risulta visibilmente mancante, o è solo assente da un log?
• Il protocollo dell'autorità viene conservato, o solo il fatto che una richiesta è partita?
• Nazionalità, tipo di documento e comune vengono risolti nei codici ufficiali?
• Un check-in completato a mano alla reception produce la stessa comunicazione di quello automatico?
• Le immagini dei documenti vengono distrutte una volta riuscita la comunicazione?