開発者向けドキュメント

広告主システムとASPBANKをサーバー間で連携するための Conversion API / Webhook の仕様です。 APIキーと署名シークレットは、広告主管理画面の「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" } }
                     // 自動承認の案件では "approved" で返ります
→ 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 で検証できます。検証に使う secret は、Webhook の登録時に一度だけ表示される値（APIキーの署名シークレットとは別物）です。

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

{
  "event": "CONVERSION_APPROVED",
  "occurred_at": "2026-01-01T00:00:00.000Z",
  "conversion": { "id": "...", "order_id": "ORDER123",
                  "status": "APPROVED", "amount": 50000, "currency": "JPY",
                  "conversion_type": "...", "traffic_source": "...",
                  "converted_at": "2026-01-01T00:00:00.000Z" }
}

署名の検証例 (Node.js)

const crypto = require("crypto");
// header: X-ASP-Signature の値 / secret: Webhook 登録時の secret / body: 受け取った生のボディ
function verify(header, secret, body) {
  const [t, v1] = String(header).split(",").map(s => s.split("=")[1]);
  if (!t || !v1) return false;
  // 5分より古い(新しい)署名は受け付けない (リプレイ対策)
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
                         .update(t + "." + body).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

ご利用開始まで

APIキーは広告主アカウントの開設後、管理画面の「API連携」から発行できます。まずは広告掲載のご相談からお問い合わせください。