アフィリエイトAPI 仕様書

---
doc: affiliate-report-api-contract
status: approved (2026-08-15・ユーザー指示で新規作成)
source: core.stellaplex.com (実装コードからの抽出)
created: 2026-08-15
target_reader: AI
---

## affiliate_report_api (成果の報告・第三者／自社決済のサービス向け)

positioning: プラットフォームのアフィリエイトを、**当社の決済を通らないサービス**へ提供するための口。
  当社の部品(SDK)が入っていないサービスからでも使える。

why_this_exists:
  既存の partner_affiliate は「**当社の決済を通る**」ことが前提で、報酬は決済のたびに
  当社が天引きして自動で分配していた(連携サービス側の実装は ref を渡すだけ)。
  ビジネスプランや第三者のサービスは**自社の決済**なので、当社は天引きできない。
  → **成果を報告してもらい、あとで清算する**方式をこの口で提供する。

## two_methods (混ぜないこと)

| | 天引き方式(既存) | 報告と清算方式(この文書) |
|---|---|---|
| 対象 | 当社の決済を通るサービス | 自社決済・第三者のサービス |
| 実装 | ref を受け取って partner_code として決済APIへ渡すだけ | この口へ成果を送る |
| 報酬の分配 | 決済のたびに当社が自動で分配 | **運営が月次で清算** |
| ライセンス認証 | 必要 | **不要** |
| 当社の部品(SDK) | 入る | **入らない** |

## authentication (3つの関門・すべて通る必要がある)

1. **APIキー** … `X-Api-Key: <発行された鍵>`
   ★共有ホスティング(Xserver 等)では `Authorization` ヘッダーが経路で削除されることがある。
   　**必ず `X-Api-Key` を使うこと。**
2. **送信元** … 鍵に登録した IP／CIDR からのみ通る。
   ★★**この口はサーバーどうしの通信なので、必ず IP か帯(CIDR)でご登録ください。**
   　ドメインの指定は**ブラウザから叩かれたときだけ**効きます(サーバーどうしでは
   　名乗りが送られてこないため)。**ドメインだけを登録すると、その鍵は常に断られます。**
   ★登録が空の鍵はどこからでも通る(既存の鍵の動きを変えないため)。
   ★★**これは二つ目の鍵**。**主役は鍵そのものと口の絞り**なので、
   　鍵はこれまでどおり厳重に扱ってください。
3. **口の絞り(scope)** … 鍵に `affiliate.report` が付いていること。
   ★第三者へ渡す鍵は**これだけ**を付ける(付けないと売上や決済まで叩ける)。

key_issuance: 鍵は運営が発行する。**1サービスにつき何本でも持てる**
  (入れ替え中に両方を生かす・試験用と本番用を分ける、といった使い方のため)。

## endpoints

### POST /api/affiliate/reports (成果を報告する)

request:
```json
{
  "partner_code": "P-ABC123",
  "external_order_id": "ORDER-20260815-001",
  "amount": 12000,
  "occurred_at": "2026-08-15T10:00:00+09:00",
  "idempotency_key": "evt-0001",
  "recurring": false
}
```

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| partner_code | string(64) | ○ | 当社のパートナーコード。`?ref=` で受け取った値をそのまま送る。★大文字小文字は問わない |
| external_order_id | string(128) | ○ | そちらのサービスでの注文の識別子。**当社は中身を解釈しない** |
| amount | integer | ○ | 成果の金額(円・税込)。**1以上・10,000,000以下**。★これを超える取引は運営へご相談ください |
| occurred_at | string(64) | ○ | いつの成果か(ISO 8601)。★**未来は受け取らない**（時計のずれのため+1日までは受ける）。★時差付きで送ると日本時間へ換算して保存する |
| idempotency_key | string(128) | ○ | **送り直しを見分ける合言葉**。★**サービスごと**に一意(鍵を入れ替えても引き継がれます)。★試験用の鍵と本番用の鍵は**別々に数えます** |
| recurring | boolean | | **継続課金の1回ぶんなら `true`**。★既定は `false`(＝買い切りの注文)。**掛ける報酬率が別なので、必ず正しく送ってください** |

response (201 Created / 200 OK):
```json
{
  "status": "success",
  "report": {
    "id": 123,
    "partner_code": "P-ABC123",
    "external_order_id": "ORDER-20260815-001",
    "amount": 12000,
    "occurred_at": "2026-08-15T10:00:00+09:00",
    "idempotency_key": "evt-0001",
    "status": "received"
  },
  "duplicate": false
}
```

★**送り直しのときは 200 と `"duplicate": true`** が返り、**何も足されない**。
★★**送り直しで中身は書き換わらない**(最初に受け取ったものが正)。
　金額を後から書き換えられないようにするため。

### POST /api/affiliate/reports/cancel (成果を取り消す)

返品・キャンセルが発生したときに送る。もとの報告と**同じ `idempotency_key`** を指す。

```json
{ "idempotency_key": "evt-0001" }
```

★二度取り消しても同じ答えが返る(送り直しがあるため)。

## errors

| HTTP | error_code | 意味 | どうすればよいか |
|---|---|---|---|
| 401 | — | 鍵が無い・無効 | 鍵を確認する |
| 403 | — | 送信元が登録外／口の絞りに合わない | 運営へ連絡する |
| 404 | not_found | その報告が無い(取り消し時) | `idempotency_key` を確認する |
| 422 | invalid_request | 入力の誤り | `details` に項目ごとの理由が入る |
| 422 | unknown_partner_code | 知らない・いま使えないパートナーコード | ★**送り直さない**。値を確認する |
| 422 | partner_not_approved | そのパートナーが、このサービスの紹介を承認されていない | ★**送り直さない**。運営へ連絡する |
| 422 | service_not_configured | **当社側**で、このサービスの紹介料の設定が確認できない | ★**送り直さない**。運営へ連絡する（そちらの誤りではありません） |
| 422 | invalid_occurred_at | 日時が読めない・未来 | 値を確認する |
| 429 | — | 回数の上限(120回/分) | 間隔を空けて送り直す |

★★**`unknown_partner_code` と `partner_not_approved` は送り直しても直らない**。
　当社はここで断ることで、書き間違いにその場で気づけるようにしている
　(黙って受け取ると、そのパートナーには**永久に支払われない**)。

## retry_policy (★必ず読むこと)

★★★**当社が落ちても、そちらのサイトを止めないこと。**
　報告は**あとから送れる**。決済や注文の完了を、この口の応答で止めてはいけない。

推奨する形:
1. 注文が確定したら、**まず自分の側に記録する**(`idempotency_key` もここで決める)
2. 報告は**あとから非同期で送る**(キュー・定期処理)
3. 失敗したら**間隔を空けて送り直す**(1分 → 5分 → 30分 → 6時間 のように)
4. `4xx` のうち 429 以外は**送り直さない**(値が誤っているので、直さない限り何度でも失敗する)

★`idempotency_key` は**そちらで決める**。注文IDから作るのが確実
  (例: `order-20260815-001`)。★注文が同じなら**必ず同じ値**にすること。

★★**鍵を入れ替えても、同じ成果は二度数えません**(数える単位はサービスです)。
　入れ替え中に古い鍵と新しい鍵の両方から送り直しても安全です。
★★**試験用の鍵と本番用の鍵は、別々に数えます**。
　試験で使った `idempotency_key` を本番でもう一度使っていただいて構いません。

## reward (報酬額の決まり方)

★★**報酬額は、当社が受け取った時点で確定します**(あとで率を変えても、
　すでに受け取った報告の額は変わりません)。

★★★**買い切りと継続で、掛ける率が別です。**
　・`recurring: false`(既定) … **買い切りの報酬率**、または**買い切りの固定額**
　・`recurring: true` … **継続の報酬率**
　★当社には見分けようがないので、**そちらで正しく指定してください**。
　　取り違えると、設定によっては**数倍ずれます**。

★パートナーごとに個別の率が設定されている場合は、そちらが優先されます。

★★**継続の上限月数（`recurring_max_months`）は、この方式では効きません。**
　当社には「その契約の何回目か」を知る手段がないためです。
　上限を設けたい場合は、**そちらで数えて、上限に達したら送らない**ようにしてください。

★★**2段階目の紹介料（tier2）は、この方式では発生しません。**
　紹介元のパートナーへのお支払いは、当社の決済を通る取引だけが対象です。

★**1つのサービスに複数の運営者が設定を持っている場合は、お受けできません**
　(どの設定で計算すべきかを当社が決められないため)。運営へご相談ください。

## settlement (清算・当社の側の動き)

★★**この口はお金を動かさない。** 受け取って記録するだけ。
　運営が月次で内容を確認し、**そちらからの入金を確認してからパートナーへ支払う**
　(★当社は立て替えない)。

★偽の報告をされても当社は損をしないが、**入金の確認が取れなければ支払われない**ので、
　報告の正しさはそちらの責任で担保すること。

## privacy (★送らないでいただきたいもの)

★★**`external_order_id` に個人情報を入れないでください。**
　当社はこの値を**そのまま保存し、運営の画面に表示します**。
　注文番号など、**そちら側でだけ意味を持つ識別子**にしてください
　(メールアドレス・氏名・電話番号を入れないこと)。

★当社がこの口で受け取るのは、**パートナーコード・注文の識別子・金額・日時**だけです。