リードのWebhookとGoogle Sheets連携

できること

フリップブックがリードを獲得するとき、新しいリードをFlipLinkから自分のシステムへ送り出せます。これら3つのエンドポイントでできることは次のとおりです。

• 新規リードのWebhookを設定する — 新しいリードごとにJSONペイロードを受け取るURL。
• Webhookをテストする — ダミーのペイロードを送って、実際のリードなしで配信と形式を確認する。
• リードをGoogle Sheetsに連携する — 新しいリードごとに、指定したシートに追加する。

始める前に

• APIキー — すべてのリクエストでX-Api-Keyヘッダー、またはAuthorization: Bearer YOUR_API_KEYとして送ります。
• {flipbookId} — フリップブックの数値IDで、create-by-file／create-by-url（IDとして）や一覧から返されます。3つのエンドポイントすべてが、これをパスパラメーターとして取ります。
• すべてのリクエストの送信先はベースURL https://go.fliplink.meです。
• PUTエンドポイント（set-lead-webhook、set-lead-google-sheets）は、ボディをform-urlencoded（JSONではありません）として送ります。test-webhookはボディを取りません。

新規リードのWebhookを設定する

新しいリードごとに受け取るWebhook URL（新規リードのWebhookとして保存）を設定します。動作を確認するには、下のテストエンドポイントを使ってください。

curl -X PUT 'https://go.fliplink.me/api/set-lead-webhook/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'WebhookURL_NewLead=https://example.com/hooks/new-lead'

レスポンス:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

Webhookをテストする

フリップブックに設定されたリードWebhookにTESTペイロードを送り、実際のリードなしで配信の形式を確認できるようにします。設定されていない場合はERROR "No lead webhook is configured for this flipbook."を返します。ペイロードの形は実際のリードと一致します（キー: pdf_id、pdf_name、lead_name、lead_email、lead_phone、lead_company、lead_date、lead_custom_1、lead_custom_2）が、ダミーの値（pdf_id:"-1"、pdf_name:"Test PDF"、…）を持ちます。実際のリードは保存されず、通知メールも送信されません。

curl -X POST 'https://go.fliplink.me/api/test-webhook/96216' \
  -H 'X-Api-Key: YOUR_API_KEY'

レスポンス:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

リードをGoogle Sheetsに連携する

リード獲得をGoogleシートに接続します。新しいリードは、指定したシートに追加されます。リクエストは3つのフォームフィールドを送ります。

• GoogleSheetURL — スプレッドシートの共有URL（Google Sheetsの共有ダイアログから取得するリンク）。
• GoogleSheetIDKey — スプレッドシートのID（シートのURLの/d/と/editの間にある長い識別子）。
• GoogleSheetName — 行を追加するワークシート（タブ）名（例: Sheet1）。

curl -X PUT 'https://go.fliplink.me/api/set-lead-google-sheets/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'GoogleSheetURL=https://docs.google.com/spreadsheets/d/1A2B3C4D5E6F7G8H9I0J/edit?usp=sharing' \
  --data-urlencode 'GoogleSheetIDKey=1A2B3C4D5E6F7G8H9I0J' \
  --data-urlencode 'GoogleSheetName=Sheet1'

レスポンス:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

起こりうるエラー

• APIキーが欠けているか無効な場合 → HTTP 401。これはプレーンなUnauthorized HTMLページを返し、JSONボディはありません。X-Api-Keyヘッダー（またはAuthorization: Bearer）が存在し、正しいことを確認してください。
• 不明な{flipbookId}（またはキーが所有していないもの） → HTTP 200で{ "Result": "ERROR", "Message": "Item not found" }。
• 不明またはスペルミスのボディフィールド（2つのPUTエンドポイントで） → HTTP 200で{ "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }。

目安として、Result: "OK"は変更が適用されたこと、Result: "ERROR"は適用されなかったことを意味します。理由はMessageを読んでください。

メモ

• テストエンドポイントは、フリップブックにWebhookが設定されていない場合、ERROR "No lead webhook is configured for this flipbook."を返します。先にset-lead-webhookで設定してください。
• テストペイロードは、実際のリードを保存することも、通知メールを送信することもありません。