メッセージは、エンドクライアントから ZOLOZ サーバーへのリクエストと、ZOLOZ サーバーからエンドクライアントへのレスポンスで構成されます。このセクションでは、リクエストとレスポンスの構造について説明します。

リクエスト構造

リクエストは標準の HTTP リクエストであり、Request-URI、メソッド、ヘッダー、および本文で構成されます。次の図は、HTTP リクエストの構造を示しています。

Request-URI

リクエストを適用するリソースを指定します。このヘッダーフィールド値の形式は /api/{version}/{restfulPath} です。ここで、

version はインターフェイスのバージョンです（例：v1）。
restfulPath はインターフェイスへのパスです。

リクエストメソッド

受け入れられるリクエストメソッドは POST のみです。

リクエストヘッダー

リクエストヘッダーには、リクエストとクライアントに関する追加情報が含まれています。ZOLOZ ゲートウェイプロトコルでは、次のヘッダーフィールドが含まれています。

Request-Time（必須）

リクエストの時刻を指定します。このフィールドの値は、次の 2 つの部分で構成される文字列です。

RFC 3339 日時標準に準拠した日付/時刻文字列
RFC 822 タイムゾーン標準に準拠したタイムゾーン文字列

例：2019-04-04T12:08:56+0530.

Content-Type（必須）

ZOLOZ サーバーに送信されるリクエスト本文のメディアタイプを指定します。ZOLOZ ゲートウェイプロトコルでは、次の 2 つのコンテンツタイプのみがサポートされています。

application/json; charset=UTF-8：リクエストが暗号化されていない場合に受け入れられます。
text/plain; charset=UTF-8：リクエストが暗号化されている場合に受け入れられます。

Content-Type フィールドの詳細については、「RFC 7231」を参照してください。

Client-Id（必須）

エンドクライアントに割り当てられているクライアント識別子を指定します。この ID は、アカウント作成時に ZOLOZ サーバーによって生成され、各エンドクライアントに対して一意であることが保証されています。このフィールドの値は 16 桁の文字列です。

Signature（必須）

メッセージの署名に関する情報を指定します。フィールドの値は、次の 2 つのキーと値のペアの組み合わせをコンマで区切ったリストです。

algorithm：リクエストの署名に使用されるアルゴリズム。RSA256 のみ受け入れられます。
signature：署名の内容。このキーの値は Base64 でエンコードする必要があります。

次の例は、有効な signature ヘッダーフィールドを示しています。

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

リクエストの署名と署名の検証の詳細については、「メッセージの署名と署名の検証」をご参照ください。

Encrypt（オプション）

メッセージの暗号化に関する情報。フィールドの値は、次の 2 つのキーと値のペアの組み合わせをコンマで区切ったリストです。

algorithm：リクエストの暗号化に使用されるアルゴリズム。RSA_AES のみ受け入れられます。
symmetricKey：RSA で暗号化された AES キー。このキーの値は Base64 でエンコードする必要があります。

次の例は、有効な encrypt ヘッダーフィールドを示しています。

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

リクエストの暗号化と復号の詳細については、「メッセージの暗号化と復号」をご参照ください。

リクエスト本文

リクエスト本文は、API の入力パラメーターを含むリクエストメッセージの内容を伝達するために使用されます。コンテンツの形式は、リクエストが暗号化されているかどうかによって異なります。

リクエストが暗号化されていない場合、メッセージの内容は JSON 形式の文字列です。この場合、Content-Type ヘッダーフィールドを application/json に設定する必要があります。
リクエストが暗号化されている場合、メッセージの内容は暗号化データに対して Base64 でエンコードされた文字列です。この場合、Content-Type ヘッダーフィールドを text/plain に設定する必要があります。

詳細なコンテンツ構造については、各 API の API 仕様を参照してください。

完全な HTTP リクエストの例

暗号化されていないリクエスト本文と暗号化されたリクエスト本文の 2 つの例を以下に示します。

暗号化されていないリクエストの例

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."
}

暗号化されたリクエストの例

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 レスポンスであり、HTTP ステータス、ヘッダー、および本文で構成されます。次の図は、HTTP レスポンスの構造を示しています。

HTTP ステータス

リクエストの処理ステータスを指定します。ZOLOZ ゲートウェイプロトコルは、標準の HTTP レスポンスコードを使用します。詳細については、「RFC 7231」を参照してください。

レスポンスヘッダー

Trace-Id

各 API 呼び出しに対して生成される一意の ID を指定します。

Response-Time

レスポンスの時刻を指定します。このフィールドの値は、次の 2 つの部分で構成される文字列です。

RFC 3339 日時標準に準拠した日付/時刻文字列
RFC 822 タイムゾーン標準に準拠したタイムゾーン文字列

例：2019-04-04T12:08:56+0530.

Content-Type

加盟店に返されるレスポンス本文のメディアタイプを指定します。次の 2 つのコンテンツタイプのみがサポートされています。

application/json; charset=UTF-8：レスポンスが暗号化されていない場合に受け入れられます。
text/plain; charset=UTF-8：レスポンスが暗号化されている場合に受け入れられます。

Content-Type フィールドの詳細については、「RFC7231」を参照してください。

Signature

メッセージの署名に関する情報を指定します。フィールドの値は、次の 2 つのキーと値のペアの組み合わせをコンマで区切ったリストです。

algorithm：リクエストの署名に使用されるアルゴリズム。RSA256 のみ受け入れられます。
signature：署名の内容。このキーの値は Base64 でエンコードする必要があります。

次の例は、有効な signature ヘッダーフィールドを示しています。

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

レスポンスの署名と署名の検証の詳細については、「メッセージの署名と署名の検証」をご参照ください。

Encrypt

メッセージの暗号化に関する情報。フィールドの値は、次の 2 つのキーと値のペアの組み合わせをコンマで区切ったリストです。

algorithm：リクエストの暗号化に使用されるアルゴリズム。RSA_AES のみ受け入れられます。
symmetricKey：RSA で暗号化された AES キー。このキーの値は Base64 でエンコードする必要があります。

次の例は、有効な encrypt ヘッダーフィールドを示しています。

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

レスポンスの暗号化と復号の詳細については、「メッセージの暗号化と復号」をご参照ください。

レスポンス本文

レスポンス本文は、API の出力パラメーターを含む、返されたメッセージの内容を伝達するために使用されます。コンテンツの形式は、レスポンスが暗号化されているかどうかによって異なります。

レスポンスが暗号化されていない場合、メッセージの内容は JSON 形式の文字列です。この場合、Content-Type ヘッダーフィールドを application/json に設定する必要があります。
レスポンスが暗号化されている場合、メッセージの内容は暗号化データに対して Base64 でエンコードされた文字列です。この場合、Content-Type ヘッダーフィールドを text/plain に設定する必要があります。

詳細なコンテンツ構造については、各 API の API 仕様を参照してください。

完全な HTTP レスポンスの例

レスポンス本文が暗号化されているかどうかによって、2 つのサンプルを以下に示します。

暗号化されていないレスポンスの例

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"
  }
}

暗号化されたレスポンスの例

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=