フリップブックを販売して売上を確認する

できること

これら5つのエンドポイントは、フリップブックを販売し、その売上を追跡するライフサイクル全体をカバーします。

• 販売を設定する — 価格、通貨、フリップブックを販売するかどうかを設定する。
• チェックアウトページをカスタマイズする — タイトル、ボタンのテキスト、ボタンの色。
• 決済ゲートウェイを選ぶ — ゲートウェイを選び、その認証情報を設定する。
• 購入を記録する — 自前の決済フローで行われた完了済みの販売を記録する。
• 売上を確認する — 完了済み（またはカゴ落ち）の販売記録を、ページ送り・CSVエクスポートで一覧表示する。

始める前に

• APIキー — すべてのリクエストでX-Api-Keyヘッダー、またはAuthorization: Bearer YOUR_API_KEYとして送ります。
• すべてのリクエストの送信先はベースURL https://go.fliplink.meです。
• List Salesを除くすべてのエンドポイントは、フリップブックの数値IDを{flipbookId}パスパラメーターとして取ります。例: .../set-sale-settings/96216。
• 書き込みエンドポイント（Set Sale Settings、Set Sale Page Text、Set Sale Gateway、Set Flipbook Purchase）は、ボディをform-urlencodedのフィールド（JSONではありません）として送ります。

販売を設定する

PUT /api/set-sale-settings/{flipbookId}は、フリップブックの販売（価格、通貨、オプション）を設定します。販売モードを有効にすると、メール認証が自動的に有効になり、リードのメールが必須になります。

主なフィールド:

• SaleAmount — 通貨の主単位（例: ドル）での価格で、小数も使えます。9.99は$9.99、1000は$1,000を意味します。これはセント／補助単位の値ではありません。
• SaleCurr — 通貨コード（デフォルトはusd）です。/api/list-currenciesから有効なコードを選んでください。

curl -X PUT 'https://go.fliplink.me/api/set-sale-settings/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsForSale=true' \
  --data-urlencode 'SaleCurr=usd' \
  --data-urlencode 'SaleAmount=9.99'

レスポンス:

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

チェックアウトページをカスタマイズする

PUT /api/set-sale-page-text/{flipbookId}は、フリップブックの販売／チェックアウトページに表示されるマーケティングの文言を設定します。

curl -X PUT 'https://go.fliplink.me/api/set-sale-page-text/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'SalePageTitle=' \
  --data-urlencode 'SaleAccessPageTitle=' \
  --data-urlencode 'SalePurchaseButtonText=' \
  --data-urlencode 'SaleButtonText=' \
  --data-urlencode 'SaleAccessButtonText=' \
  --data-urlencode 'SaleButtonColor='

レスポンス:

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

決済ゲートウェイを選ぶ

PUT /api/set-sale-gateway/{flipbookId}は、このフリップブックを販売するときに使う決済ゲートウェイを選択・設定します。

curl -X PUT 'https://go.fliplink.me/api/set-sale-gateway/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'SaleGatewayName=' \
  --data-urlencode 'SaleGatewayKey=' \
  --data-urlencode 'SaleGatewaySecret='

レスポンス:

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

購入を記録する

POST /api/set-flipbook-purchase/{flipbookId}は、完了済みのフリップブック販売（購入）を記録します。FlipLinkのStripeチェックアウトを通さず、自前の決済フローで行われた購入を記録するのに使います。購入者のEmailと、決済ゲートウェイの参照PaymentRef（Stripeの場合はPaymentIntent ID、pi_...）を送ります。どちらも必須です。Amount/Currencyは送らないでください。これらは決済参照からサーバー側で導かれます。

curl -X POST 'https://go.fliplink.me/api/set-flipbook-purchase/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Email=customer@example.com' \
  --data-urlencode 'PaymentRef=pi_3O1234567890abcdef'

レスポンス:

{
  "Result": "OK",
  "Message": "Purchase recorded successfully"
}

売上を確認する

GET /api/list-salesは、フリップブックの販売／購入記録（購入者のメール、フリップブック、金額、日付）と、売上テーブルの列定義を一覧表示します。ページ送りと、IsDownloadによるCSVエクスポートに対応しています。IsAbandoned=trueを設定すると、完了済みの販売の代わりにカゴ落ちの販売を返します。

curl -X GET 'https://go.fliplink.me/api/list-sales?ItemIDs=&SearchText=&PageNo=1&Offset=0&IsDownload=true&IsAbandoned=false' \
  -H 'X-Api-Key: YOUR_API_KEY'

レスポンス:

{
  "Result": "OK",
  "Items": [],
  "Columns": [
    {
      "ID": 1,
      "data": "ID",
      "title": "ID",
      "type": "numeric",
      "hidden": true,
      "readOnly": true,
      "defaultValue": "",
      "source": "",
      "width": 0,
      "backgroundColor": "",
      "align": "left"
    }
  ],
  "TotalRecordCount": 0
}

起こりうるエラー

• APIキーが欠けているか無効な場合 → HTTP 401。これはプレーンなUnauthorized HTMLページを返し、JSONボディはありません。X-Api-Keyヘッダーが存在し、正しいことを確認してください。
• 不明なflipbookId（またはキーが所有していないもの） → HTTP 200で{ "Result": "ERROR", "Message": "Item not found" }。これはSet Sale Settings、Set Sale Page Text、Set Sale Gateway、Set Flipbook Purchaseに当てはまります。
• 不明またはスペルミスのボディフィールド → HTTP 200で{ "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }。
• 購入に必須のフィールドが欠けている場合（Set Flipbook Purchase） → { "Result": "ERROR", "Message": "Email is required." }または{ "Result": "ERROR", "Message": "PaymentRef is required." }。

メモ

• Set Sale Settingsで販売モード（IsForSale）を有効にすると、メール認証が自動的に有効になり、リードのメールが必須になります。
• Set Flipbook Purchaseは、自前の決済フローで行われた購入のためのものです。FlipLinkのStripeチェックアウトを通さずに販売を記録できます。