View Categories

转化作废

转化作废接口用于在付费转化被判定无效时，撤销该转化产生的奖励。

接口按 transaction_id 定位转化记录，取消尚未支付的奖励，并将该转化从付费统计中剔除。

转化因订单全额退款需要撤销时，使用 转化退款 接口。

1. 接口信息 #

POST/api/open/v1/track/void
项目说明
请求域名https://api-service.partnershare.net
请求格式application/json
鉴权X-Api-Key + X-Api-Timestamp + X-Api-Sign，签名算法见 API 鉴权与签名机制
支持的 API Key 版本v2
权限密钥配置了权限列表时需包含 conversion:adjust；未配置权限列表的密钥不受限制
调用方品牌方服务端
幂等同一 transaction_id 重复调用返回 ALREADY_PROCESSED，不重复处理
适用场景转化本身无效：拒付、欺诈、重复下单、测试订单等

2. 请求头 #

Header必填说明
X-Api-Key是v2 密钥的 API Key
X-Api-Timestamp是秒级 Unix 时间戳，300 秒内有效
X-Api-Sign是v2 签名，签名覆盖请求体原文
Content-Type是application/json

3. 请求参数 #

参数类型必填说明
transaction_idstring是转化上报时传入的 transaction_id，前后空白会被去除，最长 255 字符。同一产品下必须唯一匹配一条转化
reasonstring否作废原因，最长 255 字符。写入转化记录和被取消奖励的备注，空字符串按未传处理

4. 处理规则 #

  • 按当前 API Key 所属产品 + transaction_id 查找转化。未找到时返回 1000001；匹配到多条记录时返回 1000005，接口不作处理。
  • 只允许调整付费类转化：purchase 事件，或带正数 conversion_value 的自定义事件。注册等非付费转化返回 1000005。
  • 该转化下状态为待审核或已通过的奖励（含下游子奖励）改为已拒绝，备注追加 API转化作废 及 reason。
  • 已支付的奖励不作变更，仅在响应的 preserved_paid_* 字段中计数。
  • 作废后的转化不再计入付费人数、转化金额等付费统计。
  • 同一转化只能调整一次。已退款的转化调用本接口返回 6000000。
  • 调整在单个事务内完成，失败时不产生部分变更。

5. 请求示例 #

curl -X POST "https://api-service.partnershare.net/api/open/v1/track/void" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Api-Timestamp: 1776677721" \
  -H "X-Api-Sign: 50793d436de0dceee25f7e094e298d1af8bd262329d0787569e7d9cdc8fe2980" \
  -d '{"transaction_id":"order_202604220002","reason":"chargeback"}'

示例签名以 api_secret = sk_your_api_secret 计算，可用于校验签名实现。发送的请求体必须与参与签名的字符串完全一致。

6. 响应 #

6.1 成功 #

{
  "code": 0,
  "message": "Conversion adjustment applied successfully",
  "data": {
    "conversion_id": 1024,
    "transaction_id": "order_202604220002",
    "adjustment_type": 2,
    "status": "APPLIED",
    "cancelled_reward_count": 1,
    "preserved_paid_reward_count": 0,
    "cancelled_sub_reward_count": 0,
    "preserved_paid_sub_reward_count": 0,
    "adjusted_at": "2026-04-22 15:20:31"
  }
}

6.2 重复调用 #

{
  "code": 0,
  "message": "Conversion adjustment has already been processed",
  "data": {
    "conversion_id": 1024,
    "transaction_id": "order_202604220002",
    "adjustment_type": 2,
    "status": "ALREADY_PROCESSED",
    "cancelled_reward_count": 0,
    "preserved_paid_reward_count": 0,
    "cancelled_sub_reward_count": 0,
    "preserved_paid_sub_reward_count": 0,
    "adjusted_at": "2026-04-22 15:20:31"
  }
}

6.3 响应字段 #

字段类型说明
conversion_idintPartnerShare 转化记录 ID
transaction_idstring转化记录上的交易号
adjustment_typeint作废固定为 2
statusstringAPPLIED 本次处理生效；ALREADY_PROCESSED 此前已按作废处理，本次未做变更
cancelled_reward_countint本次取消的奖励条数
preserved_paid_reward_countint已支付、未取消的奖励条数
cancelled_sub_reward_countint本次取消的下游子奖励条数
preserved_paid_sub_reward_countint已支付、未取消的下游子奖励条数
adjusted_atstring / null调整时间，Y-m-d H:i:s，时区 UTC+8

status 为 ALREADY_PROCESSED 时，各计数字段均为 0，不反映首次处理的结果。

7. 错误码 #

业务失败返回 HTTP 200，code 非 0，data 为 null。

codemessage原因
1000001The conversion for the specified transaction was not found当前产品下没有该 transaction_id 的转化
1000004This endpoint requires signature version 2使用了 v1 密钥
1000004Missing required permission: conversion:adjust密钥权限列表未包含该权限
1000004其他鉴权消息见 API 鉴权与签名机制
1000005The transaction_id field is requiredtransaction_id 为空
1000005The transaction_id field has an invalid formattransaction_id 不是字符串或整数
1000005The transaction_id field must not exceed 255 characterstransaction_id 超过 255 字符
1000005The reason field has an invalid formatreason 不是字符串
1000005The reason field must not exceed 255 charactersreason 超过 255 字符
1000005Multiple conversion records match the specified transaction_id; the request cannot be processed automatically同一 transaction_id 对应多条转化
1000005This conversion type does not support refunds or voids非付费类转化
6000000This conversion has already been fully refunded and cannot be voided again已退款的转化调用作废接口
6000000Failed to apply the conversion adjustment服务端异常，可重试；持续出现时请联系 PartnerShare 技术支持

8. 接入注意事项 #

  • 付费转化上报时应传入唯一的 transaction_id，否则无法定位转化记录。
  • 作废后该转化及其奖励不再计入统计，请确认转化确实无效后再调用。
  • 接口具备幂等性，请求超时后可使用相同参数重试。
  • 调整操作不可通过接口撤销，建议先使用测试数据验证签名与流程。
更新 07/09/2026