API Alloggiati Web

Endpoint per l’integrazione con il sistema Alloggiati Web della Polizia di Stato (Questura). Permettono di validare, inviare e verificare le schedine degli ospiti, nonché scaricare le ricevute di avvenuta comunicazione.

[!IMPORTANT]
Questi endpoint comunicano con i servizi SOAP della Questura. Assicurati che le credenziali Alloggiati Web siano configurate correttamente prima di utilizzarli.

---

Test Connessione SOAP

Verifica la connessione al servizio SOAP della Questura. Utile per diagnosticare problemi di configurazione.

GET /api/alloggiati/check

Risposta (Successo)

{
  "connected": true,
  "message": "Connessione al servizio Alloggiati Web riuscita",
  "endpoint": "https://alloggiatiweb.poliziadistato.it/service/..."
}

Risposta (Errore)

{
  "connected": false,
  "error": "Impossibile connettersi al servizio SOAP. Verificare le credenziali.",
  "status": 503
}

---

Valida Schedine

Valida i dati degli ospiti prima dell’invio alla Questura. Restituisce eventuali errori o avvisi sui record.

POST /api/alloggiati/valida

Parametri Body

Esempio di Richiesta

{
  "ospiti": [
    {
      "tipo_alloggiato": "16",
      "cognome": "Rossi",
      "nome": "Mario",
      "sesso": "M",
      "data_nascita": "1985-03-15",
      "comune_nascita": "411004",
      "provincia_nascita": "RM",
      "stato_nascita": "100000100",
      "cittadinanza": "100000100",
      "tipo_documento": "PASOR",
      "numero_documento": "YA1234567",
      "luogo_rilascio": "411004"
    }
  ],
  "prenotazione": {
    "check_in": "2026-07-20",
    "numero_notti": 5
  }
}

Risposta

{
  "valid": false,
  "errors": [
    {
      "ospite": 0,
      "campo": "provincia_nascita",
      "messaggio": "La provincia non è richiesta per cittadini stranieri"
    }
  ],
  "warnings": [
    {
      "ospite": 0,
      "campo": "numero_documento",
      "messaggio": "Formato documento potrebbe non essere valido per il tipo selezionato"
    }
  ]
}

Campi della Risposta

---

Invio Schedine alla Questura

Invia le schedine degli ospiti al servizio Alloggiati Web della Questura tramite protocollo SOAP.

POST /api/alloggiati/invio

Parametri Body

[!CAUTION]
Modalità Test vs Produzione

• Con testMode: true, viene invocato il metodo SOAP Test che valida i dati senza registrarli ufficialmente. Utilizzalo sempre durante lo sviluppo e i test.
• Con testMode: false (o omesso), viene invocato il metodo SOAP Send che registra ufficialmente le schedine presso la Questura. Questa operazione non è reversibile.

Si raccomanda di validare sempre i dati con l’endpoint /api/alloggiati/valida prima di procedere con l’invio in produzione.

Esempio di Richiesta

{
  "ospiti": [
    {
      "tipo_alloggiato": "16",
      "cognome": "Rossi",
      "nome": "Mario",
      "sesso": "M",
      "data_nascita": "1985-03-15",
      "comune_nascita": "411004",
      "provincia_nascita": "",
      "stato_nascita": "100000100",
      "cittadinanza": "100000100",
      "tipo_documento": "PASOR",
      "numero_documento": "YA1234567",
      "luogo_rilascio": "411004"
    }
  ],
  "prenotazione": {
    "check_in": "2026-07-20",
    "numero_notti": 5
  },
  "testMode": true
}

Risposta (Successo)

{
  "success": true,
  "message": "Invio completato con successo (modalità test)",
  "ricevuta": "2026-07-20-001",
  "dettagli": {
    "schedine_inviate": 1,
    "metodo": "Test"
  }
}

Risposta (Errore)

{
  "success": false,
  "error": "Errore durante l'invio alla Questura",
  "dettagli": {
    "codice_errore": "ERR_SOAP_003",
    "messaggio_soap": "Record non valido alla posizione 1"
  },
  "status": 422
}

---

Scarica Ricevute

Scarica le ricevute di avvenuta comunicazione dalla Questura per una data specifica. Restituisce un file PDF.

GET /api/alloggiati/ricevute

Parametri Query

Esempio di Richiesta

GET /api/alloggiati/ricevute?data=2026-07-20

Risposta

La risposta è un file PDF con Content-Type: application/pdf.

Content-Type: application/pdf
Content-Disposition: attachment; filename="ricevuta_2026-07-20.pdf"

[!NOTE]
Se non sono presenti ricevute per la data indicata, l’endpoint restituisce un errore 404.

---

Verifica Incrociata Ricevute

Esegue un controllo incrociato tra le prenotazioni registrate nel sistema e le ricevute effettivamente presenti sul portale della Questura, per individuare eventuali invii mancanti.

GET /api/alloggiati/verifica-ricevute

Risposta

{
  "totale_prenotazioni": 45,
  "totale_ricevute": 42,
  "mancanti": [
    {
      "prenotazione_id": 138,
      "nome_cognome": "Hans Müller",
      "check_in": "2026-07-15"
    },
    {
      "prenotazione_id": 140,
      "nome_cognome": "Sophie Dupont",
      "check_in": "2026-07-16"
    },
    {
      "prenotazione_id": 141,
      "nome_cognome": "James Wilson",
      "check_in": "2026-07-17"
    }
  ]
}

---

Codici di Riferimento

Restituisce le tabelle di codici di riferimento necessarie per la compilazione delle schedine: tipi di documento, paesi, comuni e province.

GET /api/alloggiati/codici

Risposta

{
  "tipi_documento": [
    { "codice": "PASOR", "descrizione": "Passaporto Ordinario" },
    { "codice": "IDELE", "descrizione": "Carta d'Identità Elettronica" },
    { "codice": "IDENT", "descrizione": "Carta d'Identità" },
    { "codice": "PATEN", "descrizione": "Patente di Guida" }
  ],
  "paesi": [
    { "codice": "100000100", "descrizione": "Italia" },
    { "codice": "100000200", "descrizione": "Germania" }
  ],
  "comuni": [
    { "codice": "411004", "descrizione": "Roma" },
    { "codice": "415027", "descrizione": "Milano" }
  ]
}

---

Formato Record Schedina

Ogni schedina alloggiato viene codificata come una stringa di 168 caratteri con campi a lunghezza fissa, secondo le specifiche del sistema Alloggiati Web della Questura.

Struttura del Record

Esempio di Record

1620/07/202605Rossi                                             Mario                         119850315  411004  RM100000100100000100PASORYA1234567           411004   

[!TIP]
Per i cittadini stranieri, il campo provincia (posizioni 115–116) deve essere lasciato vuoto (spazi). Il campo comune_nascita per gli stranieri indica lo stato di nascita.