猫酷开放平台

# 接入指南

# 猫酷开放平台简介

猫酷开放平台开放了用户、会员、积分、票券、支付、商户、停车、团购、活动优惠等20大类共100余种底层能力供开发者使用，开发者可以利用这些底层能力和数据为实体商业快速开发各种定制化的应用，帮助实体商业开展数字化经营最佳实践。

# 相关地址

猫酷官网：https://mallcoo.cn (opens new window)
服务市场：https://plugin.mp.mallcoo.cn (opens new window)

# 开发者账号申请流程

WARNING

分配给开发者的私钥PrivateKey请妥善保管，仅限在服务器端代码中使用，严禁在任何客户端代码中暴露。

# 接口调用方式

# API协议规则

规则 说明
传输协议 HTTPS
提交方式 POST / GET
数据格式 JSON
字符编码 UTF-8 (UrlEncode)
签名要求 请求数据均需要校验签名
签名加密算法 MD5

说明

  1. API调用统一采用 HTTPS 协议进行安全的数据传输
  2. 请求与返回数据体采用 JSON 字符串形式传输，文本应采用 UTF-8 (UrlEncode) 编码，Content-Type为 application/json
  3. AppID、PublicKey、TimeStamp、Sign 等公共请求参数中放在HTTP的头部 Header 中，其余参数放在 Body 中

# 接口请求报文说明

对于每次的API请求，需要将公共参数部分写入HTTP请求报文的Headers中，将业务参数部分写入HTTP请求报文的Body中

TIP

理解HTTP协议 (opens new window)

# Headers

每次调用接口时，需要传入一些公共参数确认开发者身份鉴权，并对传入的参数进行签名校验以防止内容被恶意篡改。这些公共参数都应在调用时写入HTTP的头部 Headers 中

名称 数据类型 必填 说明
AppID string 是 应用ID（由猫酷统一分配）
PublicKey string 是 公钥（由猫酷统一分配）
TimeStamp string 是 当前时间戳（格式 yyyyMMddHHmmss ）
Sign string 是 签名字符串（必须为大写字符）

# Body

各业务参数Data以标准JSON字符串形式传入Body中
以“获取会员积分接口”为例:

{ 
	"Mobile": "15901996272",
	"VCode": "000217",
	"PageSize": 10,
	"PageIndex": 1,
}
1
2
3
4
5
6

# 接口调用返回报文说明

名称 数据类型 必填 说明
Code int 是 状态码
Data Json 是 返回数据
Message string 是 返回状态描述

仍然以“获取会员积分接口”为例:

{
	"Code": 1,
	"Data": {
		"CurScore": 12770.0,
		"ScoreDetailModel": [{
			"ScoreRecordID": "813316",
			"ScoreType": "积分抵线下消费",
			"Score": -10.0,
			"ScoreTime": "2019/07/11 17:00:53",
			"Desc": "积分抵线下消费"
		}]
	},
	"Message": "成功"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

其中：Code为返回状态码，Message为返回状态说明，Data为返回数据体

# 如何生成签名字符串Sign

为保证接口调用内容不被篡改，请按照以下方法生成签名字符串，并按要求在每次接口调用时放入Headers中。
签名字符串Sign生成步骤如下：

  1. 将publicKey、timeStamp、data、privateKey按顺序拼接成字符串JsonData。例：
{publicKey:aaa,timeStamp:bbb,data:{...},privateKey:ddd}
1
  1. 对JsonData进行MD5加密，得到32位的加密串encryptString
  2. 截取encryptString的第9至第24个字符（共16位），得到签名字符串Sign
# 签名字符串生成示例代码（C#）：
// 公钥
var publicKey = "your public key";
// 时间戳
var timeStamp = DateTime.Now.ToString("yyyyMMddHHmmss");
// 业务参数, 需要把Json对象转换为Json字符串
var jsonData = Newtonsoft.Json.JsonConvert.SerializeObject(data);
// 私钥
var privateKey = "your private key";
// 签名字符串
var sign = string.Empty;

// 待加密字符串（顺序必须一致，大小写必须相同）
var encryptString = "{publicKey:" + publicKey + 
                    ",timeStamp:" + timeStamp + 
                    ",data:" + jsonData + 
                    ",privateKey:" + privateKey + "}";

// 生成[签名字符串](使用MD516位加密)
sign = MD5EncryptTo16(encryptString);

/// <summary>  
/// MD5加密（16位）  
/// </summary>  
/// <param name="EncryptString">需要加密的字符串</param>  
/// <returns></returns>
public static string MD5EncryptTo16(string EncryptString)  
{  
  if (string.IsNullOrEmpty(EncryptString)) { 
    throw (new Exception("密文不得为空")); 
  }  
  string tt = FormsAuthentication.HashPasswordForStoringInConfigFile(
      EncryptString, 
      "MD5"
    );  
  if (tt == "" || tt.Length < 30)  
  {  
    return string.Empty;  
  }  
  else
  {  	
    //从第9个字符开始，连续取16个字符
    return tt.Substring(8, 16);  
  }  
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# 用户授权登录与用户身份获取

猫酷开放平台采用OAuth2.0标准向开发者提供用户统一授权登录，开发者在需要获取用户身份的场景下调用猫酷开放平台用户授权页面，用户在访问时会先进入此页面，若此时用户已处于登录态，则会跳转到回调地址所在页面并在地址后面加上Ticket 与 DataSource；若用户为非登录态，则会跳转至猫酷统一注册登录页，登录成功之后再跳转到回调地址所在页面并在地址后面加上Ticket 与 DataSource。通过返回的Ticket可以换取用户身份信息，通过DataSource可以获知当前用户的客户端环境（微信小程序/支付宝/微信公众号/浏览器/Native APP等）。

# 基本流程

sequenceDiagram participant User as 用户 participant Dev as 开发者应用 participant Mallcoo as 猫酷开放平台 User->>Dev: 访问需要用户授权的页面 Dev->>Mallcoo: 请求猫酷开放平台授权登录页面 Mallcoo-->>User: 请求用户操作 User->>Mallcoo: 用户确认操作 Mallcoo-->>Dev: 重定向回开发者应用，并返回Ticket、DataSource Dev->>Mallcoo: 根据Ticket，请求获取OpenUserID Mallcoo-->>Dev: 返回OpenUserID和用户基本信息

通过OAuth获取用户信息流程如上图所示，当用户访问应用时，若应用获取不到用户身份，需重定向到猫酷开放平台用户授权页面，由猫酷开放平台用户授权页面返回Ticket给开发者应用，开发者应用再根据Ticket获取OpenUserID和用户基本信息，并保持用户身份。目前Ticket的过期时间为5分钟，UserToken的有效期为30天，建议开发者缓存UserToken和Ticket，以避免过于频繁的访问开放平台。

# OAuth调用方法（分H5、小程序和小程序嵌H5三种，可任选其一）

# H5：

统一授权登录地址(注册/登录)： https://m.mallcoo.cn/a/open/User/V2/OAuth/BaseInfo/ (opens new window)
统一授权登录地址(注册/登录/开通会员卡)： https://m.mallcoo.cn/a/open/User/V2/OAuth/CardInfo/ (opens new window)
请求类型： GET
传参方式： URL传参

请求参数

名称 数据类型 必填 说明
AppID string 是 应用ID（由猫酷统一分配）
PublicKey string 是 公钥（由猫酷统一分配）
CallbackUrl string 是 回调地址（一定要进行URL编码）

返回参数

WARNING

返回结果需要先进行URL解码(URLDecode)

名称 数据类型 必填 说明
Ticket string 是 Ticket
DataSource int 是 环境类型：
1:安卓APP
2:猫酷苹果APP
3:浏览器
5:微信

# 小程序：

跳转小程序地址： /pages/oauth/oauth?OAppID={OAppID}&OPublicKey={OPublicKey}&OIsMember={OIsMember}
小程序APPID：由通过客服获取
跳转小程序的方法参考微信官方文档（wx.navigateToMiniProgram）
https://developers.weixin.qq.com/miniprogram/dev/api/open-api/miniprogram-navigate/wx.navigateToMiniProgram.html (opens new window)

请求参数

名称 数据类型 必填 说明
OAppID string 是 应用ID（由猫酷统一分配）
OPublicKey string 是 公钥（由猫酷统一分配）
OIsMember int 是 是否会员(1代表是会员，0代表不是会员)

获取返回值的方法（App.onShow 或 wx.onAppShow 中获取到这份数据）
https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onAppShow.html (opens new window)

返回参数

名称 数据类型 必填 说明
oauth_Ticket string 是 Ticket

# 小程序嵌H5：

统一授权登录地址(注册/登录)： https://m.mallcoo.cn/a/open/User/V1/OAuth/LiteAppBaseInfo/ (opens new window)
请求类型： GET
传参方式： URL传参

请求参数

名称 数据类型 必填 说明
AppID string 是 应用ID（由猫酷统一分配）
PublicKey string 是 公钥（由猫酷统一分配）
CallbackUrl string 是 回调地址（一定要进行URL编码）

返回参数

WARNING

返回结果需要先进行URL解码(URLDecode)

名称 数据类型 必填 说明
Ticket string 是 Ticket
DataSource int 是 环境类型：
1:安卓APP
2:猫酷苹果APP
3:浏览器
5:微信

# 获取UserToken和用户基本信息

WARNING

必须使用Ticket来获取UserToken

接口地址： https://openapi10.mallcoo.cn/User/OAuth/v1/GetToken/ByTicket/ (opens new window)
请求类型： POST
数据格式： application/json; charset=utf-8
参数类型： JSON字符串
接口参数：

名称 数据类型 必填 说明
Ticket string 是 Ticket
# 接口参数示例（JSON）
{ 
  "Ticket": "a774cf727e0a1c99" 
}
1
2
3

返回结果：

名称 数据类型 必填 说明
Code int 是 状态码
Data Json 是 返回数据
Message string 是 返回状态描述
# Data
名称 数据类型 必填 说明
OpenUserID string 是 用户在当前【开发者账号+项目（集团）】下的唯一标识(相当于用户ID)
NickName string 是 用户昵称
Avatar string 是 头像地址
Mobile string 否 手机号码【默认不传，如有特别需要需单独申请】
WXOpenID string 否 微信OpenID
UserToken string 是 用户Token
Expires long 是 过期时间（单位：分钟）
UserName string 否 姓名
Gender int 是 性别（1：男，2：女，0：未知）
Age int 否 年龄
Birthday string 否 生日
# 返回结果示例（JSON）：
{
  "Code": 1,
  "Data": 
  {
    "OpenUserId": "0000000000000000",
    "NickName": "Mallcoo00000",
    "Avatar": "http://i1.mallcoo.cn/mc/0.png",
    "Mobile": "186xxxxxxxx",
    "UserToken": "12a53d83dd0000000",
    "WXOpenID": "sdjflk5s425",
    "Expires": 10080,
    "UserName": "Mallcoo",
    "Gender": 1,
    "Age": 27,
    "Birthday": "1990-01-01",
  },
  "Message": "成功"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Last Updated: 2021/6/8 下午8:28:45

更新记录 →