Ricevuta PDF tramite header DOCUMENT

Questa guida mostra il pattern di ricevuta dell’Opzione B: il messaggio WhatsApp include un header documento PDF e variabili nel corpo che descrivono la ricevuta. Usa questo pattern quando il cliente deve ricevere il documento della ricevuta direttamente in WhatsApp invece di aprire una pagina di ricevuta.

Prima di iniziare

Ti serve:

Un canale WhatsApp collegato in Switchbord.
Un modello Utility approvato con un header DOCUMENT, ad esempio payment_receipt_document.
Un URL PDF pubblico HTTPS. Meta deve poter recuperarlo.
Un id evento a monte stabile per l’idempotenza.

L’URL del documento deve essere HTTPS e raggiungibile da Meta. Non usare URL solo interni, localhost, URL con scadenza che espirano prima dell’invio, o URL contenenti segreti riutilizzabili.

Struttura del modello

Un tipico modello di ricevuta documento ha un header documento e un corpo come:

Ciao {{1}}, la ricevuta {{2}} è allegata a questo messaggio.

L’header documento riceve:

{
  "link": "https://cdn.example.com/receipts/R-1001.pdf",
  "filename": "R-1001.pdf"
}

Invio diretto tramite API

curl -X POST https://api.switchbord.ai/api/v1/template-sends \
  -H "Authorization: Bearer $SWITCHBORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-receipt-pdf-R-1001" \
  -d '{
    "templateName": "payment_receipt_document",
    "templateLocale": "it",
    "recipient": {
      "phoneE164": "+393331234567",
      "externalId": "traveller-123",
      "name": "Giulia Rossi"
    },
    "variables": {
      "header": {
        "document": {
          "link": "https://cdn.example.com/receipts/R-1001.pdf",
          "filename": "R-1001.pdf"
        }
      },
      "body": {
        "1": "Giulia",
        "2": "R-1001"
      }
    },
    "metadata": {
      "source": "booking-system",
      "eventType": "payment.receipt.pdf_ready"
    }
  }'

Risposta prevista:

{
  "data": {
    "contactId": "contact_123",
    "conversationId": "conversation_123",
    "messageId": "message_123",
    "clientMessageId": "payment-receipt-pdf-R-1001",
    "status": "queued",
    "reused": false,
    "idempotent": true
  }
}

Builder per webhook in entrata

Per mappare un evento di pagamento esterno su questo modello:

Apri Impostazioni → Integrazioni → Webhook e API.
Crea un nuovo webhook in entrata.
Seleziona il modello Utility approvato payment_receipt_document.
Mappa i campi:

Campo del modello	Modalità sorgente	Sorgente di esempio
Telefono destinatario	Percorso nel payload	`customer.phone`
ID esterno	Percorso nel payload	`receipt.id`
Link al documento PDF	Percorso nel payload	`receipt.pdf`
Nome del file PDF	Letterale o percorso nel payload	`receipt.pdf` oppure `receipt.filename`
Corpo `{{1}}`	Percorso nel payload	`customer.first_name`
Corpo `{{2}}`	Percorso nel payload	`receipt.number`

Incolla un payload di esempio ed esegui l’anteprima dry-run.
Crea il webhook. Le nuove configurazioni restano disabilitate e in dry-run di default finché la promozione live non è supportata.

Payload di esempio:

{
  "customer": {
    "phone": "+393331234567",
    "first_name": "Giulia"
  },
  "receipt": {
    "id": "payment-receipt-pdf-R-1001",
    "number": "R-1001",
    "filename": "R-1001.pdf",
    "pdf": "https://cdn.example.com/receipts/R-1001.pdf"
  }
}

Variabili del corpo con nome

Il mapper dei webhook in entrata e il compilatore transazionale interno di Switchbord supportano i parametri del corpo con nome di Meta e li compilano in voci parameter_name. La route pubblica POST /api/v1/template-sends attualmente accetta solo variabili del corpo posizionali, quindi i chiamanti API diretti dovrebbero usare chiavi numeriche del corpo o un array.

Validazione

Switchbord valida l’header del documento prima di accodare l’invio:

link deve essere un URL HTTPS valido.
filename, se fornito, deve essere non vuoto.
Le variabili del corpo richieste devono risolvere a stringhe non vuote.
Il modello selezionato deve essere Utility approvato.
La chiave di idempotenza deve essere stabile per i tentativi ripetuti.

Risoluzione dei problemi

Sintomo	Verifica
`400 invalid_media_link`	Il link del documento non è HTTPS valido o non può essere interpretato come URL.
`400 invalid_document_filename`	È stato fornito un nome file ma è risolto in una stringa vuota.
`400 missing_template_name`	La mappatura del webhook non ha risolto un modello, oppure nessun modello è stato selezionato.
`401 invalid_signature`	La richiesta webhook non è stata firmata con il segreto webhook one-time.
La consegna Meta fallisce dopo l’accodamento	Verifica che l’URL del PDF sia ancora raggiungibile da Meta e restituisca il tipo di contenuto corretto.

Riferimenti correlati

Link alla ricevuta di pagamento tramite bottone URL Rollout dry-run dei webhook in entrata

Per iniziare

Funzionalità

WhatsApp

Guide

Contribuire

Piattaforma

Operazioni

Sicurezza e Conformità

Ricevuta PDF tramite header DOCUMENT

Prima di iniziare

Struttura del modello

Invio diretto tramite API

Builder per webhook in entrata

Variabili del corpo con nome

Validazione

Risoluzione dei problemi

Riferimenti correlati

​Prima di iniziare

​Struttura del modello

​Invio diretto tramite API

​Builder per webhook in entrata

​Variabili del corpo con nome

​Validazione

​Risoluzione dei problemi

​Riferimenti correlati

Prima di iniziare

Struttura del modello

Invio diretto tramite API

Builder per webhook in entrata

Variabili del corpo con nome

Validazione

Risoluzione dei problemi

Riferimenti correlati