秀米图文同步接口文档 2.0.8

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

概念

名词

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

Q & A

  1. 秀米的官网账号的作用
    • 平台管理员需要一个秀米的官网账号来管理自己的app。
    • 用户需要登录自己的秀米的官网账号来绑定和使用秀米的所有功能,包括同步功能
  2. 一个秀米账号可以创建几个app?
    可以创建多个app,每个app可以配置不同的参数,对接不同的系统(平台)。当然,不同的app也可以配置相同的参数。另外,同一个实体(企业和个人)可以创建多个app。
  3. 在哪里创建app?
    在同步app管理控制台,URL见本文档。
  4. 任何秀米用户都可以创建app吗?
    是的,所有的秀米用户都可以创建自己的同步app,并提供给其他秀米用户绑定和使用。
  5. 审核主要审核什么内容?
    • 接口query string或path等参数不得包含secret。
    • 由于secret会在header中传输,所以接口应使用https。测试阶段可以暂时使用http,上线后继续使用http,可能会被禁用。
    • 不能使用类似https://mp.weixin.qq.com 等其他公开平台的域名
    • app名称是否符合法律法规要求,不能使用“微信公众号”等容易被误解或混淆的名称。
    • 审核时需提供企业或个人的身份证明以存档。
  6. 提交审核后,要等多久?
    一般在1到2个工作日内审核完毕。审核的结果会通过秀米站内信发送。由于提交审核后要等待审核结束后才能再次修改,请谨慎提交。
  7. 提交审核期间,接口可以正常使用吗?
    审核期间,秀米会继续使用旧的接口。如果审核通过,秀米会立即切换为新接口;如果审核驳回,接口不会发生变化。
  8. 每次修改app都要审核吗?
    是的。
  9. 每次同步时都会将图文内的图片全部传输一次吗?
    是的。
  10. 同步app费用是多少?
    目前暂不收费。未来会按app收费,预计200元/app/年。
  11. 每个同步app可以绑定多少用户?
    目前每个app最多绑定1000个秀米用户
  12. 能否在秀米的打开图文网页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字符串。
appid 在创建秀米同步app时获得的app id。
nonce 随机字符串,由您的平台在每一次签名时生成,使用于签名算法内。
timestamp 当前UNIX时间戳,单位:秒。需不早于当前时间5分钟。
signature 根据各项参数计算得出的签名字符串。算法见下面的说明。
bind_name 绑定名称,非必需字段,少于20个汉字,建议少于10个汉字。如果传递了bind_name,秀米会在导出菜单中显示“同步到「bind_name」,如果不传递bind_name,秀米会在导出菜单中显示“同步到「app_name」。

signature计算方法

  1. 将secret,timestamp,nonce,partner_user_id四个参数的值转换为字符串。保持所有字符串的大小写不变。
  2. 以字符串形式由低到高排序。
  3. 然后将四个字符串依次连接为一个字符串。
  4. 将这个字符串用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

平台发起图文编辑流程

%%{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 -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 查看自己绑定的平台。此页面提供解绑功能。

修订历史