Enviar flipbooks a Google Sheets

Qué puedes hacer

Dos endpoints te permiten mover datos de un flipbook a una hoja de Google Sheets a través de tu puente de Sheets:

• Enviar filas a una pestaña con nombre — la pestaña se crea automáticamente si aún no existe.
• Comprobar si la cuenta de servicio realmente puede escribir en una hoja, antes de depender de ella.

Entre ambos puedes añadir filas de leads (o cualquier dato tabular) y confirmar primero que la hoja está compartida correctamente, para detectar un problema de permisos antes de enviar, en lugar de que el envío se rechace con un 403.

Antes de empezar

• Una clave de API — el ejemplo de la especificación la envía como el encabezado X-Api-Key. El cuerpo de la solicitud también lleva un campo apiKey (una clave estática que coincide con la configuración del servidor), que es obligatorio en ambos endpoints.
• La URL base es tu puente de Sheets, {sheetsBaseUrl} — la URL base externa de tu puente de Google Sheets (por ejemplo, la URL de la app web de Apps Script). Es una URL completa y NO es relativa a go.fliplink.me.
• El cuerpo de la solicitud es JSON (crudo), no form-urlencoded.
• Ninguno de los endpoints usa un parámetro de ruta {flipbookId} — la hoja de destino se identifica con el campo del cuerpo sheetId.

Enviar filas a una hoja

POST {sheetsBaseUrl}/api/push-to-sheets añade filas a una hoja de Google Sheets y crea automáticamente la pestaña con nombre si falta. data puede ser un array de objetos (las claves del primer objeto se convierten en el orden de las columnas, y se escribe una fila de encabezado cuando no se da un range explícito) o un array de arrays (que se pasa tal cual). El campo opcional range toma notación A1, p. ej. "Leads!A1"; si se omite, las filas se añaden después de la última fila con contenido en la hoja con nombre.

curl -X POST '{sheetsBaseUrl}/api/push-to-sheets' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "sheetId": "YOUR_SHEET_ID",
    "sheetName": "Leads",
    "data": [
      { "Name": "Alice", "Email": "alice@corp.com" },
      { "Name": "Bob", "Email": "bob@corp.com" }
    ],
    "range": "Leads!A1"
  }'

Respuesta:

{ "Result": "OK", "Message": "Data pushed to Google Sheet.", "RowsAppended": 2 }

El sheetId es el id de la hoja de cálculo — el valor de 44 caracteres entre /spreadsheets/d/ y /edit en la URL de la hoja. sheetName es la pestaña de destino, que se crea si no existe.

Comprobar si una hoja permite escritura

POST {sheetsBaseUrl}/api/check-sheet-writable comprueba si la cuenta de servicio puede escribir en una hoja. Crea una pestaña temporal, escribe una celda en ella y luego elimina la pestaña — devolviendo IsWritable: true solo si los tres pasos tienen éxito, de modo que detecta tanto "no compartida con nosotros" como "compartida pero con celdas protegidas".

curl -X POST '{sheetsBaseUrl}/api/check-sheet-writable' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "sheetId": "YOUR_SHEET_ID"
  }'

Respuesta cuando la hoja está compartida correctamente:

{ "Result": "OK", "IsWritable": true }

Respuesta cuando la hoja no está compartida, la escritura está bloqueada o ocurre un error de transporte:

{ "Result": "OK", "IsWritable": false }

Respuesta ante un fallo de validación de la solicitud:

{ "Result": "ERROR", "Message": "...", "IsWritable": false }

Errores posibles

Para Push to Sheets:

• Hoja no compartida con la cuenta de servicio → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Clave incorrecta → { "Result": "ERROR", "Message": "Invalid API key." }
• Cuerpo vacío / nada que enviar → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Para Check Sheet Writable:

• Fallo de validación de la solicitud → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Una escritura bloqueada o fallida se reporta como { "Result": "OK", "IsWritable": false } en lugar de como un error.

Notas

• Usa Check Sheet Writable como comprobación previa antes de Push to Sheets — es más estricta que una simple prueba de permisos porque ejecuta un ciclo real de escritura y borrado, detectando hojas que están compartidas pero tienen celdas protegidas.
• En Push to Sheets, cuando data es un array de objetos y no se da un range, se escribe una fila de encabezado a partir de las claves del primer objeto; cuando data es un array de arrays, se pasa tal cual.