基本信息

财资云 API 遵循 RESTful 设计规范，使用面向资源的 URL、标准 HTTP 响应码、HTTP 方法和身份验证。
财资云 API 支持行业通用的OpenAPI Specification 规范，请求和响应参数支持 JSON Schema 规范，开发者可使用开源生态工具进行开发及调试。

身份认证

财资云 API 通过数字签名方式对调用方进行身份验证。请求发起阶段，开发者需要使用应用私钥对请求内容进行签名，财资云会使用应用公钥验证请求签名，以确保请求由开发者发出；同样的，在响应阶段，财资云会使用财资云私钥对响应结果进行签名，开发者需要使用财资云公钥验证签名，以确保响应由财资云发出。
身份信息需要通过请求的请求头Authorization字段传递，对应值可以参考签名规则
应用私钥代表应用身份，请确保私钥的安全，不要在 GitHub、客户端代码等公共可访问区域共享应用私钥。
所有的 API 请求必须使用 HTTPS，不应忽略服务器证书验证的错误，避免被恶意劫持。

请求规范

基本信息

财资云 API 协议使用 RESTful 风格请求，接口请求需要使用对应的 HTTP 方法，具体请参考业务接口文档。
动词覆盖说明：对于部分代理场景，不支持 PUT、PATCH、DELETE 等操作，可以使用 POST 发送请求，同时携带 HTTP header X-HTTP-Method-Override 来传输实际需要使用的 HTTP Method。

数据格式

财资云 API 使用JSON作为消息体的数据交换格式。请求须设置 HTTP 头部：
Content-Type: application/json
Accept: application/json
加密请求和文件上传 API 除外。
API 应答中的数据有可能包含商家传入的数据，即可能是未经检查的用户输入内容。为了避免 XSS（Cross-site scripting）攻击，请调用方在使用应答数据前根据场景做适当的转义或者过滤。

请求的唯一标识

在财资云 API 协议中，每次请求需要有唯一请求标识。当需排查问题时，可以像技术支持提供请求的唯一标识，以便我们更快的定位到具体的请求。
企业发起请求时，可以传递请求唯一标识，请求的唯一标识包含在请求的 HTTP 头 cfs-request-id 中，允许包含 a-zA-Z0-9-_ 字符，长度限制 32 位。
财资云返回响应时，会对请求分配唯一请求标识，请求的唯一标识包含在响应的 HTTP 头 cfs-trace-id 中，包含 a-zA-Z0-9-_ 字符，长度不超过 32 位。

字符集

财资云 API 使用仅支持 UTF-8 字符集，请求可以在 content-type 中显示指定使用 UTF-8，未指定则默认未 UTF-8 编码。

文件上传

财资云 API 支持文件上传功能，在使用文件上传接口时，HTTP 请求需要使用 multipart/form-data 格式，具体可参考 RFC2388 规范。传输文件时，HTTP 请求 body 会分为多个 part，其中业务参数需要通过 bizContent 字段传递，其格式为 JSON，content-type 使用 application/json，其他 part为文件内容，content-type 应为具体的文件格式。
文件上传示例如下：

错误处理

财资云 API 使用 HTTP 状态码来表示请求处理的结果。
• 业务请求处理成功，财资云返回 200。
• 财资云内部的服务系统错误，将返回 500 的状态码，对该类错误需要重试。

错误码和错误提示

当请求处理失败时，财资云会在消息体返回更多错误描述内容。

code：详细错误码，参考接口描述及公共错误码，企业需要对该错误码处理。

msg：错误描述，具体错误原因的文字描述，开发者可参考该描述判断错误原因。

错误示例

{
    "code": "102004",
    "msg": "缺少时间戳参数"
}

基本原则

基本信息#

身份认证#

请求规范#

基本信息#

数据格式#

请求的唯一标识#

字符集#

文件上传#

错误处理#

错误码和错误提示#

错误示例#

基本信息

身份认证

请求规范

基本信息

数据格式

请求的唯一标识

字符集

文件上传

错误处理

错误码和错误提示

错误示例