# 对账接口

对账接口用于商户系统与电商平台之间的交易对账和财务核对。

# 1. 核销对账单查询接口

GET /merchant/reconciliation/verify/list

查询指定时间段内的核销对账单数据。

请求参数

参数名 类型 必填 描述
start_date String 是 开始日期，格式：yyyy-MM-dd
end_date String 是 结束日期，格式：yyyy-MM-dd
page Integer 否 页码，默认1
size Integer 否 每页数量，默认20，最大100
store_id String 否 门店ID，不传则查询所有门店

响应参数

字段名 类型 描述
total Integer 总记录数
pages Integer 总页数
list Array 对账单列表

list数组中每个对象结构：

字段名 类型 描述
reconciliation_id String 对账单ID
bill_date String 账单日期，格式：yyyy-MM-dd
merchant_id String 商户ID
store_id String 门店ID
store_name String 门店名称
order_count Integer 订单总数
order_amount Decimal 订单总金额
platform_commission Decimal 平台佣金
delivery_fee Decimal 配送费
refund_amount Decimal 退款金额
actual_amount Decimal 实际结算金额
status Integer 对账状态：0-待确认，1-已确认，2-有异议
settlement_status Integer 结算状态：0-未结算，1-已结算
settlement_time Long 结算时间戳
create_time Long 创建时间戳
update_time Long 更新时间戳

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 30,
    "pages": 2,
    "list": [
      {
        "reconciliation_id": "REC20230605001",
        "bill_date": "2023-06-05",
        "merchant_id": "M10001",
        "store_id": "S2001",
        "store_name": "示例门店1",
        "order_count": 35,
        "order_amount": 3580.50,
        "platform_commission": 358.05,
        "delivery_fee": 175.00,
        "refund_amount": 150.00,
        "actual_amount": 3047.45,
        "status": 1,
        "settlement_status": 1,
        "settlement_time": 1623216000000,
        "create_time": 1623177600000,
        "update_time": 1623216000000
      },
      {
        "reconciliation_id": "REC20230604001",
        "bill_date": "2023-06-04",
        "merchant_id": "M10001",
        "store_id": "S2001",
        "store_name": "示例门店1",
        "order_count": 28,
        "order_amount": 2850.00,
        "platform_commission": 285.00,
        "delivery_fee": 140.00,
        "refund_amount": 200.00,
        "actual_amount": 2365.00,
        "status": 1,
        "settlement_status": 1,
        "settlement_time": 1623129600000,
        "create_time": 1623091200000,
        "update_time": 1623129600000
      }
    ]
  },
  "timestamp": 1623177600000
}

# 2. 对账单详情查询

GET /merchant/reconciliation/detail

查询指定对账单的详细信息。

请求参数

参数名 类型 必填 描述
reconciliation_id String 是 对账单ID

响应参数

字段名 类型 描述
reconciliation_id String 对账单ID
bill_date String 账单日期，格式：yyyy-MM-dd
merchant_id String 商户ID
merchant_name String 商户名称
store_id String 门店ID
store_name String 门店名称
order_count Integer 订单总数
order_amount Decimal 订单总金额
platform_commission Decimal 平台佣金
commission_rate Decimal 佣金率
delivery_fee Decimal 配送费
refund_count Integer 退款订单数
refund_amount Decimal 退款金额
promotion_amount Decimal 活动补贴金额
actual_amount Decimal 实际结算金额
status Integer 对账状态：0-待确认，1-已确认，2-有异议
settlement_status Integer 结算状态：0-未结算，1-已结算
settlement_time Long 结算时间戳
create_time Long 创建时间戳
update_time Long 更新时间戳
remark String 备注
order_items Array 订单明细列表
refund_items Array 退款明细列表

order_items数组中每个对象结构：

字段名 类型 描述
order_code String 订单编号
order_time Long 下单时间戳
pay_amount Decimal 支付金额
commission Decimal 佣金
delivery_fee Decimal 配送费
status Integer 订单状态

refund_items数组中每个对象结构：

字段名 类型 描述
refund_id String 退款单ID
order_code String 关联订单编号
refund_time Long 退款时间戳
refund_amount Decimal 退款金额
refund_commission Decimal 退还佣金

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "reconciliation_id": "REC20230605001",
    "bill_date": "2023-06-05",
    "merchant_id": "M10001",
    "merchant_name": "示例商户",
    "store_id": "S2001",
    "store_name": "示例门店1",
    "order_count": 35,
    "order_amount": 3580.50,
    "platform_commission": 358.05,
    "commission_rate": 0.10,
    "delivery_fee": 175.00,
    "refund_count": 2,
    "refund_amount": 150.00,
    "promotion_amount": 50.00,
    "actual_amount": 3047.45,
    "status": 1,
    "settlement_status": 1,
    "settlement_time": 1623216000000,
    "create_time": 1623177600000,
    "update_time": 1623216000000,
    "remark": "",
    "order_items": [
      {
        "order_code": "ORD20230605001",
        "order_time": 1623168000000,
        "pay_amount": 102.50,
        "commission": 10.25,
        "delivery_fee": 5.00,
        "status": 4
      },
      {
        "order_code": "ORD20230605002",
        "order_time": 1623168600000,
        "pay_amount": 88.00,
        "commission": 8.80,
        "delivery_fee": 5.00,
        "status": 4
      }
    ],
    "refund_items": [
      {
        "refund_id": "RF20230605001",
        "order_code": "ORD20230605003",
        "refund_time": 1623178800000,
        "refund_amount": 65.00,
        "refund_commission": 6.50
      },
      {
        "refund_id": "RF20230605002",
        "order_code": "ORD20230605010",
        "refund_time": 1623182400000,
        "refund_amount": 85.00,
        "refund_commission": 8.50
      }
    ]
  },
  "timestamp": 1623177600000
}

# 3. 对账单确认

POST /merchant/reconciliation/confirm

商户确认对账单无误。

请求参数

参数名 类型 必填 描述
reconciliation_id String 是 对账单ID
confirm_note String 否 确认备注
operator String 否 操作人

响应参数

字段名 类型 描述
reconciliation_id String 对账单ID
status Integer 更新后的对账状态
update_time Long 更新时间戳

请求示例

{
  "reconciliation_id": "REC20230605001",
  "confirm_note": "对账单已核实无误",
  "operator": "张经理"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "reconciliation_id": "REC20230605001",
    "status": 1,
    "update_time": 1623216000000
  },
  "timestamp": 1623216000000
}

# 4. 对账单异议提交

POST /merchant/reconciliation/dispute

商户对对账单有异议时提交申诉。

请求参数

参数名 类型 必填 描述
reconciliation_id String 是 对账单ID
dispute_type Integer 是 异议类型：1-订单数量不符，2-金额计算错误，3-佣金比例有误，4-其他
dispute_reason String 是 异议原因
expected_result String 是 期望的结果
evidence_images Array 否 证据图片URL数组
contact_name String 是 联系人姓名
contact_phone String 是 联系人电话
dispute_items Array 否 有异议的明细项

dispute_items数组中每个对象结构：

字段名 类型 描述
item_type String 明细类型：order-订单，refund-退款
item_id String 明细ID（订单号或退款单号）
current_amount Decimal 当前金额
expected_amount Decimal 期望金额
dispute_desc String 异议说明

响应参数

字段名 类型 描述
reconciliation_id String 对账单ID
dispute_id String 异议单ID
status Integer 更新后的对账状态
create_time Long 创建时间戳

请求示例

{
  "reconciliation_id": "REC20230605001",
  "dispute_type": 2,
  "dispute_reason": "订单金额计算有误，与我方数据不符",
  "expected_result": "重新核对订单金额并调整结算金额",
  "evidence_images": [
    "https://example.com/images/evidence1.jpg",
    "https://example.com/images/evidence2.jpg"
  ],
  "contact_name": "张经理",
  "contact_phone": "13800138001",
  "dispute_items": [
    {
      "item_type": "order",
      "item_id": "ORD20230605001",
      "current_amount": 102.50,
      "expected_amount": 112.50,
      "dispute_desc": "该订单金额应为112.50元"
    },
    {
      "item_type": "refund",
      "item_id": "RF20230605001",
      "current_amount": 65.00,
      "expected_amount": 60.00,
      "dispute_desc": "该退款金额应为60.00元"
    }
  ]
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "reconciliation_id": "REC20230605001",
    "dispute_id": "DIS20230606001",
    "status": 2,
    "create_time": 1623216000000
  },
  "timestamp": 1623216000000
}

# 5. 对账单异议处理结果查询

GET /merchant/reconciliation/dispute/result

查询对账单异议的处理结果。

请求参数

参数名 类型 必填 描述
dispute_id String 否 异议单ID，与reconciliation_id二选一
reconciliation_id String 否 对账单ID，与dispute_id二选一

响应参数

字段名 类型 描述
dispute_id String 异议单ID
reconciliation_id String 对账单ID
dispute_type Integer 异议类型：1-订单数量不符，2-金额计算错误，3-佣金比例有误，4-其他
dispute_reason String 异议原因
expected_result String 期望的结果
evidence_images Array 证据图片URL数组
contact_name String 联系人姓名
contact_phone String 联系人电话
dispute_status Integer 异议处理状态：0-待处理，1-处理中，2-已解决，3-已驳回
handler String 处理人
handle_time Long 处理时间戳
handle_result String 处理结果
handle_note String 处理备注
is_adjust Boolean 是否调整金额
adjust_amount Decimal 调整金额
original_amount Decimal 原金额
adjusted_amount Decimal 调整后金额
create_time Long 创建时间戳
update_time Long 更新时间戳
dispute_items Array 有异议的明细项
progress Array 处理进度列表

dispute_items数组中每个对象结构：

字段名 类型 描述
item_type String 明细类型：order-订单，refund-退款
item_id String 明细ID（订单号或退款单号）
current_amount Decimal 当前金额
expected_amount Decimal 期望金额
adjusted_amount Decimal 调整后金额
is_adjusted Boolean 是否已调整
dispute_desc String 异议说明
handle_result String 处理结果

progress数组中每个对象结构：

字段名 类型 描述
progress_time Long 进度时间戳
progress_status Integer 进度状态
progress_desc String 进度描述
operator String 操作人
operator_role String 操作人角色
remarks String 备注

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "dispute_id": "DIS20230606001",
    "reconciliation_id": "REC20230605001",
    "dispute_type": 2,
    "dispute_reason": "订单金额计算有误，与我方数据不符",
    "expected_result": "重新核对订单金额并调整结算金额",
    "evidence_images": [
      "https://example.com/images/evidence1.jpg",
      "https://example.com/images/evidence2.jpg"
    ],
    "contact_name": "张经理",
    "contact_phone": "13800138001",
    "dispute_status": 2,
    "handler": "平台客服",
    "handle_time": 1623302400000,
    "handle_result": "经核实，商户提供的订单金额正确，平台系统数据有误，已调整金额",
    "handle_note": "订单金额已调整，并已更新对账单",
    "is_adjust": true,
    "adjust_amount": 10.00,
    "original_amount": 3047.45,
    "adjusted_amount": 3057.45,
    "create_time": 1623216000000,
    "update_time": 1623302400000,
    "dispute_items": [
      {
        "item_type": "order",
        "item_id": "ORD20230605001",
        "current_amount": 102.50,
        "expected_amount": 112.50,
        "adjusted_amount": 112.50,
        "is_adjusted": true,
        "dispute_desc": "该订单金额应为112.50元",
        "handle_result": "已更正"
      },
      {
        "item_type": "refund",
        "item_id": "RF20230605001",
        "current_amount": 65.00,
        "expected_amount": 60.00,
        "adjusted_amount": 65.00,
        "is_adjusted": false,
        "dispute_desc": "该退款金额应为60.00元",
        "handle_result": "经核实，退款金额65.00元正确"
      }
    ],
    "progress": [
      {
        "progress_time": 1623216000000,
        "progress_status": 0,
        "progress_desc": "商户提交异议",
        "operator": "张经理",
        "operator_role": "商户",
        "remarks": "订单金额计算有误，与我方数据不符"
      },
      {
        "progress_time": 1623252000000,
        "progress_status": 1,
        "progress_desc": "平台受理异议",
        "operator": "平台客服",
        "operator_role": "平台",
        "remarks": "已安排核查"
      },
      {
        "progress_time": 1623302400000,
        "progress_status": 2,
        "progress_desc": "异议处理完成",
        "operator": "平台客服",
        "operator_role": "平台",
        "remarks": "经核实，商户提供的订单金额正确，平台系统数据有误，已调整金额"
      }
    ]
  },
  "timestamp": 1623302400000
}

# 6. 结算记录查询

GET /merchant/settlement/list

查询商户的结算记录。

请求参数

参数名 类型 必填 描述
start_date String 是 开始日期，格式：yyyy-MM-dd
end_date String 是 结束日期，格式：yyyy-MM-dd
page Integer 否 页码，默认1
size Integer 否 每页数量，默认20，最大100
store_id String 否 门店ID，不传则查询所有门店
status Integer 否 结算状态：0-结算中，1-结算成功，2-结算失败

响应参数

字段名 类型 描述
total Integer 总记录数
pages Integer 总页数
list Array 结算记录列表

list数组中每个对象结构：

字段名 类型 描述
settlement_id String 结算单ID
merchant_id String 商户ID
store_id String 门店ID
store_name String 门店名称
settlement_period String 结算周期，格式：yyyy-MM-dd 至 yyyy-MM-dd
settlement_amount Decimal 结算金额
status Integer 结算状态：0-结算中，1-结算成功，2-结算失败
settlement_time Long 结算时间戳
settlement_method String 结算方式：BANK-银行转账，ALIPAY-支付宝，WECHAT-微信
account_name String 收款账户名
account_no String 收款账号（脱敏）
bank_name String 银行名称
transaction_id String 交易流水号
remark String 备注
create_time Long 创建时间戳
update_time Long 更新时间戳

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 20,
    "pages": 1,
    "list": [
      {
        "settlement_id": "SET20230610001",
        "merchant_id": "M10001",
        "store_id": "S2001",
        "store_name": "示例门店1",
        "settlement_period": "2023-06-01 至 2023-06-07",
        "settlement_amount": 21520.85,
        "status": 1,
        "settlement_time": 1623302400000,
        "settlement_method": "BANK",
        "account_name": "张三",
        "account_no": "622848******1234",
        "bank_name": "招商银行",
        "transaction_id": "T202306100012345678",
        "remark": "第一周结算",
        "create_time": 1623302400000,
        "update_time": 1623302400000
      },
      {
        "settlement_id": "SET20230603001",
        "merchant_id": "M10001",
        "store_id": "S2001",
        "store_name": "示例门店1",
        "settlement_period": "2023-05-24 至 2023-05-31",
        "settlement_amount": 19850.30,
        "status": 1,
        "settlement_time": 1622736000000,
        "settlement_method": "BANK",
        "account_name": "张三",
        "account_no": "622848******1234",
        "bank_name": "招商银行",
        "transaction_id": "T202306030012345678",
        "remark": "五月最后一周结算",
        "create_time": 1622736000000,
        "update_time": 1622736000000
      }
    ]
  },
  "timestamp": 1623302400000
}

# 7. 结算详情查询

GET /merchant/settlement/detail

查询指定结算单的详细信息。

请求参数

参数名 类型 必填 描述
settlement_id String 是 结算单ID

响应参数

字段名 类型 描述
settlement_id String 结算单ID
merchant_id String 商户ID
merchant_name String 商户名称
store_id String 门店ID
store_name String 门店名称
settlement_period_start String 结算周期开始日期，格式：yyyy-MM-dd
settlement_period_end String 结算周期结束日期，格式：yyyy-MM-dd
settlement_amount Decimal 结算金额
status Integer 结算状态：0-结算中，1-结算成功，2-结算失败
settlement_time Long 结算时间戳
settlement_method String 结算方式：BANK-银行转账，ALIPAY-支付宝，WECHAT-微信
account_name String 收款账户名
account_no String 收款账号（脱敏）
bank_name String 银行名称
transaction_id String 交易流水号
order_amount Decimal 订单总金额
order_count Integer 订单总数
commission_amount Decimal 佣金总额
delivery_fee Decimal 配送费总额
refund_amount Decimal 退款总金额
refund_count Integer 退款订单数
promotion_amount Decimal 活动补贴金额
adjustment_amount Decimal 调整金额
adjustment_reason String 调整原因
fail_reason String 失败原因
remark String 备注
create_time Long 创建时间戳
update_time Long 更新时间戳
reconciliation_ids Array 关联的对账单ID列表
settlement_progress Array 结算进度列表

settlement_progress数组中每个对象结构：

字段名 类型 描述
progress_time Long 进度时间戳
progress_status Integer 进度状态
progress_desc String 进度描述
operator String 操作人
remarks String 备注

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "settlement_id": "SET20230610001",
    "merchant_id": "M10001",
    "merchant_name": "示例商户",
    "store_id": "S2001",
    "store_name": "示例门店1",
    "settlement_period_start": "2023-06-01",
    "settlement_period_end": "2023-06-07",
    "settlement_amount": 21520.85,
    "status": 1,
    "settlement_time": 1623302400000,
    "settlement_method": "BANK",
    "account_name": "张三",
    "account_no": "622848******1234",
    "bank_name": "招商银行",
    "transaction_id": "T202306100012345678",
    "order_amount": 25600.00,
    "order_count": 248,
    "commission_amount": 2560.00,
    "delivery_fee": 1240.00,
    "refund_amount": 850.00,
    "refund_count": 15,
    "promotion_amount": 120.00,
    "adjustment_amount": 30.15,
    "adjustment_reason": "对账单异议调整",
    "fail_reason": null,
    "remark": "第一周结算",
    "create_time": 1623302400000,
    "update_time": 1623302400000,
    "reconciliation_ids": [
      "REC20230601001",
      "REC20230602001",
      "REC20230603001",
      "REC20230604001",
      "REC20230605001",
      "REC20230606001",
      "REC20230607001"
    ],
    "settlement_progress": [
      {
        "progress_time": 1623301800000,
        "progress_status": 0,
        "progress_desc": "结算单创建",
        "operator": "系统",
        "remarks": "系统自动创建结算单"
      },
      {
        "progress_time": 1623302100000,
        "progress_status": 1,
        "progress_desc": "结算处理中",
        "operator": "系统",
        "remarks": "开始处理结算"
      },
      {
        "progress_time": 1623302400000,
        "progress_status": 2,
        "progress_desc": "结算成功",
        "operator": "系统",
        "remarks": "结算资金已转入商户账户"
      }
    ]
  },
  "timestamp": 1623302400000
}