OpenApi
    • API 说明文档
    • 基础档案
      • 游戏列表
        GET
      • 平台列表
        GET
      • 产品列表
        GET
      • 批量设置产品阶梯销售价
        POST
      • 区服列表(树形)
        GET
      • 渠道列表
        GET
      • 批量设置产品毛利率
        POST
      • 产品分类列表(树形)
        GET
      • 添加产品
        POST
      • 添加产品库产品
        POST
      • 游戏档案全量拉取(增量同步)
        GET
      • 平台档案全量拉取(增量同步)
        GET
      • 区服档案全量拉取(增量同步)
        GET
      • 当前租户币种设置
        GET
      • 获取销售价格管理列表
        GET
    • 采购商
      • 原始订单
        • 创建原始订单
        • 修改原始订单
        • 修改原始订单交易信息
        • 取消原始订单
        • 暂停原始订单
        • 恢复原始订单
      • 请购单
        • 订单列表
        • 订单详情
        • 更新订单
        • 删除订单
        • 创建订单
        • 暂停订单
        • 恢复订单
        • 取消订单
        • 放弃剩余数量
        • 创建询价
        • 追加询价
        • 重新派单
      • 询价
        • 询价单列表
        • 询价单详情
        • 发布询价单
        • 取消询价单
        • 手动添加供应商
        • 移除供应商
      • 报价
        • 报价列表
        • 报价详情
      • 比价
        • 比价单列表
        • 比价单详情
        • 从询价单创建比价单
        • 选标(分配中标+生成PO)
        • 取消比价单
      • 采购订单
        • 采购订单列表
        • 采购订单详情
        • 暂停采购订单
        • 恢复采购订单
        • 取消采购订单
        • 处理问题单
        • 完结申请审核
        • 催单采购订单
      • 订单变更
        • 变更列表
        • 变更详情
        • 发起变更
      • 对账单
        • 对账单列表
        • 对账单详情
        • 采购商确认对账
        • 采购商发起争议
        • 解决争议
        • 作废对账单
        • 重新生成对账单
      • 付款
        • 付款列表
        • 付款详情
        • 发起付款申请
        • 审批通过
        • 审批驳回
        • 重新提交
        • 登记付款
    • 供应商
      • 询价
        • 询价单列表
        • 询价单详情
      • 报价
        • 报价列表
        • 报价详情
        • 提交报价
        • 作废报价
        • 报价结果列表(含报价明细)
        • 报价结果详情
      • 客户订单
        • 客户订单列表
        • 客户订单详情
        • 开始发货
        • 提交发货(支持分批发货)
        • 申请完结(部分发货订单)
        • 上报问题
      • 订单变更
        • 变更列表
        • 变更详情
        • 确认变更
        • 拒绝变更
      • 对账单
        • 对账单列表
        • 对账单详情
        • 供应商确认对账
        • 供应商发起争议
      • 收款
        • 收款列表
        • 收款详情
        • 关联对账单

    API 说明文档

    一、概述#

    GameSCM SOMS 平台会在订单业务关键节点,主动向使用方配置的回调地址发送 HTTP 通知。使用方无需轮询接口,即可实时感知订单状态变化。

    二、通信协议#

    项目说明
    请求方法POST
    Content-Typeapplication/json
    连接超时15 秒
    读取超时15 秒
    成功应答响应 body 返回纯文本 success(不含引号、不含换行)
    失败判定HTTP 非 2xx、超时、或响应 body ≠ success

    三、重试策略#

    回调失败后,系统按以下间隔自动重试,最多 5 次:
    重试次数间隔
    第 1 次15 秒
    第 2 次30 秒
    第 3 次1 分钟
    第 4 次5 分钟
    第 5 次10 分钟
    超过最大重试次数后,任务标记为「最终失败」,可在后台「队列任务」页面手动重试。

    四、消息体结构#

    每次回调通知的 POST body 为统一 JSON 结构:
    {
      "event": "order.created",
      "timestamp": 1722412800,
      "nonce_str": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "data": {
        "out_order_id": 5001,
        "out_order_no": "OO202507310001",
        "status": 0,
        "status_text": "待派单",
        "game_name": "原神",
        "total_quantity": "100.0000",
        "currency": "USD",
        "total_amount": "5000.00",
        "base_currency": "USD",
        "base_total_amount": "5000.00"
      },
      "sign": "A3F8B2C1D4E5F60718293A4B5C6D7E8F"
    }

    字段说明#

    字段类型说明
    eventstring事件类型标识(见第六节)
    timestampintUnix 时间戳(秒)
    nonce_strstring32 位随机字符串,防重放
    dataobject业务数据,各事件不同(见第七节)
    signstring签名值,MD5 大写(见第五节)

    五、回调通知验签(GameSCM SOMS → 你)#

    ✅ 回调验签与 OpenAPI 请求签名是同一套算法(服务端统一实现,GameSCM SOMS → 你 与 你 → GameSCM SOMS 共用),
    拼串规则详见 第十六节「OpenAPI 请求签名详解」。参考实现:doc/open-api-sdk-php.php
    (请求签名 Signer 与回调验签 NotificationVerifier 共用同一签名核心 Signature,零依赖,php doc/open-api-sdk-php.php --test 可跑通官方回调样例自测)。
    ⚠️ 历史兼容:2026-09-21 之前发出的回调按旧算法(data 整体 JSON 字符串参与签名)生成 sign,与本节算法不兼容;对接方升级到本节算法后,历史消息重推即可对上。

    签名规则#

    1.
    取消息体全部字段(不含 sign),过滤空值(空字符串、null,仅顶层生效)
    2.
    嵌套结构按 key 字典序(ASCII)递归排序;列表数组保持索引顺序
    3.
    展平拼接为 key1=value1&key2=value2&...(data 展平为 data[字段]=值 形式,不是整体 JSON 字符串)
    4.
    末尾追加 &key={AppSecret}
    5.
    对拼接字符串取 strtoupper(md5(...))

    签名示例#

    假设收到消息体:
    {
      "event": "order.created",
      "timestamp": 1722412800,
      "nonce_str": "abc123",
      "data": { "out_order_no": "OO001", "status": 0 },
      "sign": "..."
    }
    签名计算步骤:
    // 1. 移除 sign,递归字典序排序后展平(data 展开为 data[key]=value)
    stringA = "data[out_order_no]=OO001&data[status]=0&event=order.created&nonce_str=abc123&timestamp=1722412800"
    
    // 2. 追加 secret
    stringSignTemp = stringA + "&key=your_app_secret"
    
    // 3. 签名
    sign = strtoupper(md5(stringSignTemp))
    官方完整样例(beta 实测消息体,FSOMS_APP_SECRET 换成你的 AppSecret 即可复现):
    {
      "data": {
        "status": 5,
        "status_text": "已完成",
        "out_order_no": "D260921134255174302-01",
        "raw_order_no": "D260921134255174302"
      },
      "sign": "BC91C0339A4DF0C48648AF7EB0DFC929",
      "event": "order.completed",
      "nonce_str": "2d8b1c973fc135510728d77f9c4ea81f",
      "timestamp": 1789970543
    }

    PHP 验签示例#

    推荐直接使用 doc/open-api-sdk-php.php 中的 NotificationVerifier(与请求签名 Signer 共用同一签名核心 Signature,零依赖,php doc/open-api-sdk-php.php --test 可跑通上述官方样例)。核心逻辑:

    Java 验签示例#


    六、事件类型一览#

    通知采购商的事件#

    event 值说明触发时机
    order.created订单创建请购单创建成功
    order.dispatched订单派单比价选标完成,生成采购订单
    order.completed订单完成同一采购链累计实发满足原请购需求后自动完成,或采购商接受未履约缺口手动完成(两者互斥,请购单进入终态时仅发一次)
    order.cancelled订单取消手动取消订单
    order.paused订单暂停手动暂停订单
    order.resumed订单恢复暂停后恢复执行
    purchase_order.shipping_started订单开始发货供应商点击开始发货,订单进入发货中(首批尚未发出)
    purchase_order.completed采购订单完成供应商发完全部货物,或部分发货完结审核通过
    purchase_order.shipped采购订单部分发货供应商提交本批发货但订单尚未发完
    purchase_order.close_applied采购订单完结申请供应商对部分发货订单申请完结,等待采购商审核
    purchase_order.problem_reported问题上报供应商上报问题
    purchase_order.problem_resolved问题处理采购商处理问题后恢复,或供应商撤销未处理的问题上报(两种来源均同时通知供应商与采购商;撤销来源以 data.problem_revoked=true 标识)
    purchase_order.change_confirmed变更确认供应商确认变更
    purchase_order.change_rejected变更拒绝供应商拒绝变更
    purchase_order.price_change采购订单改价申请供应商按供应商币单价申请改价(stage=applied,待采购商审核,见 7.27)
    quotation.submitted供应商报价供应商提交报价
    comparison.created比价单创建比价单创建成功
    reconciliation.supplier_confirmed供应商确认对账供应商确认,对账完成

    通知供应商的事件#

    event 值说明触发时机
    inquiry.published询价单发布询价单发布,通知供应商报价
    purchase_order.problem_resolved问题处理采购商处理问题后恢复,或供应商撤销未处理的问题上报(同时通知采购商;撤销来源以 data.problem_revoked=true 标识)
    purchase_order.close_audited完结审核结果采购商通过或驳回供应商的完结申请
    purchase_order.urged采购订单催单采购商对未完成采购订单发起催单(data.is_urging=1 + data.urge_time,重复催单保留首次时间)
    purchase_order.change_requested变更申请采购商发起订单变更
    purchase_order.price_change改价审核结果采购商通过/拒绝供应商的改价申请(stage=approved/rejected,见 7.27)
    reconciliation.created对账单生成对账单创建成功
    reconciliation.buyer_confirmed采购商已确认采购商确认对账
    reconciliation.disputed对账争议任一方发起争议
    reconciliation.resolved争议解决采购商解决争议
    reconciliation.voided对账单作废采购商人工作废
    payment.paid已付款登记付款完成

    基础档案变更事件(游戏 / 平台 / 区服)#

    前六类事件均绑定「具体单据 + 对手方租户」,由系统按业务链路精准回推。游戏、平台、区服是全局基础档案(不隶属某一租户),变更采用粗粒度通知 + 对接方增量拉取模式:平台只推送「哪张表发生了什么动作 + 时间点」,不携带明细行 ID,对接方据此调用第 7.x 节的档案同步接口按 updated_since 游标增量拉取即可。
    推送对象:所有开通**产品库接口权限(global_product_enabled)**且回调地址已验证、状态正常的平台。
    event 值说明触发时机
    basic.data.changed基础数据变更游戏/平台/区服的后台新增、修改、删除、导入操作成功后(事务提交时)各推送一条(整批导入仅推 1 条)
    data 字段
    字段类型说明
    tablestring变动的表:game / platform / server
    actionstring动作:create / update / delete / import
    occurred_atstring变动发生的时刻(Y-m-d H:i:s),仅作参考与日志,不作为拉取过滤条件
    对接方增量同步契约(重要)
    1.
    table/action 仅作参考与告警定位,不要据此只拉单表:一次游戏改动可能连带区服软删、平台解绑等多表变化,收到任一 basic.data.changed 后应对 games/platforms/servers 三表均做一次增量拉取。
    2.
    每个对接方自行持久化「上次成功拉取到的游标水位」,拉取时用 updated_since = 水位 - 数秒回溯重叠。因同步接口用 updated_at > updated_since(严格大于)且时间为秒级精度,同秒内的并发变更需靠回溯重叠兜底,重复拉取是幂等的。
    3.
    三表同步接口均已返回软删记录(含 deleted_at 非空行,且删除会刷新 updated_at):对接方拉到 deleted_at 非空的行时,应视为删除并在本地移除;platform 字段(游戏下挂平台)同样含软删平台。
    4.
    未开通 global_product_enabled 的平台不会收到本事件。
    对应拉取接口见第八节「档案全量/增量拉取」(/open-api/v1/archive/sync/games|platforms|servers,updated_since 入参)。

    七、各事件 data 字段详解#

    7.0 链路单据 ID 与单号成对回传#

    回调 data 中,链路上涉及的每张单据都会把「主键 ID」与「业务单号」成对回传:*_no 供人工排查、*_id 供稳定关联与幂等。原始订单来源时还会带上外部原始单号 raw_order_no 及其主键 raw_order_id(见下方安全边界);凡带单值 raw_order_no 的订单流程回调,同时回传该单据的渠道销售编码 channel_code。逐字段映射如下。
    各单据自身主键 ↔ 单号(平台按下表映射注入主键)
    单据单号字段主键字段出现在
    请购单out_order_noout_order_idorder.*;及 purchase_order.*、inquiry.published、quotation.submitted、comparison.created(作为父单)
    采购订单purchase_order_nopurchase_order_idpurchase_order.*
    询价单inquiry_noinquiry_idinquiry.published
    报价单quotation_noquotation_idquotation.submitted
    比价单comparison_nocomparison_idcomparison.created
    对账单reconciliation_noreconciliation_idreconciliation.*
    付款单payment_nopayment_idpayment.paid
    变更单—(无单号)change_idpurchase_order.change_requested / change_confirmed / change_rejected / price_change(业务侧显式携带,同时是 /supplier/change/{id}/* 的路径参数)
    逐事件回传的链路 ID 与安全边界
    event回溯入口(businessType)接收方回传的链路 ID
    order.created / order.dispatched / order.completed / order.cancelled / order.paused / order.resumedout_order采购商out_order_id + raw_order_no/raw_order_id + channel_code(原始单来源)
    purchase_order.completed / purchase_order.shipping_started / purchase_order.shipped / purchase_order.close_applied / purchase_order.problem_reported / purchase_order.change_confirmed / purchase_order.change_rejected / purchase_order.price_change(stage=applied)purchase_order采购商purchase_order_id + 父 out_order_id + raw_order_no/raw_order_id + channel_code(原始单来源);变更事件另含 change_id
    purchase_order.problem_resolvedpurchase_order供应商 + 采购商purchase_order_id + 父 out_order_id(双方均含);raw_order_no/raw_order_id 仅发给采购商(原始单归属方)时回传,发给供应商不含(供应商撤销来源同样双方回传)
    purchase_order.close_audited / purchase_order.change_requested / purchase_order.price_change / purchase_order.urgedpurchase_order供应商purchase_order_id + 父 out_order_id;不含 raw_*(外部单号不得跨租户给供应商);change_requested / price_change 另含 change_id;urged 另含 is_urging + urge_time
    inquiry.publishedinquiry供应商inquiry_id + out_order_id;不含 raw_*
    quotation.submittedquotation → 询价单 → 请购单采购商quotation_id + out_order_id + raw_order_no/raw_order_id + channel_code(原始单来源)
    comparison.createdcomparison → 询价单 → 请购单采购商comparison_id + out_order_id + raw_order_no/raw_order_id + channel_code(原始单来源)
    reconciliation.created / reconciliation.buyer_confirmed / reconciliation.voidedreconciliation供应商reconciliation_id;不含 raw_*
    reconciliation.supplier_confirmedreconciliation → 对账明细 → 采购订单采购商reconciliation_id;原始单来源含 raw_order_no + raw_order_id,跨多张原始单时改给 raw_order_nos + raw_order_ids 数组
    reconciliation.disputed / reconciliation.resolved同上争议对方 / 争议发起方reconciliation_id;raw_* 视接收方是否为原始单归属采购商而定
    payment.paidpayment → 对账单 → 采购订单供应商payment_id;不含 raw_*
    supplier_category_access(供应商类目准入,非本章事件)不适用—与订单无关,不回溯
    注入规则(务必阅读):
    1.
    平台注入的主键与单号成对:上表所列由平台回传的 *_id(当前事件自身单据主键、父请购单 out_order_id、原始单 raw_order_id)其对应 *_no 必在同一 data 中;建议以 *_id 做幂等与关联、*_no 做人工核对。例外(业务侧显式携带、平台不补主键的关联号):quotation.submitted / comparison.created 的 inquiry_no 不补 inquiry_id;payment.paid 的 reconciliation_no 不补 reconciliation_id。需要这些主键时请调对应详情接口换取。
    2.
    父单 out_order_id:采购订单类、询价/报价/比价事件除自身主键外,还带上其父请购单 out_order_id。out_order_no 本就随这些事件下发,out_order_id 与之同级、买卖双方均可见。
    3.
    raw_order_id 只在派生单上出现:非原始订单拆分的单据(raw_order_id = 0)不携带 raw_order_no / raw_order_id;字段缺省即表示本次业务与原始订单无关,不要按空字符串处理。channel_code(渠道销售编码)随单值 raw_order_no 一同回传,同样只在原始单来源且能定位单一订单快照(请购单/采购订单)时给出;跨多张原始单归因(raw_order_nos 数组,如对账单)不带该字段。
    4.
    raw_* 只发给原始单归属采购商:平台按回调接收方租户判定,接收方不是该原始单的采购商时一律不注入(如供应商侧的 inquiry.published、payment.paid、发给供应商的 purchase_order.* 拿不到外部单号),避免跨租户数据泄漏。out_order_id / purchase_order_id 等属平台内部链路信息,不受此限。
    5.
    平台不覆盖业务方已显式给出的同名字段(如部分事件本就带 out_order_no)。
    6.
    本类型新增事件 purchase_order.price_change(见 7.27);除该新增外上表均为既有事件,只是 data 内新增 *_id(及 raw_order_no / raw_order_id / raw_order_ids)字段。
    7.
    示例报文的读取方式:本章示例中 raw_* 只出现在发往采购商的报文里;发往供应商的事件(purchase_order.problem_resolved / close_audited / change_requested / price_change、inquiry.published、reconciliation.created / buyer_confirmed / voided、payment.paid)示例中一律不列 raw_*,联调时不要期待该字段。示例里的各类 *_id 为占位值,真实值以回调为准。

    7.1 order.created — 订单创建#

    {
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "channel_code": "dd373",
      "status": 0,
      "status_text": "待派单",
      "game_name": "原神",
      "total_quantity": "100.0000",
      "currency": "USD",
      "total_amount": "5000.00",
      "base_currency": "USD",
      "base_exchange_rate": "1.000000000000",
      "rate_effective_at": "2025-07-31",
      "base_total_amount": "5000.00"
    }
    字段类型说明
    out_order_idint请购单 ID(与 out_order_no 一一对应)
    out_order_nostring请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    channel_codestring渠道销售编码(取自 channel.code,仅随单值 raw_order_no 回传;非原始单来源不带。其余带 raw_order_no 的订单流程事件同理,见 7.0)
    statusint订单状态码(0=待派单)
    status_textstring状态中文描述
    game_namestring游戏名称
    total_quantitystring总数量(十进制字符串,最多 4 位小数)
    currencystring交易币种(ISO 4217,采购商配置,订单创建时锁定)
    total_amountstring交易币总金额
    base_currencystring本位币代码(平台统计口径币种)
    base_exchange_ratestring订单创建时锁定的交易币→本位币汇率
    rate_effective_atstring汇率牌价日期(yyyy-MM-dd)
    base_total_amountstring本位币总金额(按锁定汇率换算)

    7.2 order.dispatched — 订单派单#

    {
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 3,
      "status_text": "已派单",
      "purchase_order_count": 2
    }
    字段类型说明
    out_order_idint请购单 ID(与 out_order_no 一一对应)
    out_order_nostring请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint订单状态码(3=已派单)
    status_textstring状态中文描述
    purchase_order_countint本次生成的采购订单数量

    7.3 order.completed — 订单完成#

    触发时机:请购单进入终态「已完成」时发一次,两种途径互斥——①同一采购链累计实发满足原请购需求(含赠品全部发齐)后系统自动完成;
    ②采购商接受未履约缺口手动完成(completion_type=manual)。发起补货询价本身不触发本事件;实发不足不会被自动完成,须由手动完成收尾。
    手动完成只收尾「已派但未实发」与「已放弃未派剩余」两类缺口;仍有未派且未放弃的需求时须先派单/追加询价或放弃,不会被静默关闭。
    {
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 5,
      "status_text": "已完成",
      "completion_type": "fully_shipped",
      "completion_type_text": "累计实发满足需求自动完成",
      "complete_time": "2025-07-31 18:20:00",
      "complete_user_name": "系统自动",
      "accepted_gap": []
    }
    字段类型说明
    out_order_idint请购单 ID(与 out_order_no 一一对应)
    out_order_nostring请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint订单状态码(5=已完成)
    status_textstring状态中文描述
    completion_typestring完成方式:fully_shipped=累计实发满足需求自动完成;manual=采购商接受缺口手动完成
    completion_type_textstring完成方式中文描述
    complete_timestring请购单完成时间 YYYY-MM-DD HH:mm:ss
    complete_user_namestring完成操作人(自动完成固定为 系统自动)
    accepted_gaparray手动完成时逐行给出接受的缺口;自动完成(实发满足需求)固定为 []
    accepted_gap[].source_typestringout_order_item=原请购明细缺口;purchase_order_item=采购单赠品行缺口
    accepted_gap[].out_order_item_idint原请购明细 ID(source_type=out_order_item 时有值,否则为 0)
    accepted_gap[].purchase_order_item_idint采购明细 ID(source_type=purchase_order_item 时有值,否则为 0)
    accepted_gap[].purchase_order_nostring相关采购订单号(原请购明细缺口为空)
    accepted_gap[].product_namestring商品名称
    accepted_gap[].external_product_codestring外部商品编码(赠品行为空)
    accepted_gap[].external_product_namestring外部商品名称
    accepted_gap[].required_quantitystring(decimal)应发数量(原请购需求量 / 赠品行订购量)
    accepted_gap[].shipped_quantitystring(decimal)该来源累计实际发货数量
    accepted_gap[].gap_quantitystring(decimal)未履约缺口 = required − shipped
    accepted_gap[].is_giftint1=赠品行缺口(赠品不进补货,未发部分由本事件关闭)
    accepted_gap[].is_abandonedint1=该原请购明细的未派剩余已被放弃

    7.4 order.cancelled — 订单取消#

    {
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 8,
      "status_text": "已取消",
      "cancel_reason": "客户主动取消"
    }
    字段类型说明
    out_order_idint请购单 ID(与 out_order_no 一一对应)
    out_order_nostring请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint订单状态码(8=已取消)
    status_textstring状态中文描述
    cancel_reasonstring取消原因

    7.5 order.paused — 订单暂停#

    {
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 6,
      "status_text": "已暂停"
    }
    字段类型说明
    out_order_idint请购单 ID(与 out_order_no 一一对应)
    out_order_nostring请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint订单状态码(6=已暂停)
    status_textstring状态中文描述

    7.6 order.resumed — 订单恢复#

    {
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 4,
      "status_text": "已恢复"
    }
    字段类型说明
    out_order_idint请购单 ID(与 out_order_no 一一对应)
    out_order_nostring请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint恢复后的订单状态码(如 4=执行中)
    status_textstring状态中文描述

    7.7 purchase_order.completed — 采购订单完成#

    订单进入终态时推送,共四个来源:公共字段完全一致,来源专有字段只增不改语义,用 trigger / trigger_text 判别。四个来源都携带 items 明细(发货来源为本批明细、非发货来源为全量明细,见下)。下例为「供应商发完最后一批」来源:
    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 2,
      "status_text": "已完成",
      "trigger": "shipment_all_done",
      "trigger_text": "发货完成(发完最后一批)",
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "100.0000",
      "shipped_amount": "5000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 1,
      "ship_type_text": "全部发货完成",
      "shipment_no": "SH202508010002",
      "request_no": "api-20250801-0002",
      "batch_quantity": "40.0000",
      "batch_amount": "2000.00",
      "is_final": 1,
      "ship_images": ["https://cdn.example.com/ship/proof-1.jpg"],
      "last_ship_time": "2025-08-01 10:00:00",
      "items": [
        {
          "purchase_order_item_id": 9101,
          "product_name": "物品 fc26-items-normal",
          "product_en_name": "Pinnacle Boss Keys - ceshi",
          "server_name": "赛季",
          "external_product_icon": "https://cdn.example.com/icon/16539753.png",
          "external_product_code": "16539753",
          "external_product_name": "Pinnacle Boss Keys - ceshi",
          "external_product_description": "",
          "quantity": "100.0000",
          "shipped_quantity": "100.0000",
          "remaining_quantity": "0.0000",
          "ship_quantity": "40.0000"
        }
      ]
    }
    公共字段(四个来源都携带)
    字段类型说明
    purchase_order_idint采购订单 ID(与 purchase_order_no 一一对应)
    purchase_order_nostring采购订单号
    out_order_idint关联请购单 ID(与 out_order_no 对应;父单主键)
    out_order_nostring关联请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint采购订单状态码(2=已完成)
    status_textstring状态中文描述
    triggerstring完成来源(shipment_all_done=发完最后一批,close_audit_passed=完结审核通过,raw_order_auto_close=原始订单取消系统自动完结,change_confirm=变更后自动完成)
    trigger_textstring完成来源的中文描述,与 trigger 一一对应
    currencystring交易币种
    base_currencystring本位币代码
    total_quantitystring订单数量(下单/变更后口径)
    total_amountstring订单金额(交易币)
    shipped_quantitystring实际已发数量
    shipped_amountstring实际已发金额(交易币,按币种精度舍入)
    settle_quantitystring可结算数量(ship_type=2 时为实发数量,否则等于订单数量)
    settle_amountstring可结算金额(交易币,对账/付款依据)
    settle_base_amountstring可结算金额(本位币,按订单锁定汇率逐行换算舍入后汇总,可能与 settle_amount × 汇率 差 1 个最小单位)
    ship_typeint发货结果(1=全部发货完成,2=部分发货完结,见第九节)
    ship_type_textstring发货结果中文描述
    来源专有字段
    来源trigger专有字段
    供应商发完最后一批shipment_all_doneshipment_no 批次号(SH 前缀)、request_no 发货幂等标识、batch_quantity/batch_amount 本批数量与入账金额、is_final(恒为 1)、ship_images 本批发货凭证(URL 数组,至少一张)、last_ship_time、items 本批发货明细(仅本批实际发货的行);不携带 finish_time
    完结审核通过(部分发货完结)close_audit_passedfinish_time 完成时间、items 全量发货明细(ship_quantity 恒为 0);本来源 ship_type=2,结算按实发金额,未发部分记 close_gap_action=2(本单结束未发部分)
    原始订单取消,系统自动交易完结raw_order_auto_closefinish_time 完成时间、items 全量发货明细(ship_quantity 恒为 0);本来源 ship_type=2,未发部分记 close_gap_action=2(本单结束未发部分)
    变更后「可发数量归零」自动完成change_confirmfinish_time、items 全量发货明细(ship_quantity 恒为 0);本批改价调整流水号见同批的 purchase_order.change_confirmed.adjust_shipment_no(7.11)
    发货明细 items(四个来源都携带;purchase_order.shipped(7.23)携带结构完全一致)
    trigger=shipment_all_done(及 7.23 分批发货):仅回传本批发货涉及的明细(本批实际发货的行,ship_quantity > 0),本批未触及的历史明细不出现。
    其余三个非发货来源(close_audit_passed / raw_order_auto_close / change_confirm):回传全量明细(该采购订单的全部行),因非发货动作触发,ship_quantity 恒为 0。
    明细的累计口径始终看 shipped_quantity(含历史各批),全单汇总见头部 shipped_quantity/shipped_amount。
    字段类型说明
    purchase_order_item_idint采购订单明细 ID(purchase_order_item.id,供关联/幂等)
    product_name / product_en_namestring平台产品名称(中 / 英)
    server_namestring区服名称(全路径)
    external_product_iconstring外部产品图标 URL
    external_product_codestring外部产品编码
    external_product_namestring外部产品名称
    external_product_descriptionstring外部产品描述
    quantitystring该明细订单数量
    shipped_quantitystring该明细累计已发数量(含本批)
    remaining_quantitystring该明细剩余待发数量(quantity - shipped_quantity,发完为 0)
    ship_quantitystring本批对该明细的发货数量;发货来源(shipment_all_done / 7.23)恒 > 0,非发货来源恒为 0
    三类金额口径严禁混用:财务结算取 settle_*,发货统计取 shipped_*,下单口径取 total_*。

    7.8 purchase_order.problem_reported — 问题上报(→采购商)#

    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 3,
      "status_text": "问题单",
      "problem_desc": "商品缺货,需要更换产品",
      "problem_proof": ["https://cdn.example.com/problem/shortage-1.jpg"]
    }
    字段类型说明
    purchase_order_idint采购订单 ID(与 purchase_order_no 一一对应)
    purchase_order_nostring采购订单号
    out_order_idint关联请购单 ID(与 out_order_no 对应;父单主键)
    out_order_nostring关联请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    statusint采购订单状态码(3=问题单)
    status_textstring状态中文描述
    problem_descstring问题描述
    problem_proofarray问题凭证图片 URL 数组(供应商上报时上传,无则为空数组)

    7.9 purchase_order.problem_resolved — 问题处理 / 供应商撤销(→供应商 + 采购商)#

    本事件由两种来源触发,买卖双方各收到一条:
    1.
    采购商处理问题单(回调不携带 problem_revoked)——携带 resolution 与 problem_reply_proof;不含 problem_type / problem_revoked / revoke_reason / problem_type_reset(采购商处理回调报文不回传问题类型)。
    2.
    供应商撤销未处理的问题上报(problem_revoked=true)——额外携带 problem_type(一律重置为 0)、problem_revoked、revoke_reason(撤销说明,可空)、problem_type_reset=true;此时 resolution 恒为空字符串、problem_reply_proof 恒为空数组。
    {
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "status": 7,
      "status_text": "部分发货",
      "resolution": "同意更换为同类产品",
      "problem_reply_proof": ["https://cdn.example.com/reply/confirm-1.jpg"]
    }
    字段类型说明
    金额/数量字段string/int含义同 7.7(恢复到部分发货时,供应商据此知道还能发多少)
    purchase_order_idint采购订单 ID(与 purchase_order_no 一一对应)
    purchase_order_nostring采购订单号
    out_order_idint关联请购单 ID(与 out_order_no 对应;父单主键)
    out_order_nostring关联请购单号
    statusint恢复后的状态码(上报前的状态,可能是 0/1/7)
    status_textstring状态中文描述,与 status 同源(已接单/发货中/部分发货);订单状态机无「已恢复」这个状态,客户端一律以 status 分支
    resolutionstring处理方式说明(仅采购商处理来源有值;供应商撤销来源恒为空字符串)
    problem_reply_proofarray采购商处理问题时上传的回复凭证图片 URL 数组(无则为空数组;与供应商上报的 problem_proof 为两类凭证;撤销来源恒为空数组)
    problem_typeint问题类型(仅撤销来源携带,恒为 0=非问题单;采购商处理来源不含此字段)
    problem_revokedbool事件来源标识:true=供应商撤销触发(采购商处理来源不含此字段)
    revoke_reasonstring撤销说明(仅撤销来源携带,供应商上报时选填,可空)
    problem_type_resetbool是否已将 problem_type 重置为 0(仅撤销来源携带,恒为 true;历史问题靠业务日志追溯)
    接收方与 raw_* 差异:本事件同时通知供应商与采购商,二者上述字段完全一致;差异仅在 raw_*——平台按接收方租户自动注入,发给采购商(原始单归属方)时额外携带 raw_order_no / raw_order_id(原始单来源),发给供应商时不含(上方示例即供应商侧报文)。采购商据此恢复其订单状态,供应商据此继续发货。
    撤销来源示例(供应商主动撤销,买卖双方均收到;供应商侧报文不含 raw_*):
    {
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "0.0000",
      "shipped_amount": "0.00",
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "status": 0,
      "status_text": "已接单",
      "resolution": "",
      "problem_reply_proof": [],
      "problem_revoked": true,
      "revoke_reason": "缺货问题已内部协调解决,无需处理",
      "problem_type": 0,
      "problem_type_reset": true
    }

    7.10 purchase_order.change_requested — 变更申请(→供应商)#

    {
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "change_id": 301,
      "change_type": "quantity",
      "status": 5,
      "status_text": "变更待确认",
      "remark": "客户调整数量"
    }
    字段类型说明
    金额/数量字段string/int含义同 7.7,为变更前口径;部分发货后供应商需据此判断「已发不可回收,变更只能作用于可发量」
    purchase_order_idint采购订单 ID(与 purchase_order_no 一一对应)
    purchase_order_nostring采购订单号
    out_order_idint关联请购单 ID(与 out_order_no 对应;父单主键)
    out_order_nostring关联请购单号
    change_idint变更单 ID(确认/拒绝接口路径参数即此 ID)
    change_typestring变更类型(quantity/price/product/mixed/other)
    statusint变更后采购订单状态码(正常为 5=变更中)
    status_textstring状态中文描述
    remarkstring变更备注

    7.11 purchase_order.change_confirmed — 变更确认(→采购商)#

    {
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "change_id": 301,
      "change_type": "quantity",
      "status": 1,
      "status_text": "变更已确认",
      "adjust_shipment_no": ""
    }
    字段类型说明
    金额/数量字段string/int含义同 7.7,均为变更后重算的当前口径(改价会把已发部分按新单价重算,因此 total_amount/shipped_amount/settle_amount 可能同时变化)
    purchase_order_idint采购订单 ID(与 purchase_order_no 一一对应)
    purchase_order_nostring采购订单号
    out_order_idint关联请购单 ID(与 out_order_no 对应;父单主键)
    out_order_nostring关联请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    change_typestring变更类型
    statusint变更后采购订单状态码(0=已接单, 1=发货中, 2=已完成, 4=已暂停, 6=已取消, 7=部分发货)
    status_textstring状态中文描述(变更已确认 / 变更已确认,订单自动完成 / 变更已确认,订单已自动取消)
    adjust_shipment_nostring本次变更产生的改价追溯调整流水号(AJ 前缀,biz_type=2);非改价或未影响已发金额为空串。该流水是「已发金额被重算」的唯一权威凭证,需据此对账而非反推差额
    因变更自动完成时,本事件之后会紧接着一条 purchase_order.completed(trigger=change_confirm,见 7.7);两条事件同一来源,不得只取其一。

    7.12 purchase_order.change_rejected — 变更拒绝(→采购商)#

    {
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "60.0000",
      "settle_amount": "3000.00",
      "settle_base_amount": "3000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "change_id": 301,
      "change_type": "price",
      "status": 7,
      "status_text": "变更被拒绝",
      "reject_reason": "价格已确认,无法调整"
    }
    字段类型说明
    金额/数量字段string/int含义同 7.7;拒绝不影响金额口径,total_* 仍为变更前值
    purchase_order_idint采购订单 ID(与 purchase_order_no 一一对应)
    purchase_order_nostring采购订单号
    out_order_idint关联请购单 ID(与 out_order_no 对应;父单主键)
    out_order_nostring关联请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    change_idint被拒绝的变更单 ID
    change_typestring变更类型
    statusint拒绝后订单已从「变更中」回退到上报前状态(0/1/7),不带此字段则采购商无从判断已解冻
    status_textstring状态中文描述(固定为「变更被拒绝」,动作描述;真实状态以 status 为准)
    reject_reasonstring拒绝原因

    7.13 inquiry.published — 询价单发布(→供应商)#

    {
      "inquiry_id": 3001,
      "inquiry_no": "IN202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "status": 1,
      "status_text": "待报价",
      "deadline_at": "2025-08-05 18:00:00",
      "item_count": 3
    }
    字段类型说明
    inquiry_idint询价单 ID(与 inquiry_no 对应)
    inquiry_nostring询价单号
    out_order_idint关联请购单 ID(父单主键)
    out_order_nostring关联请购单号
    statusint询价单状态码(1=待报价)
    status_textstring状态中文描述
    deadline_atstring/null报价截止时间
    item_countint询价明细数量

    7.14 quotation.submitted — 供应商报价(→采购商)#

    {
      "quotation_id": 4001,
      "quotation_no": "QT202507310001",
      "inquiry_no": "IN202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "supplier_id": 3,
      "supplier_name": "供应商A",
      "total_quantity": "100.0000",
      "currency": "USD",
      "total_amount": "4500.00",
      "base_currency": "USD",
      "base_total_amount": "4500.00",
      "supplier_currency": "EUR",
      "supplier_total_amount": "4200.00",
      "items": [
        {
          "product_name": "金币",
          "external_product_icon": "https://cdn.example.com/icon/gold-pack.png",
          "external_product_code": "EXT-GOLD-001",
          "external_product_name": "金币特惠礼包",
          "external_product_description": "金币特惠礼包,限时优惠",
          "server_name": "亚洲1区",
          "quantity": "100.0000",
          "unit_price": "45.000000",
          "total_price": "4500.00",
          "base_unit_price": "45.000000",
          "base_total_price": "4500.00",
          "supplier_currency": "EUR",
          "supplier_unit_price": "42.000000",
          "supplier_total_price": "4200.00"
        }
      ]
    }
    字段类型说明
    quotation_idint报价单 ID(与 quotation_no 对应)
    quotation_nostring报价单号
    inquiry_nostring关联询价单号(业务侧携带,平台不额外补 inquiry_id)
    out_order_idint关联请购单 ID(父单主键)
    out_order_nostring关联请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    supplier_idint供应商租户ID
    supplier_namestring供应商名称
    total_quantitystring报价总数量(十进制字符串)
    currencystring交易币种(与订单一致)
    total_amountstring交易币报价总金额
    base_currencystring本位币代码
    base_total_amountstring本位币报价总金额
    supplier_currencystring供应商交易币种(ISO 4217,供应商原币报价快照,仅展示,不参与比价/结算;历史无快照报价为空串)
    supplier_total_amountstring供应商币报价总金额(供应商原币;无快照为 null)
    itemsarray报价明细列表
    items[].product_namestring系统产品大类名称
    items[].external_product_iconstring外部产品图标URL
    items[].external_product_codestring外部产品编码
    items[].external_product_namestring外部产品名称(实际成交商品名称,长文本无业务上限)
    items[].external_product_descriptionstring外部产品描述(长文本无业务上限)
    items[].server_namestring区服名称
    items[].quantitystring数量(十进制字符串)
    items[].unit_pricestring交易币单价
    items[].total_pricestring交易币行总价
    items[].base_unit_pricestring本位币单价(按订单锁定汇率换算,十进制字符串)
    items[].base_total_pricestring本位币行总价(后端自算)
    items[].supplier_currencystring供应商交易币种(供应商原币快照,仅展示;无快照为 null)
    items[].supplier_unit_pricestring供应商币单价(供应商原币报价,6 位小数;无快照为 null)
    items[].supplier_total_pricestring供应商币行总价(按供应商币精度量化;无快照为 null)

    7.15 comparison.created — 比价单创建(→采购商)#

    {
      "comparison_id": 4501,
      "comparison_no": "CP202507310001",
      "inquiry_no": "IN202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "quotation_count": 3
    }
    字段类型说明
    comparison_idint比价单 ID(与 comparison_no 对应)
    comparison_nostring比价单号
    inquiry_nostring关联询价单号(业务侧携带,平台不额外补 inquiry_id)
    out_order_idint关联请购单 ID(父单主键)
    out_order_nostring关联请购单号
    raw_order_nostring外部原始订单号(仅原始订单派生的单据携带;缺省即本单与原始订单无关)
    raw_order_idint原始订单表 ID(与 raw_order_no 一一对应)
    quotation_countint汇总的报价单数量

    7.16 reconciliation.created — 对账单生成(→供应商)#

    {
      "reconciliation_id": 6001,
      "reconciliation_no": "REC202508010001",
      "status": 0,
      "status_text": "待采购商确认",
      "currency": "USD",
      "total_amount": "15000.00",
      "base_currency": "USD",
      "base_total_amount": "15000.00",
      "period_date": "2025-07-31",
      "order_count": 5
    }
    字段类型说明
    reconciliation_idint对账单 ID(与 reconciliation_no 对应)
    reconciliation_nostring对账单号
    statusint对账单状态码(0=待采购商确认)
    status_textstring状态中文描述
    currencystring交易币种(从订单快照继承,同一对账单内币种一致)
    total_amountstring交易币对账总金额 = Σ 各订单可结算金额(全部发货=订单金额;部分发货完结=实际已发金额),不等于订单原总额
    base_currencystring本位币代码
    base_total_amountstring本位币对账总金额(与 total_amount 同口径,逐行换算舍入后汇总)
    period_datestring账期日期
    order_countint关联订单笔数

    7.17 reconciliation.buyer_confirmed — 采购商确认对账(→供应商)#

    {
      "reconciliation_id": 6001,
      "reconciliation_no": "REC202508010001",
      "status": 1,
      "status_text": "待供应商确认",
      "currency": "USD",
      "total_amount": "15000.00",
      "base_currency": "USD",
      "base_total_amount": "15000.00",
      "period_date": "2025-07-31",
      "order_count": 5
    }
    字段类型说明
    reconciliation_idint对账单 ID(与 reconciliation_no 对应)
    reconciliation_nostring对账单号
    statusint对账单状态码(1=待供应商确认)
    status_textstring状态中文描述
    currencystring交易币种(从订单快照继承)
    total_amountstring交易币对账总金额 = Σ 各订单可结算金额(全部发货=订单金额;部分发货完结=实际已发金额),不等于订单原总额
    base_currencystring本位币代码
    base_total_amountstring本位币对账总金额(与 total_amount 同口径,逐行换算舍入后汇总)
    period_datestring账期日期
    order_countint关联订单笔数

    7.18 reconciliation.supplier_confirmed — 供应商确认对账(→采购商)#

    {
      "reconciliation_id": 6001,
      "reconciliation_no": "REC202508010001",
      "status": 2,
      "status_text": "已完成",
      "currency": "USD",
      "total_amount": "15000.00",
      "base_currency": "USD",
      "base_total_amount": "15000.00",
      "period_date": "2025-07-31",
      "order_count": 5,
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801
    }
    字段类型说明
    reconciliation_idint对账单 ID(与 reconciliation_no 对应)
    reconciliation_nostring对账单号
    statusint对账单状态码(2=已完成)
    status_textstring状态中文描述
    currencystring交易币种(从订单快照继承)
    total_amountstring交易币对账总金额 = Σ 各订单可结算金额(全部发货=订单金额;部分发货完结=实际已发金额),不等于订单原总额
    base_currencystring本位币代码
    base_total_amountstring本位币对账总金额(与 total_amount 同口径,逐行换算舍入后汇总)
    period_datestring账期日期
    order_countint关联订单笔数

    7.19 reconciliation.disputed — 对账争议(→对方)#

    {
      "reconciliation_id": 6001,
      "reconciliation_no": "REC202508010001",
      "status": 3,
      "status_text": "有争议",
      "currency": "USD",
      "total_amount": "15000.00",
      "base_currency": "USD",
      "base_total_amount": "15000.00",
      "period_date": "2025-07-31",
      "order_count": 5,
      "dispute_reason": "订单PO202507310003金额有误",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801
    }
    字段类型说明
    reconciliation_idint对账单 ID(与 reconciliation_no 对应)
    reconciliation_nostring对账单号
    statusint对账单状态码(3=有争议)
    status_textstring状态中文描述
    currencystring交易币种(从订单快照继承)
    total_amountstring交易币对账总金额 = Σ 各订单可结算金额(全部发货=订单金额;部分发货完结=实际已发金额),不等于订单原总额
    base_currencystring本位币代码
    base_total_amountstring本位币对账总金额(与 total_amount 同口径,逐行换算舍入后汇总)
    period_datestring账期日期
    order_countint关联订单笔数
    dispute_reasonstring争议原因
    raw_order_no / raw_order_idstring / int仅当接收方是该原始单归属采购商时携带(发往供应商的一侧不含);跨多张原始单时改为 raw_order_nos / raw_order_ids 同序数组

    7.20 reconciliation.resolved — 争议解决(→争议发起方)#

    {
      "reconciliation_id": 6001,
      "reconciliation_no": "REC202508010001",
      "status": 1,
      "status_text": "待供应商确认",
      "currency": "USD",
      "total_amount": "15000.00",
      "base_currency": "USD",
      "base_total_amount": "15000.00",
      "period_date": "2025-07-31",
      "order_count": 5
    }
    字段类型说明
    reconciliation_idint对账单 ID(与 reconciliation_no 对应)
    reconciliation_nostring对账单号
    statusint解决后回退的状态码
    status_textstring状态中文描述
    currencystring交易币种(从订单快照继承)
    total_amountstring交易币对账总金额 = Σ 各订单可结算金额(全部发货=订单金额;部分发货完结=实际已发金额),不等于订单原总额
    base_currencystring本位币代码
    base_total_amountstring本位币对账总金额(与 total_amount 同口径,逐行换算舍入后汇总)
    period_datestring账期日期
    order_countint关联订单笔数
    raw_order_no / raw_order_idstring / int仅当接收方(争议发起方)是该原始单归属采购商时携带;跨多张原始单时改为 raw_order_nos / raw_order_ids 同序数组

    7.21 reconciliation.voided — 对账单作废(→供应商)#

    {
      "reconciliation_id": 6001,
      "reconciliation_no": "REC202508010001",
      "status": 4,
      "status_text": "已作废",
      "currency": "USD",
      "total_amount": "15000.00",
      "base_currency": "USD",
      "base_total_amount": "15000.00",
      "period_date": "2025-07-31",
      "order_count": 5
    }
    字段类型说明
    reconciliation_idint对账单 ID(与 reconciliation_no 对应)
    reconciliation_nostring对账单号
    statusint对账单状态码(4=已作废)
    status_textstring状态中文描述
    currencystring交易币种(从订单快照继承)
    total_amountstring交易币对账总金额 = Σ 各订单可结算金额(全部发货=订单金额;部分发货完结=实际已发金额),不等于订单原总额
    base_currencystring本位币代码
    base_total_amountstring本位币对账总金额(与 total_amount 同口径,逐行换算舍入后汇总)
    period_datestring账期日期
    order_countint关联订单笔数

    7.22 payment.paid — 已付款(→供应商)#

    {
      "payment_id": 9001,
      "payment_no": "PAY202508010001",
      "reconciliation_no": "REC202508010001",
      "status": 3,
      "status_text": "已付款",
      "currency": "USD",
      "amount": "15000.00",
      "base_amount": "15000.00",
      "pay_method": "alipay",
      "pay_time": "2025-08-01 14:30:00"
    }
    字段类型说明
    payment_idint付款单 ID(与 payment_no 对应)
    payment_nostring付款单号
    reconciliation_nostring关联对账单号
    statusint付款单状态码(3=已付款)
    status_textstring状态中文描述
    currencystring交易币种(继承对账单)
    amountstring交易币付款金额(继承对账单总额,即 Σ 可结算金额,不重新换汇)
    base_amountstring本位币付款金额
    pay_methodstring付款方式(alipay/bank/wechat/other)
    pay_timestring付款时间

    7.23 purchase_order.shipped — 采购订单部分发货(→采购商)#

    供应商提交本批发货但尚未发完时触发(订单进入 status=7 部分发货);发完时改推 purchase_order.completed(见 7.7)。
    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 7,
      "status_text": "部分发货",
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "trigger": "shipment_batch",
      "trigger_text": "分批发货(本批未发完)",
      "shipment_no": "SH202508010001",
      "request_no": "api-20250801-0001",
      "batch_quantity": "20.0000",
      "batch_amount": "1000.00",
      "is_final": 0,
      "ship_images": ["https://cdn.example.com/ship/proof-1.jpg"],
      "last_ship_time": "2025-08-01 10:00:00",
      "items": [
        {
          "purchase_order_item_id": 9101,
          "product_name": "物品 fc26-items-normal",
          "product_en_name": "Pinnacle Boss Keys - ceshi",
          "server_name": "赛季",
          "external_product_icon": "https://cdn.example.com/icon/16539753.png",
          "external_product_code": "16539753",
          "external_product_name": "Pinnacle Boss Keys - ceshi",
          "external_product_description": "",
          "quantity": "100.0000",
          "shipped_quantity": "60.0000",
          "remaining_quantity": "40.0000",
          "ship_quantity": "20.0000"
        }
      ]
    }
    字段类型说明
    purchase_order_id / out_order_idint采购订单 ID / 父请购单 ID(与同名单号成对回传,见 7.0)
    金额/数量字段string/int含义同 7.7;订单未完结(ship_type=0)时 settle_* 仍等于订单口径 total_*,不代表已发生结算
    triggerstring固定为 shipment_batch(本批未发完);发完时改推 purchase_order.completed(trigger=shipment_all_done,携带同一批批次字段,见 7.7)
    trigger_textstring来源中文描述,固定为 分批发货(本批未发完)
    shipment_nostring本批发货批次号(SH 前缀)
    request_nostring本次发货的幂等标识(回显调用方传入值;未传时服务端生成)
    batch_quantitystring本批发货数量
    batch_amountstring本批入账金额(累计已发金额的前后差额,可能与「单价×本批数量」差 1 个最小单位)
    is_finalint是否终批(1=已发完,仅 purchase_order.completed 场景为 1)
    ship_imagesarray本批发货凭证图片 URL 数组(发货入口校验至少一张)
    last_ship_timestring最近一次发货时间
    itemsarray本批发货明细,仅含本批实际发货的行(ship_quantity > 0);字段结构同 7.7「发货明细 items」

    7.24 purchase_order.close_applied — 采购订单完结申请(→采购商)#

    部分发货的订单由供应商发起完结申请(原因必填),进入待审核;审核入口见 /open-api/v1/buyer/purchase-order/{id}/close-audit。
    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "status": 7,
      "status_text": "部分发货",
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "close_apply_seq": 1,
      "close_reason": "渠道库存不足,剩余无法交付",
      "close_apply_time": "2025-08-01 11:00:00"
    }
    字段类型说明
    purchase_order_id / out_order_idint采购订单 ID / 父请购单 ID(与同名单号成对回传,见 7.0)
    金额/数量字段string/int含义同 7.7(申请时订单仍为 ship_type=0,结算口径仍按订单金额)
    close_apply_seqint完结申请序号(审核乐观锁版本,每次申请 +1,审核时需原样回传)
    close_reasonstring供应商填写的申请原因
    close_apply_timestring申请时间

    7.25 purchase_order.close_audited — 完结审核结果(→供应商)#

    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "status": 2,
      "status_text": "已完成",
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "60.0000",
      "shipped_amount": "3000.00",
      "settle_quantity": "60.0000",
      "settle_amount": "3000.00",
      "settle_base_amount": "3000.00",
      "ship_type": 2,
      "ship_type_text": "部分发货完结",
      "pass": true,
      "close_apply_seq": 1,
      "gap_action": 2,
      "gap_action_text": "本单结束未发部分",
      "close_audit_remark": "已核对发货凭证,剩余不再交付",
      "close_audit_time": "2025-08-01 15:00:00"
    }
    字段类型说明
    purchase_order_id / out_order_idint采购订单 ID / 父请购单 ID(与同名单号成对回传,见 7.0。本事件发给供应商,不含 raw_*)
    金额/数量字段string/int含义同 7.7;审核通过后 ship_type=2,对账与付款按 settle_amount(=实发金额)进行
    passbool审核结果(true=通过,false=驳回)
    close_apply_seqint本次审核对应的申请序号
    gap_actionint剩余缺口处理(通过时固定 2=接受缺口,即本单结束未发部分;驳回时为 0。1=释放剩余已下线,仅历史数据可能出现)
    gap_action_textstring缺口处理中文描述(新数据为「本单结束未发部分」)
    close_audit_remarkstring审核备注(驳回时必填)
    close_audit_timestring审核时间
    驳回时订单保持 status=7 部分发货(close_apply_status=3),供应商可继续发货或重新申请完结。

    7.26 purchase_order.shipping_started — 订单开始发货(→采购商)#

    供应商点击「开始发货」时触发(采购订单由 status=0 已接单 进入 status=1 发货中),表示进入发货阶段但首批尚未发出。后续每批实际发货推 purchase_order.shipped(见 7.23),发完推 purchase_order.completed(见 7.7)。
    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "channel_code": "dd373",
      "status": 1,
      "status_text": "发货中",
      "currency": "USD",
      "base_currency": "USD",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "0.0000",
      "shipped_amount": "0.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 0,
      "ship_type_text": "未完结",
      "ship_start_time": "2025-08-01 09:00:00",
      "shipper_name": "supplierzhang"
    }
    字段类型说明
    purchase_order_id / out_order_idint采购订单 ID / 父请购单 ID(与同名单号成对回传,见 7.0)
    raw_order_no / raw_order_id / channel_codestring/int仅原始单来源时回传(见 7.0);channel_code 为渠道销售编码
    金额/数量字段string/int含义同 7.7;开始发货时尚未发出任何货物,shipped_quantity/shipped_amount 为 0;订单未完结(ship_type=0)故 settle_* 仍等于订单口径 total_*,不代表已发生结算
    status / status_textint/string固定为 1 / 发货中
    ship_start_timestring开始发货时间
    shipper_namestring发货人(供应商侧操作账号名)

    7.27 purchase_order.price_change — 采购订单改价(供应商申请改价,→按 stage 区分接收方)#

    面向已完成且从未生成对账单的采购订单,由供应商按自己的供应商币单价发起改价申请、采购商审核。与既有「采购商发起→供应商确认」的变更事件(7.10~7.12)方向相反,且改价后采购订单保持已完成(status=2)不变、不进入变更中,不会再次触发 purchase_order.completed。同一 change_id 按 stage 分三次投递:
    stage=applied:供应商提交申请 → 通知采购商(待审核)。
    stage=approved:采购商通过 → 通知供应商(金额已生效)。
    stage=rejected:采购商拒绝 → 通知供应商(附拒绝意见 note)。
    供应商输入、items 明细与展示均为供应商币单价;交易币单价由订单锁定的 supplier_to_order_rate 换算得出(after_unit_price = round(after_supplier_unit_price × rate)),平台绝不从采购商单价反算,供应商币原值全程保留。
    示例一(stage=approved,发供应商,含前后金额对比;发供应商事件不含 raw_*;applied/rejected 无下方 before_*/after_*/adjust_shipment_no 对比块)
    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "change_id": 305,
      "stage": "approved",
      "change_type": "price",
      "initiator": 2,
      "status": 2,
      "currency": "USD",
      "base_currency": "USD",
      "supplier_currency": "JPY",
      "supplier_to_order_rate": "0.0068",
      "total_quantity": "100.0000",
      "total_amount": "5000.00",
      "shipped_quantity": "100.0000",
      "shipped_amount": "5000.00",
      "settle_quantity": "100.0000",
      "settle_amount": "5000.00",
      "settle_base_amount": "5000.00",
      "ship_type": 1,
      "ship_type_text": "全部发货完结",
      "before_total_amount": "4800.00",
      "after_total_amount": "5000.00",
      "before_shipped_amount": "4800.00",
      "after_shipped_amount": "5000.00",
      "before_settle_amount": "4800.00",
      "after_settle_amount": "5000.00",
      "before_supplier_total_amount": "705882.00",
      "after_supplier_total_amount": "735294.00",
      "adjust_shipment_no": "AJ202508010001",
      "remark": "实际结算单价录入错误,申请更正",
      "note": "",
      "items": [
        {
          "purchase_order_item_id": 9001,
          "product_name": "648 元礼包",
          "product_en_name": "648 Gift Pack",
          "external_product_name": "648礼包",
          "external_product_code": "GIFT648",
          "quantity": "100.0000",
          "before_unit_price": "48.000000",
          "after_unit_price": "50.000000",
          "before_supplier_unit_price": "7058.823529",
          "after_supplier_unit_price": "7352.941176"
        }
      ]
    }
    示例二(stage=applied,发采购商、待审核;原始单来源时含 raw_*,金额仍为变更前值且无 before_*/after_*/adjust_shipment_no 对比块)
    {
      "purchase_order_id": 7001,
      "purchase_order_no": "PO202507310001",
      "out_order_id": 5001,
      "out_order_no": "OO202507310001",
      "raw_order_no": "EXT20250729001",
      "raw_order_id": 8801,
      "channel_code": "dd373",
      "change_id": 305,
      "stage": "applied",
      "change_type": "price",
      "initiator": 2,
      "status": 2,
      "currency": "USD",
      "base_currency": "USD",
      "supplier_currency": "JPY",
      "supplier_to_order_rate": "0.0068",
      "total_quantity": "100.0000",
      "total_amount": "4800.00",
      "shipped_quantity": "100.0000",
      "shipped_amount": "4800.00",
      "settle_quantity": "100.0000",
      "settle_amount": "4800.00",
      "settle_base_amount": "4800.00",
      "ship_type": 1,
      "ship_type_text": "全部发货完结",
      "remark": "实际结算单价录入错误,申请更正",
      "note": "",
      "items": [
        {
          "purchase_order_item_id": 9001,
          "product_name": "648 元礼包",
          "product_en_name": "648 Gift Pack",
          "external_product_name": "648礼包",
          "external_product_code": "GIFT648",
          "quantity": "100.0000",
          "before_unit_price": "48.000000",
          "after_unit_price": "50.000000",
          "before_supplier_unit_price": "7058.823529",
          "after_supplier_unit_price": "7352.941176"
        }
      ]
    }
    字段类型说明
    purchase_order_id / out_order_idint采购订单 ID / 父请购单 ID(与同名单号成对回传,见 7.0)
    raw_order_no / raw_order_id / channel_codestring/int仅 stage=applied(发采购商)且原始单来源时回传;approved/rejected 发供应商,不含 raw_*(见 7.0)
    change_idint改价申请单(变更单)ID
    stagestringapplied=待审核(→采购商)/ approved=已通过(→供应商)/ rejected=已拒绝(→供应商)
    change_typestring固定 price(本入口仅允许改单价)
    initiatorint发起方:2=供应商(本事件恒为 2)
    status / status_textint/string采购订单状态;改价全程保持已完成(status=2),不翻转
    currency / base_currencystring交易币 / 本位币代码
    supplier_currencystring供应商币代码(订单快照)
    supplier_to_order_ratestring供应商币→交易币锁定汇率;交易币单价 = 供应商币单价 × 该汇率
    金额/数量字段string/int含义同 7.7。applied 时为变更前当前口径(申请尚未生效);approved 后重算,为变更后口径
    before**_amount / after**_amountstring仅 approved 携带:前后订单/已发/结算/供应商币总额对比(before_total_amount…after_supplier_total_amount)
    adjust_shipment_nostring仅 approved 携带:已发部分被重定价产生的改价追溯调整流水号(biz_type=2);无已发重算则为空串。是「已发金额被重算」的权威凭证
    remarkstring供应商申请改价时的备注
    notestring审核意见:rejected 为拒绝原因;approved 可为审核备注;applied 为空串
    items[]array逐行明细(前后对比)
    items[].purchase_order_item_idint采购订单明细行 ID
    items[].quantitystring行数量(改价不变)
    items[].before/after_supplier_unit_pricestring供应商币单价(申请输入原值,前后对比)
    items[].before/after_unit_pricestring交易币单价(前后对比;after 为换算后结果)
    已对账拦截:对账单可先生成,但 approved 受拦——审核时若该订单已存在对账(含作废残留历史行)则禁止通过、仅可拒绝。settle_* 口径与其他采购订单事件一致(部分发货完结订单结算按已发金额)。

    八、接收方应答规范#

    成功应答#

    收到通知并处理完成后,返回 HTTP 200,body 为纯文本:
    success
    ⚠️ 注意:不要返回 JSON {"code":0} 或带换行的 success\n,必须严格等于字符串 success。

    失败/忽略#

    若返回非 success 内容或 HTTP 非 2xx,平台将视为投递失败并触发重试。

    幂等性要求#

    由于存在重试机制,同一事件可能收到多次通知。接收方应基于 event + data 中的业务单号做幂等处理,避免重复执行业务逻辑。

    九、状态码参考#

    请购单状态(out_order.status)#

    值含义
    0待派单
    1报价中
    2待比价
    3已派单
    4执行中
    5已完成
    6已暂停
    7异常
    8已取消

    原始订单状态(raw_order.status)#

    值含义
    0待拆分(尚未建出子请购单)
    1进行中(已拆出子请购单,履约中)
    2已完成(全部子请购单已完成)
    3已取消(全部子请购单已取消)
    4部分取消(子请购单完成/取消混合)
    5拆分/重建未完成(split_error 记原因;续跑入口看 rebuild_stage:0 以同一外部订单号重试创建接口,1/2 重试修改接口)
    取消中途失败不会停在 5:原始单保持聚合出的非终态(1 进行中 / 4 部分取消)并以 split_error 记原因,接口同时返回失败(非 200),重试路径是重发取消接口。
    明细变更重建期间(rebuild_stage > 0)状态不自动推进,以该次重建结束后的结果为准。

    明细重建阶段(raw_order.rebuild_stage)#

    值含义中断后如何继续
    0无进行中的重建—
    1重建中:原请购单作废阶段用包含相同 items 的同一请求体重发修改接口,从断点继续
    2重建中:新请购单建单阶段同上,重发修改接口只补建尚未建出的分组
    阶段 > 0 时创建接口返回 422(不报幂等成功),续跑只能重发修改接口;取消接口会把未完成的重建一并放弃(阶段复位),此后该次重建不可续跑。

    原始订单与子请购单的对应关系(单号规则)#

    规则说明
    外部单号唯一范围raw_order_no 在采购商租户内唯一(含已删除记录);创建接口据此幂等,不报「单号重复」
    幂等不等于改写幂等命中时会比对本次请求内容(交易信息/角色名/附件/截止时间/明细),不一致直接 422 并列出差异项;确实要改内容请走修改接口或换新外部单号
    并发同号同一外部单号的并发创建不会报错,后到的请求按幂等命中处理(含内容比对与未拆完续跑)
    长度与字符集raw_order_no 最长 58 个字符,仅允许字母/数字/下划线/短横线(为子单序号预留 3 位)
    子请购单号out_order_no = raw_order_no + "-" + 两位序号,如 EXT20250101001-01;序号只增不复用
    分组维度「游戏 + 平台 + 区服」三元组,一组一张请购单,固定整单派单模式
    金额口径原始单总额 = Σ 子请购单总额(拆分完成后回填);子单继承原始单锁定的币种与汇率
    处理顺序同一原始单的拆分/重建/取消串行执行:正在处理时返回 422「正在被另一个拆分/重建请求处理」,原样重发即可

    采购订单状态(purchase_order.status)#

    值含义
    0已接单
    1发货中
    2已完成
    3问题单
    4已暂停
    5变更中
    6已取消
    7部分发货(非终态,可继续发货或申请完结)

    发货结果(purchase_order.ship_type)#

    值含义结算口径
    0未完结(进行中,含部分发货)按订单金额
    1全部发货完成按订单金额(total_amount)
    2部分发货完结(审核通过)按实际已发金额(shipped_amount)

    完结审核状态(purchase_order.close_apply_status)#

    值含义
    0无
    1待审核(此时发货/变更/暂停/上报问题均被冻结)
    2已通过
    3已驳回(可继续发货或重新申请)

    剩余缺口处理(purchase_order.close_gap_action)#

    值含义
    0未设置
    1释放剩余(入口已下线:审核通过不再回退请购单已派数量与比价中标数量,仅历史数据可能出现)
    2接受缺口:本采购单结束未发部分。完结审核通过时固定写入,未发数量保留为历史事实;是否继续采购由「发起补货」或请购单「手动完成」决定

    分批发货与订单完结流程#

    1.
    分批发货:POST /open-api/v1/supplier/order/{id}/complete-shipping 可多次调用,每次只传本批明细
    items:[{item_id, quantity}](item_id 为整数,quantity 为十进制字符串且不接受 JSON 浮点数,小数位最多 4 位、整数位最多 14 位且不得超过剩余待发量;
    明细为标量或缺必填项、类型/位宽非法均返回 422);未发完订单保持 status=7,
    发完自动转 status=2(ship_type=1)。items 字段完全不传为旧契约(按剩余量全量发货,向后兼容);
    显式传 [] 或 null 返回 422。ship_images 必须为字符串数组(至少 1 张、最多 20 张、单项 URL 最长 500 字符),ship_remark 最长 500 字。
    2.
    幂等:建议每次都传 request_no(1-64 位字母/数字与 - _ : .)。同一 request_no 重试返回首次处理结果快照(HTTP 200、
    code=200、data.duplicated=true),不重复入账也不重发回调;同 request_no 但内容不同返回 422。
    重试返回体里的 status / ship_type / shipped_quantity / shipped_amount / total_quantity / total_amount / settle_* / last_ship_time
    均为当时该批处理完成时的值,不会因后续发货或审核而改变(与 batch_quantity、is_final 保持同一时点);
    其中 settle_base_amount 同样直接回放首次落库的快照值,不会重新换汇,与首次响应逐字相同。
    不传 request_no 不具备幂等保护,调用方需自行避免超时重发。
    3.
    申请完结:部分发货后若无法继续交付,供应商调 POST /open-api/v1/supplier/order/{id}/close-apply(reason 必填且最长 500 字),
    订单保持 status=7,close_apply_status=1,close_apply_seq 自增。
    4.
    冻结规则:close_apply_status=1 期间,发货、上报问题、撤销问题上报、发起变更、暂停/恢复(含按请购单级联的暂停/恢复)一律被拒绝,
    需先由采购商审核。审核通过/驳回后自动解冻。
    5.
    审核:采购商调 POST /open-api/v1/buyer/purchase-order/{id}/close-audit,只传 pass(缺口处理不再是审核项:通过即本单结束未发部分;
    gap_action 为兼容入参:不传或传 2 均按 close_gap_action=2 落库,传 1(释放剩余)一律返回 422;该入参严格限整数 0~2,传 1.5、「2abc」等同样返回 422,不会被截断成另一个合法动作),驳回时 remark 必填(最长 500 字)。为避免并发窗口误审,close_apply_seq 与
    snapshot{shipped_quantity, shipped_amount, total_quantity, total_amount} 五项均为必传
    (取详情接口当时的值原样回传),
    缺失或格式错误直接 422,不一致同样 422(订单数据已变化,需重新拉详情后再审)。
    通过→ status=2 + ship_type=2(结算按实发金额)+ close_gap_action=2;驳回→ 保持 status=7 + close_apply_status=3。通过后未发部分保留为缺口,处理入口见第 6 条。
    6.
    完结后的缺口处理不属于审核动作:审核通过只锁定本轮实发,不回退请购单已派数量与比价中标数量;要继续采购由采购商对该采购订单发起补货询价(数量取本轮未发付费缺口、不可编辑,赠品未发部分不进入补货),
    决定不再采购则由请购单「手动完成」接受缺口收尾。补货询价本身不触发 order.completed:该事件只在请购单进入终态时发一次——同一采购链累计实发满足原请购需求后自动完成,或采购商接受缺口手动完成(completion_type=manual,回调带 accepted_gap 缺口明细);请购单进入终态后不得再从旧采购单发起补货。手动完成只收尾本轮已派未发(含未发赠品)与已放弃未派数量;若还有未派且未放弃的需求,须先派单/追加询价或放弃后再完成。
    7.
    「释放剩余」已全局下线:旧文档中的 gap_action=1(释放回请购单)不再可用,整单派单模式与多供应商拆分派单一致,审核通过一律记 close_gap_action=2;
    历史数据中 close_gap_action=1 的单据(当时已回退上游数量)保持原状,且不开放补货入口,只能走请购单「手动完成」。
    8.
    撤销问题上报:处于问题单状态(status=3)时,供应商可调 POST /open-api/v1/supplier/order/{id}/revoke-problem(reason 选填、最长 500 字)主动撤销上报:
    订单恢复到上报前状态(prev_status,无则回退已接单),problem_type 重置为 0(该单不再计为问题单),若关联请购单无其他问题单则从异常中恢复;完结审核中(close_apply_status=1)禁止撤销。
    撤销复用 purchase_order.problem_resolved 事件、买卖双方各回传一条(data.problem_revoked=true),详见 7.9。

    对账单状态(reconciliation.status)#

    值含义
    0待采购商确认
    1待供应商确认
    2已完成
    3有争议
    4已作废

    付款单状态(payment.status)#

    值含义
    0待审批
    1已审批
    2已驳回
    3已付款

    问题单类型(purchase_order.problem_type)#

    用于「暂停订单」「暂停采购订单」与「上报问题」接口的问题归类,采购订单详情/列表的 problem_type 字段也使用同一枚举:
    值枚举常量含义
    0PROBLEM_TYPE_NONE非问题单(数据默认值,接口不接受传 0)
    1PROBLEM_TYPE_SUPPLIER供应商问题
    2PROBLEM_TYPE_PURCHASER采购商问题
    3PROBLEM_TYPE_CUSTOMER客户问题
    暂停订单 / 暂停采购订单:problem_type 和 problem_parse 均为必填(1/2/3),problem_proof(问题凭证 URL 数组)选填,与管理后台保持一致;请购单暂停时采集的问题类型、暂停原因和凭证会透传写入被级联暂停的采购订单。
    处理问题单(采购商侧):resolution 必填,problem_proof(处理结果凭证 URL 数组)选填,与管理后台一致。
    上报问题:problem_desc 必填,problem_type 可选(不传时默认 0=未分类),订单均会进入「问题单」状态。
    撤销问题上报(供应商侧):仅 status=3 可撤销,reason 选填(最长 500 字);撤销一律将 problem_type 重置为 0(撤销即归零,不查历史处理日志),problem_desc/problem_proof 保留不清空仅作留痕,历史问题靠业务日志追溯。

    十、回调地址配置#

    1.
    登录管理后台 → API开放平台
    2.
    点击「设置回调」按钮
    3.
    输入回调地址(必须为 HTTPS 或 HTTP 可访问地址)
    4.
    点击「验证」— 平台向该地址发起 GET 请求,返回 success 即通过
    5.
    验证通过后点击「保存」
    修改回调地址后需重新验证,未验证的地址不会收到任何通知。

    回调目标平台的确定(一个租户配置多个 API 平台时)#

    同一租户名下存在多个 API 平台时,每条回调按以下三级规则确定推送目标(签名使用的 app_secret 与推送地址永远来自同一个被选中的平台):
    1.
    发起请求的平台:本次业务动作由某个平台的 OpenAPI 调用触发(如通过 API 取消/暂停/驳回),且该平台属于回调接收租户并已验证回调地址 → 推给发起调用的平台;
    2.
    下单来源平台:建单时平台快照已随订单落库(out_order.api_platform_id,拆分子单继承原始单),后台人工操作/系统事件触发的回调仍推回当初下单的平台;
    3.
    租户默认兜底:无来源平台(手动单、存量 API 单)或发给供应商的事件 → 取接收租户名下已验证、启用平台中 id 最小(最早创建)的一个。
    边界说明:
    第 1/2 级命中的平台若已停用/回调地址未验证/已删除,不硬发,逐级回退到第 3 级;完全无合规平台时静默跳过(不影响主业务,后台 admin 日志可查)。
    对账单/付款单等聚合多张请购单的事件,仅当链路内来源平台完全一致时才按第 2 级归因,否则落入第 3 级。
    存量(本次改造前创建的)API 订单没有来源平台快照,按第 3 级处理;改造后新建的 API 订单自动按上述规则路由。

    十一、常见问题#

    Q: 为什么没有收到回调通知?#

    1.
    确认回调地址已配置且验证通过(后台显示「已验证」)
    2.
    确认 API 平台状态为启用
    3.
    确认接收方服务器可被外网访问
    4.
    查看后台「队列任务」页面是否有失败记录

    Q: 签名验证总是失败?#

    1.
    确认 data 字段参与签名时使用的是 JSON 字符串(非对象)
    2.
    JSON 序列化时使用 JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    3.
    确认 AppSecret 正确
    4.
    注意 http_build_query 会进行 URL 编码,签名前需 urldecode

    Q: 如何区分重复通知?#

    使用 event + data.out_order_no(或 data.purchase_order_no)作为唯一键,在本地记录已处理的通知,重复收到时直接返回 success 不再处理。

    十二、OpenAPI 接口错误码参考#

    本章适用于所有 /open-api/v1/* 主动调用接口(接口定义见 doc/open-api.json)。

    12.0 供应商侧响应字段收敛(破坏性变更)#

    仅作用于 /open-api/v1/supplier/* 的响应体(采购商侧 Buyer/* 响应不变)。当前尚无供应商接入 OpenAPI,本节为契约描述同步,不涉及对既有调用方的兼容过渡。本节不影响第七节的回调(webhook)报文——回调字段表按原样仍有效。
    供应商侧各读接口响应体按「供应商页面/操作实际所需」收敛,剔除以下三类字段:
    1.
    采购商敏感标识:out_buyer_id、out_buyer_email、channel_code、order_source 一律不再下发;请购单销售价类字段(out_order 嵌套、sales_unit_price、sales_amount、source_snapshot 等)不下发。
    2.
    本位币与汇率快照:base_currency、base_exchange_rate、base_total_amount、base_amount、base_unit_price、base_total_price、base_shipped_amount、settle_base_amount、rate_effective_at、rate_source、auto_source_currency、source_to_order_rate 不下发(结算/对账口径仍走交易币 settle_amount)。
    3.
    内部关联 ID:out_order_id、buyer_id、comparison_id、quotation_id、inquiry_id(询价/报价头上的级联外键)、raw_order_id、raw_order_no、source_out_order_item_id、purchase_order_item_id、shipper_id、prev_status、各 *_user_id/created_by/updated_by/deleted_by/deleted_at/updated_at 等不下发。
    保留原则:供应商页面打开详情/提交报价/跳转所依赖的 ID 显式保留——采购订单/变更行保留 id、product_id、purchase_order_id(打开订单详情),报价结果/收款保留 reconciliation_id(关联对账),询价明细保留 id(提交报价)。
    角色名与交易信息:character_name、trade_info 属「中标生成采购订单后可见」要素,在采购订单列表/详情、订单变更、对账单环节保留下发;在报价池、报价结果环节继续不下发(与现网一致)。

    12.1 统一响应结构#

    所有接口(含失败)均返回以下 JSON 结构,HTTP 状态码恒为 200,请以响应体 code 字段判断成败:
    {
      "code": 500,
      "message": "当前订单状态不可创建询价",
      "data": [],
      "trace_id": "8f3b2c1d-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
    字段类型说明
    codeint业务状态码(见 12.2),200=成功
    messagestring提示信息,失败时为具体错误原因(中文)
    dataobject/array业务数据,失败时为空数组
    trace_idstring请求追踪ID,排查问题时提供给平台方定位日志
    响应 Header 中同时携带 Request-Id,与 trace_id 一致。

    12.2 业务状态码总览#

    code含义典型场景处理建议
    200成功请求处理成功解析 data
    401未认证鉴权参数缺失/无效/过期/签名错误检查签名参数与算法(见第五节)
    403无权限租户停用、角色不匹配、功能模块未授权联系平台方开通
    404资源不存在ID 错误、单据不属于当前租户核对资源ID
    422参数校验失败必填缺失、数值越界、格式错误根据 message 修正参数
    500业务规则失败状态不允许操作、重复操作、截止等根据 message 调整业务流程

    12.3 鉴权类错误(401 / 403)#

    codemessage原因
    401缺少鉴权参数Header 未带齐 X-App-Key / X-Timestamp / X-Nonce-Str / X-Sign
    401无效的AppKeyAppKey 不存在或平台已停用
    401请求已过期时间戳与服务器偏差超过 ±300 秒,请校准服务器时间
    401签名验证失败签名算法/参数收集有误,对照第五节排查
    403租户已停用平台关联的租户被停用
    403无权访问采购商接口供应商角色(tenant.type=1)调用了 /buyer/ 接口
    403无权访问供应商接口采购商角色(tenant.type=2)调用了 /supplier/ 接口
    403该功能模块未授权平台未开通对应功能开关(order_enabled / reconciliation_enabled / finance_enabled / basicfile_enabled / global_product_enabled)

    12.4 资源不存在(404)#

    访问的单据不存在或不属于当前租户(租户隔离下不区分两者):
    message涉及接口
    订单不存在请购单详情/更新/删除/创建询价
    订单明细不存在放弃明细
    询价单不存在询价发布/取消/详情
    询价明细不存在添加供应商
    询价供应商记录不存在移除供应商
    报价单不存在报价详情/作废/报价结果详情
    比价单不存在比价详情/选标/取消
    采购订单不存在采购订单详情/暂停/恢复/取消
    变更记录不存在变更详情/确认/拒绝
    对账单不存在对账详情/确认/争议/作废

    12.5 无权限操作(403)#

    单据存在但不属于当前租户、或当前角色无权操作:
    message说明
    无权操作该订单 / 无权查看该订单请购单归属校验
    无权操作该询价单询价单归属校验
    您未被分配此询价单供应商端访问未派单给自己的询价
    无权查看该报价单 / 无权作废该报价单报价单归属校验
    无权操作该比价单比价单归属校验
    无权操作该采购订单 / 无权查看该采购订单采购订单归属校验
    无权操作该变更记录 / 无权查看该变更记录变更单归属校验
    无权操作该对账单 / 无权查看该对账单对账单归属校验

    12.6 参数校验失败(422)#

    涉及接口典型 message
    创建/更新订单游戏ID {id} 不存在或已停用;游戏编码 {code} 不存在;区服ID {id} 不存在或不属于当前游戏;产品 {code} 不存在或已停用;订单明细不能为空;产品[{name}]在订单明细中重复出现;明细外部产品名称不能为空;明细外部产品图标不能为空;明细外部产品编码不能为空;明细单价不能为负数;明细总价不能为负数;明细单价最多支持 6 位小数: {value};明细单价整数位最多 18 位(超出可存储范围): {value};明细总价最多支持 {n} 位小数: {value};数量/单价/总价必须为十进制字符串(不支持浮点数等类型);非法的十进制数值: {value};明细单价与总价不一致(单价×数量 ≠ 总价);数量为0,无法由总价推导单价;截止时间不能早于当前时间;外部订单号 {no} 已存在,请更换后重试;游戏ID或游戏编码必须提供;订单备注最多 500 字(当前 {n} 字)
    提交报价请先在基础设置中配置供应商交易币种(交易币种),设置后不可更改(供应商未配置交易币种时的前置拦截);未提交任何有效的报价明细;产品[{name}]的报价单价必须大于0;产品[{name}]的报价总价必须大于0;产品[{name}]的报价单价与总价至少填写一项;报价明细存在重复的询价明细项;产品[{name}]的报价单价最多支持 6 位小数: {value};产品[{name}]的报价单价整数位最多 18 位(超出可存储范围): {value};产品[{name}]的报价总价({currency})最多支持 {n} 位小数: {value};报价单价/总价/数量必须为十进制字符串(不支持浮点数等类型);产品[{name}]的报价单价与总价不一致(单价×数量=总价 与 总价÷数量=单价 任一方向自洽即可);产品[{name}]的报价数量与询价数量不一致;该订单要求供应商对所有产品进行报价,请补全未报价的产品;报价备注最多 500 字(当前 {n} 字);报价明细备注最多 500 字(当前 {n} 字)
    创建询价请选择报价截止时间;报价截止时间不能早于当前时间
    批量设置阶梯销售价/毛利率请提供待设置的数据项(items);单次提交不能超过 2000 条,请分批提交;销售价最多支持 6 位小数 / 整数位最多 18 位(超出可存储范围): {value};销售价不得为负数;区间非法:要么 00(不限数量默认档),要么 1 ≤ 起始 ≤ 截止;区间起始/截止数量必须为非负整数;产品[{code}]销售价数量区间交叉:{a} 与 {b};产品[{code}]销售价存在多条 00 默认档;档位ID 不存在或不属于当前供应商;毛利率最多支持 2 位小数 / 整数位最多 3 位(超出可存储范围): {value};销售价/毛利率必须为十进制字符串(不支持浮点数等类型)(逐条位宽错误不抛异常,以「第 {n} 条:…」/「第 {n} 行:…」形式通过 code=200 + data.errors 返回,见接口文档)
    添加产品(提交审核 / 产品库)销售价(cost_price)不支持在本接口提交,请在产品入库后使用 /open-api/v1/archive/product-prices/cost 接口设置
    报价结果详情无权查看此报价单
    暂停订单 / 暂停采购订单请选择问题类型;请填写暂停原因;问题类型必须为整数 / 问题类型取值范围为 0 ~ 3(problem_type 传 1.5、"abc" 等非整数时);暂停原因必须为字符串(当前为 {类型});问题凭证必须为字符串数组(当前为 {类型})
    提交发货(分批发货)请填写本次发货明细;发货明细必须为数组(当前为 {类型});发货明细第 n 项格式错误:必须为对象;发货明细第 n 项缺少合法的 item*id;发货明细第 n 项缺少 quantity;发货明细第 n 项数量必须为十进制字符串(不支持浮点数等类型)/ 最多支持 4 位小数: {value} / 整数位最多 14 位(超出可存储范围);发货明细不存在或不属于该订单;同一 产品在一次发货请求中只能出现一次;产品[{name}]本次发货数量必须大于 0;产品[{name}]本次发货数量不能超过剩余待发数量 {n};发货凭证必须为字符串数组(当前为 {类型})/ 第 n 项必须为字符串 / 不能为空 / 地址最多 500 字符;发货备注最多 500 字(当前 {n} 字)/ 必须为字符串(当前为 {类型});已发金额/本位币已发金额/已发总额/本批发货总额 整数位最多 18 位(超出可存储范围): {value};已发总数量/本批发货总数量 整数位最多 14 位(超出可存储范围): {value};订单已无待发货数量;发货请求标识重复但内容不一致,请更换 request_no;request_no 仅允许 1-64 位字母、数字与 - * : . 字符 / 必须为字符串(当前为 {类型})
    完结申请 / 完结申请审核请填写申请完结原因;申请完结原因最多 500 字(当前 {n} 字)/ 必须为字符串(当前为 {类型});完结审核备注最多 500 字(当前 {n} 字)/ 必须为字符串(当前为 {类型});请明确审核结果(通过/驳回);审核结果格式错误,必须为布尔值;剩余缺口处理方式必须为整数 / 取值范围为 0 ~ 2(gap_action 传 1.5、「2abc」等时直接 422,不会被截断改写成另一个合法动作);审核请求必须完整携带完结申请序号与订单数据快照,缺少或格式错误:{key};审核快照参数必须为十进制字符串:{key};完结审核不再处理缺口,「释放剩余」已下线(通过后未发付费商品可在订单完结后发起补货);驳回完结申请必须填写审核备注; 订单数据已变化,请刷新后重新审核;仅「本单结束未发部分」完结(部分发货完结)的采购订单可发起补货
    变更 / 暂停 / 取消 / 上报问题 / 对账争议 / 付款申请变更备注、暂停原因、取消原因、问题描述、争议原因、付款申请备注、审批备注、驳回原因、付款备注最多 500 字(当前 {n} 字);拒绝变更原因最多 500 字(当前 {n} 字);付款流水号最多 100 字(当前 {n} 字);付款方式/暂停原因/取消原因/问题描述/完结原因/审核备注/申请快照等文本入参必须为字符串(当前为 {类型});问题凭证必须为字符串数组(当前为 {类型});变更明细单价必须为十进制字符串(不支持浮点数等类型)/ 最多 6 位小数 / 整数位最多 18 位(超出可存储范围)
    订单变更(已发货部分)产品[{name}]变更后数量不得小于已发货数量 {n};产品[{name}]已发货,不可删除或更换产品;订单已发货,不可清空全部明细,请走完结审核流程
    乘积与汇总位宽(全部写库入口)单价/数量入参各自合法不代表乘积与累加结果能写入金额列,行总价/本位币行总价/由总价推导的单价/累计数量/头部总额(交易币与本位币)写入前一律按目标列位宽校验:金额与单价「整数位最多 18 位(超出可存储范围): {value}」、数量「整数位最多 14 位(超出可存储范围): {value}」(涉及创建/更新订单、提交报价、选标派单、订单变更、分批发货、完结审核、对账生成)

    12.7 业务规则失败(500)#

    模块典型 message
    创建询价当前订单状态不可创建询价;该订单已存在进行中的询价单({inquiry_no}),请勿重复创建;未找到有效的订单明细
    创建比价没有可比较的报价;该询价单已存在进行中的比价单({comparison_no}),请先完成或取消比价
    发布询价仅草稿状态可发布;没有匹配的供应商,无法发布
    报价询价单当前状态不可报价;报价已截止,截止时间:{deadline_at};您已提交过报价,如需修改请作废后重新报价
    比价/选标询价单当前状态不可比价;请至少选择一个中标项;该订单不允许拆分给多个供应商,请选择单一供应商;整单派单模式下必须将供应商的全部明细整单中标,请补全中标明细;订单已暂停,不允许选标生成采购订单,请先恢复订单
    订单操作当前状态不可取消;当前状态不可暂停;仅暂停状态可恢复;仅已取消状态可重新派单;当前状态不可追加询价;当前订单已有进行中的询价单,请等待完成或取消后再追加;整单派单模式的订单不支持追加询价;所选明细无剩余数量可追加询价;当前订单有进行中的比价单,请先完成或取消比价后再放弃剩余;该明细已全部分配,无剩余可放弃;当前状态不可放弃剩余数量
    订单变更已有待确认的变更,请等待供应商处理;变更明细不属于当前采购订单;变更基准数据存在重复的明细;变更基准数据必须完整覆盖当前订单全部明细,请刷新页面后重试;变更后数据存在重复的明细;变更后数据包含不属于当前订单的明细;变更后订单存在重复产品,请检查;当前状态不可确认
    发货与完结审核仅发货中/部分发货状态可提交发货;请上传发货凭证;订单无发货明细;请填写申请完结原因;仅部分发货状态可申请完结;该订单已提交完结申请,请等待采购商审核;尚未发货的订单不可申请完结,请继续完成全部发货;订单完结审核中,请先等待采购商审核;仅部分发货状态的订单可审核完结申请;该订单无待审核的完结申请
    采购订单操作当前状态不可取消;订单已发货,不可取消,请走完结审核流程;当前状态不可暂停;该请购单下有订单正在完结审核,请先完成审核后再暂停/恢复整单
    对账没有可生成对账单的已完成订单;已完成的对账单不可作废;所选订单币种不一致,无法生成对账单,请按币种分开对账
    币种/汇率租户未设置交易币种,请先在基础设置中配置;未找到币种 XXX 的有效汇率或汇率已超 72 小时未更新,请联系平台维护汇率后重试
    注:批量设置阶梯销售价接口(POST /open-api/v1/archive/product-prices/cost)支持三种写法——条目带 id 时按档位 ID 精确更新已设置记录(校验供应商归属,未提交的 min_quantity/max_quantity/price 沿用该记录原值,可只改价或只改区间);不带 id 时按产品编码/ID + 区间匹配(同产品同区间已有档则更新,否则新增);顶层 delete_ids 传入档位 ID 数组显式删除记录(仅删除属于本供应商的记录,其余忽略)。毛利率接口逻辑不变。批量接口采用全量校验模式,单条数据错误(含负价、区间非法、精度超限、条目 id 非正整数/非纯数字字符串,以及同一档位 ID 同时出现在 items(更新)与 delete_ids(删除)或同批 items 内重复更新的冲突)均不抛异常,而是返回 code=200 + data.errors 错误清单(success=0),仅 items 与 delete_ids 同时为空、超过 2000 条、delete_ids 非数组、delete_ids 含非正整数/非纯数字字符串元素等结构性/参数错误才返回 422;data.success 计入「新增+修改+删除」,data.total 计入「有效条目+错误条目+删除条目」。阶梯销售价同一事务内按产品升序加行锁后做区间交叉校验,任一冲突整批回滚。
    销售价格读取:GET /open-api/v1/archive/product-prices/cost 获取销售价格管理列表(阶梯销售价档位分页),查询条件与后台「销售价管理」抽屉完全一致(page/page_size/game_id/platform_id/server_id/category_id/cn_name/en_name),仅返回本供应商「我的供应」范围内产品的档位;返回行的 id 可直接用于上述更新/删除。
    供需范围:两个批量接口的产品都必须是本租户供需范围内的产品(供应商=「我的供应」已上架区服,采购商=「我的需求」已上架区服,平台租户不限制),与档案查询接口(games/platforms/servers/products)的过滤口径完全一致;范围外产品按「第 {n} 条:产品 {code} 不存在或不在当前「我的供应/我的需求」范围内」逐条报错,不会静默写入。

    12.8 排查建议#

    1.
    记录响应中的 trace_id,提供给平台方可在 api_request_log / open-api-error 日志中精确定位;
    2.
    401 错误优先核对服务器时钟(±300秒)与签名算法(第五节);
    3.
    403「该功能模块未授权」需在管理后台 API开放平台开通对应功能开关;
    4.
    500 业务错误的 message 已包含具体原因与单号,按提示调整业务流程即可,无需重试。

    十三、币种与精度字段说明#

    13.1 字段与语义说明#

    1.
    所有金额/数量/汇率字段均为十进制字符串,数量最多 4 位小数、单价最多 6 位小数、汇率 12 位小数;
    2.
    currency 为交易币种(采购商配置,创建订单时锁定快照);base_* 为平台本位币口径(按订单创建时锁定汇率换算);
    3.
    对账/付款币种与金额继承上游快照,不重新换汇;同一对账单内订单币种一致(混币生成会被拒绝);
    4.
    通过 API 创建订单仍使用采购商已配置的交易币种,接口不接收币种参数。
    5.
    双价规则(订单与报价一致):unit_price(最多 6 位小数)与 total_price(最多订单币种精度位小数)超出精度将返回 422 明确拒绝(不静默舍入);
    双传时按双向校验——单价×数量=总价(币种精度量化)或 总价÷数量=单价(同样按币种精度量化)任一方向自洽即通过,通过后按传入值原样保存;
    只传单价由后端算总价,只传总价由后端反推单价(6 位)。订单接口允许单价与总价都不传(价格留待后续环节填写);报价接口必须至少传一个;报价数量与询价需求数量不一致返回 422。
    6.
    整数位上限(与存储位宽一致):数量 decimal(18,4) → 整数位最多 14 位;单价/金额 decimal(24,6) → 18 位;汇率 decimal(24,12) → 12 位;
    参考价 decimal(10,2) → 8 位;毛利率 decimal(5,2) → 3 位。超位宽返回 422「整数位最多 N 位(超出可存储范围)」,不会透到 SQL 层报 22003;
    该校验不仅针对单个入参,乘积与汇总结果写入前同样校验(行总价、本位币行总价、累计数量、头部总额),因为「单价×数量」与「多条明细累加」
    都可能产生各自合法但超出列宽的结果;
    7.
    不接受 JSON 浮点数:数量/单价/金额/汇率入参必须是 JSON 字符串(或整数),传 123.45 这类 JSON number 直接 422「必须为十进制字符串」
    (浮点解析阶段已丢精度,Number('123456789012345678.123456') → 123456789012345680);响应中同名字段也一律为十进制字符串(如 "5.0000" 而非 5),
    客户端请勿按 number 解析;
    8.
    文本列长度:备注/原因/描述类字段(remark、reason、ship_remark、close_reason、完结审核 remark、problem_desc、problem_parse、争议原因、
    付款备注/审批备注/驳回原因等)最长 500 字;pay_trade_no 最长 100 字符;发货/问题凭证最多 20 项且单项 URL 最长 500 字符。超长统一 422(不依赖数据库截断)。
    external_product_name(外部产品名称)与 external_product_description(外部产品描述)为 text 长文本列,不设业务长度上限,
    仅按列容量(utf8mb4 按字符计 16000 字)兜底,超长同样 422;trade_info 交易信息同属长文本列。
    9.
    类型错误不得被强转吸收:文本入参必须是字符串/整数,凭证类必须是字符串数组,items(发货明细)必须是数组;服务端不会先用 (string)/(array)
    规范化再校验(那会把 "url" 洗成合法单元素数组、把 []/{} 洗成 "Array"/"Object" 落库),类型不符直接 422 并回显
    「{字段} 必须为字符串/字符串数组/数组(当前为 数组/对象/布尔值/浮点数)」;枚举整数入参(problem_type、完结审核的 gap_action)同理:1.5 不再被截断成 1,而是 422。

    13.2 新增错误码场景#

    场景提示
    采购商未设置交易币种创建订单/询价前需在管理后台「基础设置」配置交易币种(设置后不可更改)
    汇率缺失或超 72 小时未更新订单创建被阻断,平台会收到钉钉告警并人工维护汇率
    混币对账所选订单币种不一致,无法生成对账单

    十四、渠道 Webhook 接收(外部店铺 → 平台)#

    前十三节描述的是平台主动外发的回调与接口;本节描述外部店铺向平台推送数据的入站地址,方向相反、鉴权方式不同。

    14.1 地址格式#

    {API 基础地址}/open-api/webhook/channel/{渠道编码}
    示例:https://api.example.com/open-api/webhook/channel/SHOPA001
    项目说明
    渠道编码管理后台「渠道管理」中创建的渠道编码(英文字母 + 数字,全局唯一)
    地址来源不落库,由渠道编码实时派生,页面列表可直接复制
    修改方式修改渠道编码即等于更换 Webhook 地址,需在店铺后台同步更新订阅地址
    鉴权免鉴权:不走开放平台签名(AppKey/Sign)校验,也不校验登录态

    14.2 接口定义#

    方法路径用途
    GET/open-api/webhook/channel/{code}连通性探测,固定返回纯文本 ok,供店铺后台保存订阅地址时校验
    POST/open-api/webhook/channel/{code}接收店铺推送的订单/事件报文
    Content-Type 不作限制,application/json、application/x-www-form-urlencoded、自定义文本均可;
    请求体原样落库(超出 200000 字符会截断),查询参数与请求头一并记录;
    事件类型尽力从 event / event_type / type / msg_type / action 中解析,解析不到不影响受理。

    14.3 应答规范#

    受理成功(HTTP 200):
    {
      "code": 200,
      "message": "成功",
      "data": {
        "log_id": 1,
        "channel_code": "SHOPA001",
        "event": "order.created"
      },
      "trace_id": "..."
    }
    渠道编码不存在或渠道已停用(HTTP 200,业务码 422):
    {
      "code": 422,
      "message": "渠道 SHOPA001 已停用,不再接收推送",
      "data": [],
      "trace_id": "..."
    }
    应答中只返回受理凭证,不会返回渠道的 AppKey/AppSecret 等验签凭据。

    14.4 本期范围与后续规划#

    1.
    本期只保证收得到、存得下:原始报文写入 channel_webhook_log(含渠道、租户、平台类型、来源 IP、事件),verify_status=0(未验签)、process_status=0(未处理);
    2.
    待细化:按渠道所属平台类型(支持店铺)内置的接口地址与验签规则(AppKey/AppSecret)校验报文 → 解析订单 → 与开放平台创建请购单一致的业务落库,并回写 verify_status / process_status / error_message;
    3.
    排查建议:响应中的 trace_id 可与 open-api 文件日志、channel_webhook_log 记录互相对照定位。

    十五、原始订单接口(跨游戏区服下单)#

    一张外部订单可以同时包含多个游戏/平台/区服的产品。平台按「游戏 + 平台 + 区服」分组,同步拆分为多张整单模式请购单(每张照常自动创建并发布询价单、进入报价/比价/采购订单流程)。

    15.1 接口清单#

    方法路径说明
    POST/open-api/v1/buyer/raw-order创建原始订单(同步拆分,响应直接回子请购单列表)
    PUT/open-api/v1/buyer/raw-order/{id}修改原始订单(交易信息同步 / 明细变更则整单重建)
    PUT/open-api/v1/buyer/raw-order/{id}/trade-info修改原始订单交易信息(仅同步交易字段)
    POST/open-api/v1/buyer/raw-order/{id}/cancel取消原始订单(其下请购单与采购订单一并取消或自动完结)
    POST/open-api/v1/buyer/raw-order/{id}/pause暂停原始订单(其下全部进行中请购单原子级联暂停)
    POST/open-api/v1/buyer/raw-order/{id}/resume恢复原始订单(其下全部已暂停请购单原子级联恢复)

    15.2 请求约定#

    1.
    需开通 order_enabled 模块开关,否则返回 403;签名与消息体规则同第二章/第五章。
    2.
    定位方式:路径 {id} 传原始订单ID;只握有外部单号时 {id} 传 0 并带 raw_order_no(查询参数或请求体),两者同时提供时必须指向同一张单,否则 422;一律带采购商租户隔离,跨租户查不到即 404。
    3.
    以上接口均返回同一结构(原始单主体 + 子请购单列表),必含 raw_order_id,请保存以便发起修改/取消/暂停/恢复。
    4.
    不接受的入参:订单头的 game_id / platform_id / server_id / allow_split_supplier(区服由产品明细带出,子单固定整单模式);currency 由采购商租户配置锁定;购买人只认 out_buyer_id / out_buyer_email,传入 buyer_id / buyer_email 即 422。
    5.
    必填与限额:raw_order_no ≤ 58 且限 [A-Za-z0-9_-];创建必填 channel_code(≤ 32 且必须是已启用渠道编码,创建后锁定不可改)与 deadline_at(报价截止日期,不得早于当前时间);明细 1~100 行、拆分组 ≤ 20 组;每行必填 external_product_icon(≤ 255)、external_product_code(≤ 64)、external_product_name(长文本列,无业务长度上限,仅按存储列容量兜底),external_product_description(同口径长文本列)选填;out_buyer_id ≤ 64;out_buyer_email ≤ 100 且需为合法邮箱;remark ≤ 500;order_source(订单来源,即你方系统自己的来源标识,如店铺/渠道单来源)≤ 255 且选填。缺失或超限返回 422。
    6.
    明细的外部产品三字段、购买人三字段(channel_code / out_buyer_id / out_buyer_email)与交易类长文本(character_name 角色名 ≤ 255、trade_info 交易信息)随拆分原值下发到子请购单,并快照到采购订单,在请购单/采购订单/比价详情与发货详情同位置展示。order_source(订单来源)同样沿「原始订单 → 请购单 → 采购订单」逐层快照传递(不回写、不联动修改),并在对账单明细导出的「订单来源」列输出。

    15.3 修改与取消口径#

    修改(PUT /buyer/raw-order/{id}):
    可改:trade_info(交易信息,长文本) / character_name(角色名,≤ 255) / attachments / out_buyer_id / out_buyer_email(同步到其下全部请购单与采购订单,不触发回调);items(整体替换明细,差异比对与行序无关)。
    不可改:raw_order_no / currency / base_exchange_rate / channel_code(创建时必传、创建后锁定)与 order_source(下单来源事实快照,仅创建时可写),以及本期不支持的 remark / pay_time / deadline_at,传入不同值返回 422。
    明细变更等于取消其下请购单并按新明细重建,会成倍发出 order.cancelled 与 order.created 回调。
    明细变更/重建(请求含 items 变更):其下任一采购订单已提交发货或已完成时整体拒绝 422「订单已提交发货,请通过采购订单变更流程处理」;原始单已完成/已取消、或拆分未完成时同样拒绝。
    纯交易信息同步(只改 trade_info / character_name / attachments / out_buyer_id / out_buyer_email、不动明细):即使其下采购订单已提交发货也允许直接同步——只刷新子请购单与采购订单的交易快照,不改流程与状态、不触发回调,并记录原始订单操作日志与文件日志;但原始单已完成/已取消、或拆分未完成时仍拒绝 422。
    修改交易信息(PUT /buyer/raw-order/{id}/trade-info):
    只改交易信息,相当于上面“纯交易信息同步”那部分的独立入口;定位方式、闸门、同步范围与并发处理与「修改原始订单」完全一致。
    可改:trade_info(交易信息,长文本) / character_name(角色名,≤ 255) / attachments / out_buyer_id / out_buyer_email,新值同步到其下全部请购单与采购订单的交易快照,不触发回调、不改流程与状态。
    本接口仅受理上述交易信息字段(raw_order_no 仅用于定位单据);如需变更产品明细,请使用「修改原始订单」PUT /buyer/raw-order/{id}。
    闸门与返回结构同“纯交易信息同步”:其下采购订单已发货仍允许同步,原始单已完成/已取消/拆分未完成拒绝 422;无差异时幂等返回当前详情,返回结构与「修改原始订单」一致(必含 raw_order_id)。
    取消(POST /buyer/raw-order/{id}/cancel):
    取消其下全部请购单(级联询价单/比价单/报价单)与采购订单:未发货的采购订单直接取消;部分发货或已发货未完成的由平台自动完结(无需审核,缺口按「接受缺口」结算),照常发出 purchase_order.completed。
    只要存在已完成的采购订单,整个请求被拒绝(422「采购订单已完成,不允许取消」),不做部分执行、不修改任何数据。
    结果状态:全部取消 → 3 已取消;已完成与已取消混合 → 4 部分取消;原始单已取消时幂等返回当前详情,不报错。
    返回语义:仅当代全部子单取消/完结成功才返回 200(终态可为 3/2/4,以响应 split_error 为空为准);执行段任一子单取消受阻即停并返回失败(非 200),message 给出受阻原因与「已取消子单清单」——已取消的子单不回滚,按提示重发本接口即从断点续跑(已处理子单会跳过)。
    暂停 / 恢复(POST /buyer/raw-order/{id}/pause、POST /buyer/raw-order/{id}/resume):
    定位方式与取消一致(路径 {id} 或 raw_order_no 二选一);作用对象为当前拆分代次的全部子请购单,每张请购单再级联其下采购订单。
    暂停入参与管理后台/请购单暂停接口一致:problem_type(1=供应商问题 / 2=采购商问题 / 3=用户问题,必填)、problem_parse(暂停原因,必填)、problem_proof(问题凭证 URL 数组,选填);恢复仅需定位参数。
    原子性:与取消的「失败即停、已取消部分保留、可重发续跑」不同,暂停/恢复要求同一事务内全部子单一起成功——任一进行中请购单状态不满足暂停条件、或其下有采购订单正处于完结审核(冻结)时,整体返回 422 并回滚全部数据,不产生「一半暂停一半进行」的中间态;全部成功后才统一发出 order.paused / order.resumed 回调与供应商站内信。
    已处于目标态的子单不阻断整体:暂停时「已暂停」视为已满足、「已完成/已取消」不属暂停作用域(跳过);恢复时仅处理「已暂停」的子单,其余跳过。若一次请求没有任何可处理子单则返回 422。
    闸门:原始订单处于重建中 / 已取消 / 已完成 / 拆分未完成时不允许发起暂停/恢复(返回 422,请稍后或改走对应流程)。

    15.4 受理语义与重试(必读)#

    创建/修改接口返回 200 表示已受理,不表示全部完成,也不保证「要么全部生效、要么全部不生效」;取消接口返回 200 即当代子单已全部取消/完结完成,未能全部完成时返回失败(非 200),已取消的子单不回滚、可重发续跑。请按下表判定下一步:
    响应表现含义调用方动作
    status = 5、split_error 非空拆分/重建未完成,已成功的子单保留并照常流转按 rebuild_stage 选择重发哪个接口(见下两行)
    status = 5 且 rebuild_stage = 0首次拆分的分组未建完以同一 raw_order_no 原样重发创建接口,只补建剩余分组
    rebuild_stage > 0明细变更的重建未完用包含相同 items 的同一请求体重发修改接口续跑;此时创建接口返回 422
    取消接口返回失败(非 200;split_error 非空、原始单为非终态)取消中途失败(某张子单取消受阻即停)重发取消接口从断点继续,已处理子单会跳过;受阻原因看 message / split_error
    deduplicated = true命中已存在的外部单号(多为超时重发)直接取当前详情;若本次内容与已存在的单不一致,则不命中而是 422
    超时重试请原样重发(含原请求体),不要先查后改:幂等只重放同一份请求,改内容后的重发直接 422。
    同一原始单的拆分/重建/取消/暂停/恢复共用同一把互斥锁串行执行:恰有请求在飞时本次返回 422「正在被另一个拆分/重建请求处理」,稍后原样重发即可。
    取消会放弃该单尚未完成的明细重建(该次重建不再可续跑),因此请勿在重建未结束时发起取消。
    回调放大:一张外部单拆出 N 张子单,order.created 等事件按 N 条发出;明细变更重建更会成倍发出 order.cancelled + order.created。接收方需按 event + 单号做幂等(见第八章)。

    15.5 派生请购单不可直连操作#

    拆出的子请购单是派生数据:对其编辑、删除、取消、重新派单(无论后台页面还是 /buyer/order* 直连接口)均返回 422,提示改走原始订单接口;对这些单据的合法入口只有本组接口。以下路径保持开放:询价发布/追加、报价、比价选标、采购订单发货、采购订单变更、完结审核、对账与付款。(暂停/恢复对派生子单不强制走原始订单入口,但整单一致性建议统一使用本组 raw-order 暂停/恢复接口。)

    15.6 整单模式带来的既有行为差异#

    子单固定整单派单模式,因此:不支持向已有询价单追加询价(追加接口对整单模式直接报错);完结审核通过一律按已发数量结算(缺口处理不再是审核项,gap_action 已全局下线)。

    十六、OpenAPI 请求签名详解(你 → GameSCM SOMS)#

    本节适用于你主动调用 /open-api/v1/* 下面所有接口时的 签名生成。回调通知验签(第五节)与本节是同一套算法,可互相参考。
    参考实现:doc/open-api-sdk-php.php(PHP,含 Signature 统一签名核心、Signer 工具类与 Client 封装;回调验签 NotificationVerifier 也在同文件,直接 runnable)。

    16.1 必需 Header#

    Header说明
    X-App-Key平台分配的 AppKey
    X-TimestampUnix 时间戳(秒),与服务端当前时间差 ≤ 300s
    X-Nonce-Str随机字符串(建议 16–32 位),防重放
    X-Sign下方算法计算出的签名,MD5 大写
    Content-Typeapplication/json

    16.2 签名算法(与服务端 OpenApiSignMiddleware::verifySign 一一对齐)#

    1.
    参数集合:
    POST / PUT / PATCH:取 JSON body 解析后的 完整对象(包含 items 这类嵌套)。
    GET / DELETE:取 query 参数。
    末尾补上 timestamp、nonce_str 两个参数。
    2.
    一级空值过滤:仅剔除参数 最外层 中值为 '' 或 null 的项;嵌套里的空字符串 仍参与签名。
    3.
    递归字典序排序(ASCII):对象按 key 排序;列表数组保持索引顺序(不排序,避免 items[10] 排到 items[2] 前)。
    4.
    展平:按 PHP http_build_query 风格展开成单层。嵌套对象/数组 → parent[child]=value;列表 → items[0][field]=value。
    5.
    URL 解码(关键!很多对接方少这一步):对拼接后的字符串整体执行一次 urldecode,等价于「不对 value 做任何 URL 编码,直接 key=value 拼接」。含 :、/、中文字符等特殊符号的字段(如 external_product_icon、external_product_name)必需这一步才能与服务端对齐。
    6.
    追加密钥:末尾拼 &key={AppSecret}(注意 AppSecret 不参与排序、不 URL 编码)。
    7.
    哈希:X-Sign = strtoupper(md5(stringSignTemp))。

    16.3 完整示例(创建原始订单)#

    请求:POST /open-api/v1/buyer/raw-order,Content-Type: application/json
    Body:
    {
      "raw_order_no": "DEMO20260918001",
      "channel_code": "dd373",
      "deadline_at": "2026-09-25 18:00:00",
      "items": [
        {
          "product_code": "SKU-DEMO-001",
          "quantity": "1.0000",
          "unit_price": "10.00",
          "external_product_icon": "https://cdn.example.com/icon/gold-pack.png",
          "external_product_code": "EXT-GOLD-001",
          "external_product_name": "金币特惠礼包"
        }
      ]
    }
    Header 中的时间/随机串:X-Timestamp: 1758230400,X-Nonce-Str: abc123def456
    拼出的 stringSignTemp(已排序、已 urldecode,中文与 :// 保持原样):
    channel_code=dd373&deadline_at=2026-09-25 18:00:00&items[0][external_product_code]=EXT-GOLD-001&items[0][external_product_icon]=https://cdn.example.com/icon/gold-pack.png&items[0][external_product_name]=金币特惠礼包&items[0][product_code]=SKU-DEMO-001&items[0][quantity]=1.0000&items[0][unit_price]=10.00&nonce_str=abc123def456&raw_order_no=DEMO20260918001&timestamp=1758230400&key=你的AppSecret
    顶层参数排序后为 channel_code → deadline_at → items → nonce_str → raw_order_no → timestamp(items[0][…] 内部字段也已按 ASCII 升序)。
    签名:X-Sign = strtoupper(md5(上面这串))。

    16.4 PHP 参考代码#

    16.5 Java / Node.js 等效写法#

    不同语言实现时 只要保证下面三点,与服务端就能对齐:
    1.
    展平方式:嵌套对象 → parent[child],列表 → arr[下标];一路拼到叶子。
    2.
    排序:关联对象按 key ASCII 升序,列表保持原顺序。
    3.
    不 URL 编码 value:直接把原始字符串拼到 key=value。中文、:、/、&、= 均原样保留。
    ⚠️ 如你使用 Java 的 URLEncoder.encode 或 JS 的 encodeURIComponent,拼完整个字符串后必须再对应地 decode 一次(Java:URLDecoder.decode(s, "UTF-8");JS:decodeURIComponent(s)),否则 https:// 会变成 https%3A%2F%2F 导致与服务端不一致。最简单的做法:不 encode,直接拼。

    16.6 常见 401 验证失败排查清单#

    现象原因修正
    不带 URL/中文类字段时签名通过,带了就 401拼串时对 value 做了 URL 编码但没反向 urldecode拼完不 encode 或整体 decode 一次
    一直 401,无任何字段能过参数没递归排序(嵌套 items 里字段顺序不同)实现 recursiveKsort
    签名时带上了 sign 本身顶层参数多了一个把 sign 从待签参数里剔除
    时间头与签名中的 timestamp 不一致取时间时头与体分开取取一次时间,同时写入头和签名参数
    中文乱码导致 401先 JSON encode 后又 URL encode 两次中文保持原样,不 encode
    布尔值传了 true/falsePHP http_build_query 会转为 1/0自己拼接时也要转 1/0
    items: [] 时 401一级数组不为空但内容空建议至少传 1 行明细

    16.7 获取 trace_id#

    验签失败时返回体中会包含 trace_id(也同名字段写入日志),提供该 trace_id 给平台方可快速定位实际拼串。
    修改于 2026-11-10 08:30:51
    下一页
    游戏列表
    Built with