Flipbooks in Google Sheets pushen

Was du tun kannst

Mit zwei Endpunkten bewegst du Flipbook-Daten über deine Sheets-Bridge in ein Google Sheet:

• Pushen von Zeilen in einen benannten Sheet-Tab – der Tab wird automatisch angelegt, falls er noch nicht existiert.
• Prüfen, ob das Dienstkonto tatsächlich in ein Sheet schreiben kann, bevor du dich darauf verlässt.

Zusammen kannst du damit Lead-Zeilen (oder beliebige tabellarische Daten) anhängen und zuerst bestätigen, dass das Sheet korrekt geteilt ist, sodass du ein Freigabeproblem erkennst, bevor du pushst, statt dass der Push mit einem 403 abgelehnt wird.

Bevor du loslegst

• Einen API-Schlüssel – das Beispiel der Spezifikation sendet ihn als X-Api-Key-Header. Der Request-Body trägt außerdem ein apiKey-Feld (ein statischer Schlüssel, der zur Server-Konfiguration passt), das auf beiden Endpunkten erforderlich ist.
• Die Basis-URL ist deine Sheets-Bridge, {sheetsBaseUrl} – die externe Basis-URL deiner Google-Sheets-Bridge (zum Beispiel die URL der Apps-Script-Web-App). Sie ist eine vollständige URL und NICHT relativ zu go.fliplink.me.
• Der Request-Body ist JSON (roh), nicht form-urlencoded.
• Keiner der Endpunkte verwendet einen {flipbookId}-Pfadparameter – das Ziel-Sheet wird über das Body-Feld sheetId identifiziert.

Zeilen in ein Sheet pushen

POST {sheetsBaseUrl}/api/push-to-sheets hängt Zeilen an ein Google Sheet an und legt den benannten Sheet-Tab automatisch an, falls er fehlt. data kann ein Array von Objekten sein (die Schlüssel des ersten Objekts bestimmen die Spaltenreihenfolge, und eine Kopfzeile wird geschrieben, wenn kein expliziter range angegeben ist) oder ein Array von Arrays (wird unverändert durchgereicht). Das optionale Feld range nimmt A1-Notation entgegen, z. B. "Leads!A1"; wird es weggelassen, werden Zeilen nach der letzten gefüllten Zeile im benannten Sheet angehängt.

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

Antwort:

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

Die sheetId ist die Spreadsheet-ID – der 44-stellige Wert zwischen /spreadsheets/d/ und /edit in der URL des Sheets. sheetName ist der Ziel-Tab, der angelegt wird, falls er fehlt.

Prüfen, ob ein Sheet beschreibbar ist

POST {sheetsBaseUrl}/api/check-sheet-writable prüft, ob das Dienstkonto in ein Sheet schreiben kann. Es legt einen temporären Tab an, schreibt eine Zelle hinein und löscht den Tab dann wieder – und gibt IsWritable: true nur zurück, wenn alle drei Schritte gelingen, sodass es sowohl „nicht mit uns geteilt“ als auch „geteilt, aber Zellen geschützt" erkennt.

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

Antwort, wenn das Sheet korrekt geteilt ist:

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

Antwort, wenn das Sheet nicht geteilt ist, der Schreibvorgang blockiert wird oder ein Transportfehler auftritt:

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

Antwort bei einem Validierungsfehler der Anfrage:

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

Mögliche Fehler

Für Push to Sheets:

• Sheet nicht mit dem Dienstkonto geteilt → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Falscher Schlüssel → { "Result": "ERROR", "Message": "Invalid API key." }
• Leerer Body / nichts zu senden → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Für Check Sheet Writable:

• Validierungsfehler der Anfrage → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Ein blockierter oder fehlgeschlagener Schreibvorgang wird als { "Result": "OK", "IsWritable": false } gemeldet, nicht als Fehler.

Hinweise

• Verwende Check Sheet Writable als Vorabprüfung vor Push to Sheets – es ist strenger als ein bloßer Freigabetest, weil es einen echten Schreib-dann-Lösch-Zyklus durchläuft und so Sheets erkennt, die geteilt sind, aber geschützte Zellen haben.
• Bei Push to Sheets wird, wenn data ein Array von Objekten ist und kein range angegeben ist, eine Kopfzeile aus den Schlüsseln des ersten Objekts geschrieben; wenn data ein Array von Arrays ist, wird es unverändert durchgereicht.