[TOC]
# 创客贴 API 文档 1.6.1
## Demo
[在线预览](https://www.chuangkit.com/apidemo)
## 示例代码
[点击下载](https://static.chuangkit.com/document/demo/chuangkitApiClientSample.zip)
## 使用
### 引入 SDK
方式一：
在网页的`<body>`中任意位置写入以下代码：
```html
<script>(function(d,s,a){var w=d.createElement(s),s=d.getElementsByTagName(s)[0];w.src=a;s.parentNode.insertBefore(w,s);})(document,'script','https://static.chuangkit.com/api/v4.1.3.js');</script>
```
方式二：
```sh
npm install @chuangkit/chuangkit-design
```
### 调起
组装调起创客贴 API 所需的参数对象（参数主要来控制创客贴 API 调起后的形态，比如画布尺寸），对象写法如下（对象中支持参数说明见 [附录](#appendix)）：
```js
var option = {
"data-access": "",
"data-exp": "",
"sign": "",
"signType": ""
}
```
调起创客贴 API 之前须进行实例化，如下：
方式一：
```js
var cktIframe = new ChuangkitIframe(option)
```
方式二：
```js
import cktDesign from "@chuangkit/chuangkit-design"
var design = new cktDesign(option)
```
实例化后即可在需要时调起创客贴 API：
```js
cktIframe.openIframe()
// 方式一
design.openIframe() // 方式二
```
如需关闭，方法如下：
```js
cktIframe.closeIframe() // 方式一
design.closeIframe() // 方式二
```
## 数据返回
在页面 js 中定义全局方法 chuangkitComplete 之后可以从调起的创客贴 API 得到数据，如下：
```js
window.chuangkitComplete = function(data){
console.log(data);
}
```
data 为返回的数据对象，返回值说明如下：
|参数名|必有|类型|说明|
|:--|:--|:--|:--|
|cktMessage|是|boolean|判断是否是创客贴 API 的返回|
|kind|是|number|1：保存设计成功；2：生成缩略图成功；-1：错误|
|design-id|是|string|本次调起创客贴 API 使用的设计 ID|
|thumb-urls|kind 为 2 时必有|array|生成的图片缩略图地址|
|source-urls<sup style="color: red;">new</sup>|kind 为 2 且初始化参数 data-definition 为 1 时必有|array|生成的原图地址
|thumb-exp|kind 为 2 时必有|number|thumb-urls 有效时长(秒)|
|error|kind 小于 0 必有|string|报错说明|
## 原图换取
> 自 v4.1.1 版本开始，通过增加初始化参数 data-definition: 1 可直接返回原图，无需再使用本功能。
如果返回数据中的图片不能满足使用要求，可调用换取原图接口（仅供后端服务器调用，前端不可用）。
### 请求URL：
- `https://openapi.chuangkit.com/api/getSourceImage.do`
### 请求方式：
- POST
### 参数：
|参数名|类型|必选|默认值|说明|
|:--|:--|:--|:--|:--|
|appId|string|是| |创客贴分配的企业 appId|
|designId|string|是| |设计 ID|
|fileType|int|是||请求的文件类型（0:jpg; 1:png; 2:pdf）|
|noticeUrl|string|是| |异步通知地址（创客贴服务器完成图片处理后会向该地址推送信息）|
|sign|string|是||参数签名（签名生成方式详见 [附录 参数签名生成方式](#sign)）|
|signType|string|是||加密算法，目前仅支持 ( MD5 )|
### 接口请求同步返回参数示例
```json
{
"code":200
}
```
### 接口请求同步返回参数说明
|参数名|类型|必有|说明|
|:--|:--|:--|:--|
|code|int|是|执行结果状态码（10000参数不合法；10001appId参数错误；10002designId参数错误；10005sign参数错误；10007接口调用凭证超时；200操作成功）|
### 异步通知申请结果
#### 异步通知示例
异步通知时，创客贴服务器会以 POST 请求的方式请求 noticeUrl，携带包含参数内容的 JSON 字符串，通知参数示例如下：
```json
{
"downloadUrl":[
"https://www.chuangkit.com/xxx/xxx"
],
"fileType":0,
"designId":"xxx-xxx-xxx",
"downloadUrlExp":3600,
"code":200
}
```
#### 异步通知时携带参数说明
|参数名|类型|必有|说明|
|:--|:--|:--|:--|
|code|int|是|执行结果状态码|
|downloadUrl|array|code=1 必有|文件下载地址|
|fileType|int|code=1 必有|生成的文件类型（0:jpg; 1:png; 2:pdf）|
|designId|string|code=1 必有|设计 ID|
|downloadUrlExp|int|code=1 必有|下载地址有效时长（秒）|
<a id="appendix"></a>
## 附录
<a id="init-params"></a>
### 初始化参数说明
> 目前已知 Microsoft Edge 等浏览器渲染个别字符存在问题，导致从本文档复制的参数在后续签名后验证不通过，若排查参数名无误后仍然报错，请更换 PDF 浏览器或手动输入参数名
|参数名|必选|类型|默认值|说明|
|:--|:--|:--|:--|:--|
|data-access|是|string||企业 appId（创客贴提供）|
|data-exp|是|timestamp||参数生效截止时间的毫秒时间戳（自定义，须晚于当前时间，超过该时间后再调起创客贴 jssdk 将无法通过通过权限校验）|
|sign|是|string||参数签名（签名生成方式详见 [附录 参数签名生成方式](#sign) ）|
|signType|是|string||加密算法，目前仅支持（MD5 ）|
|data-ext-ref-user-flag|是|string||用于**保留用户资产（制作的设计、购买的模板等）**，不传该参数则每次调用均创建临时账户。保证该标识与贵平台的用户一一对应即可，推荐使用贵平台用户的用户 ID|
|data-template-id|data-template-id、data-design-id、data-width、data-kind 只能选其一且必选其一|number||使用指定模板创建设计|
|data-design-id|data-template-id、data-design-id、data-width、data-kind 只能选其一且必选其一|string||已存在的设计ID（修改设计时使用该参数）|
|data-kind|data-template-id、data-design-id、data-width、data-kind 只能选其一且必选其一|number||创建画布所使用的场景（创客贴 kindId 查询见 [附录 场景对应表](#scenelist)）|
|data-width|data-template-id、data-design-id、data-width、data-kind 只能选其一且必选其一|number||自定义尺寸创建画布时画布的宽度|
|data-height|使用 data-width 参数时必选|number||自定义尺寸创建画布时画布的高度|
|data-unit|使用 data-width 参数时必选|string||自定义尺寸创建画布时画布的单位,可选值（px 或 mm）|
|data-zIndex|否|number|10000|创客贴弹窗的 z-index|
|data-imgkind|否|number|1|生成图片的 content-type（1：可下载文件的content-type；2：图片格式对应content-type）|
|upload-img|否|string||需要上传到创客贴的图片 URL|
|data-upload-img-width|使用 upload-img 时必选|number||上传到创客贴的图⽚放入创客贴画布中时展示的宽度，该值必须大于 0|
|data-upload-img-top|否|number||上传到创客贴的图⽚放入创客贴画布中时与创客贴画布顶部的距离，该值必须大于 0|
|data-upload-img-left|否|number||上传到创客贴的图⽚放入创客贴画布中时与创客贴画布左侧的距离，该值必须大于 0|
|data-finish-btn-name|否|string||自定义创客贴“完成” 按钮显示的内容，该值长度必须为两个字符|
|data-charged-template-show|否|number|0|是否显示创客贴付费模板（0：不显示；1：显示）|
|data-definition|否|number|0|生成图片清晰度（1：高清；0：普清）|
|data-allow-login|否|number|0|是否允许创客贴用户登录（1：允许；0：不允许）|
|data-auto-save|否|number|1|是否允许自动保存（1：允许；0：不允许）|
**注意：** data-charged-template-show 为 1 时 **必须** 传入 data-ext-ref-user-flag，否则用户清除浏览器缓存后无法再次使用已购买过的模板。
### 附加参数说明
|参数名|必选|类型|默认值|说明|
|:--|:--|:--|:--|:--|
|data-extra-add-text-list|否|json||上传到创客贴的文字列表（多个文字字符串的数组转成 json，比如 "['文字一','文字二','文字三']" ）|
|data-extra-add-img-list|否|json||上传到创客贴的图片列表（多个图片地址的数组转成 json，比如 "['url1','url2','url3']" ）|
|data-extra-add-svg-frame|否|string||上传到创客贴的吸附框列表（a:圆形；b:正方形；c:长方形，比如想添加一个圆形和一个正方形 'ab'）|
|data-extra-template-search-keyword|否|string||调起设计页时候默认展示关键词相关模板|
**注意：** 附加参数不参与参数签名
<a id="sign"></a>
### 参数签名生成方式
#### 筛选并排序
获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除 sign 字段和 signType 字段，剔除值为空的参数，并按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推。
#### 拼接
将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用 & 字符连接起来，然后在字符串末尾拼接上用户私钥（创客贴提供），此时生成的字符串为待签名字符串。
例如下面的请求示例：
假设请求信息如下，用户私钥为 abcdefg
```
REQUEST URL: https://openapi.chuangkit.com/xxx/xxxx
REQUEST METHOD: POST
CONTENT:
a=1
b=20
c=300
```
则待签名字符串为：
```js
a=1&b=20&c=300abcdefg
```
#### 调用签名函数签名
MD5 方式：使用各自语言对应的 MD5 签名函数对待签名字符串进行签名，生成大写 32 位 MD5 签名结果。
上述示例签名结果即为：03564928A5126990E773BE7BB5714B6A
### 全局状态码含义
|代码值|说明|
|:-----|-----|
|200|成功|
|10001|appId 参数错误|
|10002|designId 参数错误|
|10003|fileType 参数错误|
|10004|noticeUrl 参数错误|
|10005|sign 参数错误（若一直报错，请按[初始化参数说明](#init-params)的提示尝试解决）|
|10006|欠费|
|10007|data-exp 参数错误|
|10008|data-kind 参数错误|
|10009|data-width 参数错误|
|10010|data-height 参数错误|
|10011|data-imgkind 参数错误|
|10012|data-design-id、data-kind、data-width 参数必选其一|
<a id="scenelist"></a>
### 场景对应表
[点击查看](https://www.chuangkit.com/apidemo#scene-list)
## 常见问题
### Safari 浏览器中调起时只有灰色蒙层
原因：使用 iframe 方式加载第三方网页时，新版 Safari 默认禁止第三方 Cookie，导致创客贴无法正常使用
解决方案：使用 SDK 的 `setCookie` 方法（接受一个必选参数：redirectUrl）。该方法将做如下操作：
1. 重定向到创客贴中转页
2. 设置 Cookie
3. 跳转回原页面，并增加 "hasCookie=1" 的 queryString
调用方根据 `hasCookie` 设置标志，下次调用时判断若有标志则无需再调用 `setCookie` 走上述流程
