油猴联调接口说明

用途与阶段

• 用途：用于油猴技术向 n8n 推送抖音订单测试报文。
• 阶段：抖音一期联调。当前已有「字段校验入口」和「真实写表联调入口」。真实写表入口会向企微智能表新增记录，请只发送约定的测试订单。

一、接口信息

• 请求方式：POST
• Content-Type：application/json
• 字段校验地址：https://gzl.amulx.com/webhook/orders/douyin/test
• 真实写表联调地址：https://gzl.amulx.com/webhook/orders/douyin/write-durable-test

说明：

1. 字段校验地址：只校验字段和标准化回传，不写入企微表。
2. 真实写表联调地址：会进行字段校验、产品匹配，并在匹配成功后写入 4 个目标表：平台单、子订单、客户订单、母订单。
3. 当前真实写表联调入口使用临时策略快照匹配产品；若油猴推送的抖音产品 ID/SKU 不在快照中，会返回 match_error，不会写表。
4. 同一 order_source + platform_order_no 已成功导入后，再次提交会返回 duplicated，不会再次写表。
5. 如果中途只有部分目标表写入成功，后续同一订单号重试会跳过已成功的目标表，只补写失败后的步骤。
6. 请勿批量压测真实写表入口，避免产生大量测试记录。

二、推荐联调顺序

1. 先向字段校验地址推送 1 条真实抖音正常单，确认字段名、类型、日期格式、金额格式能被 n8n 正常识别。
2. 如字段校验返回 received，再向真实写表联调地址推送同结构的新订单号，验证端到端落表。
3. 用同一个订单号再推送一次，验证重复单返回 duplicated。
4. 如返回 match_error，请把接口返回的 errorMessage 和该订单的 platform_package_id、platform_sku_id 发回，用于补产品匹配关系。

三、请求字段

四、请求示例

{
  "platform_order_no": "DY202608280001",
  "platform_package_id": "PKG001",
  "platform_sku_id": "SKU001",
  "customer_name": "张三",
  "client_phone": "13800138000",
  "client_supplement": "无",
  "order_quantity": 1,
  "order_date": "2026-08-28",
  "travel_date": "2026-09-01",
  "sub_platform": "抖音来客阿目国际旅行社",
  "sub_order_amount": 599,
  "order_source": "抖音"
}

五、成功响应示例

字段校验入口成功响应示例

{
  "requestId": "1787888266949-vgv2b9",
  "importStatus": "received",
  "errorCode": "",
  "errorMessage": "",
  "receivedAt": "2026-08-28T03:37:46.950Z",
  "source": "抖音",
  "orderNo": "DY-SYS-20260828-004",
  "normalized": {
    "platform_order_no": "DY-SYS-20260828-004",
    "platform_package_id": "PKG001",
    "platform_sku_id": "SKU001",
    "customer_name": "测试客户",
    "client_phone": "13000000000",
    "client_supplement": "",
    "order_quantity": 1,
    "order_date": "2026-08-28",
    "travel_date": "2026-09-01",
    "sub_platform": "抖音来客阿目国际旅行社",
    "sub_order_amount": 1,
    "order_source": "抖音"
  }
}

真实写表联调入口成功响应示例

{
  "requestId": "1787904712351-rszhea",
  "importStatus": "success",
  "errorCode": "",
  "errorMessage": "",
  "orderNo": "WT2026082812",
  "idempotencyKey": "平台单:WT2026082812",
  "records": {
    "platformLedger": "...",
    "subOrder": "...",
    "customerOrder": "...",
    "parentOrder": "..."
  }
}

六、字段缺失响应示例

{
  "requestId": "1787888523374-yq5y2f",
  "importStatus": "validation_error",
  "errorCode": "MISSING_REQUIRED_FIELDS",
  "errorMessage": "缺少必填字段：platform_package_id, platform_sku_id, client_phone, order_quantity, order_date, travel_date, sub_platform, sub_order_amount, order_source",
  "orderNo": "DY-SYS-20260828-MISSING"
}

七、产品未匹配响应示例

{
  "requestId": "1787893751567-3wjwqk",
  "importStatus": "match_error",
  "errorCode": "PRODUCT_NOT_FOUND",
  "errorMessage": "未匹配到平台产品：NO_MATCH_PACKAGE|NO_MATCH_SKU",
  "orderNo": "WT2026082801"
}

八、重复单响应示例

{
  "requestId": "1787904731605-cn0zuf",
  "importStatus": "duplicated",
  "errorCode": "ORDER_ALREADY_IMPORTED",
  "errorMessage": "订单已导入：WT2026082812",
  "orderNo": "WT2026082812",
  "idempotencyKey": "平台单:WT2026082812",
  "records": {
    "platformLedger": "...",
    "subOrder": "...",
    "customerOrder": "...",
    "parentOrder": "..."
  },
  "previousRequestId": "1787904712351-rszhea",
  "previousSavedAt": "2026-08-28T08:12:04.365Z"
}

九、部分失败响应示例

{
  "requestId": "1787904825624-1jc1z9",
  "importStatus": "partial_failed",
  "errorCode": "PARTIAL_WRITE_FAILED",
  "errorMessage": "customerOrder 写入失败",
  "orderNo": "WT2026082813",
  "idempotencyKey": "平台单:WT2026082813",
  "records": {
    "platformLedger": "...",
    "subOrder": "..."
  },
  "retryHint": "同一订单号重试会跳过已成功写入的目标表，只补写失败后的步骤。"
}

十、当前说明

• 如果只是确认字段名称、类型、日期格式和金额格式，请先推送到字段校验地址。
• 如果需要端到端联调真实落表，请推送到真实写表联调地址。
• 油猴侧请先推送一条真实抖音正常单；如产品暂未命中策略快照，请回传接口响应中的 errorMessage，再补充对应产品匹配关系。