客户 API

创建、查询、更新和删除店铺中的客户。

接口列表

GET

/customers

customers:read

获取分页客户列表。

GET

/customers/:id

customers:read

通过 ID 获取单个客户信息。

POST

/customers

customers:write

创建新客户。

PUT

/customers/:id

customers:write

更新现有客户信息。支持部分更新。

DELETE

/customers/:id

customers:write

软删除客户。记录可在 30 天内恢复。

字段参考

字段	类型	必填	描述
id	string	否	唯一客户标识符（只读）
name	string	是	客户姓名
email	string	是	客户电子邮箱
phone	string	否	含国家区号的电话号码
createdAt	datetime	否	ISO 8601 时间戳（只读）
updatedAt	datetime	否	ISO 8601 时间戳（只读）

查询参数（列表）

字段	类型	必填	描述
page	integer	否	页码（默认：1）
limit	integer	否	每页条数（默认：20，最大：100）
q	string	否	按客户姓名或邮箱搜索

示例

分页获取客户列表

bash

curl "https://api.mercozy.com/api/v1/external/customers?page=1&limit=20" \
  -H "X-API-Key: mk_live_xxxxx"

创建客户

bash

curl -X POST "https://api.mercozy.com/api/v1/external/customers" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

响应示例

json

{
  "data": {
    "id": "cust_abc123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "createdAt": "2025-12-15T10:30:00Z",
    "updatedAt": "2025-12-15T10:30:00Z"
  }
}