先把要寫的東西放上來，剩下的再解釋。訂單成立、而且你知道它來自推廣夥伴時，從你的後端打這一支：

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

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

這就是必要的全部。merchantSlug 就是你的識別碼，沒有另外的 API Key 要管。點擊回報是選用的，不做只是少一份點擊統計，分潤照算。

第一個會出事的地方：重複回報

金流的 webhook 會重送。第三方支付超時會重送。你自己的重試邏輯也會重送。如果每一次重送都產生一筆新的成交，你就會為同一張訂單付兩次分潤，而且通常是月底對帳才發現。

Afflixo 是以 orderId 在你的計畫範圍內去重的。同一組 orderId 再送一次，回給你的是原本那一筆成交和那一份分潤，不會多開。所以重送是安全的，你也不需要帶任何額外的標頭。

條件只有一個：orderId 在你自己的系統裡必須唯一。用你的訂單編號通常就對了。如果你的訂單編號會因為改單、退款重開而重複，那要先處理這件事，不然去重會把兩張不同的訂單當成同一張。

第二個會出事的地方：歸因掉了

系統要知道這筆訂單算誰的。夥伴代碼有三個來源，依序取用：

  1. 你在 body 裡送的 affiliateCode。
  2. x-affiliate-code 標頭。
  3. 訪客身上的 affiliate_ref cookie，這個 cookie 在他點推薦連結時就寫好了。

三個都沒有的話，請求會被擋下來回 400，因為系統無法判斷這筆該算給誰。這是刻意的：與其猜一個，不如讓你當場知道歸因斷在哪裡。

實務上最常斷掉的是第三種。訪客在手機上點了推薦連結，後來在電腦上結帳，cookie 不在那台機器上。或者你的結帳流程走的是另一個網域，cookie 帶不過去。這兩種情況下，正確的做法是在訪客落地時就把代碼從網址參數讀出來，存進你自己的 session 或訂單資料，結帳時再從 body 明確送出來，不要依賴 cookie 還在。

分潤規則

三個設定大概涵蓋所有情況：抽成、固定金額，以及掛在單一夥伴身上的費率。你先給整個計畫一個預設值，需要時再對個別夥伴覆寫；兩邊都有的時候，以夥伴身上那個為準。

適用範圍是另一回事，跟費率分開設：只算首單、只算前 N 筆，或限定一段時間內。

招募頁

推廣夥伴看到的第一頁通常就是你的招募頁，而這一頁老得很快：優惠會改、費率會改、截圖會過期。如果改一句標題要開票給工程師，那這頁很快就沒人改了。所以它是在視覺化編輯器裡改的，編輯器裡看到什麼，線上就是什麼，中間沒有部署這一關。

撥款

夥伴提出提領，你核准，然後用你原本就在用的方式付錢。Afflixo 只把狀態記下來，避免同一筆被核准兩次。它不碰金流，這是刻意留的界線：錢什麼時候出去，由你決定。

不做的事

多層分潤、每個商戶一個自訂網域、透過 PayPal 或 Stripe 自動撥款、美元以外的幣別，目前都沒有。如果你要的就是上面那幾項，完整規格在開發文件。