API Reference
  1. 正式环境API

平台店铺API能力

平台店铺API能力

Headless 模式 API 文档

为使用自定义前端（React/Vue/Next.js 等）的平台商户提供统一事件上报 API

📋 基础信息

什么是 Headless 模式？

当您将店铺前端改造为自定义 React/Vue 等框架时，Headless 模式 API 允许您通过服务端或客户端直接调用接口，将用户行为事件上报到 MambaSMS 系统，确保以下自动化流程正常触发：

  • 浏览挽回（用户浏览商品后离开）
  • 购物车挽回（用户加购后未结账）
  • 订阅欢迎（用户通过自己弹窗等操作订阅 Email/手机号）

统一接口

所有事件通过同一个接口提交，通过 endpoint 字段区分事件类型：

POST /api/v1/headless/events

🔑 认证方式

API 服务地址

  • 生产环境： https://front-api.mambasms.com
  • 测试环境： https://olapapi.mambasend.com

获取 API Token

  1. 登录 MambaSMS 后台
  2. 进入 商店设置 → 查看密钥
  3. 复制 密钥（格式：shop_xxxxxxxx）

请求头

Content-Type: application/json
X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

📡 统一事件 API

接口地址

POST /api/v1/headless/events

支持的事件类型

事件类型endpoint 值说明触发自动化
浏览商品page/viewed用户访问商品详情页✅ 浏览挽回
加入购物车carts/create用户点击加入购物车✅ 购物车挽回
更新购物车carts/update用户修改购物车✅ 购物车挽回
用户订阅customers/create收集用户 Email/手机号（表单可用）✅ 订阅欢迎自动化

通用请求格式

{
  "endpoint": "事件类型",
  "source_id": "唯一标识符（用于去重，最大50字符）",
  "data": {
    // 事件具体数据
  }
}

通用响应格式

成功：

{
  "success": true
}

重复提交：

{
  "success": false,
  "code": 304,
  "message": "SourceId already exist"
}

📝 事件详细说明

1. 浏览商品事件

endpoint: page/viewed

触发"浏览挽回"自动化流程，需要用户已登录（有 customerId）才能触发。

使用场景：

场景1：未登录用户浏览商品

  • 只记录浏览行为，不触发自动化
  • 用于统计商品热度和页面访问量
  • customerId 留空或不传
{
  "endpoint": "page/viewed",
  "source_id": "view_guest_1774520000",
  "data": {
    "requestId": "req_view_001",
    "type": "page",
    "includeProduct": 1,
    "page": {
      "url": "https://pitaka.com/products/magsafe-case",
      "title": "MagSafe 手机壳",
      "productId": "product_123456"
    }
    // 未登录，不传 customerId
  }
}

场景2：已登录用户浏览商品（触发自动化）

  • 记录浏览行为 + 触发浏览挽回自动化
  • 用户离开后可以发送提醒邮件/短信
  • 必须传入 customerId
{
  "endpoint": "page/viewed",
  "source_id": "view_user_1774520000",
  "data": {
    "requestId": "req_view_002",
    "type": "page",
    "includeProduct": 1,
    "page": {
      "url": "https://pitaka.com/products/magsafe-case",
      "title": "MagSafe 手机壳",
      "productId": "product_123456"
    },
    "customerId": "customer_origin_id_789"  // 已登录用户
  }
}

场景3：用户浏览多个商品

  • 记录用户兴趣偏好
  • 用于个性化推荐
  • 每个商品浏览都需要单独上报
// 浏览第一个商品
{
  "endpoint": "page/viewed",
  "source_id": "view_product1_1774520000",
  "data": {
    "requestId": "req_view_003",
    "type": "page",
    "includeProduct": 1,
    "page": {
      "url": "https://pitaka.com/products/magsafe-case",
      "title": "MagSafe 手机壳",
      "productId": "product_123456"
    },
    "customerId": "customer_origin_id_789"
  }
}

// 浏览第二个商品
{
  "endpoint": "page/viewed",
  "source_id": "view_product2_1774520100",
  "data": {
    "requestId": "req_view_004",
    "type": "page",
    "includeProduct": 1,
    "page": {
      "url": "https://pitaka.com/products/magsafe-charger",
      "title": "MagSafe 充电器",
      "productId": "product_789012"
    },
    "customerId": "customer_origin_id_789"
  }
}

场景4：浏览非商品页面

  • 记录普通页面访问（如首页、分类页）
  • 不触发自动化
  • includeProduct 设为 0
{
  "endpoint": "page/viewed",
  "source_id": "view_homepage_1774520000",
  "data": {
    "requestId": "req_view_005",
    "type": "page",
    "includeProduct": 0,  // 非商品页面
    "page": {
      "url": "https://pitaka.com/",
      "title": "PITAKA 官网首页"
    },
    "customerId": "customer_origin_id_789"
  }
}

请求参数：

字段类型必填说明
endpointString✅固定值：page/viewed
source_idString✅唯一标识符（最大50字符）
data.requestIdString✅本次请求唯一ID，用于去重
data.typeString✅固定值：page
data.includeProductInteger✅是否包含商品：1 是，0 否
data.page.urlString✅商品页面完整URL
data.page.titleString✅商品标题
data.page.productIdString✅商品ID（触发浏览挽回必填）
data.customerIdString⚠️用户在平台的 origin_id（已登录时必填，触发自动化必须）

请求示例：

{
  "endpoint": "page/viewed",
  "source_id": "view_magsafe_1774513800",
  "data": {
    "requestId": "req_view_magsafe_001",
    "type": "page",
    "includeProduct": 1,
    "page": {
      "url": "https://pitaka.com/products/magsafe-case",
      "title": "MagSafe 手机壳",
      "productId": "product_123456"
    },
    "customerId": "customer_origin_id_789"
  }
}

2. 加入购物车事件

endpoint: carts/create

触发"购物车挽回"自动化流程。

请求参数：

字段类型必填说明
endpointString✅固定值：carts/create
source_idString✅唯一标识符（最大50字符）
data.tokenString✅购物车唯一 Token
data.checkout_urlString✅结账页面URL
data.timestampLong✅Unix时间戳（秒）
data.line_itemsArray✅购物车商品列表
data.line_items[].titleString✅商品标题
data.line_items[].quantityInteger✅商品数量
data.line_items[].priceString✅商品单价
data.line_items[].product_idString✅商品ID
data.customer_idString⚠️用户在平台的 origin_id（已登录时必填）

请求示例：

{
  "endpoint": "carts/create",
  "source_id": "cart_abc123_1774513800",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774513800,
    "customer_id": "customer_origin_id_789",
    "line_items": [
      {
        "title": "MagSafe 手机壳",
        "quantity": 1,
        "price": "49.99",
        "product_id": "product_123456",
        "sku": "PITAKA-CASE-001"
      }
    ]
  }
}

3. 更新购物车事件

endpoint: carts/update

更新购物车内容，触发"购物车挽回"自动化流程。

⚠️ 重要说明：全量覆盖机制

carts/update 采用全量覆盖方式，而非增量更新：

  1. 系统会先删除该购物车的所有商品
  2. 然后插入新传入的商品列表
  3. 客户端需要传递完整的购物车商品列表

请求参数：

字段类型必填说明
endpointString✅固定值：carts/update
source_idString✅唯一标识符（最大50字符）
data.tokenString✅购物车唯一 Token（与 create 时相同）
data.checkout_urlString✅结账页面URL
data.timestampLong✅Unix时间戳（秒）
data.line_itemsArray✅购物车商品列表（完整列表）
data.customer_idString⚠️用户在平台的 origin_id（已登录时必填）

使用场景示例：

场景1：修改商品数量

{
  "endpoint": "carts/update",
  "source_id": "cart_update_abc123_1774520000",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774520000,
    "customer_id": "customer_origin_id_789",
    "line_items": [
      {
        "title": "MagSafe 手机壳",
        "quantity": 3,  // 从 1 改为 3
        "price": "49.99",
        "product_id": "product_123456"
      }
    ]
  }
}

场景2：删除某个商品

{
  "endpoint": "carts/update",
  "source_id": "cart_update_abc123_1774520100",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774520100,
    "customer_id": "customer_origin_id_789",
    "line_items": [
      // 只保留剩余的商品，删除的商品不传
      {
        "title": "MagSafe 充电器",
        "quantity": 1,
        "price": "29.99",
        "product_id": "product_789012"
      }
    ]
  }
}

场景3：清空购物车

{
  "endpoint": "carts/update",
  "source_id": "cart_update_abc123_1774520200",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774520200,
    "customer_id": "customer_origin_id_789",
    "line_items": []  // 空数组表示清空购物车
  }
}

场景4：添加新商品

{
  "endpoint": "carts/update",
  "source_id": "cart_update_abc123_1774520300",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774520300,
    "customer_id": "customer_origin_id_789",
    "line_items": [
      // 必须包含原有商品
      {
        "title": "MagSafe 手机壳",
        "quantity": 1,
        "price": "49.99",
        "product_id": "product_123456"
      },
      // 新增的商品
      {
        "title": "MagSafe 充电器",
        "quantity": 1,
        "price": "29.99",
        "product_id": "product_789012"
      }
    ]
  }
}

购物车自动删除机制：

系统会在以下情况自动删除购物车：

  • 用户完成订单支付时
  • 用户进入结账页面（checkout）时

因此不需要单独的购物车删除接口。

4. 表单订阅事件

endpoint: customers/create

用于收集用户 Email 和/或手机号订阅，触发"订阅欢迎"自动化流程。

⚠️ 重要说明：

  • carts/update 采用全量覆盖方式更新
  • 系统会先删除购物车的所有商品，再插入新的商品列表
  • 客户端需要传递购物车的完整商品列表（不是增量更新）

使用场景：

场景处理方式
商品数量变化传递更新后数量的完整商品列表
删除某个商品传递剩余商品的列表（不包含被删除的商品）
清空购物车传递空数组 line_items: []
添加新商品传递包含新商品的完整列表

请求参数：与 carts/create 相同

请求示例：

// 场景1：用户删除了一个商品，只剩一个商品
{
  "endpoint": "carts/update",
  "source_id": "cart_abc123_update_1774513900",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774513900,
    "customer_id": "customer_origin_id_789",
    "line_items": [
      {
        "title": "MagSafe 手机壳",
        "quantity": 2,
        "price": "49.99",
        "product_id": "product_123456"
      }
    ]
  }
}

// 场景2：用户清空了购物车
{
  "endpoint": "carts/update",
  "source_id": "cart_abc123_clear_1774514000",
  "data": {
    "token": "cart_token_abc123",
    "checkout_url": "https://pitaka.com/checkout",
    "timestamp": 1774514000,
    "customer_id": "customer_origin_id_789",
    "line_items": []
  }
}

购物车自动删除：

购物车会在以下情况自动删除，无需客户端调用删除接口：

  • ✅ 用户完成支付（orders/paid 事件触发）
  • ✅ 用户进入结账页面（checkouts/create 事件触发）

3. 用户订阅事件

endpoint: customers/create

用于收集用户 Email 和/或手机号订阅，触发"订阅欢迎"自动化流程。

请求参数：

字段类型必填说明
endpointString✅固定值：customers/create
source_idString✅唯一标识符（最大50字符）
data.idString✅用户在原平台的唯一ID（如 Shopify customer_id），用于去重和关联，系统会自动生成内部主键
data.created_atLong✅创建时间（Unix时间戳，秒）
data.emailString⚠️邮箱地址（与 phone 至少填一个）
data.phoneString⚠️手机号含国际区号（与 email 至少填一个）
data.country_codeString否手机号国家编码（如 US、CN）
data.first_nameString否名
data.last_nameString否姓
data.email_marketing_consent.stateString否subscribed 表示邮件已订阅
data.sms_marketing_consent.stateString否subscribed 表示短信已订阅

请求示例：

{
  "endpoint": "customers/create",
  "source_id": "[email protected]_1774513800",
  "data": {
    "id": "shopify_customer_12345",
    "email": "[email protected]",
    "phone": "+1234567890",
    "country_code": "US",
    "first_name": "John",
    "last_name": "Doe",
    "created_at": 1774513800,
    "email_marketing_consent": {
      "state": "subscribed"
    },
    "sms_marketing_consent": {
      "state": "subscribed"
    }
  }
}

字段说明：

  • data.id：用户在原平台（如 Shopify）的 customer_id，用于去重和关联订单数据，系统会自动生成内部主键 ID
  • 如果同一个 id 重复提交，系统会执行更新操作而不是创建新用户

⚠️ 重要注意事项

1. source_id 去重机制

source_id 用于事件去重，相同的 source_id 只会被处理一次

2. 自动化触发条件

事件触发自动化的前提条件
浏览商品✅ 用户已登录（传入 customerId）
✅ includeProduct=1
✅ productId 在数据库中存在
✅ 商品有图片（image_url 不为空）
✅ requestId 不为空
加入购物车无特殊要求，有 customer_id 时可关联用户
表单订阅无特殊要求，自动触发订阅欢迎自动化

3. 错误码说明

错误码说明解决方案
200成功-
304source_id 已存在（重复提交）正常现象，无需处理
401Token 无效检查 X-Mamba-Access-Token
412校验失败检查参数格式
429请求过于频繁降低请求频率（限制每秒40次）

🚀 快速开始

1. 获取 API Token

登录后台 → 店铺设置 → API 密钥 → 复制 Security Key

2. 测试环境信息

  • 测试环境域名：https://olapapi.mambasend.com
  • 生产环境域名：https://front-api.mambasms.com

3. 完整测试流程

以下是一个完整的测试示例，演示如何触发三个自动化：

#!/bin/bash

BASE_URL="https://olapapi.mambasend.com"
TOKEN="your_shop_token_here"
TIMESTAMP=$(date +%s)
CUSTOMER_ID="test_user_${TIMESTAMP}"
EMAIL="test${TIMESTAMP}@example.com"

# 步骤1：创建用户（触发订阅欢迎自动化）
echo "1. 创建用户..."
curl -X POST "${BASE_URL}/api/v1/headless/events" \
  -H "Content-Type: application/json" \
  -H "X-Mamba-Access-Token: ${TOKEN}" \
  -d '{
    "endpoint": "customers/create",
    "source_id": "sub_'${TIMESTAMP}'",
    "data": {
      "id": "'${CUSTOMER_ID}'",
      "email": "'${EMAIL}'",
      "phone": "+1234567890",
      "country_code": "US",
      "first_name": "Test",
      "last_name": "User",
      "created_at": '${TIMESTAMP}',
      "email_marketing_consent": { "state": "subscribed" }
    }
  }'

sleep 3

# 步骤2：浏览商品（触发浏览商品挽回自动化）
# ⚠️ 注意：必须使用真实存在的商品ID
echo "2. 浏览商品..."
curl -X POST "${BASE_URL}/api/v1/headless/events" \
  -H "Content-Type: application/json" \
  -H "X-Mamba-Access-Token: ${TOKEN}" \
  -d '{
    "endpoint": "page/viewed",
    "source_id": "view_'${TIMESTAMP}'",
    "data": {
      "requestId": "req_view_'${TIMESTAMP}'",
      "type": "page",
      "includeProduct": 1,
      "page": {
        "url": "https://example.com/products/test-product",
        "title": "测试商品",
        "productId": "your_real_product_id"
      },
      "customerId": "'${CUSTOMER_ID}'",
      "currencySymbol": "$"
    }
  }'

sleep 2

# 步骤3：加入购物车（触发购物车挽回自动化）
echo "3. 加入购物车..."
curl -X POST "${BASE_URL}/api/v1/headless/events" \
  -H "Content-Type: application/json" \
  -H "X-Mamba-Access-Token: ${TOKEN}" \
  -d '{
    "endpoint": "carts/create",
    "source_id": "cart_'${TIMESTAMP}'",
    "data": {
      "token": "cart_token_'${TIMESTAMP}'",
      "checkout_url": "https://example.com/checkout",
      "timestamp": '${TIMESTAMP}',
      "customer_id": "'${CUSTOMER_ID}'",
      "email": "'${EMAIL}'",
      "line_items": [
        {
          "title": "测试商品",
          "quantity": 1,
          "price": "49.99",
          "product_id": "your_real_product_id"
        }
      ]
    }
  }'

echo "测试完成！"