Flipbooks naar Google Sheets pushen

Wat je kunt doen

Met twee endpoints verplaats je flipbookdata naar een Google Sheet via je Sheets-bridge:

• Push rijen naar een genoemd sheettabblad — het tabblad wordt automatisch aangemaakt als het nog niet bestaat.
• Controleer of het serviceaccount echt naar een sheet kan schrijven, voordat je erop vertrouwt.

Samen kun je zo leadrijen (of andere tabulaire data) toevoegen en eerst bevestigen dat de sheet correct is gedeeld, zodat je een deelprobleem opvangt vóórdat je pusht, in plaats van dat de push met een 403 wordt geweigerd.

Voordat je begint

• Een API-sleutel — het voorbeeld in de spec stuurt die mee als de X-Api-Key-header. De request-body bevat ook een apiKey-veld (een statische sleutel die overeenkomt met de serverconfig), dat op beide endpoints verplicht is.
• De basis-URL is je Sheets-bridge, {sheetsBaseUrl} — de externe basis-URL van je Google Sheets-bridge (bijvoorbeeld de web-app-URL van Apps Script). Het is een volledige URL en staat NIET relatief ten opzichte van go.fliplink.me.
• De request-body is JSON (raw), geen form-urlencoded.
• Geen van beide endpoints gebruikt een {flipbookId}-padparameter — de doelsheet wordt geïdentificeerd door het sheetId-body-veld.

Rijen naar een sheet pushen

POST {sheetsBaseUrl}/api/push-to-sheets voegt rijen toe aan een Google Sheet en maakt het genoemde sheettabblad automatisch aan als het ontbreekt. data mag een array van objecten zijn (de sleutels van het eerste object bepalen de kolomvolgorde, en er wordt een kopregel geschreven wanneer je geen expliciete range opgeeft) of een array van arrays (die ongewijzigd wordt doorgegeven). Het optionele veld range neemt A1-notatie, bijv. "Leads!A1"; als je het weglaat, worden rijen toegevoegd na de laatste gevulde rij in het genoemde tabblad.

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

Response:

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

De sheetId is de spreadsheet-id — de waarde van 44 tekens tussen /spreadsheets/d/ en /edit in de URL van de sheet. sheetName is het doeltabblad, dat wordt aangemaakt als het ontbreekt.

Controleren of een sheet beschrijfbaar is

POST {sheetsBaseUrl}/api/check-sheet-writable test of het serviceaccount naar een sheet kan schrijven. Het maakt een tijdelijk tabblad, schrijft er één cel naar en verwijdert het tabblad daarna — het geeft IsWritable: true alleen terug als alle drie de stappen slagen, zodat het zowel "niet met ons gedeeld" als "gedeeld maar cellen beschermd" opvangt.

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

Response wanneer de sheet correct is gedeeld:

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

Response wanneer de sheet niet is gedeeld, de schrijfactie is geblokkeerd, of er een transportfout optreedt:

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

Response bij een validatiefout van het verzoek:

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

Mogelijke fouten

Voor Push to Sheets:

• Sheet niet gedeeld met het serviceaccount → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Verkeerde sleutel → { "Result": "ERROR", "Message": "Invalid API key." }
• Lege body / niets te versturen → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Voor Check Sheet Writable:

• Validatiefout van het verzoek → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Een geblokkeerde of mislukte schrijfactie wordt gemeld als { "Result": "OK", "IsWritable": false } in plaats van als een fout.

Opmerkingen

• Gebruik Check Sheet Writable als pre-flight vóór Push to Sheets — het is strenger dan een simpele deeltest, omdat het een echte schrijf-en-verwijder-cyclus uitvoert en zo sheets opvangt die wel gedeeld zijn maar beschermde cellen hebben.
• Bij Push to Sheets wordt, wanneer data een array van objecten is en er geen range is opgegeven, een kopregel geschreven op basis van de sleutels van het eerste object; wanneer data een array van arrays is, wordt die ongewijzigd doorgegeven.