フリップブックをGoogle Sheetsに送る

できること

2つのエンドポイントで、Sheetsブリッジ経由でフリップブックのデータをGoogleシートに移せます。

• 名前付きのシートタブに行を送る（push） — タブがまだ存在しない場合は自動的に作成されます。
• サービスアカウントがシートに実際に書き込めるかを、頼りにする前に確認する。

この2つを使えば、リードの行（または任意の表形式データ）を追加でき、また先にシートが正しく共有されているかを確認できます。そのため、pushが403で拒否される前に、共有の問題を捉えられます。

始める前に

• APIキー — 仕様の例ではX-Api-Keyヘッダーとして送ります。リクエストボディにもapiKeyフィールド（サーバー設定と一致する静的なキー）があり、これは両方のエンドポイントで必須です。
• ベースURLはSheetsブリッジの{sheetsBaseUrl} — Google Sheetsブリッジの外部ベースURL（たとえばApps ScriptのウェブアプリURL）です。これは完全なURLであり、go.fliplink.meからの相対パスではありません。
• リクエストボディはJSON（raw）で、form-urlencodedではありません。
• どちらのエンドポイントも{flipbookId}パスパラメーターを使いません。対象のシートはsheetIdボディフィールドで特定されます。

シートに行を送る

POST {sheetsBaseUrl}/api/push-to-sheetsは、Googleシートに行を追加し、名前付きのシートタブがなければ自動的に作成します。dataはオブジェクトの配列（最初のオブジェクトのキーが列の順序になり、明示的なrangeがない場合はヘッダー行が書き込まれます）または配列の配列（そのまま渡されます）です。任意のrangeフィールドはA1記法（例: "Leads!A1"）を取ります。省略すると、名前付きシートの最後の入力済みの行の後に追加されます。

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

レスポンス:

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

sheetIdはスプレッドシートのIDです。シートのURLの/spreadsheets/d/と/editの間にある44文字の値です。sheetNameは対象のタブで、なければ作成されます。

シートに書き込めるかを確認する

POST {sheetsBaseUrl}/api/check-sheet-writableは、サービスアカウントがシートに書き込めるかを調べます。一時的なタブを作成し、そこに1つのセルを書き込んでから、そのタブを削除します。3つのステップすべてが成功した場合のみIsWritable: trueを返すので、「共有されていない」ことと「共有されているがセルが保護されている」ことの両方を捉えます。

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

シートが正しく共有されている場合のレスポンス:

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

シートが共有されていない、書き込みがブロックされている、または転送エラーが起きた場合のレスポンス:

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

リクエストの検証に失敗した場合のレスポンス:

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

起こりうるエラー

Push to Sheetsの場合:

• シートがサービスアカウントと共有されていない場合 → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• キーが不正な場合 → { "Result": "ERROR", "Message": "Invalid API key." }
• ボディが空／送るものがない場合 → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Check Sheet Writableの場合:

• リクエストの検証に失敗した場合 → { "Result": "ERROR", "Message": "...", "IsWritable": false }。ブロックされた、または失敗した書き込みは、エラーではなく{ "Result": "OK", "IsWritable": false }として報告されます。

メモ

• Push to Sheetsの前のプリフライトとしてCheck Sheet Writableを使ってください。実際の書き込みと削除のサイクルを実行するため、単なる共有テストより厳格で、共有されているがセルが保護されているシートを捉えます。
• Push to Sheetsでは、dataがオブジェクトの配列でrangeが指定されていない場合、最初のオブジェクトのキーからヘッダー行が書き込まれます。dataが配列の配列の場合は、そのまま渡されます。