Webhooks de leads y sincronización con Google Sheets

Qué puedes hacer

Cuando un flipbook captura leads, puedes enrutar cada nuevo lead fuera de FlipLink y hacia tus propios sistemas. Estos tres endpoints te permiten:

• Definir un webhook de nuevo lead — una URL que recibe una carga JSON por cada nuevo lead.
• Probar el webhook — disparar una carga ficticia para que puedas verificar la entrega y el formato sin un lead real.
• Sincronizar los leads con Google Sheets — añadir cada nuevo lead a una hoja que especifiques.

Antes de empezar

• Una clave de API — se envía como el encabezado X-Api-Key o como Authorization: Bearer YOUR_API_KEY en cada solicitud.
• El {flipbookId} — el ID numérico del flipbook, devuelto por create-by-file / create-by-url (como ID) o por list. Los tres endpoints lo toman como un parámetro de ruta.
• Todas las solicitudes van a la URL base https://go.fliplink.me.
• Los endpoints PUT (set-lead-webhook, set-lead-google-sheets) envían su cuerpo como form-urlencoded (no JSON). test-webhook no toma cuerpo.

Define el webhook de nuevo lead

Define una URL de webhook que recibe cada nuevo lead (guardada como el webhook de nuevo lead). Usa el endpoint de prueba de abajo para verificar que se dispara.

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'

Respuesta:

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

Prueba el webhook

Dispara una carga de PRUEBA al webhook de leads configurado del flipbook para que puedas verificar el formato de entrega sin un lead real. Devuelve ERROR "No lead webhook is configured for this flipbook." si no hay ninguno configurado. La forma de la carga coincide con la de un lead real (claves: pdf_id, pdf_name, lead_name, lead_email, lead_phone, lead_company, lead_date, lead_custom_1, lead_custom_2) pero lleva valores ficticios (pdf_id:"-1", pdf_name:"Test PDF", …). No se almacena ningún lead real y no se envía ningún correo de notificación.

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

Respuesta:

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

Sincroniza los leads con Google Sheets

Conecta la captura de leads a una hoja de Google Sheets — los nuevos leads se añaden a la hoja que especifiques. La solicitud envía tres campos de formulario:

• GoogleSheetURL — la URL para compartir de la hoja de cálculo (el enlace que obtienes desde el diálogo de Compartir de Google Sheets).
• GoogleSheetIDKey — el ID de la hoja de cálculo (el identificador largo en la URL de la hoja, entre /d/ y /edit).
• GoogleSheetName — el nombre de la hoja (pestaña) a la que añadir filas, p. ej. 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'

Respuesta:

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

Errores posibles

• Clave de API ausente o no válida → HTTP 401. Esto devuelve una página HTML de "Unauthorized" sin formato — no hay cuerpo JSON. Comprueba que el encabezado X-Api-Key (o Authorization: Bearer) esté presente y sea correcto.
• {flipbookId} desconocido (o uno no perteneciente a tu clave) → HTTP 200 con { "Result": "ERROR", "Message": "Item not found" }.
• Campo del cuerpo desconocido o mal escrito (en los dos endpoints PUT) → HTTP 200 con { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.

Una regla práctica rápida: Result: "OK" significa que el cambio se aplicó; Result: "ERROR" significa que no — lee el Message para conocer el motivo.

Notas

• El endpoint de prueba devuelve ERROR "No lead webhook is configured for this flipbook." cuando el flipbook no tiene webhook configurado — configúralo primero con set-lead-webhook.
• Una carga de prueba nunca almacena un lead real y nunca envía un correo de notificación.