70 lines
4.6 KiB
Markdown
70 lines
4.6 KiB
Markdown
# 查询客户详细信息 (youzan.scrm.customer.detail.get.1.0.1)
|
||
|
||
## 1. 接口基本信息
|
||
|
||
* **API 名称**：查询客户详细信息
|
||
* **API 接口名**：`youzan.scrm.customer.detail.get`
|
||
* **版本号**：`1.0.1`
|
||
* **接口描述**：用于精确查询单个客户在店铺/网点内的详细视图数据。通过指定查询模块，可以一次性获取客户的基础资料、标签、积分、会员等级、储值、权益卡以及自定义属性等全方位数据。
|
||
|
||
---
|
||
|
||
## 2. 请求说明
|
||
|
||
* **请求协议**：HTTPS
|
||
* **请求方式**：**POST** (严格要求，推荐 `application/json` 格式)
|
||
* **请求地址**：
|
||
|
||
```http
|
||
https://open.youzanyun.com/api/youzan.scrm.customer.detail.get/1.0.1
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 请求参数
|
||
|
||
在请求的 Body 中传入以下 JSON 数据参数：
|
||
|
||
| 参数名称 | 类型 | 是否必填 | 示例值 | 参数说明 |
|
||
| :--- | :--- | :---: | :--- | :--- |
|
||
| `access_token` | String | **是** | `9b510e232...` | 有赞云 API 鉴权凭证 |
|
||
| `yz_open_id` | String | 否 | `hijaMaXo65...` | 客户在有赞体系内的唯一身份标识。**（推荐使用，与 `account_info` 至少二选一）** |
|
||
| `account_info` | Object | 否 | - | 账户信息对象（如果不传 `yz_open_id`，可通过此字段检索如手机号匹配的客户） |
|
||
| `└─ account_id` | String | 否 | `13800138000` | 账号标识，如具体的手机号码 |
|
||
| `└─ account_type`| Integer| 否 | `2` | 账号类型，`2` 代表国内手机号 |
|
||
| `fields` | String | 否 | `user_base,credit` | **指定需要返回的客户信息模块**，多个用英文逗号分隔。<br>支持：`user_base`(基础资料), `tags`(标签), `benefit_cards`(权益卡), `benefit_level`(会员等级), `benefit_rights`(权益), `credit`(积分), `behavior`(行为数据), `giftcard`(礼品卡), `prepaid`(储值), `coupon`(优惠券), `level`(成长值/等级), `auth_info`(授权信息), `customer_attrInfos`(自定义属性) |
|
||
| `is_do_ext_point`| Boolean| 否 | `false` | 是否触发外部积分扩展点查询校验，默认为 `false` |
|
||
|
||
---
|
||
|
||
## 4. 响应参数
|
||
|
||
响应主体包裹在 `data` 中。因为该接口是**按需返回**的（基于 `fields` 传入的模块名），以下整理全量核心业务模块的响应结构：
|
||
|
||
| 根级参数名称 | 类型 | 描述说明 |
|
||
| :--- | :--- | :--- |
|
||
| `success` | Boolean | 请求是否成功 (`true`/`false`) |
|
||
| `code` | Integer | 状态码，`200` 表示成功 |
|
||
| `message` | String | 成功或错误提示信息 |
|
||
| `data` | Object | **客户详情数据总包**（内含根据 fields 指定返回的各个业务模块数据） |
|
||
|
||
### 4.1 `data` 内部核心业务模块解构
|
||
|
||
| 内部模块结构 / 数组 | 核心包含内容与说明 |
|
||
| :--- | :--- |
|
||
| **`user_base`**<br>*(基础资料)* | 客户的核心基础信息。<br>`yz_open_id`(有赞唯一标识); `name`(客户姓名/昵称); `gender`(性别:0未知,1男,2女); `birthday`(生日); `mobile` / `phone`(手机号，通常含脱敏星号); `remark`(商家后台备注); `created_at`(成为本店客户的时间); `ascription_kdt_id`(归属店铺/网点ID) |
|
||
| **`tags`** (Array)<br>*(标签信息)* | 客户被打上的标签列表。<br>`tag_id`(标签ID); `tag_name`(标签名称) |
|
||
| **`level_infos`** (Array)<br>*(等级信息)* | 从 `level` 或 `benefit_level` 调取出的客户当前等级情况。<br>`level_alias`(等级名称，如白银会员); `level_type`(等级类型：免费/付费等) |
|
||
| **`cards`** (Array)<br>*(权益卡/礼品卡)*| 返回客户名下持有的卡信息。<br>`card_alias_no`(卡号); `card_type`(卡类型); `name`(卡名称) |
|
||
| **`rights`** (Array)<br>*(会员权益)* | 包含客户享有的具体权益ID、权益名称（如包邮、专享折扣等细则项） |
|
||
| **`credit`**<br>*(积分信息)* | `current_credit`(客户当前可用积分余额); `total_credit`(历史累计总积分) |
|
||
| **`behavior`**<br>*(行为/交易数据)*| `trade_count`(客户本店累计交易笔数); `trade_amount`(累计交易总金额); `last_trade_time`(最近一次交易时间) |
|
||
| **`customer_attrInfos`** (Array)<br>*(自定义属性)* | 商家在后台为客户模板设置的自定义扩展项。<br>`attr_id`(属性项ID); `attr_name`(属性项名称); `attr_value`(属性值) |
|
||
|
||
---
|
||
|
||
## 5. ⚠️ 开发者防坑指南与注意事项
|
||
|
||
1. **请求方式的陷阱（必需 POST）**：
|
||
虽然 API 接口命名是以 `.get` 结尾（`youzan.scrm.customer.detail.get`），但是该接口**严格要求使用 HTTP POST** 并在 Body 中传递 JSON。如果错误地使用了 GET 方法且在 URL 后拼接参数，接口会报错 `invalid params` 或导致返回的数组模块全部为空（如 `"tags":
|