API Lettere di Benvenuto

Endpoint per la gestione delle lettere di benvenuto inviate agli ospiti. Le lettere vengono generate automaticamente in base alla lingua dell’ospite e ai dati della prenotazione.

Lista Lettere di Benvenuto

Restituisce l’elenco completo di tutte le lettere di benvenuto generate.

GET /api/lettere-benvenuto

Risposta

{
  "data": [
    {
      "id": 1,
      "prenotazione_id": 142,
      "nome_ospite": "Mario Rossi",
      "lingua": "IT",
      "created_at": "2026-07-18T09:00:00Z",
      "url": "https://..."
    },
    {
      "id": 2,
      "prenotazione_id": 143,
      "nome_ospite": "John Smith",
      "lingua": "EN",
      "created_at": "2026-07-19T10:30:00Z",
      "url": "https://..."
    }
  ]
}

Campi della Risposta

Campo Tipo Descrizione
id number ID univoco della lettera
prenotazione_id number ID della prenotazione associata
nome_ospite string Nome dell’ospite destinatario
lingua string Codice lingua della lettera
created_at string Data e ora di generazione
url string URL per il download della lettera

Verifica Esistenza Lettera

Controlla se esiste già una lettera di benvenuto per una specifica prenotazione. Utile per determinare se è necessario generarne una nuova o se è già stata creata.

GET /api/lettere-benvenuto/:prenotazioneId

Parametri URL

Parametro Tipo Obbligatorio Descrizione
prenotazioneId number ✅ ID della prenotazione

Esempio di Richiesta

GET /api/lettere-benvenuto/142

Risposta (Lettera Esistente)

{
  "exists": true,
  "data": {
    "id": 1,
    "prenotazione_id": 142,
    "nome_ospite": "Mario Rossi",
    "lingua": "IT",
    "created_at": "2026-07-18T09:00:00Z",
    "url": "https://..."
  }
}

Risposta (Lettera Non Esistente)

{
  "exists": false,
  "data": null
}

Genera Lettera di Benvenuto

Genera una nuova lettera di benvenuto per una prenotazione. La lettera viene creata in base alla lingua specificata e ai dati del template.

POST /api/lettere-benvenuto/genera

Parametri Body

Parametro Tipo Obbligatorio Descrizione
prenotazione_id number ✅ ID della prenotazione
nome_ospite string ✅ Nome completo dell’ospite
lingua string ✅ Codice lingua (IT, EN, DE, FR, ecc.)
template_data object ❌ Dati aggiuntivi per il template

Struttura template_data

Campo Tipo Descrizione
nome_ospite string Nome dell’ospite (default: nome_ospite del body)
greeting string Saluto introduttivo localizzato (es. Ciao,, Hello,, Bonjour,)
text1 string Primo blocco di testo o benvenuto (es. Benvenuto/a, Welcome)
text2 string Secondo blocco di testo di accoglienza
text3 string Terzo blocco di testo di augurio e disponibilità
enjoy_text string Testo del badge di augurio (es. Buon soggiorno!, Enjoy your stay!)
codice number Codice identificativo della prenotazione (idf_gen)

Esempio di Richiesta

{
  "prenotazione_id": 144,
  "nome_ospite": "Cristiano Bleve",
  "lingua": "Italiano",
  "template_data": {
    "nome_ospite": "Cristiano Bleve",
    "greeting": "Ciao,",
    "text1": "Benvenuto/a",
    "text2": "Siamo felici di accogliervi nella nostra casa vacanze.",
    "text3": "Vi auguriamo un soggiorno rilassante e vi ricordiamo che per qualsiasi necessità siamo sempre a disposizione.",
    "enjoy_text": "Buon soggiorno!",
    "codice": 12345678
  }
}

Risposta (201 Created)

{
  "success": true,
  "data": {
    "id": 3,
    "prenotazione_id": 144,
    "nome_ospite": "Maria Bianchi",
    "lingua": "IT",
    "url": "https://...",
    "created_at": "2026-07-15T14:00:00Z"
  },
  "message": "Lettera di benvenuto generata con successo"
}

Errori Comuni

Codice Messaggio Causa
400 Prenotazione ID obbligatorio Manca il parametro prenotazione_id
409 Lettera già esistente per questa prenotazione Esiste già una lettera; eliminala prima di rigenerarla
404 Prenotazione non trovata L’ID prenotazione non esiste

[!TIP]
Se devi rigenerare una lettera (ad esempio dopo una modifica alla prenotazione), elimina prima quella esistente con l’endpoint DELETE e poi genera una nuova versione.

Elimina Lettera di Benvenuto

Elimina la lettera di benvenuto associata a una prenotazione. Questa operazione è necessaria prima di poter rigenerare una lettera aggiornata.

DELETE /api/lettere-benvenuto/:prenotazioneId

Parametri URL

Parametro Tipo Obbligatorio Descrizione
prenotazioneId number ✅ ID della prenotazione

Esempio di Richiesta

DELETE /api/lettere-benvenuto/142

Risposta

{
  "success": true,
  "message": "Lettera di benvenuto eliminata con successo"
}

Risposta (Lettera Non Trovata)

{
  "error": "Nessuna lettera di benvenuto trovata per questa prenotazione",
  "status": 404
}

Flusso Tipico

Il flusso standard per la gestione delle lettere di benvenuto è il seguente:

flowchart TD A[Nuova Prenotazione] --> B{Lettera esistente?} B -->|No| C[Genera Lettera] B -->|Sì| D{Dati aggiornati?} D -->|No| E[Usa lettera esistente] D -->|Sì| F[Elimina lettera] F --> C C --> G[Lettera disponibile] E --> G
  1. Verifica se esiste già una lettera con GET /api/lettere-benvenuto/:prenotazioneId
  2. Se non esiste, genera una nuova con POST /api/lettere-benvenuto/genera
  3. Se esiste ma i dati sono cambiati, elimina con DELETE e poi rigenera
Previous Documenti & PDF Next OCR & MRZ