送るリクエスト

先に実物を出します。紹介経由の注文が確定したら、自社のサーバーからこれを 1 回呼びます。

POST /api/<merchantSlug>/track/conversion
Content-Type: application/json

{
  "orderId": "ORD-12345",
  "amount": 99.00,
  "currency": "USD",
  "affiliateCode": "ABC123"
}

必須はこれだけです。URL の merchantSlug が識別子なので、管理すべき API Key はありません。管理画面で Webhook シークレットを設定した場合のみ、リクエストの生ボディに対する HMAC-SHA256 署名が追加で検証されます。クリック通知は任意で、送らなくても失うのはクリック統計だけです。

壊れる 1 か所目：重複計上

決済の Webhook は再送されます。決済代行のタイムアウトでも再送されます。自社のリトライでも再送されます。再送のたびに新しい成果が作られると、1 件の注文に対して報酬を二重に払うことになり、気づくのはたいてい月末の突合のときです。

Afflixo は自社プログラムの範囲内で orderId による重複排除を行います。同じ orderId をもう一度送っても、新しい成果ではなく既存の成果と報酬がそのまま返ります。したがって再送は安全で、追加のヘッダーも不要です。

条件は 1 つ、orderId が自社システム内で一意であることです。通常は注文番号がそのまま使えます。キャンセルや再作成で番号を再利用する運用になっている場合は、先にそちらを整理してください。そうしないと、別の注文が同じ注文として扱われます。

壊れる 2 か所目：紐付けが切れる

どのパートナーの成果かは、次の順に探されます。

  1. ボディの affiliateCode
  2. x-affiliate-code ヘッダー
  3. 紹介リンクが設定した affiliate_ref Cookie

3 つとも見つからない場合、リクエストは 400 で拒否されます。誰に付ければよいか判断できないからです。これは意図した挙動で、黙って誤った相手に付けるより、その場で失敗させる方を選んでいます。

実務で最も切れやすいのが 3 番目です。紹介リンクをスマートフォンで開き、後から PC で購入すれば、Cookie は別の端末にあります。決済ページが別ドメインにあり、戻ってきたときに Cookie が付いてこない構成でも同じことが起きます。

確実にするには、Cookie に頼らないことです。訪問者が着地した時点で URL パラメータからコードを読み、自社のセッションか注文レコードに保存し、確定時にボディの affiliateCode として明示的に送ります。

通貨の扱い

currency は保存されますが、換算は行われません。報酬は amount に入れた数値からそのまま計算されます。Afflixo は米ドルで精算するため、円建てで請求している場合は送信前に換算してください。そうしないと、円の金額がドルとして記録されます。

報酬ルールと支払い

報酬は料率か定額で、プログラム全体の既定値を置き、必要な相手だけ個別に上書きします。両方ある場合はパートナー側が優先されます。適用範囲は料率とは別で、初回注文のみ、最初の N 件、期間指定から選べます。

支払いはパートナーが申請し、あなたが承認し、普段の方法で支払います。Afflixo は状態を記録して二重承認を防ぐだけで、資金は動かしません。これは意図した線引きです。

多階層の報酬、広告主ごとの独自ドメイン、PayPal や Stripe による自動支払い、米ドル以外での精算は現時点でありません。仕様の詳細は開発ドキュメントにあります。