Back to Details

syndicate-test-conversion

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syndicate Links Test Conversion

Syndicate Links测试转化

Use this skill to verify merchant attribution without creating a real payable affiliate event.
The shipped test rail is:
http
POST https://api.syndicatelinks.co/merchant/test-links
POST https://api.syndicatelinks.co/merchant/test-links/:code/fire-conversion
Do not use the production conversion endpoint for smoke tests, do not add 
isTest
to production conversion payloads, and do not point at a separate sandbox URL.
使用该技能可验证商家归因，无需创建真实的可结算联盟事件。
官方提供的测试流程接口如下：
http
POST https://api.syndicatelinks.co/merchant/test-links
POST https://api.syndicatelinks.co/merchant/test-links/:code/fire-conversion
请勿使用生产转化端点进行冒烟测试，不要在生产转化请求体中添加
isTest
参数，也不要指向单独的沙箱URL。

Prerequisites

前置条件

  • TOKEN
    set to a Syndicate Links merchant key
  • A product ID owned by the merchant
  • Optional: a program ID when the product belongs to a specific program
The test link flow creates or reuses an internal test affiliate and marks generated test events so they stay out of real publisher metrics and payouts.
  • 已设置
    TOKEN
    为Syndicate Links商家密钥
  • 拥有商家名下的产品ID
  • 可选：若产品属于特定项目，需提供项目ID
测试链接流程会创建或复用内部测试联盟账号，并标记生成的测试事件，使其不会计入真实发布商的指标和佣金结算。

1. Confirm the merchant key is present

1. 确认商家密钥已配置

bash
test -n "${TOKEN:-}" || { echo "Set TOKEN to your Syndicate Links merchant key first"; exit 1; }
bash
test -n "${TOKEN:-}" || { echo "请先将TOKEN设置为你的Syndicate Links商家密钥"; exit 1; }

2. Generate a merchant test link

2. 生成商家测试链接

bash
curl -sS -X POST https://api.syndicatelinks.co/merchant/test-links \
  -H "Authorization: Bearer ${MERCHANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product_uuid",
    "programId": "program_uuid"
  }' | python3 -m json.tool
If the product is products-first and has no program, omit 
programId
. The API can mint the internal house program needed for the test-link flow.
Expected response shape:
json
{
  "trackingLink": {
    "id": "...",
    "code": "abc123xy",
    "clickUrl": "https://api.syndicatelinks.co/click/abc123xy",
    "destinationUrl": "https://merchant.example/product",
    "productId": "...",
    "programId": "...",
    "affiliateId": "..."
  },
  "affiliate": {
    "id": "...",
    "name": "Merchant Name Internal Test",
    "isInternalTest": true
  }
}
Copy 
trackingLink.code
for the next step.
bash
curl -sS -X POST https://api.syndicatelinks.co/merchant/test-links \
  -H "Authorization: Bearer ${MERCHANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product_uuid",
    "programId": "program_uuid"
  }' | python3 -m json.tool
如果产品以产品为核心且无所属项目，可省略
programId
。API会自动创建测试链接流程所需的内部项目。
预期响应格式：
json
{
  "trackingLink": {
    "id": "...",
    "code": "abc123xy",
    "clickUrl": "https://api.syndicatelinks.co/click/abc123xy",
    "destinationUrl": "https://merchant.example/product",
    "productId": "...",
    "programId": "...",
    "affiliateId": "..."
  },
  "affiliate": {
    "id": "...",
    "name": "Merchant Name Internal Test",
    "isInternalTest": true
  }
}
复制
trackingLink.code
用于下一步操作。

3. Fire the synthetic test conversion

3. 触发模拟测试转化

bash
TRACKING_CODE="abc123xy"
ORDER_ID="test-$(date +%s)"

curl -sS -X POST "https://api.syndicatelinks.co/merchant/test-links/$TRACKING_CODE/fire-conversion" \
  -H "Authorization: Bearer ${MERCHANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"saleAmount\": 99.99, \"orderId\": \"$ORDER_ID\"}" | python3 -m json.tool
Expected response contains 
event
with:
  • type: "conversion"
  • orderId
    matching the test order
  • saleAmount
  • commissionAmount
  • commissionStatus: "approved"
bash
TRACKING_CODE="abc123xy"
ORDER_ID="test-$(date +%s)"

curl -sS -X POST "https://api.syndicatelinks.co/merchant/test-links/$TRACKING_CODE/fire-conversion" \
  -H "Authorization: Bearer ${MERCHANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"saleAmount\": 99.99, \"orderId\": \"$ORDER_ID\"}" | python3 -m json.tool
预期响应包含
event
字段，其中：
  • type: "conversion"
  • orderId
    与测试订单一致
  • saleAmount
    （销售额）
  • commissionAmount
    （佣金金额）
  • commissionStatus: "approved"
    （佣金状态：已批准）

4. Verify the real conversion rail separately

4. 单独验证真实转化流程

For production conversion reporting, use the real merchant endpoint with a real tracking link:
bash
curl -sS -X POST https://api.syndicatelinks.co/merchant/conversions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingCode": "real_tracking_code",
    "orderId": "real_order_id",
    "saleAmount": 99.99,
    "currency": "USD"
  }' | python3 -m json.tool
Use this only when you intentionally want to record a real conversion. The test-link endpoint is safer for smoke tests.
如需生产转化报告，请使用真实商家端点和真实跟踪链接：
bash
curl -sS -X POST https://api.syndicatelinks.co/merchant/conversions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingCode": "real_tracking_code",
    "orderId": "real_order_id",
    "saleAmount": 99.99,
    "currency": "USD"
  }' | python3 -m json.tool
仅当你有意记录真实转化时才使用此接口。测试链接端点更适合冒烟测试。

Quick smoke test script

快速冒烟测试脚本

bash
#!/usr/bin/env bash
set -euo pipefail

PRODUCT_ID="${1:?Usage: $0 <product_uuid> [program_uuid]}"
PROGRAM_ID="${2:-}"
export PRODUCT_ID PROGRAM_ID
BODY=$(python3 - <<'PY'
import json, os
body = {"productId": os.environ["PRODUCT_ID"]}
program_id = os.environ.get("PROGRAM_ID")
if program_id:
    body["programId"] = program_id
print(json.dumps(body))
PY
)

LINK_RESPONSE=$(curl -sS -X POST https://api.syndicatelinks.co/merchant/test-links \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$BODY")

CODE=$(printf '%s' "$LINK_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["trackingLink"]["code"])')
ORDER_ID="test-$(date +%s)"

curl -sS -X POST "https://api.syndicatelinks.co/merchant/test-links/$CODE/fire-conversion" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"saleAmount\":99.99,\"orderId\":\"$ORDER_ID\"}" | python3 -m json.tool
bash
#!/usr/bin/env bash
set -euo pipefail

PRODUCT_ID="${1:?Usage: $0 <product_uuid> [program_uuid]}"
PROGRAM_ID="${2:-}"
export PRODUCT_ID PROGRAM_ID
BODY=$(python3 - <<'PY'
import json, os
body = {"productId": os.environ["PRODUCT_ID"]}
program_id = os.environ.get("PROGRAM_ID")
if program_id:
    body["programId"] = program_id
print(json.dumps(body))
PY
)

LINK_RESPONSE=$(curl -sS -X POST https://api.syndicatelinks.co/merchant/test-links \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$BODY")

CODE=$(printf '%s' "$LINK_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["trackingLink"]["code"])')
ORDER_ID="test-$(date +%s)"

curl -sS -X POST "https://api.syndicatelinks.co/merchant/test-links/$CODE/fire-conversion" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"saleAmount\":99.99,\"orderId\":\"$ORDER_ID\"}" | python3 -m json.tool

Common pitfalls

常见误区

  1. Using real conversion fire for smoke tests. Use 
    /merchant/test-links/:code/fire-conversion
    unless you intentionally want a real conversion.
  2. Missing product ID. 
    POST /merchant/test-links
    requires a merchant-owned product ID.
  3. Wrong tracking code. The fire endpoint requires a test tracking link code, not a real affiliate link code.
  4. Expecting test rows in normal reports. Internal test events are filtered from real metrics by design.
  5. Wrong endpoint prefix. Use the exact merchant test-link paths shown above with no version prefix.
  1. 使用真实转化接口进行冒烟测试：除非有意记录真实转化，否则请使用
    /merchant/test-links/:code/fire-conversion
    接口。
  2. 缺少产品ID：
    POST /merchant/test-links
    接口必须提供商家名下的产品ID。
  3. 跟踪代码错误：触发转化的端点需要测试跟踪链接代码，而非真实联盟链接代码。
  4. 期望在常规报告中看到测试数据：内部测试事件默认会从真实指标中过滤掉。
  5. 端点前缀错误：请使用上述准确的商家测试链接路径，不要添加版本前缀。

Links

相关链接