Tracking, Tag và S2S

Affiliate project hỗ trợ redirect tracking, browser tag conversion tracking, và server-to-server postback.

Partner Tracking URL

Partner nhận URL theo định dạng:

https://go.mcv.network/{trackingCode}

Khi mở URL, MCV ghi một AffiliateClick và redirect tới advertiser destination URL kèm UTM parameters và:

mcv_aff={trackingCode}
mcv_click_id={clickId}

Advertiser nên lưu mcv_click_id khi có thể. Click ID cho attribution chắc hơn tracking code đơn thuần.

Browser Tag Endpoint

Dùng browser tag endpoint cho báo cáo conversion đơn giản phía client:

https://track.mcv.network/tag/{projectSlug}?tracking_code={trackingCode}&event_type=qualified_lead&external_id=lead_123

Parameter được chấp nhận:

Parameter	Bắt buộc	Mô tả
tracking_code	Bắt buộc trừ khi gửi click_id	Partner tracking code.
click_id	Bắt buộc trừ khi gửi tracking_code	Click ID từ mcv_click_id.
event_type	Có	qualified_lead hoặc sale.
external_id	Khuyến nghị	Lead/order ID phía advertiser để idempotency.
order_id	Bắt buộc cho sale S2S	Advertiser order ID dùng reconciliation.
sale_amount	Chỉ sale	Sale amount theo currency của project.
currency	Chỉ sale	Mã tiền tệ 3 ký tự. Mặc định là currency của project.
customer_hash	Không bắt buộc	Customer identifier đã hash để fraud review mà không lộ PII.

Tag endpoint mặc định trả về ảnh GIF 1x1. Thêm format=json để nhận JSON response.

Server-to-Server Postback

Dùng S2S khi backend của advertiser có thể báo conversion trực tiếp.

POST https://track.mcv.network/s2s/{projectSlug}

Advertiser cũng có thể dùng API gateway alias nếu policy nội bộ yêu cầu tích hợp qua API domain:

POST https://api.mcv.network/affiliate/s2s/{projectSlug}

Payload:

{
  "tracking_code": "aff_1_2_partner",
  "click_id": "clk_...",
  "event_type": "sale",
  "order_id": "ORDER-1001",
  "external_id": "checkout_1001",
  "sale_amount": "100.00",
  "currency": "USD",
  "customer_hash": "sha256_customer_identifier",
  "signature": "..."
}

Chữ Ký S2S

Tạo signature payload đúng thứ tự sau:

tracking_code|click_id|event_type|order_id|sale_amount|currency

Sau đó ký bằng postback secret của affiliate project:

signature = HMAC_SHA256(payload, postback_secret)

Request có signature không hợp lệ trả 403.

Response Body

Postback thành công trả về dữ liệu reconciliation theo order:

{
  "ok": true,
  "response_code": "000000",
  "message": "Conversion accepted.",
  "project": "q3-partner-program",
  "conversion_id": 123,
  "order_id": "ORDER-1001",
  "external_id": "checkout_1001",
  "event_type": "sale",
  "status": "pending",
  "deduped": false,
  "sale_amount_cents": 10000,
  "commission_cents": 3500,
  "currency": "USD",
  "occurred_at": "2026-07-09T10:30:00+07:00"
}

Idempotency Và Reconciliation

Gửi order_id ổn định cho mỗi sale. MCV lưu một conversion cho mỗi project và order ID để tránh payout trùng khi postback lặp lại.

Conversion vào trạng thái pending trước. Advertiser sở hữu project có thể approve order hợp lệ rồi pay commission từ ví advertiser sang ví partner. Operations vẫn có thể approve, reject, hoặc settle conversion từ affiliate reconciliation console khi cần support hoặc xử lý tranh chấp.

Khi commission được paid, MCV gửi email credit ví cho partner ngay lập tức. Cuối ngày, MCV gửi cho mỗi advertiser digest các affiliate conversion đã paid trong ngày và số dư ví cuối ngày. Command digest là php artisan affiliate:send-daily-paid-digest và được schedule hằng ngày lúc 23:55 Asia/Ho_Chi_Minh.

Legacy URL

Các URL cũ vẫn được giữ tạm thời để không làm hỏng link đã phát hành:

https://app.mcv.network/aff/{trackingCode}
https://app.mcv.network/affiliate/tag/{projectSlug}
https://app.mcv.network/affiliate/s2s/{projectSlug}

Tích hợp mới nên dùng go.mcv.network và track.mcv.network.