Envoyer des flipbooks vers Google Sheets

Ce que tu peux faire

Deux endpoints te permettent de transférer les données d'un flipbook vers une feuille Google Sheets via ton pont Sheets :

• Envoyer des lignes dans un onglet de feuille nommé — l'onglet est créé automatiquement s'il n'existe pas encore.
• Vérifier si le compte de service peut réellement écrire dans une feuille, avant de t'y fier.

À eux deux, ils te permettent d'ajouter des lignes de prospects (ou n'importe quelles données tabulaires) et de confirmer d'abord que la feuille est partagée correctement, pour repérer un problème de partage avant l'envoi, plutôt que de voir l'envoi rejeté avec un 403.

Avant de commencer

• Une clé d'API — l'exemple de la spec l'envoie dans l'en-tête X-Api-Key. Le corps de la requête contient aussi un champ apiKey (une clé statique correspondant à la configuration du serveur), qui est obligatoire sur les deux endpoints.
• L'URL de base est ton pont Sheets, {sheetsBaseUrl} — l'URL de base externe de ton pont Google Sheets (par exemple, l'URL de l'application web Apps Script). C'est une URL complète et elle n'est PAS relative à go.fliplink.me.
• Le corps de la requête est du JSON (brut), pas du form-urlencoded.
• Aucun des deux endpoints n'utilise de paramètre de chemin {flipbookId} — la feuille cible est identifiée par le champ de corps sheetId.

Envoyer des lignes dans une feuille

POST {sheetsBaseUrl}/api/push-to-sheets ajoute des lignes à une feuille Google Sheets et crée automatiquement l'onglet nommé s'il est absent. data peut être un tableau d'objets (les clés du premier objet déterminent l'ordre des colonnes, et une ligne d'en-tête est écrite lorsqu'aucun range explicite n'est fourni) ou un tableau de tableaux (transmis tel quel). Le champ facultatif range accepte la notation A1, par exemple "Leads!A1" ; s'il est omis, les lignes sont ajoutées après la dernière ligne remplie de la feuille nommée.

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"
  }'

Réponse :

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

Le sheetId est l'id du tableur — la valeur de 44 caractères entre /spreadsheets/d/ et /edit dans l'URL de la feuille. sheetName est l'onglet cible, créé s'il est absent.

Vérifier si une feuille est accessible en écriture

POST {sheetsBaseUrl}/api/check-sheet-writable vérifie si le compte de service peut écrire dans une feuille. Il crée un onglet temporaire, y écrit une cellule, puis supprime l'onglet — en renvoyant IsWritable: true uniquement si les trois étapes réussissent, ce qui permet de détecter à la fois « feuille non partagée avec nous » et « partagée mais cellules protégées ».

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"
  }'

Réponse lorsque la feuille est partagée correctement :

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

Réponse lorsque la feuille n'est pas partagée, que l'écriture est bloquée ou qu'une erreur de transport se produit :

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

Réponse en cas d'échec de validation de la requête :

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

Erreurs possibles

Pour Push to Sheets :

• Feuille non partagée avec le compte de service → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Clé incorrecte → { "Result": "ERROR", "Message": "Invalid API key." }
• Corps vide / rien à envoyer → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Pour Check Sheet Writable :

• Échec de validation de la requête → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Une écriture bloquée ou en échec est signalée par { "Result": "OK", "IsWritable": false } plutôt que par une erreur.

Notes

• Utilise Check Sheet Writable comme contrôle préalable avant Push to Sheets — c'est plus strict qu'un simple test de partage, car cela exécute un véritable cycle d'écriture puis de suppression, ce qui permet de repérer les feuilles partagées mais dont les cellules sont protégées.
• Sur Push to Sheets, lorsque data est un tableau d'objets et qu'aucun range n'est fourni, une ligne d'en-tête est écrite à partir des clés du premier objet ; lorsque data est un tableau de tableaux, il est transmis tel quel.