開発者向けドキュメント

広告主システムとASPBANKをサーバー間で連携するための Conversion API / Webhook の仕様です。 APIキーと署名シークレットは、広告主アカウント開設時に発行されます。

認証

すべてのリクエストに Bearer トークン、書き込み系には HMAC-SHA256 署名が必要です。

Authorization: Bearer ak_live_xxxxxxxx
X-Signature: t={unix秒},v1={HMAC-SHA256(secret, "{t}.{リクエストボディ}")}
Idempotency-Key: {注文ごとに一意な値}   ← 再送時の二重登録防止 (推奨)

成果の登録 — Conversion API

POST https://aspbank.jp/api/v1/conversions
Content-Type: application/json

{
  "click_id": "clk_xxx",     // LPに付与される asp_cid パラメータの値
  "order_id": "ORDER123",    // 貴社システムの注文ID (重複防止キー)
  "amount": 50000,           // 売上金額 (円・整数)
  "currency": "JPY"
}

→ 201 { "data": { "conversion_id": "...", "status": "pending" } }
→ 200 { "data": { "duplicated": true, ... } }   // 同一order_idの再送時

成果の承認・否認

PATCH https://aspbank.jp/api/v1/conversions/{conversion_id}

{ "status": "approved" }            // approved | rejected | cancelled
{ "status": "rejected", "reason": "重複注文のため" }

Webhook 受信

成果の作成・承認・否認・取消を貴社エンドポイントへ通知します。2xx以外の応答は指数バックオフで最大8回再送されるため、 X-ASP-Delivery ヘッダで冪等化してください。署名は上記と同形式の X-ASP-Signature で検証できます。

POST {貴社URL}
X-ASP-Event: CONVERSION_APPROVED
X-ASP-Delivery: {配送ID}
X-ASP-Signature: t=...,v1=...

{
  "event": "CONVERSION_APPROVED",
  "conversion": { "id": "...", "order_id": "ORDER123",
                  "status": "APPROVED", "amount": 50000, "currency": "JPY" }
}

署名の検証例 (Node.js)

const crypto = require("crypto");
function verify(header, secret, body) {
  const [t, v1] = header.split(",").map(s => s.split("=")[1]);
  const expected = crypto.createHmac("sha256", secret)
                         .update(t + "." + body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

ご利用開始まで

APIキーの発行は広告主アカウント開設時に行います。まずは広告掲載のご相談からお問い合わせください。