ZOLOZZOLOZDOCS

报文结构

报文包括终端客户端发送到ZOLOZ服务器的请求报文，以及ZOLOZ服务器发送到终端客户端的响应报文。本文介绍请求报文和响应报文的结构。

请求报文的结构

ZOLOZ采用的是标准的HTTP request请求格式，请求由以下几部分组成：

HTTP请求结构如下图所示：

image.png

Request-URI

Request-URI指应用请求的资源，字段值格式为/api/{version}/{restfulPath}。

  • version：接口版本，例如v1。
  • restfulPath：接口路径。

Request Method

Request Method指请求方法，请求方法仅支持POST。

Request Header

Request Header指请求头，包含了请求和客户端的附加信息，ZOLOZ网关协议包括以下header字段。

header字段

是否必须

描述

Request-Time

必须

请求时间。该字段值为字符串，例如2019-04-04T12:08:56+0530。由以下两部分组成：

Content-Type

必须

发送给ZOLOZ服务器的请求正文的格式类型。ZOLOZ网关协议仅支持以下两种内容格式：

  • application/json; charset=UTF-8：适用于未加密请求。
  • text/plain; charset=UTF-8：适用于加密的请求。

有关Content-Type字段的更多信息，请参见RFC 7231。

Client-Id

必须

分配给终端客户端的客户端标识符，该字段值为16位字符串。此ID在创建账号时由ZOLOZ服务器生成，且每个终端客户端的ID具有唯一性。

Signature

必须

报文签名相关信息。该字段值为列表，由以下两个键值对组成，用英文逗号隔开。

  • algorithm：用于请求签名的算法，仅支持RSA256。
  • signature：签名内容，键值必须采用Base64编码。

有关签名请求和验证签名的更多信息，请参见报文签名和签名验证。

Encrypt

可选

报文加密信息。该字段值为列表，由以下两个键值对组成，用英文逗号隔开。

  • algorithm：用于加密请求的算法，仅支持RSA_AES。
  • symmetricKey：以RSA加密的AES密钥，键值必须采用Base64编码。

有关加密和解密请求的更多信息，请参见报文加密和报文解密。

以下是一个有效的signature header字段示例：

copy
signature: algorithm=RSA256, signature=IpmAgtDqkjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCkw==

以下是一个有效的encrypt header字段示例：

copy
encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

Request Body

Request Body指请求正文，用于携带请求报文内容，包含API的输入参数。未加密请求和加密请求的内容格式不同。具体如下：

  • 未加密请求的报文内容为JSON格式的字符串，Content-Type header字段必须设置为application/json。
  • 加密请求的报文内容是采用Base64编码加密数据的字符串，Content-Type header字段必须设置为text/plain。

有关内容结构的更多信息，请参见各API接口文档。

完整的HTTP request示例

  • 未加密请求示例
copy
POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m

{
  "title": "hello",
  "description": "just for demonstration."
}
  • 加密的请求示例
copy
POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: text/plain; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m
Encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

r8w8wbc8Nv6sC2meJzArtGjDkbiAzg55UaDiq7TId1a7uzcv18qpOxVkXvqa3q/6TPemDDItZ79oHMzDJyvAngYqfpZZaedArWPCDeddqUl62zU5VwaB1NVhNmjHLNQ6bA1LxpsnMGnb6n8iWAEU4MtJ3TpXerMY6RToSBbI/IBA4MJFbXds0z6XLqQh9XNrLL/J0FUSV0XGFiBRxVMvUP2ytzEKh9HE6fqX/ZqTqadtp89PRTJZM87Rkb3oPdJAlaM7JUaIznGrtKe45UwjtrdYk86QhOmpWXj4L2g0Gww=

响应报文的结构

ZOLOZ采用的是标准的HTTP response响应格式，响应由以下几部分组成：

HTTP响应结构如下图所示：

image.png

HTTP status

HTTP status指请求的处理状态，ZOLOZ网关协议使用的是标准的HTTP response代码。更多信息，请参见RFC 7231。

Response Header

Response Header指响应头，包括以下header字段。

header字段

描述

Trace-Id

为每个API调用生成的唯一ID。

Response-Time

响应时间。该字段值为字符串，例如2019-04-04T12:08:56+0530。由以下两部分组成：

Content-Type

返回给商户的响应正文的格式类型。仅支持以下两种内容格式：

  • application/json; charset=UTF-8：适用于未加密响应。
  • text/plain; charset=UTF-8：适用于加密响应。

有关Content-Type字段更多信息，请参见RFC7231。

Signature

报文签名相关信息。该字段值为列表，由以下两个键值对组成，用英文逗号隔开。

  • algorithm：用于请求签名的算法，仅支持RSA256。
  • signature：签名内容，键值必须采用Base64编码。

有关签名响应和验证签名的更多信息，请参见报文签名和签名验证。

Encrypt

报文加密信息。该字段值为列表，由以下两个键值对组成，用英文逗号隔开。

  • algorithm：用于加密请求的算法，仅支持RSA_AES。
  • symmetricKey：以RSA加密的AES密钥，键值必须采用Base64编码。

有关加密和解密响应的更多信息，请参见报文加密和报文解密。

以下是一个有效的signature header字段示例：

copy
signature: algorithm=RSA256, signature=QexLgtKpdjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCky++

以下是一个有效的encrypt header字段示例：

copy
encrypt: algorithm=RSA_AES, symmetricKey=HnI+keXgI9eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC00++

Response Body

Response Body指响应正文，用于携带响应报文内容，包含API的输出参数。未加密响应和加密响应的内容格式不同。具体如下：

  • 未加密响应的报文内容为JSON格式的字符串，Content-Type header字段必须设置为application/json。
  • 加密响应的报文内容是采用Base64编码加密数据的字符串，Content-Type header字段必须设置为text/plain。

有关内容结构的更多信息，请参见各API接口文档。

完整的HTTP response示例

  • 未加密响应示例
copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15+0800
Signature: algorithm=RSA256, signature=SGnqy/sC1sbrfK+jAl0ATJwtqUg4jUhkqpPheEYPgnM+20P69NsdrL8BB/ml5ehfFVzsst1bzwEYpDNZvqqNSBo2BPVg78pjJEk0GGNIu7NQ/pyRncYy3pIIXvr91lIvINysHcw8AgUEXRLtjMf1ktQN2OsA3+OFKB6Cf7BrKNnxjeF1lSjzbTk2ua+z1unGHUOeA9GBloSL3rL8ngC/Zqn24/eHWyKJrMFnq1jv+IhOVCqeY4knVFcPgp/bFBs4gyTdE1G1fCK5xmzk9Co8dK0wr6KcC872evBGz7SCMYZCn6Y8O5uRqS9I6F26yKKdqw8PZv2rlwJFsX21l7wRSQ==

{
  "title": "hello",
  "description": "just for demonstration."
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}
  • 加密的响应示例
copy
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Response-Time: 2019-02-23T01:45:57+0000
Signature: algorithm=RSA256, signature=imNNW52LHemfAiUFqek4QQg3ZkdHBGEUOs2SBx0OxPGBIBC0bmpu0%2BviBH%2Bh9w86VTooveJmKQSBVIf0i7hQWXqyd5Qibz49d4k9AhIhTjBKQF1VZTlJUrlphWvisSa9zn5wl3P74v9Z4CDVvHfL3wZzfwg8ujo13nSYjYdsswhSZwkGUgkSCDjq2ObtsPMHG6ZRuzrTjW6tCrqTe6EY4HyHg1mWnsAj12i1b%2FnKNayP%2FCpAe%2BT0%2Fn66NeLGjR9hjTYJ8XKKNoZ5vW%2BVYjWiDt8XWSb3KEO2Zh5Cofswe85sVPnk2S%2BvbN0nlPNU0zlJJJK6ifoSyl%2FSKI6Siu05xw%3D%3D
Encrypt: algorithm=RSA_AES, symmetricKey=eXhw3n3fdpfruNv2kh9cJQ4NzqhNhjKjCynAu6Kn92p0WPY77d8DHJV5Y4QE9fShsW%2FYZIVhCtiZSC2bBS%2F1m9HnCwhKiWzKWTwo44J692DU%2B24Yty%2FHTalqD7QWoOOd0HCskrKFHgf4INE9PMskGnZbp4B7yuLmaUEtuo8FIFNB4e%2FCIL1DhBMdsgcYL%2FiWLylNbpXztE8kMVjoEeOsz%2FbBr3Z22A4%2BQveAIDEc5sr9cjkzCB2gJsjNt4bZUWiZfP8BPLV0QEEh9mhmqzprNao2x9DsuShFcjyc3db%2BZcbMOuI8NxI0V%2FwTDi23%2BloH6Q1Mg0QgWFORlJG9da8s7Q%3D%3D

0JR682PMFgoc2ttribGxpl3f/7rNvjwpmoaAvahki1RxWUSO6mKxyQf87OUgQxQULGabLL4Q5vjFx8XvW/ugvpFexfqLojDeMgNMTyJpkT8=