开发指南 重要

重要提醒

开发者在进行开放能力对接之前，请仔细阅读开发指南，并充分理解本指南中关于接口规则、接口调用流程的相关内容。

概述

1. API网关开放了丰富的能力接口，开发者可以借助接口能力，实现平台内置接口的集成。支持的能力，通过目录导航可以快速预览，目录树按功能块聚合归类，如消息中心、用户管理、待办中心等。
2. 文档的阅读次序，建议先阅读一遍开发指南，详细了解接入流程以及相关定义后，根据实际业务场景查看对应模块文档说明。
3. 该指南仅适用V2版接口！（V1接口只为兼容老版本，不再额外提供开放能力！）
4. 为增强接口能力，V2接口在后续版本中可能会追加新的字段，开发时需要考虑新字段的拓展，避免新增字段导致对接模块无法解析等问题。
5. 文档中，新增接口正常会标记对应的提供版本，老版本则无此接口，需要升级对应版本才能使用。（若在已有的接口中新增字段，正常未做版本标记，故调用时若发现客户环境中实际提供的接口字段比此文档描述的少，一般为版本差异，以客户实际环境为准！若需要对应的字段功能，需要客户环境升级至最新版本）
6. 接口文档中的示例，仅作为接口调用示例，接口调用时，请根据实际业务场景，替换接口参数。若文档描述及示例有误，欢迎提交小助手反馈。

阅读对象

本文阅读对象：集成网关涉及的技术架构师，研发工程师，测试工程师，系统运维工程师等。

接口规则

提示

所有规则如无特殊说明，以全局规则为准，如接口指定规则，则以接口规则为准。

参数兼容性

• 请求是否成功，与请求参数的顺序无关。
• 请求是否成功，与业务参数JSON中的键值对出现的顺序无关。
• 处理应答时，不应假设应答参数或业务参数JSON中的键值对出现的顺序。
• 请求或应答中可能会出现接口文档中未提及的字段，需支持未知参数，避免解析错误。

字符集

仅支持UTF-8字符编码的一个子集：使用一至三个字节编码的字符。也就是说，不支持Unicode辅助平面中的四至六字节编码的字符。

参数必填标记说明

必填标记	说明
M	强制项，不可为空
O	可选项，根据业务要求填制，可以为空
*M	特定的情况下必填
+M	请求成功时必填

参数组成说明

• 路径参数(Path)：路径参数为请求地址路径中的一部分内容，例如：https://www.example.com/user/{id}，在该示例中id即为路径参数，假设id的值为1，则最终请求的请求地址为：https://www.example.com/user/1。

• 查询参数(Query)：查询参数为请求地址中Query部分参数，以?拼接在原始请求路径字符串上，参数之间通过&连接，参数键值对之间使用=连接，假设请求地址为：https://www.example.com/user，查询参数名为：id，对应查询参数值为：1，则最终请求的请求地址为：https://www.example.com/user?id=1，如果参数中存在中文等特殊字符，需要对其进行URLEncoder处理，避免参数解析失败。

• 请求头(Request Header)：是指在HTTP请求中包含的键值对，用于传递请求的附加信息。请求头位于请求行之后，空行之前，包含了很多有用的信息，如客户端类型、请求数据的格式、缓存指令等。常见的HTTP请求头字段及说明如下：

  • User-Agent：标识发起请求的客户端应用程序的类型、操作系统、软件版本等信息。示例：User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36。
  • Content-Type：说明请求体的MIME类型。示例：Content-Type: application/json。
  • Referer：指明请求来源的URL。示例：Referer: https://www.example.com。
  示例

  GET /example.com HTTP/1.1
  Host: www.example.com
  User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36
  Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
  Accept-Language: en-US,en;q=0.9
  Accept-Encoding: gzip, deflate, br
  Connection: keep-alive

• 请求体(Body)：仅在某些请求方法（如 POST、PUT）中存在，用于传输数据。请求体的内容类型由 Content-Type 请求头字段指定。常见的内容类型包括：

  • application/x-www-form-urlencoded：默认的表单提交类型，数据格式为键值对。

    示例

    POST /api HTTP/1.1
    Host: example.com
    Content-Type: application/x-www-form-urlencoded
    
    field1=value1&field2=value2

  • multipart/form-data：用于文件上传，数据格式为多部分编码。

    示例

    POST /upload HTTP/1.1
    Host: example.com
    Content-Type: multipart/form-data; boundary=----    WebKitFormBoundary7MA4YWxkTrZu0gW
    
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="file"; filename="example.txt"
    Content-Type: text/plain
    
    (file content here)
    ------WebKitFormBoundary7MA4YWxkTrZu0gW--

  • application/json：用于发送 JSON 格式的数据。

    示例

    POST /api HTTP/1.1
    Host: example.com
    Content-Type: application/json
    
    {
      "name": "John Doe",
      "age": 30
    }

  • text/plain：发送纯文本数据。

数据交互 重要

V2接口中数据交互过程中存在公共数据交互要求，如接口无特殊说明，则全部遵守本规范，除公共约束外的具体的业务参数说明见对应API文档说明。

公共请求头

字段名	参数名	必填	类型	描述
应用ID	appId	M	String(128)	接入网关的应用ID
Token	accessToken	M	String	接入网关的accessToken

提示

• CASP相关接口: 如业务API无特殊说明，除获取AccessToken接口外，其余接口皆需要传递上述公共请求头信息。若API接口中有其他请求头需要上送，除非API接口中明确标注不需要公共请求头部分，否则API请求头与公共请求头都需要上送。
• CIAP相关接口: 不涉及此部分
• Smart相关接口: 不涉及此部分，参照文档独立实现

HTTP状态码

常见的HTTP状态码见下表。

状态码	错误类型
200 - OK	请求成功，服务器返回所请求的资源
202 - Accepted	服务器已接受请求，但尚未处理
204 - No Content	服务器成功处理了请求，但没有返回任何内容
301 - Moved Permanently	请求的资源已被永久移动到新位置，响应中应包含新的URI
302 - Found	请求的资源临时移动到新位置
304 - Not Modified	请求的资源未修改，客户端可以使用缓存的版本
400 - Bad Request	协议或者参数非法
401 - Unauthorized	请求要求用户认证
403 - Forbidden	服务器拒绝请求，客户端没有权限访问资源
404 - Not Found	请求的资源不存在
405 - Method Not Allowed	请求方法被禁止
409 - Conflict	请求与资源的当前状态发生冲突
429 - Too Many Requests	请求超过频率限制
500 - Server Error	服务器内部错误，无法完成请求
502 - Bad Gateway	服务下线，暂时不可用
503 - Service Unavailable	服务不可用，过载保护
504 - Gateway Timeout	服务超时

接口调用流程

1. 应用调用具体业务接口需要使用accessToken，若accessToken信息不存在或已过期，则需要重新获取。
2. 获取到accessToken信息后需要将其按照过期时间进行缓存以便于后续请求使用。

提示

• CASP相关接口: 不能频繁调用获取AccessToken接口，否则会判定为恶意请求受到频率拦截。
• CIAP相关接口: 不涉及此部分
• Smart相关接口: 不涉及此部分，参照文档独立实现

错误码规范

• 错误码（正常为6位字符）详见各个章节。
• 注：若错误码为"999" 代表统一错误码，对应错误信息参见接口实际返回的描述信息。

错误码示例

错误码	描述
111001	必填参数不能为空
111002	请求参数格式错误，例如：参数值不在要求范围内
999	统一错误码，详细描述信息参见接口返回

提示

• CASP相关接口: 参照此部分规则
• CIAP相关接口: 不涉及此部分
• Smart相关接口: 不涉及此部分，参照文档独立实现

文档标记说明

在API接口文档中，由于版本的迭代会导致部分API或参数为CASP指定版本新增或不推荐使用的参数，标记示例如下：

3.6.1.Beta2+：表示从3.6.1.Beta2版本开始新增

3.6.1.Beta2-：表示从3.6.1.Beta2版本开始不推荐，标记为过时

提示

在对接过程中应避免选择已经标记为过时的接口或参数。