API文档 - M1云端市场部

M1 API已更新到V2.0版本，现已支持oauth2验证方式，如您还在使用旧版，考虑更安全使用方式，建议您尽快升级到新版API。

API文档说明

1. API请求均使用HTTP协议的GET或POST请求方式。

2. 字符编码：均使用UTF-8 编码。

3. 返回值：以json数据格式返回。

4. API地址：http://api.m1world.com/v2

5. API调用权限仅限于M1云端市场部付费用户（黄金版/钻石版），点击这里了解版本价格及更多权益。
如果您已经是黄金版或钻石版用户，可在“ 账户中心》 API ”页面获得您的调用app_key和app_secret。如在使用时有任何疑问，可联系客服。

错误码说明

名称	说明
E10001	服务器异常
E10101	无效的Token
E10102	无权限访问API
E10103	参数缺失
E00001	当前版本为免费版，联系人总数量不能超过5000
E00002	您的金装版已过期，联系人总数量不能超过5000
E00003	您当前为金装版，联系人总数量不能超过100000
E00004	您的钻石版已过期，联系人总数量不能超过5000
E00005	每次提交导入联系人总数量不能超过1000条
E10104	API调用频繁，已超过每小时限额

API访问频次说明

免费版	黄金版	钻石版
-	2000次/小时	4000次/小时

如果对API请求频次有疑问，可联系客服 021-51602866-789。

oauth2验证（Step1）:获取code

请求方式：GET

请求地址：http://auth2.m1world.com/authorize

参数：

名称	类型	是否必须	说明
client_id	string	是	分配到的app_key
redirect_uri	string	是	授权回调地址，站外应用需与设置的回调地址一致
response_type	string	是	固定传 "code"

返回数据：

成功：
        跳转至授权回调地址，回调地址后附带code参数
失败：
        {"error_description":"错误描述","error":"错误"}

注意：回调地址后会附带code参数，可保存下来用于Step2获取访问令牌/token时使用，code为一次性生成，不可重复使用

oauth2验证（Step2）获取访问令牌/token

请求方式：POST

请求地址：http://auth2.m1world.com/access_token

传参方式：URL

令牌有效期：24小时

参数：

名称	类型	是否必须	说明
client_id	string	是	分配到的app_key
client_secret	string	是	分配到的app_secret
grant_type	string	是	可以传"authorization_code"，"refresh_token"

当grant_type为authorization_code时

名称	类型	是否必须	说明
code	string	是	调用authorize获得的code值。
redirect_uri	string	是	授权回调地址，站外应用需与设置的回调地址一致

返回数据：

成功：
{
    "access_token": "6ae20ce9b0af1bed73ba8718698b87671487923047611",
    "refresh_token": "15e3599c39868dc4579957a0f9423a841487923047611",
    "expires_in": 1488009447620 //令牌到期时间
}

失败：
{"error_description":"错误描述","error":"错误"}

当grant_type为refresh_token时

名称	类型	是否必须	说明
refresh_token	string	是	与授权令牌同时获取的刷新令牌。

返回数据：

成功：
{
    "access_token": "6ae20ce9b0af1bed73ba8718698b87671487923047611",
    "refresh_token": "15e3599c39868dc4579957a0f9423a841487923047611",
    "expires_in": 1488009447620 //令牌到期时间
}

失败：
{"error_description":"错误描述","error":"错误"}

获取当前账号所有字段列表

请求方式：GET

请求地址：/contact/setting

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值

返回数据：

{
"success": true,
"data": {
           "id": 339,
           "setting": [
                         {
                              "field": "fullName",
                              "name": "姓名",
                              "isOrigin": true,
                              "isShowInQuery": true,
                              "orderby": 1,
                              "type": 1
                         },
                         {
                              "field": "gender",
                              "name": "性别",
                              "isOrigin": true,
                              "isShowInQuery": false,
                              "orderby": 2,
                              "type": 1
                         }
                         ...
                       ]
         }
}

新增联系人

请求方式：POST

请求地址：/contact/add

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
contacts	Object	true	联系人数据集合对象的json字符串
groupName	String	false	群组名称
opType	String	true	操作类型：1覆盖、2合并、3新增

参数示例：

contacts：

[
    {
        "fullName": "测试名称1",
        "gender": true,//布尔型
        "birthday": 1443628800000,//时间戳
        "companyName": "梅花信息",
        "jobTitle": "开发",
        "email": "meihua1@meihua.info",
        "workPhone": "13800000012",
        "mobilePhone": " ",
        "website": " ",
        "fax": " ",
        "country": " ",
        "province_zh": "上海",//省份
        "city_zh ": "上海",//城市
        "address": " ",
        "postCode": " ",
        "qQ": " ",
        "weibo": " ",
        "weixin": " ",
        "notes": " ",
        "propertys": [
                        {
                            "propertyId": 159,
                            "label": "文本"
                        },
                        {
                            "propertyId": 160,
                            "label": "文字"
                        }
                      ]
        },
        {
            "fullName": "测试名称2",
            "gender": true,
            "birthday": 1443628800000,
            "companyName": "梅花信息",
            "jobTitle": "开发",
            "email": "meihua2@meihua.info",
            "workPhone": "13800000013",
            "mobilePhone": " ",
            "website": " ",
            "fax": " ",
            "country": " ",
            "province_zh": "上海",//省份
            "city_zh ": "上海",//城市
            "address": " ",
            "postCode": " ",
            "qQ": " ",
            "weibo": " ",
            "weixin": " ",
            "notes": " ",
            "propertys": [
                            {
                                "propertyId": 159,
                                "label": "文本"
                            },
                            {
                                "propertyId": 160,
                                "label": "339"
                            }
                          ]
    }
]

返回数据：

//不添加群组参数的返回结果
{
    "success": true,
    "data": {
                "groupId": "null"
             }
}
//添加群组的返回结果
{
    "success": true,
    "data": {
                "groupId": 256
             }
}

删除联系人

请求方式：POST

请求地址：/contact/delete

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
ids	String	true	联系人ids，联系人id数组，如[id1,id2,id3]

返回数据：

{
    "success": true,
    "data": "success"
}

编辑联系人

请求方式：POST

请求地址：/contact/edit

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
contacts	Object	true	联系人数据集合对象的json字符串
fields	Object	true	字段顺序[标注唯一字段，用作更新条件], 参数值为数据集合对象的json字符串

参数示例：

contacts：

[
    [
        "test1",
        "梅花信息",
        "开发测试",
        "13800000000",
        "test@meihua.info",
        "上海",
        "上海",
        "男",
        "Thu May 10 00:00:00 CDT 1990",
        "文本1",
        "选项1"
    ],
    [
        "test2",
        "梅花信息",
        "开发",
        "13800000001",
        "123456@qq.com",
        "上海",
        "上海",
        "女",
        "Fri May 11 00:00:00 CDT 1990",
        "文本2",
        "选项2"
    ]
]

fields：参数格式样例（属性说明：field 字段名[额外字段为额外字段的id]、name 字段中文名称、isOrigin 是否为系统字段、type [文本类型 1,下拉框类型 2]、isUniq[是否设为唯一字段]）

[
    {
        "field": "fullName",
        "name": "姓名",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "companyName",
        "name": "公司",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "jobTitle",
        "name": "职位",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "workPhone",
        "name": "电话",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "email",
        "isUniq": true,
        "name": "邮箱",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "province",
        "name": "省份",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "city",
        "name": "城市",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "gender",
        "name": "性别",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "birthday",
        "name": "生日",
        "isOrigin": true,
        "type": 1
    },
    {
        "field": "159",
        "name": "API测试额外字段（文本）",
        "isOrigin": false,
        "type": 1
    },
    {
        "field": "160",
        "name": "API测试额外字段（下拉框）",
        "isOrigin": false,
        "type": 2
    }
]

返回数据：

{
    "success": true,
    "data": "success"
}

获取联系人详情

请求方式：GET

请求地址：/contact/detail

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
id	String	true	联系人id

返回数据：

{
    "success": true,
    "data": {
        "detail": {
            "id": 2172079,
            "fullName": "李玫",
            "birthday_des": "",
            "companyName": "美啦",
            "jobTitle": "Age",
            "email": "test@sina.com",
            "workPhone": " ",
            "mobilePhone": " ",
            "website": " ",
            "fax": " ",
            "country": " ",
            "province": 0,
            "city": 0,
            "address": "",
            "postCode": " ",
            "qQ": " ",
            "weibo": " ",
            "weixin": " ",
            "notes": "100021",
            "createAt": 287006,
            "accountId": "7",
            "createTime": 1445399164287,
            "updateTime": 1445399164287,
            "QRCodeURL": "http://contact.m1world.com/download_tmp/联系人二维码_1445500487311.jpg",
            "isEmailActive": true,
            "propertys": [
                {
                    "id": 0,
                    "propertyId": 189,
                    "contactId": 0,
                    "label": "OnePassUserName",
                    "createTime": 0,
                    "updateTime": 0
                }
            ],
            "groups": [
                {
                    "id": 0,
                    "groupId": 779,
                    "groupName": "群组",
                    "contactId": 0,
                    "createTime": 0
                }
            ],
            "sources": [
                {
                    "id": 0,
                    "sourceId": 223,
                    "name": "144539583634516",
                    "contactId": 0,
                    "createTime": 0
                }
            ],
            "opLogs": [
                {
                    "date": "2015-10-21",
                    "log": [
                        {
                            "logs": [
                                        "通过Excel导入了联系人李玫"
                             ],
                            "username": "sunwellgu"
                         }
                      ]
                },
                {
                    "date": "2015-10-22",
                    "log": [
                        {
                            "logs": [
                                        "创建了群组:群组"
                                    ],
                            "username": "sunwellgu"
                        }
                    ]
                }
            ],
            "tags": []
            },
            "edm": {
                "isEmailActive": false,
                "edmBehavior": [
                    {
                        "task_id": 2880,
                        "subject": "我们更新了一款圣诞主题",
                        "thumbnail": "http://7xl909.com2.z0.glb.qiniucdn.com/Fru9jCF1IlmkCsHZ0JGPOCoPfPmv",
                        "sendtime": 1450972800000,
                        "dmdtype": "open",
                        "email": "test@meihua.info",
                        "eventdate": "2015-12-25 10:10:44.0",
                        "clickname": "",
                        "clickurl": "",
                        "ip": "203.156.203.10",
                        "country": "中国",
                        "province": "上海",
                        "city": "上海",
                        "software": "Windows 7",
                        "clientOs": "[Unknown]",
                        "mailing_id": "4905"
                    }
                ]
            }
        }
}

获取联系人列表

请求方式：GET

请求地址：/contact/all

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
groupIds	Array	false	群组id集合，[id1,id2]
page	String	true	分页页码
limit	String	true	每页条数（每页最多50条）

返回数据：

{
    "success": true,
    "data": {
        "total": 4831,
        "list": [
            {
                "id": 4338372,
                "fullName": " ",
                "gender": true,
                "gender_des": " ",
                "birthday": 1451024631,
                "birthday_des": "1970-01-18",
                "companyName": " ",
                "jobTitle": " ",
                "email": "baixiaoshen@milord.cn",
                "workPhone": " ",
                "mobilePhone": " ",
                "website": " ",
                "fax": " ",
                "country": " ",
                "province": 0,
                "province_des": " ",
                "province_zh": " ",
                "city": 0,
                "city_des": " ",
                "city_zh": " ",
                "address": " ",
                "postCode": " ",
                "qQ": " ",
                "weibo": " ",
                "weixin": " ",
                "notes": " ",
                "createAt": 0,
                "accountId": "2627",
                "createTime": 1451024646979,
                "updateTime": 1451024646979,
                "QRCodeURL": " ",
                "isEmailActive": true,
                "propertys": [],
                "groups": [
                    {
                        "id": 0,
                        "groupId": 1605,
                        "groupName": "shengdan-shengdan",
                        "contactId": 0,
                        "createTime": 0
                    }
                ],
                "sources": [
                    {
                        "id": 0,
                        "sourceId": 299,
                        "name": "API导入",
                        "contactId": 0,
                        "createTime": 0
                    }
                ],
                "tags": []
            },
            {
                "id": 4338373,
                "fullName": " ",
                "gender": true,
                "gender_des": " ",
                "birthday": 1451024631,
                "birthday_des": "1970-01-18",
                "companyName": " ",
                "jobTitle": " ",
                "email": "v-ing@vip.163.com",
                "workPhone": " ",
                "mobilePhone": " ",
                "website": " ",
                "fax": " ",
                "country": " ",
                "province": 0,
                "province_des": " ",
                "province_zh": " ",
                "city": 0,
                "city_des": " ",
                "city_zh": " ",
                "address": " ",
                "postCode": " ",
                "qQ": " ",
                "weibo": " ",
                "weixin": " ",
                "notes": " ",
                "createAt": 0,
                "accountId": "2627",
                "createTime": 1451024646985,
                "updateTime": 1451024646985,
                "QRCodeURL": " ",
                "isEmailActive": true,
                "propertys": [],
                "groups": [
                    {
                        "id": 0,
                        "groupId": 1605,
                        "groupName": "shengdan-shengdan",
                        "contactId": 0,
                        "createTime": 0
                    }
                ],
                "sources": [
                    {
                        "id": 0,
                        "sourceId": 299,
                        "name": "API导入",
                        "contactId": 0,
                        "createTime": 0
                    }
                ],
                "tags": []
            }
        ]
    }
}

添加群组

请求方式：POST

请求地址：/contact/group/add

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
name	String	true	群组名称

返回数据：

{
"success": true,
"data":{
"id": 12802,
"groupName": "0627",
"createAt": 287006,
"createTime": 1498549684469,
"updateTime": 1498549684469,
"accountId": "7"
}
}

删除群组

请求方式：POST

请求地址：/contact/group/delete

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
ids	String	true	群组ids，群组id集合如:[id1,id2]
flag	Bool	true	是否删除关联联系人（true，false）

返回数据：

{
    "success": true,
    "data": "success"
}

获取群组列表

请求方式：GET

请求地址：/contact/group/all

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
page	String	true	分页页码
limit	String	true	分页条数
key	String	false	关键字

返回数据：

{
    "success": true,
    "data": {
        "total": 2,
        "groups": [
            {
                "groupName": "群组1",
                "id": 402,
                "contactSize": 0
            },
            {
                "groupName": "群组2",
                "id": 401,
                "contactSize": 0
            }
        ]
    }
}

添加标签

请求方式：POST

请求地址：/contact/tag/add

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
name	String	true	标签名称

返回数据：

{
    "success": true,
    "data": "success"
}

获取标签列表

请求方式：GET

请求地址：/contact/tag/all

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
page	String	true	分页页码
limit	String	true	分页条数
key	String	false	关键字

返回数据：

{
    "success": true,
    "data": {
        "total": 2,
        "tags": [
            {
                "tagName": "标签1",
                "id": 402,
                "contactSize": 0
            },
            {
                "tagName": "标签2",
                "id": 401,
                "contactSize": 0
            }
        ]
    }
}

添加自定义字段

请求方式：POST

请求地址：/contact/property/add

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
label	String	true	自定义字段名
fieldType	String	true	字段类型（1 单个，2 下拉框）
description	String	true	字段描述
subpropertys	Object	false	字段类型为下拉框时，字段下的子节点集合

参数示例：

subpropertys:

[
    {
        "label": "电商行业"
    },
    {
        "label": "化工行业"
    }
]

返回数据：

{
    "success": true,
    "data": "success"
}

编辑自定义字段

请求方式：POST

请求地址：/contact/property/edit

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
id	String	true	自定义字段id
label	String	true	自定义字段名称
fieldType	String	true	字段类型（1 单个，2 下拉框）
description	String	true	字段描述
subpropertys	Object	false	字段类型为下拉框时，字段下的子节点集合

参数示例：

subpropertys:

[
    {
        "label": "电商行业"
    },
    {
        "label": "化工行业"
    }
]

返回数据：

{
    "success": true,
    "data": "success"
}

获取自定义字段列表

请求方式：POST

请求地址：/contact/property/all

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值

返回数据：

{
    "success": true,
    "data": [
        {
            "description": "字段描述",
            "id": 60,
            "label": "注册时间",
            "type": 2
        },
        {
            "description": "字段描述",
            "id": 121,
            "label": "注册来源",
            "type": 1
        }
    ]
}

删除自定义字段

请求方式：POST

请求地址：/contact/property/delete

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
id	String	true	自定义字段id(仅支持单个字段id)

返回数据：

{
    "success": true,
    "data": "success"
}

获取EDM列表

请求方式：GET

请求地址：/edm/tasks

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
start	String	true	开始时间戳
end	String	true	结束时间戳

返回数据：

{
    "success": true,
    "data": [
        {
            "task_id": 3450,
            "createtime": 1452134460000,
            "sendtime": 1452214800000,
            "subject": "邮件主题",
            "thumbnail": "http://7xl909.com2.z0.glb.qiniucdn.com/Fs6biaZF6OAadv0e8ZZ59Vd_4i2F",
            "status": 4
        },
        {
            "task_id": 2956,
            "createtime": 1451284270000,
            "sendtime": 1451426400000,
            "subject": "邮件主题",
            "thumbnail": "http://7xl909.com2.z0.glb.qiniucdn.com/FgUdksoyXVRaXeul1BYP6N4bZYc9",
            "status": 4
        }
    ]
}

获取指定EDM明细

请求方式：GET

请求地址：/edm/task/detail

参数：

名称	类型	是否必须	说明
token	String	true	api请求token值
type	String	true	操作类型【注：0（默认，获取全部）,1 (有打开行为的),2 (有点击点击),3 (有退订行为的),4 (软弹),5 (硬弹),6 (投诉)】
id	String	true	邮件发送任务编号
start	String	true	开始时间戳
end	String	true	结束时间戳
page	String	true	分页页码
limit	String	true	分页条数

返回数据：

{
    "success": true,
    "data": {
        "total_count": 500,
        "detail": [
            {
                "task_id": 3450,
                "subject": "邮件主题",
                "thumbnail": "http://7xl909.com2.z0.glb.qiniucdn.com/Fs6biaZF6OAadv0e8ZZ59Vd_4i2F",
                "sendtime": 1452214800000,
                "dmdtype": "open"//客户操作类型【注：Open(打开),Click(点击),Unsubscribe(退订),Softbounce1x
(软弹1 次),Softbounce2x(软弹2 次),Softbounce3x(软弹3 次),Softbounce final(最终软弹),Hardbounce1x(硬弹1次),
Hardbounce2x(硬弹2次),Hardbounce3x(硬弹3次),HardBounce final（最终硬弹）,Spamcomplaint(投诉)】,
                "email": "test@163.com",
                "eventdate": "2016-01-11 21:49:57.0",
                "clickname": ""//邮件中链接的名字,
                "clickurl": ""//邮件中链接的地址,
                "ip": "183.69.234.48",
                "country": "中国",
                "province": "重庆",
                "city": "重庆",
                "software": "Windows 7",
                "clientOs": "Google Chrome",
                "mailing_id": "24788"
            },
            {
                "task_id": 3450,
                "subject": "邮件主题",
                "thumbnail": "http://7xl909.com2.z0.glb.qiniucdn.com/Fs6biaZF6OAadv0e8ZZ59Vd_4i2F",
                "sendtime": 1452214800000,
                "dmdtype": "open",
                "email": "test@163.com",
                "eventdate": "2016-01-11 20:42:45.0",
                "clickname": "",
                "clickurl": "",
                "ip": "114.64.232.182",
                "country": "中国",
                "province": "北京",
                "city": "北京",
                "software": "Windows 8",
                "clientOs": "Google Chrome",
                "mailing_id": "24788"
            }
        ]
    }
}