Webhook dei lead e sincronizzazione con Google Sheets

Cosa puoi fare

Quando un flipbook cattura lead, puoi instradare ogni nuovo lead fuori da FlipLink e verso i tuoi sistemi. Questi tre endpoint ti permettono di:

• Impostare un webhook per i nuovi lead — un URL che riceve un payload JSON per ogni nuovo lead.
• Testare il webhook — invia un payload fittizio così puoi verificare il recapito e il formato senza un lead reale.
• Sincronizzare i lead con Google Sheets — aggiungi ogni nuovo lead a un foglio che indichi.

Prima di iniziare

• Una chiave API — inviata come header X-Api-Key o come Authorization: Bearer YOUR_API_KEY in ogni richiesta.
• Il {flipbookId} — l'ID numerico del flipbook, restituito da create-by-file / create-by-url (come ID) o da list. Tutti e tre gli endpoint lo accettano come parametro nel percorso.
• Tutte le richieste vanno all'URL di base https://go.fliplink.me.
• Gli endpoint PUT (set-lead-webhook, set-lead-google-sheets) inviano il loro body come form-urlencoded (non JSON). test-webhook non accetta alcun body.

Impostare il webhook per i nuovi lead

Imposta un URL webhook che riceve ogni nuovo lead (salvato come webhook per i nuovi lead). Usa l'endpoint di test qui sotto per verificare che si attivi.

curl -X PUT 'https://go.fliplink.me/api/set-lead-webhook/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'WebhookURL_NewLead=https://example.com/hooks/new-lead'

Risposta:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

Testare il webhook

Invia un payload di TEST al webhook per i lead configurato del flipbook, così puoi verificare il formato di recapito senza un lead reale. Restituisce ERROR "No lead webhook is configured for this flipbook." se non ne è impostato nessuno. La forma del payload corrisponde a un lead reale (chiavi: pdf_id, pdf_name, lead_name, lead_email, lead_phone, lead_company, lead_date, lead_custom_1, lead_custom_2) ma contiene valori fittizi (pdf_id:"-1", pdf_name:"Test PDF", …). Non viene memorizzato alcun lead reale e non viene inviata alcuna email di notifica.

curl -X POST 'https://go.fliplink.me/api/test-webhook/96216' \
  -H 'X-Api-Key: YOUR_API_KEY'

Risposta:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

Sincronizzare i lead con Google Sheets

Collega la cattura lead a un foglio Google — i nuovi lead vengono aggiunti al foglio che indichi. La richiesta invia tre campi form:

• GoogleSheetURL — l'URL di condivisione del foglio di calcolo (il link che ottieni dalla finestra di condivisione di Google Sheets).
• GoogleSheetIDKey — l'ID del foglio di calcolo (il lungo identificatore nell'URL del foglio, tra /d/ e /edit).
• GoogleSheetName — il nome del foglio di lavoro (scheda) a cui aggiungere le righe, per esempio Sheet1.

curl -X PUT 'https://go.fliplink.me/api/set-lead-google-sheets/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'GoogleSheetURL=https://docs.google.com/spreadsheets/d/1A2B3C4D5E6F7G8H9I0J/edit?usp=sharing' \
  --data-urlencode 'GoogleSheetIDKey=1A2B3C4D5E6F7G8H9I0J' \
  --data-urlencode 'GoogleSheetName=Sheet1'

Risposta:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

Errori possibili

• Chiave API mancante o non valida → HTTP 401. Restituisce una semplice pagina HTML di Unauthorized — non c'è alcun body JSON. Controlla che l'header X-Api-Key (o Authorization: Bearer) sia presente e corretto.
• {flipbookId} sconosciuto (o non di proprietà della tua chiave) → HTTP 200 con { "Result": "ERROR", "Message": "Item not found" }.
• Campo del body sconosciuto o scritto male (sui due endpoint PUT) → HTTP 200 con { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.

Una regola pratica: Result: "OK" significa che la modifica è stata applicata; Result: "ERROR" significa che non lo è stata — leggi il Message per capirne il motivo.

Note

• L'endpoint di test restituisce ERROR "No lead webhook is configured for this flipbook." quando il flipbook non ha un webhook impostato — configuralo prima con set-lead-webhook.
• Un payload di test non memorizza mai un lead reale e non invia mai un'email di notifica.