報文包括終端用戶端發送到ZOLOZ伺服器的請求報文，以及ZOLOZ伺服器發送到終端用戶端的響應報文。本文介紹請求報文和響應報文的結構。

請求報文的結構

ZOLOZ採用的是標準的HTTP request請求格式，請求由以下幾部分組成：

Request-URI：應用請求的資源。
Request Method：要求方法。
Request Header：要求標頭。
Request Body：請求本文。

HTTP請求結構如下圖所示：

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`。由以下兩部分組成：日期和時間字串，遵循RFC 3339 datetime standard。時區字串，遵循RFC 822 timezone standard。
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欄位樣本：

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

以下是一個有效encrypt header欄位樣本：

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-Typeheader欄位必須設定為application/json。
加密請求的報文內容是採用Base64編碼加密資料的字串，Content-Typeheader欄位必須設定為text/plain。

有關內容結構的更多資訊，請參見各API介面文檔。

完整的HTTP request樣本

未加密請求樣本

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

{

加密的請求樣本

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 status：請求的處理狀態。
Response Header：回應標頭。
Response Body：響應本文。

HTTP響應結構如下圖所示：

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`。由以下兩部分組成：日期和時間字串，遵循規範RFC 3339 datetime standard。時區字串，遵循規範RFC 822 timezone standard。
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欄位樣本：

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

以下是一個有效encrypt header欄位樣本：

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-Typeheader欄位必須設定為application/json。
加密響應的報文內容是採用Base64編碼加密資料的字串，Content-Typeheader欄位必須設定為text/plain。

有關內容結構的更多資訊，請參見各API介面文檔。

完整的HTTP response樣本

未加密響應樣本

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==

{

加密的響應樣本

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/ugvpFexfqLojDe