第三方店铺同步接口文档

版本：V1.0
更新日期：2026-07-11
说明：第三方（如省药监平台）将药店入驻信息同步到我方系统，自动创建/更新用户及入驻记录

1. 概述

本接口用于第三方系统向我方同步药店入驻信息。按手机号自动匹配用户，用户不存在则自动创建，并同步入驻信息到 t_business_license。

项目	说明
接口名称	第三方店铺信息同步
请求方式	`POST`
接口路径	`/api/sync_shop_resource/report_user`
鉴权	无鉴权（白名单路径，对第三方开放）
Content-Type	`application/json`

2. 请求参数

所有参数通过 JSON Body 传递，字段名使用 snake_case 格式。

2.1 必填字段

参数名	类型	必填	说明
`phone`	String	是	手机号码（用于识别客户唯一身份）

2.2 用户/药店信息字段（全部可选）

参数名	类型	必填	说明	映射我方字段
`contact_name`	String	否	联系人名称	`nickname`, `contact_person`
`contact_phone`	String	否	联系电话	`contact_phone`
`contact_shop`	String	否	店铺名称	`pharmacy_name`, `store_name`
`contact_province`	String	否	省份	`province`
`contact_city`	String	否	城市	`city`
`contact_area`	String	否	地区	`district`
`contact_addr`	String	否	详细地址	`pharmacy_address`, `store_address`

2.3 店铺类型

参数名	类型	必填	说明	映射值
`shop_type`	String	否	店铺类型	`1`→SINGLE 单店 / `2`→CHAIN 连锁 / `3`→CLINIC 诊所、社康

2.4 证照图片字段（全部可选）

参数名	类型	必填	说明	映射我方字段
`business_license_image`	String	否	营业执照图片URL	`license_image_url`
`drug_business_license_image`	String	否	药品经营许可证图片URL	`drug_license_url`
`two_medical_device_registration`	String	否	二类医疗器械备案图片URL	`medical_device_class2_url`
`three_medical_device_business_license`	String	否	三类医疗器械经营许可图片URL	`medical_device_class3_url`

2.5 审核与操作字段

参数名	类型	必填	说明
`status`	String	否	审核状态：`0`=审核中 / `1`=审核成功 / `2`=审核失败（不传默认`0`）
`remarks`	String	否	备注信息（如拒绝原因等）
`operator_userid`	String	否	操作人用户ID（默认`0`）
`user_type`	String	否	用户类型：`1`=客户端用户 / `2`=后台用户
`app_id`	String	否	小程序APPID

3. 请求示例

{
  "phone": "13800138000",
  "contact_name": "张老三",
  "contact_shop": "好店铺",
  "shop_type": "1",
  "contact_province": "广东省",
  "contact_city": "深圳市",
  "contact_area": "龙华新区",
  "contact_addr": "上芬街道",
  "contact_phone": "18219207546",
  "business_license_image": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "drug_business_license_image": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "two_medical_device_registration": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "three_medical_device_business_license": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "status": "0",
  "remarks": "资料不全，缺少药品经营许可证",
  "operator_userid": "0",
  "user_type": "1",
  "app_id": "wx246605ec671bf08d"
}

4. 响应

4.1 通用响应格式

{
  "code": "success",
  "msg": "同步成功",
  "data": {
    "user_id": "1234567890123456789",
    "new_user": false
  }
}

4.2 响应字段

字段	类型	说明
`code`	String	`"success"` 成功 / `"error"` 失败
`msg`	String	提示信息
`data.user_id`	String	我方系统中的用户ID
`data.new_user`	Boolean	是否为新创建的用户

4.3 错误响应

{
  "code": "error",
  "msg": "手机号不能为空"
}

5. 业务逻辑

5.1 用户处理

场景	行为
手机号不存在	自动创建新用户（PLUS 会员），昵称用 contactName
手机号已存在	更新非空的用户信息字段

5.2 入驻信息处理

💡 核心原则：以第三方传入的最新数据为准，非空字段直接覆盖本地记录。

场景	行为
无入驻记录	创建新记录，写入全部证照和店铺信息
已有入驻记录（非 APPROVED）	以第三方传入字段覆盖本地，同时更新审核状态
已有入驻记录（已 APPROVED）	以第三方传入字段覆盖本地，重置为 PENDING 待重新审核；奖励标记保留，不重复发放

5.3 审核状态

status 值	我方状态	说明
`0` 或不传	`PENDING`	待运营审核
`1`	`APPROVED`	审核通过，首次通过赠送 30 天 PRO 高级会员
`2`	`REJECTED`	审核失败

💡 已 APPROVED 的记录再次同步时，更新入驻字段并重置为 PENDING 待重新审核；奖励仅首次发放，不会重复。

5.4 shopType 映射

第三方值	我方 terminalType
`"1"`	`SINGLE`（单店）
`"2"`	`CHAIN`（连锁）
`"3"`	`CLINIC`（诊所、社康）
其他	原值透传

6. 字段映射表

6.1 用户信息（t_users）

第三方字段	我方字段	说明
`phone`	`phone`	手机号（唯一标识）
`contact_name`	`nickname`	用户昵称
`contact_shop`	`pharmacy_name`	药店名称
`contact_province`	`province`	省
`contact_city`	`city`	市
`contact_area`	`district`	区
`contact_addr`	`pharmacy_address`	详细地址
`contact_phone`	`contact_phone`	联系电话

6.2 入驻信息（t_business_license）

第三方字段	我方字段	说明
`contact_shop`	`store_name`	店铺名称
`shop_type`	`terminal_type`	终端类型（`1`→SINGLE / `2`→CHAIN / `3`→CLINIC）
`contact_province`	`province`	省
`contact_city`	`city`	市
`contact_area`	`district`	区
`contact_addr`	`store_address`	详细地址
`contact_name`	`contact_person`	联系人
`contact_phone`	`contact_phone`	联系电话
`business_license_image`	`license_image_url`	营业执照图片URL
`drug_business_license_image`	`drug_license_url`	药品经营许可证图片URL
`two_medical_device_registration`	`medical_device_class2_url`	二类医疗器械备案图片URL
`three_medical_device_business_license`	`medical_device_class3_url`	三类医疗器械备案图片URL
`status`	`review_status`	审核状态（`0`→PENDING / `1`→APPROVED / `2`→REJECTED）
`remarks`	`remark`	备注（如拒绝原因等）

💡 入驻记录保存时，自动补充以下字段：

sync_source ← 固定为 MINIAPP_SYNC

show_verified_badge ← 首次审核通过时设为 true

credit_code ← 本次不自动填入（第三方可通过 /external/sync 接口传入 businessLicenseNo 补充）

7. 注意事项

#	说明
1	本接口无鉴权，直接对第三方开放，路径已加入白名单
2	请求参数通过 JSON Body 传递，字段名使用 snake_case 格式
3	手机号未注册时自动创建用户，初始化 PLUS 会员
4	不返回 Token，仅返回同步确认（user_id + new_user）
5	如需返回 Token，请调用登录接口 `/api/auth/external/miniapp-token`
6	建议第三方在店铺信息变更时主动调用本接口更新
7	状态字段为字符串类型（`"0"`/`"1"`/`"2"`），内部自动转为 Integer

8. 变更记录

版本	日期	变更内容
V1.1	2026-07-15	新增 `remarks` 字段，支持双向传递拒绝原因等备注信息
V1.0	2026-07-11	初始版本，支持第三方通过 Query 参数同步店铺信息

第三方店铺同步接口文档.md 8.6 KB Permalink History Raw

第三方店铺同步接口文档

1. 概述

2. 请求参数

2.1 必填字段

2.2 用户/药店信息字段（全部可选）

2.3 店铺类型

2.4 证照图片字段（全部可选）

2.5 审核与操作字段

3. 请求示例

4. 响应

4.1 通用响应格式

4.2 响应字段

4.3 错误响应

5. 业务逻辑

5.1 用户处理

5.2 入驻信息处理

5.3 审核状态

5.4 shopType 映射

6. 字段映射表

6.1 用户信息（t_users）

6.2 入驻信息（t_business_license）

7. 注意事项

8. 变更记录

第三方店铺同步接口文档.md 8.6 KB

Permalink History Raw