用API与秀米对接

基本概念

秀米提供一些接口及接口定义，以便用户可以以合作方平台用户的身份登录秀米的在线图文编辑器，也能够将在秀米创作的图文的文本、格式和图片等保存至您的平台。秀米图文编辑器也支持按您平台的用户的身份重新载入已保存的图文，进行进一步的创作。由于秀米将用户创作的图文同时回传至您的平台，您可以自行管理、发布和分析用户的图文数据。

进一步的说明

进入编辑器

由于秀米提供的入口接受图文编号（mediaid）作为参数，因此您可以提供给用户两种进入方式：从头开始创作一个新图文或读取一个已经保存的图文并继续编辑。

用户账户

在用户进入编辑器时，您通过API参数提供该用户的ID（非秀米ID），如果该ID从未使用对接的编辑器，秀米将为他/她创建一个独立的秀米账户，以后该用户的所有数据都将保存在这个账户内。该账户的会员等级及权限，由您的平台与秀米协商和控制。

保存图文

当用户编辑完成当前图文，点击保存按钮时，秀米在保存该图文的同时，会调用您（依据秀米的接口定义）的预定接口，依次将图文文本、图文基本数据和图文所用图片上传至合作方。

用户编辑流程

在接入前，要做什么？

请务必仔细阅读本文档。强烈推荐您通过在线演示网页来体验秀米编辑器接入。在线演示模拟了一个图文列表、新建一个空白图文、重新进入并编辑一个已存在的图文等基本功能。

对接与调试

如您已经依本文档的定义实现了接口，我们需要您提供接口的URL，并记录到秀米的系统中，然后，由专人负责与您对接调试。您需要填写此表单（点击），以便我们安排专人接待，为您预设一些关键数据，如：APPID，TOKEN，SECRET。

申请流程

如您有其他疑问，请与我们联系（邮箱：support@xiumi.us）。

秀米提供的接口

用户登录入口

https://xiumi.us/auth/partner/login?route_type=article&signature=jae5aigeig9eTeen9cha1Pheich0phap&timestamp=1544426764&nonce=590946&uid=100005667161&appid=Geethi7eexu1ging3tahzoe6ye7eek1p&mediaid=0

请注意：务必使用https来访问秀米

参数 说明
route_type 登录后使用的功能，当前固定为article，表示“图文编辑器”
timestamp 当前UNIX时间戳，单位：秒。
uid 正整数，小于2的32次方。用户在您的平台的唯一标识。 由您提供，秀米将使用其作为用户在秀米的身份标识。
appid 您的平台在秀米平台的唯一标识，由秀米提前颁发，形式为一个32个字符的字符串。
nonce 随机字符串，由您的平台在每一次签名时生成，使用于签名算法内。
signature 每次登录时根据各项参数计算得出的签名字符串。算法见下面的说明。
mediaid 图文在秀米的唯一编号，通过“接收图文内容的接口”获得。 如果参数合法，并且图文存在，则打开该图文继续编辑。 如果不传此参数，则打开一个新的空白图文。

签名算法
将token，timestamp，nonce，uid四个参数的值以字符串形式由低到高排序，然后将四个字符串依次连接为一个字符串，然后用md5函数计算两次哈希（计算中字符串使用小写字母），得到signature字符串。其中token由秀米提前颁发，形式为一个32个字符的字符串。

返回值
无。该URL将直接重定向至秀米的图文编辑器。

您需要提供的接口

我们先假设your-domain.com是您平台的域名，some_path_for_access_token是您平台对于access_token接口的路径，其他接口也有类似的假设。具体的域名和路径完全由您决定，秀米只对接口的参数作出了约定。

获取access_token的接口

http://your-domain.com/some_path_for_access_token?appid=Geethi7eexu1ging3tahzoe6ye7eek1p&nonce=590946&signature=jae5aigeig9eTeen9cha1Pheich0phap&timestamp=1544426764

cURL调用示例

秀米调用您的这个接口时，调用的方式和内容与以下的cURL命令相同

curl -X GET \
  'http://your-domain.com/some_path_for_access_token?appid=Geethi7eexu1ging3tahzoe6ye7eek1p&nonce=590946&signature=jae5aigeig9eTeen9cha1Pheich0phap&timestamp=1544426764'

参数

参数 说明
appid 秀米发放给合作方的唯一标识
timestamp 调用接口时的UNIX时间戳，单位是秒
nonce 一个随机短字符串
signature 根据调用参数计算的签名字符串，算法见下面的详细说明。

signature签名算法
将secret，timestamp，nonce，uid四个参数的值以字符串形式由低到高排序，然后将四个字符串依次连接为一个字符串，然后用md5函数计算两次哈希，得到signature字符串。其中secret由秀米提前颁发，形式为一个32个字符的字符串。

返回值

正常返回access_token时

{
    "access_token" : "iD8tahtair4eex2ohB7thoh3veezisha",
    "expires_in" : 64800
}

说明：expires_in是access_token有效的时间，单位是秒，自发放access_token之时开始计算。

如果发生错误

{
    "code": 1,
    "msg": "任何可以说明错误原因的文字",
    "data": {}
}

说明：code设定为一个非0的整数值，表示发生了错误，具体值的含义没有约定。
msg是一个字符串，用来说明错误原因，可能在页面上显示给用户。
data是任何有效的json对象，用来传递发生错误相关的数据，便于双方理解和分析错误的原因，秀米不会自动解析，但会作为日志记录，以供错误分析。

接收图文内容的接口

http://your-domain.com/some_path_for_articles?access_token=iD8tahtair4eex2ohB7thoh3veezisha&timestamp=1544426764&uid=100005667161&signature=1890fc764311979354d92d37f0443d0f

cURL调用示例

秀米调用您的这个接口时，调用的方式和内容与以下的cURL命令相同

curl -X POST \
  'http://your-domain.com/some_path_for_articles?access_token=iD8tahtair4eex2ohB7thoh3veezisha&timestamp=1544426764&uid=100005667161&signature=1890fc764311979354d92d37f0443d0f' \
  -d '{
    "articles": [
        {
            "author": "",
            "description": "此处是图文的HTML",
            "from_id": 9013,
            "picurl": "http://your-domain.com/upload/1_15502167086304527.jpg",
            "showCover": 0,
            "summary": "happy new year",
            "title": "新年快乐",
            "url": ""
        },
        {
            "author": "",
            "description": "此处是图文的HTML",
            "from_id": 9014,
            "picurl": "http://your-domain.com/upload/1_15502167068304527.jpg",
            "showCover": 0,
            "summary": "wish you health",
            "title": "身体健康",
            "url": ""
        }
    ]
}
'

参数

参数 说明
access_token 秀米通过access_token接口获得的有效access_token
timestamp 发起请求时的UNIX时间戳，单位：秒。
uid 用户对接的唯一标识。
signature 根据各项参数计算得出的签名字符串，算法见下面的详细说明。

signature签名算法

将token，timestamp两个参数的值以字符串形式依次拼接为一个字符串，然后用md5函数计算哈希，将得到的哈希字符串与uid依次拼接为一个字符串，然后用md5函数计算哈希，得到signature字符串。

以PHP代码为例：

    $signature = md5(md5($access_token . $timestamp) . $uid);

request body

秀米调用此接口时，会将图文内容以JSON文本的形式，放置在request body中。格式如下：

{
    "articles": [
        {
            "author": "",
            "description": "此处是图文的HTML",
            "from_id": 9013,
            "picurl": "http://your-domain.com/upload/1_15502167086304527.jpg",
            "showCover": 0,
            "summary": "happy new year",
            "title": "新年快乐",
            "url": ""
        },
        {
            "author": "",
            "description": "此处是图文的HTML",
            "from_id": 9014,
            "picurl": "http://your-domain.com/upload/1_15502167068304527.jpg",
            "showCover": 0,
            "summary": "wish you health",
            "title": "身体健康",
            "url": ""
        }
    ]
}

说明：from_id是该图文在秀米的唯一编号，您需要记录此编号，以便用户在未来意图编辑此图文时，作为mediaid参数传送给秀米的用户登录接口。description是一个HTML格式的字符串，包含图文内容。

返回值

{
    "code": 0,
    "msg": "success"
}

说明：code指示图文是否被正常接收，0表示正常，其他值为异常。msg是说明文本，提供相关的说明。

接收图片文件的接口

http://your-domain.com/some_path_for_image?access_token=iD8tahtair4eex2ohB7thoh3veezisha&timestamp=1544426764&uid=100005667161&signature=1890fc764311979354d92d37f0443d0f

注：当一篇图文中包含多个图片时，秀米会为每一个图片调用一次图片接口

cURL调用示例

秀米调用您的这个接口时，调用的方式和内容与以下的cURL命令相同

curl -X POST \
  'http://your-domain.com/some_path_for_image?access_token=iD8tahtair4eex2ohB7thoh3veezisha&timestamp=1544426764&uid=100005667161&signature=1890fc764311979354d92d37f0443d0f' \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F img-upload=123.jpg

参数

参数 说明
access_token 秀米通过access_token接口获得的有效access_token
timestamp 发起请求时的UNIX时间戳，单位：秒。
uid 用户对接的唯一标识。
signature 根据各项参数计算得出的签名字符串，算法与接收图文内容的接口算法相同。

post request

图片二进制文件以multipart/form-data的形式发送

返回值

{
  "code": 0,
  "msg": "",
  "data": {
    "url": "http://图片在合作方的URL",
    "name": "图片的名称，在html中可能作为alt显示"
}

说明：code指示图文是否被正常接收，0表示正常，其他值为异常。msg是说明文本，提供相关的说明。

编辑完成后跳转URL

秀米编辑器在用户编辑完成后，点按保存按钮时，除了调用图文和图片接口传输文件，还会在所有传输成功后，自动将用户的当前浏览器窗口重定向到一个您指定的固定URL。您需要预先将此URL提供给秀米，秀米会保存此URL，每次重定向时使用。

示例代码与在线演示

为了更好地理解上述对接方式，我们准备了一些简单的PHP代码来演示如何实现接口，为了排除不必要的学习成本和干扰，示例使用了最简短的代码，同时移除了很多必要的数据检查和数据库连接等等与接口无关的部分，因此不可能作为实际的工程用途。

代码下载

如需马上体验示例代码的接入场景，请访问我们的在线演示。

在线演示

如在接入开发中遇到签名问题，可以使用我们的签名验证工具验证签名是否正确。

在线验证

Q&A

  1. 以上的接口都需要开发完毕才能申请秀米的接口参数吗？

    获取token的接口需要先实现，即使是硬编码也可以。秀米服务器会在接入账号配置完毕后立即开始调用token接口，如果在72小时内连续调用失败，秀米服务器会自动暂停调用。如果您发现秀米服务器没有调用您的token接口，可能是因为这个原因，请联系我们重新激活对接账号。其它接口不需要预先实现，只需要定义即可。

  2. 如果遇到“出错了，正在跳转……”（网址：xiumi.us/auth/failure/-104） 怎么办？

    这个情况很有可能是由于在登录时使用了 http://xiumi.us/ 开头的网址。改为 https://xiumi.us/ 开头即可解决。

  3. 上传图片的参数名字是什么？一次传送几张图片

    参数的名字是img-upload，每次调用传送一张图片。