Events API 接口文档

通用说明

接口地址： POST https://api.mambasms.com/api/v1/events

认证方式： Header 携带 X-Mamba-Access-Token: shop_xxxx

Content-Type： application/json

请求体结构：

参数	类型	必填	说明
endpoint	String	✅	事件类型
source_id	String	✅	事件唯一标识，最长 50 字符，重复提交返回 304
data	Object	✅	事件数据，结构因 endpoint 而异

返回格式：

// 成功
{"code": 200, "message": "ok"}

// source_id 重复（防重）
{"code": 304, "message": "SourceId already exist"}

// 参数校验失败
{"code": 412, "message": "具体错误描述"}

限流： 每秒最多 40 次请求。

全局参数 ignore_flow： 所有事件的 data 内均可传入，不传默认 "N" 正常触发自动化；传 "Y" 跳过所有自动化。

一、客户事件

1.1 `customers/create` — 创建客户

{
  "endpoint": "customers/create",
  "source_id": "cust_001",
  "data": {
    "id": "user_001",                          // ✅ 必填，用户在自有系统的唯一标识
    "email": "[email protected]",               // ✅ 必填，邮箱地址
    "created_at": 1680170229,                  // ✅ 必填，Unix 秒级时间戳（10位），自动兼容毫秒
    "first_name": "John",                      // 名
    "last_name": "Doe",                        // 姓
    "phone": "+1234567890",                    // 手机号（含国际区号）
    "country_code": "US",                      // 国家，ISO 二位编码 (US/CN)
    "locale": "en",                            // 语言
    "gender": "male",                          // 性别
    "birth_date": "1990-01-15",                // 生日
    "city": "Los Angeles",                     // 城市
    "email_marketing_consent": {               // 邮件订阅状态
      "state": "subscribed",                    //   subscribed=已订阅 / not_subscribed=已退订 / unsubscribed=已退订
      "updatedAt": 1680170229                   //   订阅操作时间，Unix 秒级时间戳
    },
    "sms_marketing_consent": {                 // 短信订阅状态（同上）
      "state": "not_subscribed"
    },
    "default_address": {                       // 默认地址
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1234567890",
      "country_code": "US",                    //   国家编码
      "country_name": "United States",         //   国家名称
      "province": "California",                //   省份
      "province_code": "CA",                   //   省份代码
      "city": "Los Angeles",                   //   城市
      "zip": "90001",                          //   邮编
      "address1": "123 Main St",               //   地址行1
      "address2": "Apt 4B"                     //   地址行2
    },
    "tags": ["vip", "loyal"],                  // 用户标签数组，存入平台标签树（需手动同步才在标签树可见）
    "tag_value": "会员等级:VIP,来源渠道:官网",  // 分类标签，格式 分类名:标签值，多组逗号分隔，存入 sys_api 目录下
    "ignore_flow": "N"                         // 不传默认N=触发自动化，Y=跳过
  }
}

1.2 `customers/update` — 更新客户

字段同 customers/create，仅更新传入的字段。

1.3 `customers` — 创建或更新（自动判断）

系统根据 id 自动判断：已存在则更新，不存在则创建。

二、订单事件

2.1 `orders/create` — 创建订单

{
  "endpoint": "orders/create",
  "source_id": "ord_001",
  "data": {
    "id": "order_001",                         // ✅ 必填，订单唯一标识
    "customer_id": "user_001",                 // ✅ 必填，关联的客户 id
    "email": "[email protected]",               // ✅ 必填，客户邮箱
    "name": "#1001",                           // ✅ 必填，订单编号/名称
    "order_status": "pending",                 // ✅ 必填，订单状态: pending/paid/fulfilled/cancelled/voided/refunded
    "total_price": "99.99",                    // ✅ 必填，订单总金额
    "line_items": [                            // ✅ 必填，至少1条
      {
        "id": "li_001",                        //   行ID
        "product_id": "prod_001",              //   商品 SPU ID
        "variant_id": "sku_001",               //   SKU ID
        "sku": "IP-RED-M",                     //   SKU 编码
        "name": "iPhone 手机壳",               //   商品名
        "title": "iPhone 手机壳 - 红色 M",     //   行标题
        "variant_title": "红色 / M",           //   规格描述
        "quantity": 2,                         //   数量
        "price": "29.99",                      //   单价
        "line_price": "59.98",                 //   行总价
        "total_discount": "5.00",              //   行折扣
        "src": "https://example.com/img.jpg",  //   商品图片 URL
        "product_url": "https://shop.com/p",   //   商品详情页 URL
        "fulfillment_status": null,            //   发货状态
        "tracking_company": "",                //   物流公司（发货事件时填入）
        "tracking_number": "",                 //   物流单号（发货事件时填入）
        "tracking_url": ""                     //   物流追踪链接（发货事件时填入）
      }
    ],
    "currency": "USD",                         // 货币，如 USD/CNY
    "subtotal_price": "89.99",                 // 小计（商品总价，不含运费税费）
    "total_discount": "10.00",                 // 折扣总额
    "total_shipping": "5.00",                  // 运费
    "total_tax": "5.00",                       // 税费
    "payment_method": "credit_card",           // 支付方式
    "shipping_method": "standard",             // 物流方式
    "cart_token": "cart_token_001",            // 购物车标识，关联弃单流程
    "checkout_token": "checkout_token_001",    // 结账标识，关联结账流程
    "order_status_url": "https://shop.com/orders/1001",  // 用户查看订单的页面链接
    "payment_at": 1680170229,                  // 支付时间，Unix 秒级时间戳
    "created_at": 1680170229,                  // 创建时间
    "updated_at": 1680170229,                  // 更新时间
    "fulfillment_status": "unfulfilled",       // 发货状态: fulfilled/partial/unfulfilled
    "phone": "+1234567890",                    // 手机号
    "country_code": "US",                      // 国家
    "shipping_address": {                      // 收货地址（字段同客户地址）
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1234567890",
      "country_code": "US",
      "province": "California",
      "city": "Los Angeles",
      "address1": "123 Main St",
      "zip": "90001"
    },
    "billing_address": {},                     // 账单地址（同上结构）
    "ignore_flow": "N"                         // Y=跳过自动化
  }
}

2.2 `orders/paid` — 订单支付

字段同 orders/create。传入 cart_token 和 checkout_token 可自动清理弃单数据。

2.3 `orders/fulfilled` — 订单发货

字段同 orders/create，需在 line_items 中填入 tracking_company、tracking_number、tracking_url。

2.4 `orders/update` — 更新订单｜状态变为 paid 时自动清理购物车

2.5 `orders/cancelled` — 订单取消

2.6 `orders/refunded` — 订单退款

三、商品事件

3.1 `products/create` — 创建商品

{
  "endpoint": "products/create",
  "source_id": "prod_001",
  "data": {
    "id": "prod_001",                          // ✅ 必填，SPU 唯一标识
    "title": "iPhone 手机壳",                  // ✅ 必填，商品名称
    "src": "https://example.com/main.jpg",     // ✅ 必填，商品主图 URL
    "purchase_url": "https://shop.com/product/iphone-case",  // ✅ 必填，商品详情页链接
    "handle": "iphone-case",                   // SEO 别名
    "created_at": 1680170229,                  // 创建时间，Unix 秒级时间戳
    "variants": [                              // ✅ 必填，SKU 数组，至少1条
      {
        "id": "sku_001",                       //   SKU 唯一标识
        "sku": "IP-RED-M",                     //   SKU 编码
        "price": "29.99",                      //   价格（纯数字，不带货币符号）
        "src": "https://example.com/red.jpg",  //   SKU 图片 URL
        "inventory_quantity": 100,             //   库存数量
        "option1": "红色",                     //   规格1（如颜色）
        "option2": "M",                        //   规格2（如尺码）
        "option3": "皮质"                      //   规格3（如材质）
      },
      {
        "id": "sku_002",
        "sku": "IP-BLUE-L",
        "price": "35.99",
        "src": "https://example.com/blue.jpg",
        "inventory_quantity": 50,
        "option1": "蓝色",
        "option2": "L",
        "option3": "硅胶"
      }
    ]
  }
}

一个 SPU 一条记录，variants 数组里放所有 SKU，不需要按 SKU 拆多条。

3.2 `products/update` 和 `products`

同 products/create，products 自动判断新建或更新。

四、购物车事件

4.1 `carts/create` — 加入购物车

{
  "endpoint": "carts/create",
  "source_id": "cart_001",
  "data": {
    "id": "cart_001",                          // 购物车 ID
    "token": "cart_token_001",                 // 购物车 Token，核心标识，关联弃单
    "email": "[email protected]",               // 邮箱，弃单触发的关键字段
    "phone": "+1234567890",                    // 手机号
    "first_name": "John",                      // 名
    "last_name": "Doe",                        // 姓
    "country_code": "US",                      // 国家
    "customer_id": "user_001",                 // 关联客户 ID
    "checkout_url": "https://shop.com/cart/checkout",  // 结账页面链接
    "line_items": [                            // 商品列表
      {
        "id": "ci_001",                        //   行 ID
        "product_id": "prod_001",              //   ✅ 必填，商品 SPU ID
        "variant_id": "sku_001",               //   ✅ 必填，SKU ID
        "sku": "IP-RED-M",                     //   SKU 编码
        "title": "iPhone 手机壳",              //   商品标题
        "quantity": 2,                         //   数量
        "price": "29.99",                      //   单价
        "line_price": "59.98",                 //   行总价
        "product_image_url": "https://example.com/img.jpg",  // 商品图片
        "product_url": "https://example.com/product"          // 商品链接
      }
    ],
    "ignore_flow": "N"
  }
}

购物车写入后系统会在 1 小时后检查，若仍未结账则自动触发对应的弃单挽回流程。

4.2 `carts/update` 和 `carts`

同上，均触发弃单挽回。

五、结账事件

5.1 `checkouts/create` — 进入结账｜自动删除对应购物车

{
  "endpoint": "checkouts/create",
  "source_id": "chk_001",
  "data": {
    "token": "checkout_token_001",             // 结账 Token，核心标识
    "cart_token": "cart_token_001",            // 购物车 Token，用于清理购物车
    "email": "[email protected]",               // 邮箱
    "phone": "+1234567890",                    // 手机号
    "customer_id": "user_001",                 // 客户 ID
    "country_code": "US",                      // 国家
    "currency": "USD",                         // 货币
    "total_price": "99.99",                    // 总金额
    "subtotal_price": "89.99",                 // 小计
    "total_discount": "10.00",                 // 折扣
    "total_shipping": "5.00",                  // 运费
    "total_tax": "5.00",                       // 税费
    "abandoned_checkout_url": "https://shop.com/checkout/recover",  // 弃单恢复链接
    "created_at": 1680170229,                  // 创建时间，Unix 秒级时间戳
    "shipping_address": {                      // 收货地址
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "US",
      "city": "Los Angeles",
      "address1": "123 Main St"
    },
    "line_items": [                            // 商品列表（同购物车 line_items）
      {
        "id": "ci_001",
        "product_id": "prod_001",
        "variant_id": "sku_001",
        "sku": "IP-RED-M",
        "title": "iPhone 手机壳",
        "quantity": 2,
        "price": "29.99",
        "line_price": "59.98",
        "product_image_url": "https://example.com/img.jpg",
        "product_url": "https://example.com/product"
      }
    ],
    "ignore_flow": "N"
  }
}

用户进入结账时，系统自动删除对应的购物车记录。

六、浏览事件

6.1 `page/viewed` — 浏览商品

{
  "endpoint": "page/viewed",
  "source_id": "pv_001",
  "data": {
    "email": "[email protected]",               // 用户邮箱
    "product_id": "prod_001",                  // 商品 SPU ID
    "url": "https://shop.com/products/iphone-case",  // 浏览页面 URL
    "timestamp": 1680170229                    // 浏览时间，Unix 秒级时间戳
  }
}

七、补货通知

7.1 `products/back_in_stock` — 用户订阅补货通知

{
  "endpoint": "products/back_in_stock",
  "source_id": "bis_001",
  "data": {
    "email": "[email protected]",               // 订阅用户邮箱
    "product_id": "prod_001",                  // 商品 SPU ID
    "variant_id": "sku_001"                    // SKU ID（可选）
  }
}

7.2 `products/restock` — 商品补货触发通知

{
  "endpoint": "products/restock",
  "source_id": "restock_001",
  "data": {
    "product_id": "prod_001",                  // 到货商品 SPU ID
    "variant_id": "sku_001"                    // 到货 SKU ID（可选）
  }
}

使用流程： 用户订阅 back_in_stock → 商品到货后调用 restock → 系统自动给所有订阅者推送通知。

八、自定义通知

8.1 `flow/notify` — 定向触发指定自动化

注意： 此接口是定向触发，不是通用事件广播。必须指定一个已在后台创建并启用、且触发器类型为"自定义通知"的自动化。

{
  "endpoint": "flow/notify",
  "source_id": "fn_001",
  "data": {
    "flow_id": "1234567890",                   // ✅ 必填，要触发 Flow 的 ID（在后台 Flow 列表中可查）
    "email": "[email protected]",               // 用户邮箱
    "phone": "+1234567890",                    // 手机号
    "country_code": "US",                      // 国家
    "first_name": "John",                      // 名
    "last_name": "Doe",                        // 姓
    "ignore_flow": "N",                        // Y=跳过
    "custom": {                                // 自定义业务数据（可选，在 Flow 条件中匹配使用）
      "event_type": "member_upgrade",
      "member_level": "gold",
      "points": 1000
    }
  }
}

工作原理：

系统根据 flow_id + 当前店铺 + status=enabled + triggerKey=FLOW_NOTIFY 精确查找目标 Flow
找到则执行该 Flow，用户信息（email/phone 等）和自定义数据（custom）传入 Flow 上下文
未找到则静默跳过，不会报错

使用前提： 需先在后台创建一条 Flow，触发器选择「自定义通知」，发布启用后拿到 Flow ID，再通过此接口定向触发。

附录 A：返回状态码汇总

code	含义
200	成功，事件已入队列，异步处理
304	source_id 重复，本次请求被忽略
412	参数校验失败，message 中有具体错误描述

附录 B：ignore_flow 说明

所有事件类型的 data 内都支持 ignore_flow 参数：

ignore_flow 值	行为
不传（默认 `"N"`）	✅ 正常触发自动化 Flow
`"Y"`	❌ 跳过，不触发任何自动化

附录 C：与批量导入的关系

	Events API (`/api/v1/events`)	Batch API (`/api/v1/batch`)
用途	实时事件推送 + 触发自动化	大批量历史数据导入
触发 Flow	✅ 支持	❌ 仅写库
限流	每秒 40 次	约每 10 秒 1 次
推荐场景	实时业务事件	初次全量迁移

附录 D：地址子模型（AddressModel）

字段	JSON key	类型	说明
first_name	`first_name`	String	名
last_name	`last_name`	String	姓
phone	`phone`	String	电话
country_code	`country_code`	String	国家代码
country_name	`country_name`	String	国家名称
province	`province`	String	省份
province_code	`province_code`	String	省份代码
city	`city`	String	城市
zip	`zip`	String	邮编
address1	`address1`	String	地址行1
address2	`address2`	String	地址行2

附录 E：订阅意愿子模型（MarketingConsent）

字段	JSON key	类型	说明
state	`state`	String	subscribed / not_subscribed / unsubscribed
updatedAt	`updatedAt`	Long	订阅时间，Unix 秒级时间戳

附录 F：自动化 Flow 触发规则

Events API 的各类事件与自动化 Flow 的触发关系如下：

事件 endpoint	触发 Flow？	说明
`customers/create`	✅	创建新客户时触发，匹配触发器类型「客户创建」的已启用 Flow
`customers/update`	❌	仅更新客户数据，不触发
`customers`	✅	自动判断新建/更新，新建时触发（同 `customers/create`）
`orders/create`	❌	仅入库，不触发
`orders/paid`	✅	订单支付后触发，匹配「订单支付」Flow
`orders/fulfilled`	✅	订单发货后触发，匹配「订单发货」Flow
`orders/update`	✅	订单状态变化时触发，匹配「订单状态变更」Flow
`orders/cancelled`	❌	—
`orders/refunded`	✅	触发「订单退款」Flow
`products/create`	❌	—
`products/update`	❌	—
`carts/create`	✅	购物车创建 1 小时后仍未结账时触发，匹配「弃单挽回」Flow
`carts/update`	✅	同上
`checkouts/create`	✅	进入结账时触发，匹配「结账挽回」Flow，同时自动删除对应购物车
`checkouts/update`	❌	—
`page/viewed`	❌	仅记录浏览历史，供 Flow 条件匹配使用，不直接触发
`products/back_in_stock`	❌	仅记录用户订阅意愿
`products/restock`	✅	触发补货通知，向订阅用户推送消息
`flow/notify`	✅	定向触发指定 Flow（需传 `flow_id`，Flows 触发器须为「自定义通知」）

通用规则： 所有事件均可通过 "ignore_flow": "Y" 跳过 Flow 触发。批量导入接口（/api/v1/batch）不走 Events API，不会触发任何 Flow。

Events API 接口文档

通用说明

一、客户事件

1.1 customers/create — 创建客户

1.2 customers/update — 更新客户

1.3 customers — 创建或更新（自动判断）

二、订单事件

2.1 orders/create — 创建订单

2.2 orders/paid — 订单支付

2.3 orders/fulfilled — 订单发货

2.4 orders/update — 更新订单｜状态变为 paid 时自动清理购物车

2.5 orders/cancelled — 订单取消

2.6 orders/refunded — 订单退款