webhooks

webhooks功能说明：

在【获取授权】的接口头部信息中传入回调地址“x-webhook-url”，将会启用webhook功能。
回调地址存储时间：30天
回调事件：地址标签验证、订单状态变化、明细订单变化

• 一、地址标签验证
  除美国和日本以外，当tag为提前验证的类型时，地址验证完成后，会执行回调。

• 二、订单状态变化
  订单状态发生改变时，会执行回调。
  订单状态枚举值：
  1下单中：初始状态，不会执行回调
  2处理中：执行回调
  3制作中：执行回调，如果成功数量(success_num) 等于订单数量(num)。 所有明细订单皆成功，不会另外执行明细订单的回调。当订单success_num<num时（部分成功部分失败），明细订单的状态会执行回调。
  4已寄出：执行回调
  5异常退款：执行回调。异常退款时，所有明细订单皆为失败，不会另外执行明细订单的回调。
  6待发送/待重试：执行回调 ，系统异常时出现。一般在24小时内会处理完成
  7预约：不会执行回调
  8手动取消：执行回调

• 三、明细订单变化
  状态变化：订单order存在(fail_num)大于0，执行回调
  物流跟踪变化：执行回调

重试机制：

接口接收到http状态码为200时，视为成功。
其他情况视为失败，失败情况下会每隔5分钟重试一次，最大重试次数3次。
如果3次均失败，则不再执行回调。需要主动查询

返回结构中的签名(sign)生成逻辑： x-api-auth + & + timestamp，然后做md5(32位小)
x-api-auth：账户的x-api-auth
timestamp：接口结构中返回的时间戳

示例：

x-api-auth：d41d8cd98f00b204e9800998ecf8427e
timestamp：1723617205
拼接字符串：d41d8cd98f00b204e9800998ecf8427e&1723617205
md5：42239b8743f611fe24c174ce50900e14

回调接口返回结构可查看

回调分别有3个类型

1. sub_order类型回调结构 下面是回调示例

{
    "sign": "a5c27cb1c1ce1797de560e9af741bbbd",
    "agent_id": 3,
    "timestamp": 1731147429,
    "event_type": "sub_order",
    "callback_url": "http://callbackurl",
    "data": {
        "address1": "Calle urbion 8",
        "address2": "PISO 3, Letra A",
        "agent_id": 3,
        "back": "\u003cdiv\u003e\u003cimg class=\"back\" src=\"https://test-1258279456.cos.ap-hongkong.myqcloud.com/1/2024-10/393fca65-ca78-4d7c-8e49-5364333f5a6c.jpg\"\u003e\u003c/div\u003e",
        "city": "LAS ROZAS",
        "color": "color",
        "country_code": "ES",
        "created_at": "2024-10-11 15:28:48",
        "email": "",
        "express": "default",
        "fail_reason": "",
        "front": "\u003cdiv\u003e\u003cimg class=\"front\" src=\"https://test-1258279456.cos.ap-hongkong.myqcloud.com/platform/2024-10/ebe108de-f297-407d-8116-387ab788a676.jpg\"\u003e\u003c/div\u003e",
        "id": 1816,
        "inv_id": 4,
        "is_valid": 2,
        "last_name": "",
        "month": "2024-10",
        "name": "AMANDA MARTIN RIVAS ",
        "order_id": 4223,
        "phone": "",
        "pid": 3,
        "price": "8.98",
        "scan_num": 0,
        "scan_time": "0001-01-01 00:00:00",
        "size": "A6",
        "state": "MADRID",
        "status": 4,
        "sub_type": 1,
        "token": "",
        "track_detail": "",
        "track_status": "",
        "type": 1,
        "updated_at": "2024-10-11 15:38:51",
        "zip": "28231"
    }
}

2. order类型回调结构 下面是回调示例

{
    "sign": "7f4cb64fa7cc866ff730379fc301eafb",
    "agent_id": 23,
    "timestamp": 1730362464,
    "event_type": "order",
    "callback_url": "http://callback/mailzong/callback",
    "data": {
        "agent_id": 23,
        "agent_name": "oushengjia@jyxtech.com.cn",
        "check_num": 124,
        "color": "color",
        "country_code": "US",
        "created_at": "2024-10-15 15:15:27",
        "currency": "CNY",
        "day": "2024-10-15",
        "express": "usps_first_class",
        "fail_num": 2,
        "id": 4306,
        "inv_id": 24,
        "is_refund": 3,
        "is_subscribe": -1,
        "month": "2024-10",
        "num": 126,
        "order_name": "直邮订单-24100084548",
        "order_no": "Po012410151515274",
        "pid": 23,
        "preview": "https://img.wahuto.com/web/fbgourp/a48acc597a0b43049be01f5cfd61f0bc",
        "price": "734.08",
        "refund_price": "11.84",
        "request_id": "24100084548",
        "scan_uv": 0,
        "sender": "",
        "size": "6x11",
        "status": 4,
        "sub_type": 1,
        "subscribe_day": "",
        "success_num": 124,
        "surcharge": "0",
        "tag": "",
        "tag_id": 5847,
        "template_id": 2019,
        "type": 1,
        "unit_price": "5.92",
        "updated_at": "2024-10-31 16:14:24"
    }
}

3. address_tag 类型回调结构 下面是回调示例

{
    "sign": "322015b53609c5e1701b019c1e233183",
    "agent_id": 3,
    "timestamp": 1732257844,
    "event_type": "address_tag",
    "callback_url": "http://callbackurl",
    "data": {
        "agent_id": 3,
        "agent_name": "test001",
        "check_num": 62,
        "country_code": "CA",
        "created_at": "2024-11-22 14:41:31",
        "id": 6079,
        "in_num": 62,
        "month": "2024-11",
        "name": "哈哈提前验证测试",
        "num": 62,
        "pre_verification": 1,
        "send_num": 0,
        "status": 3,
        "updated_at": "2024-11-22 14:44:03"
    }
}