店铺管理 API
1. 接口概述
店铺管理 API 提供了店铺信息的查询和添加功能。通过这些接口，您可以获取系统中的店铺信息列表，也可以向系统中添加新的店铺信息。
2. 接口列表
| 接口名 | 方法 | 功能描述 |
|---|---|---|
shop.getList | POST | 批量获取店铺信息列表 |
shop.get | POST | 获取单个店铺详细信息 |
3. 系统级参数
系统级参数是调用所有接口都必须提供的参数：
| 参数名 | 类型 | 必填 | 名称 | 描述 |
|---|---|---|---|---|
flag | string | 是 | 应用标识 | 用于标识调用方身份 |
method | string | 是 | 接口方法名 | 例如：shop.getList |
ver | number | 是 | 版本号 | 固定为1 |
charset | string | 是 | 字符集 | 固定为utf-8 |
type | string | 是 | 返回格式 | 固定为json |
timestamp | string | 是 | 时间戳 | 格式：yyyyMMddHHmmss |
sign | string | 是 | 签名 | 用于验证请求的合法性 |
4. 接口详细说明
4.1 批量获取店铺信息列表
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
shop_bn | string | 否 | 店铺编号，多个用逗号分隔 |
shop_name | string | 否 | 店铺名称，支持模糊搜索 |
page_no | int | 是 | 页码，默认 1 |
page_size | int | 是 | 每页条数，默认 50，最大 1000 |
响应参数
| 参数名 | 类型 | 描述 |
|---|---|---|
count | int | 总记录数 |
lists | array | 店铺信息列表 |
lists 数组中的每个对象包含以下字段：
| 参数名 | 类型 | 描述 |
|---|---|---|
shop_bn | string | 店铺编号 |
shop_name | string | 店铺名称 |
company_name | string | 公司名称 |
contact_name | string | 联系人 |
contact_tel | string | 联系电话 |
status | string | 状态：online-在线, offline-离线 |
createtime | string | 创建时间 |
updatetime | string | 更新时间 |
请求示例
请参考openapi.md文档中【6. 接口调用示例】。
响应示例
json
{
"count": 10,
"lists": [
{
"shop_bn": "SHOP001",
"shop_name": "测试店铺",
"company_name": "测试公司",
"contact_name": "张三",
"contact_tel": "13800138000",
"status": "online",
"createtime": "2024-01-01 10:00:00",
"updatetime": "2024-01-01 10:00:00"
}
]
}4.2 获取单个店铺详细信息
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
shop_bn | string | 是 | 店铺编号 |
响应参数
| 参数名 | 类型 | 描述 |
|---|---|---|
shop_bn | string | 店铺编号 |
shop_name | string | 店铺名称 |
company_name | string | 公司名称 |
contact_name | string | 联系人 |
contact_tel | string | 联系电话 |
contact_email | string | 联系邮箱 |
address | string | 地址 |
status | string | 状态：online-在线, offline-离线 |
createtime | string | 创建时间 |
updatetime | string | 更新时间 |
请求示例
请参考openapi.md文档中【6. 接口调用示例】。
响应示例
json
{
"shop_bn": "SHOP001",
"shop_name": "测试店铺",
"company_name": "测试公司",
"contact_name": "张三",
"contact_tel": "13800138000",
"contact_email": "test@example.com",
"address": "北京市朝阳区测试路1号",
"status": "online",
"createtime": "2024-01-01 10:00:00",
"updatetime": "2024-01-01 10:00:00"
}5. 错误码说明
| 错误码 | 错误信息 | 解决方案 |
|---|---|---|
| 0 | 成功 | - |
| 1 | 参数错误 | 检查参数格式是否正确，所有必填参数是否都已提供 |
| 400 | 参数错误 | 检查参数格式是否正确，所有必填参数是否都已提供 |
| 401 | 未授权访问 | 检查flag和sign是否正确 |
| 403 | 禁止访问 | 联系管理员获取权限 |
| 404 | 店铺不存在 | 检查店铺编号是否正确 |
| 500 | 服务器内部错误 | 检查请求参数或联系技术支持 |
| 1001 | 非法的flag | 请检查flag是否正确 |
| 1002 | 请求已过期 | 请检查timestamp是否正确，请求有效期为5分钟 |
| 1003 | 签名错误 | 请检查签名算法和参数是否正确 |
| 1004 | 不支持的type格式 | 请使用json格式 |
| 2001 | 缺少必要的参数 | 请检查请求参数是否完整 |
| 2002 | 非法的请求参数 | 请检查参数格式和范围是否正确 |
| 2003 | 接口不存在 | 请检查接口方法名是否正确 |
6. 注意事项
page_size参数最大支持 1000，默认50，超过100将被限制为 100。- 对于大数据量的查询，建议使用店铺编号进行精确筛选，以提高查询效率。
- 时间戳必须与服务器时间保持同步，误差不超过3600秒。
- 每个请求必须生成唯一的签名，避免重复提交。
- 请妥善保管接口密钥，避免泄露。
- 所有请求参数中的特殊字符必须进行 URL 编码，特别是在使用 GET 方法时。
- 请确保在请求头中设置正确的 Content-Type，对于 POST 请求建议使用 application/json。
- 为了系统性能和稳定性，请避免短时间内发送大量请求，建议控制调用频率。
- 敏感数据（如签名、密钥等）请勿在日志中记录，确保数据安全。