秀米图文同步接口文档 2.0.8

秀米图文同步接口文档 2.0.8

「秀米图文同步」是秀米推出的新版本同步服务，使用此服务，用户可以将自己的图文传输到某个绑定的平台，类似于秀米同步到微信公众号的功能。
同步服务有两个参与方：平台和秀米用户。平台负责提供接入的接口，供秀米用户绑定。秀米用户绑定接口，同步图文到平台。

概念

名词

平台：提供同步对接功能的网站或其他在线系统，负责实现对接接口。
平台管理员：将平台同步功能注册到秀米的管理人员，同时也是一个拥有秀米官网账号的普通用户。
同步app：是平台管理员在秀米网站创建的配置对象，用于管理同步接口相关的数据。注意：app不是一个供运行的二进制程序。
平台用户：平台的用户，可能同时使用秀米图文编辑器和平台的其他功能。
秀米用户：秀米的官网用户。
绑定：用户通过绑定页面，将平台用户的身份和秀米官网的用户身份相关联。
同步：用户点击编辑器菜单，将当前图文的HTML和图片等信息传输到平台。
应用密钥（secret）：应用密钥用于认证和加密平台和秀米间的通信。应用密钥不得在url调用时作为Query String等明文传递。

Q & A

秀米的官网账号的作用
- 平台管理员需要一个秀米的官网账号来管理自己的app。
- 用户需要登录自己的秀米的官网账号来绑定和使用秀米的所有功能，包括同步功能
一个秀米账号可以创建几个app？
可以创建多个app，每个app可以配置不同的参数，对接不同的系统（平台）。当然，不同的app也可以配置相同的参数。另外，同一个实体（企业和个人）可以创建多个app。
在哪里创建app？
在同步app管理控制台，URL见本文档。
任何秀米用户都可以创建app吗？
是的，所有的秀米用户都可以创建自己的同步app，并提供给其他秀米用户绑定和使用。
审核主要审核什么内容？
- 接口query string或path等参数不得包含secret。
- 由于secret会在header中传输，所以接口应使用https。测试阶段可以暂时使用http，上线后继续使用http，可能会被禁用。
- 不能使用类似https://mp.weixin.qq.com 等其他公开平台的域名
- app名称是否符合法律法规要求，不能使用“微信公众号”等容易被误解或混淆的名称。
- 审核时需提供企业或个人的身份证明以存档。
提交审核后，要等多久？
一般在1到2个工作日内审核完毕。审核的结果会通过秀米站内信发送。由于提交审核后要等待审核结束后才能再次修改，请谨慎提交。
提交审核期间，接口可以正常使用吗？
审核期间，秀米会继续使用旧的接口。如果审核通过，秀米会立即切换为新接口；如果审核驳回，接口不会发生变化。
每次修改app都要审核吗？
是的。
每次同步时都会将图文内的图片全部传输一次吗？
是的。
同步app费用是多少？
目前暂不收费。未来会按app收费，预计200元/app/年。
每个同步app可以绑定多少用户？
目前每个app最多绑定1000个秀米用户
能否在秀米的打开图文网页URL（edit），传递自定义参数？
不能。因为 1. 同步的内容中参数不一定每次都有效，比如，用户可能首先打开秀米编辑器，编辑图文后同步，此时没有平台参数。2. 即使用户通过edit打开，用户也可以在秀米编辑器，打开另一个图文编辑并同步。

创建app的流程

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': 'rgb(214,128,123, 0.8)', 'secondaryColor': 'white', 'fontFamily': 'Source Han Sans SC Normal'}}}%% graph TD A(登录秀米账号) --> B[进入同步APP列表] B --> C[创建同步app] C --> D[设置app资料] D --> E{提交审核} E -->|审核通过| F[编写程序] E -->|审核拒绝| G[修改资料] G --> E F --> H[在平台提供绑定和编辑入口]

用户使用同步app的流程

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': 'rgb(214,128,123, 0.8)', 'secondaryColor': 'white', 'fontFamily': 'Source Han Sans SC Normal'}}}%% graph TD A[用户进入平台] --> B{平台用户已绑定秀米} B --> |未绑定| C[在平台点击绑定入口] B --> |已绑定| D[在平台点击编辑入口] C --> E[登录用户自己的秀米账号] E --> F[点击绑定] F --> G[绑定成功] --> H[进入编辑器] D --> I[登录用户自己的秀米账号] I --> H

用户绑定后同步图文的方式

秀米用户绑定成功后，可以在图文编辑器的导出菜单内找到新的导出选项，名称默认与app的名称相同（或者等于bind_name，见绑定接口的参数说明）。如下图：

秀米提供的网页

绑定秀米用户与第三方平台用户

本网页应由平台提供给平台用户使用（比如点击“绑定秀米”按钮）

URL

https://xiumi.us/auth/partner/bind?signature=jae5aigeig9eTeen9cha1Pheich0phap&timestamp=1544426764&nonce=590946&partner_user_id=a100005667161&appid=Geethi7eexu1ging3tahzoe6ye7eek1p&bind_name=融媒体平台XX电视台

参数说明

参数	说明
partner_user_id	用户在平台（不是秀米）的唯一ID。可以不使用平台的用户编号，而为秀米对接特地生成一个专用的ID字符串。
app_id	在创建秀米同步app时获得的app id。
nonce	随机字符串，由您的平台在每一次签名时生成，使用于签名算法内。
timestamp	当前UNIX时间戳，单位：秒。需不早于当前时间5分钟。
signature	根据各项参数计算得出的签名字符串。算法见下面的说明。
bind_name	绑定名称，非必需字段，少于20个汉字，建议少于10个汉字。如果传递了bind_name，秀米会在导出菜单中显示“同步到「bind_name」，如果不传递bind_name，秀米会在导出菜单中显示“同步到「app_name」。

signature计算方法

将secret，timestamp，nonce，partner_user_id四个参数的值转换为字符串。保持所有字符串的大小写不变。
以字符串形式由低到高排序。
然后将四个字符串依次连接为一个字符串。
将这个字符串用md5函数计算两次哈希，得到signature字符串。

JavaScript代码的例子

let data = [partner_user_id, secret, timestamp, nonce];
data.sort();
let cs = data[0] + data[1] + data[2] + data[3];
let signature = md5(md5(cs));

注：其中partner_user_id, secret, timestamp, nonce都是字符串

PHP代码的例子

$timestamp = time();
$nonce = mt_rand();
$array = [$secret, $timestamp, $nonce, $partner_user_id];
sort($array, SORT_STRING);
$signature = md5(md5(implode($array)));

在线签名验证工具

绑定流程

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': 'rgb(214,128,123, 0.8)', 'secondaryColor': 'white', 'fontFamily': 'Source Han Sans SC Normal'}}}%% sequenceDiagram participant 平台网页 participant 平台服务器 participant 秀米网页 participant 秀米服务器平台网页->>平台网页: 用户登录平台网站平台网页->>秀米网页: 发起绑定秀米用户（签名发送partner_user_id）秀米网页->>秀米网页: 登录秀米或创建新秀米用户秀米网页->>秀米网页: 绑定平台用户到当前秀米用户秀米服务器->>平台服务器: 绑定成功通知秀米网页->>秀米网页: 重定向到秀米编辑器秀米网页->>秀米网页: 编辑图文秀米网页->>秀米网页: 发起同步秀米网页->>秀米服务器: 保存图文秀米服务器->>平台服务器: 同步图文

新建或打开图文

本网页应由平台提供给平台用户使用（比如点击“编辑图文”按钮或链接）

URL

https://xiumi.us/auth/partner/edit?open_id=eegh5ootiu5re3rahwup6EiYaiSe5vie&article_id=123456

open_id: 秀米为每个用户指定的ID，在用户绑定成功时通过通知接口传送一次。
article_id: 图文在秀米的ID，在HTML上传时附带。 如果是新建一个图文，article必须为空，或不传递此参数。

平台发起图文编辑流程

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': 'rgb(214,128,123, 0.8)', 'secondaryColor': 'white', 'fontFamily': 'Source Han Sans SC Normal'}}}%% sequenceDiagram participant 平台网页 participant 平台服务器 participant 秀米网页 participant 秀米服务器平台网页->>平台网页: 用户登录平台网站平台网页->>秀米网页: 秀米编辑器（发送article_id及open_id）秀米网页->>秀米网页: 登录秀米（确认用户权限）秀米网页->>秀米网页: 编辑图文秀米网页->>秀米网页: 发起同步秀米网页->>秀米服务器: 保存图文秀米服务器->>平台服务器: 同步图文

您平台需要提供的接口

秀米服务器会在后台调用您的接口。

传送图文HTML的接口

本接口用于接收用户同步的某一个图文的HTML。本接口会在用户点击 “同步到……” 菜单后触发，在调用本接口前，秀米会先调用“传送图片的接口”（见下一节），确保所有图片已经传输成功，并替换所有的图片URL。

URL
POST https://www.example.com/您的HTML接收路径?partner_user_id=a100005667161

验证
对接平台需提供URL用于接收图文HTML，URL授权验证方式为：
秀米在调用您的URL时，会在HTTP header中增加
"Authorization: secret ielep1kieshaeteeCie1eeShixooPhie"
其中的“ielep1kieshaeteeCie1eeShixooPhie”，是您在秀米官网申请app时，页面上显示的secret。
您的URL收到调用请求时，应该验证此header。

参数说明

参数	说明
partner_user_id	用户ID

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

{
    "articles" : [
        {
            "description": "<section style=\"box-sizing: border-box; font-style: normal; font-weight: 400; text-align: justify; font-size: 16px;\"><section style=\"text-align: center; justify-content: center; margin: 10px 0% 0px; transform: translate3d(-1px, 0px, 0px); -webkit-transform: transl...",
            "article_id": 9013,
            "picurl": "https://www.example.com/upload/images/cover.jpg",
            "title": "标题：新年快乐",
            "summary": "文章简介",
        }
    ]
}

返回值

您的接口正常接收HTML后，应该返回如下内容

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

调试
此接口调用出现问题时，秀米会将平台服务器返回的内容输出到浏览器控制台。

传送图片的接口

本接口用于接收图文HTML中所有使用的图片文件

URL
POST https://www.example.com/您的图片上传路径?partner_user_id=a100005667161

验证
对接平台需提供URL用于接收图文附属的图片文件，URL授权验证方式为：
秀米在调用您的URL时，会在HTTP header中增加
"Authorization: secret ielep1kieshaeteeCie1eeShixooPhie"
其中的“ielep1kieshaeteeCie1eeShixooPhie”，是您在秀米官网申请app时，页面上显示的secret。
您的URL收到调用请求时，应该验证此header。

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

参数说明

参数	说明
partner_user_id	用户ID

数据

图片二进制文件以multipart/form-data的形式发送。图片的文件名是img-upload

返回值
您的接口正常接收图片后，应该返回如下内容

{
  "code": 0,
  "msg": "",
  "data": {
    "url": "图片在您平台的URL"
}

我们会将HTML中的所有秀米图片URL替换为返回值中的URL。

cURL调用示例

curl -X POST \
  'http://www.example.com/path_for_upload_image \
  -H 'cache-control: no-cache' \
  -H 'Authorization: secret ielep1kieshaeteeCie1eeShixooPhie' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F img-upload=123.jpg

接收通知数据接口

URL
POST https://www.example.com/您的通知接收路径

对接平台需提供URL用于接收一些通知消息和数据回传，URL授权验证方式为：
秀米在调用您的URL时，会在HTTP header中增加
"Authorization: secret ielep1kieshaeteeCie1eeShixooPhie"
其中的“ielep1kieshaeteeCie1eeShixooPhie”，是您在秀米官网申请app时，页面上显示的secret。
您的URL收到调用请求时，应该验证此header。
注：「secret被重置」消息验证方式不同。

支持的通知消息类型及参数

绑定成功

{
    "type": "bind",
    "app_id": "au4eosh5osaev2ohtoogahv5uivoh4Ea",
    "partner_user_id": "a3123456",
    "open_id": "ue5ahShoh7raegaesooyaisooriep9ri",
}

解绑成功

{
    "type": "unbind",
    "app_id": "au4eosh5osaev2ohtoogahv5uivoh4Ea",
    "partner_user_id": "a3123456",
    "open_id": "ue5ahShoh7raegaesooyaisooriep9ri",
}

HTML接口出错

{
    "type": "err_html",
    "app_id": "au4eosh5osaev2ohtoogahv5uivoh4Ea",
    "open_id": "ue5ahShoh7raegaesooyaisooriep9ri",
    "err_code": 101,
    "err_msg": "the readable message"
}

图片接口出错

{
    "type": "err_image",
    "app_id": "au4eosh5osaev2ohtoogahv5uivoh4Ea",
    "open_id": "ue5ahShoh7raegaesooyaisooriep9ri",
    "err_code": 101,
    "err_msg": "the readable message"
}

secret（应用密钥）被重置

特殊说明：由于secret已被重置，此消息使用重置前的旧secret认证header，消息发送后，旧secret即被秀米丢弃

{
    "type": "secret_reset",
    "app_id": "au4eosh5osaev2ohtoogahv5uivoh4Ea",
}

同步app的管理控制台

app控制台用于创建、删除和修改秀米同步app

https://xiumi.us/#/user/ownerpartnerbind
注意：以上入口需秀米用户登录后才能正常访问。否则创建app时会失败。

用户解绑的入口

目前解绑的入口没有公开在官网，秀米用户可以访问 https://xiumi.us/#/user/partnerbind 查看自己绑定的平台。此页面提供解绑功能。

修订历史

2.0.8
- 绑定接口增加“绑定名称”
2.0.7
- Q&A中补充了新内容
- 增加“用户解绑的入口”的说明
2.0.6
- 增加同步app的管理控制台入口
- 增加在线签名验证工具
- 增加签名的PHP代码示例
2.0.5
- 修正了“HTML接口”的articles数据结构
- 增加章节：用户绑定后同步图文的方式
- 增加对应用密钥的名词说明
- Q&A中补充了新内容
2.0.4
- 修正了“通知接口”的Authorization参数
2.0.3
- 修正了“新建或打开图文”的article_id参数
2.0.2
- 修正了“新建或打开图文”的URL路径
- 删除通知接口中未实现字段