Merge pull request #5 from zaifdotjp/develop

Develop
zaifdotjp · Oct 31, 2023 · fd5b233 · fd5b233
2 parents c32b2b3 + c7ab36b
commit fd5b233
Show file tree

Hide file tree

Showing 5 changed files with 80 additions and 31 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+#
+# # Required
+version: 2
+
+# # Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: requirements.txt
diff --git a/docs/PaymentAPI.md b/docs/PaymentAPI.md
@@ -57,8 +57,9 @@ method APIメソッド名 get_info
 ```
 
 ``` Note::
-	メソッド毎の固有のパラメータも全てPOSTパラメータにて送信してください。
-	nonceパラメータの値は実効毎に増分されていないとエラーが発生します。また、増分量は少数点以下の値にも対応しております。
+  メソッド毎の固有のパラメータも全てPOSTパラメータにて送信してください。
+  nonceパラメータの値は実効毎に増分されていないとエラーが発生します。また、増分量は少数点以下の値にも対応しております。
+  ミリ秒まで含むunixtimeを使うと比較的簡単にAPIを呼び出すことができますが、多重送信の防止と呼び出し順序にnonceパラメータを使用して呼び出しの管理をすることを検討してください。
 ```
 
 ### 戻り値
@@ -87,7 +88,7 @@ return  実行結果   dict or string
 ======================================== ===================================================================
 nonce not incremented                    前回API実行時よりnonce値が加算されていません。
 account has not permission to use ec api アカウントが決済APIを使用する権限がありません。
-invalid parameter \{\}                     パラメータが不正です。
+invalid parameter \{\}                     パラメータ\{\}が不正です。
 ======================================== ===================================================================
 ```
 
@@ -99,12 +100,14 @@ invalid parameter \{\}                     パラメータが不正です。
 
 **インボイスの表示**
 
-作成したインボイスから支払フォームを表示することにより、利用者からBitcoin/Monacoinによる支払いを促します。 支払いフォームのURLは以下の通りです。
+作成したインボイスから支払フォームを表示することにより、利用者から暗号資産による支払いを促します。 支払いフォームのURLは以下の通りです。
 
 https://zaif.jp/invoice/form/{invoiceId}
 
 {invoiceId}はインボイスの作成時に発行されたIDになります。 下記のようにしてiframeによる表示を行うことも可能です。
 
+https://zaif.jp/invoice/iframe/{invoiceId}
+
 ```
 <iframe id="zaif_ec_iframe"
 scrolling="no"
@@ -133,9 +136,10 @@ style='width:500px; overflow: hidden; padding:10px;'></iframe>
 パラメータ         必須 詳細                                                                                                                                    型  例
 ================== ==== ======================================================================================================================================= === ================
 method             Yes  createInvoice                                                                                                                           str 
-speed              No   決済完了とみなすスピード。                                                                                                              str high medium low
+speed              No   （廃止済み）決済完了とみなすスピード。                                                                                                              str high medium low
 notificationUri    No   決済完了したタイミングでの通知先URI 事業者様のECサイトシステムに通知を行うためのものになります。                                        str 
 notificationMethod No   決済完了したタイミングでの通知先URIへ通知する際に使用されるHTTPメソッド。デフォルトはPOSTになります。                                   str GET または POST
+webhookUrl         No   決済の状態が変化したタイミングでwebhook通知を送信する先のURL。事業者様のECサイトシステムに通知を行うためのものになります。                                        str 
 redirectUri        No   決済フォームで着金後、ECサイトへ戻るためのリダイレクト先のURI。設定されなかった場合はリダイレクトせず着金後のステータスが表示されます。 str 
 currency           Yes  決済に使用する暗号通貨                                                                                                                  str btc または mona
 amount             Yes  決済金額（日本円）。実際の請求対象金額。1円単位、カンマ無し。                                                                           int 
@@ -161,15 +165,21 @@ buyerEmail         No   利用者メールアドレス
 ```
 
 ``` Note::
-	speed（決済スピード）について
+  speed（決済スピード）について
+
+  speedパラメーターについては2022年の再開以降無効となり、high/mediaum/lowどのパラメーターを指定しても共通で下記のような状態推移となります。
+
+  決済の有効期限はインボイスの作成から10分間となり、支払トランザクションが暗号資産ネットワーク上に検知された状態（未承認の状態）でstatusがpaid(支払い開始)と見なされます、その後、暗号資産ネットワーク上で1承認された時点でstatusがconfirmed（確認済み）となり、暗号資産毎の必要承認数（BTCで3、MONAで100など）を経過した時点でstatusはcomplete（完了）となります。
 
-	highとすると、暗号通貨ネットワーク上での送金トランザクションについて、確認前の状態でも、着金次第決済完了とみなします。 mediumとすると、1件以上の確認が入ったタイミングで決済完了とみなします。これはbitcoinで平均10分、monacoinで平均2分程度になります。 lowとすると、6件以上の確認が入ったタイミングで決済完了とみなします。これはbitcoinで平均1時間、monacoinで平均12分程度になります。 highとすると顧客側の送金が完了したタイミングとほぼ同時に着金し、決済完了とみなされますが、万一このトランザクションがネットワーク上で認証されなかった場合、決済が後から取り消しされる場合があります。
+  有効期限内に着金した場合、有効期限の10分以内に1承認とならなくても直ちに有効期限切れにはなりませんが、1時間以内（有効期限切れ後50分以内）に1承認とならない場合は有効期限切れとなります。
 ```
 
 ``` Note::
-	利用者の氏名・住所などについて
+  利用者の氏名・住所などについて
 
-	利用者の氏名・住所・電話番号などのフィールドについては、送信していただくと決済フォームに表示されます。ただし、利用者IDについては表示されません。 決済フォームはインボイスIDがもれない限りアクセスすることができませんが、インターネット上ではアクセス制限なしに公開される状態になりますので、個人情報保護の観点から、必要でない場合（注文番号などから顧客が関連付けできる場合）は顧客の情報を送信されないことをお勧めします。
+  利用者の氏名・住所・電話番号などのフィールドについては、送信していただくと決済フォームに表示されます。ただし、利用者IDについては表示されません。
+
+  決済フォームはインボイスIDがもれない限りアクセスすることができませんが、インターネット上ではアクセス制限なしに公開される状態になりますので、個人情報保護の観点から、必要でない場合（注文番号などから顧客が関連付けできる場合）は顧客の情報を送信されないことをお勧めします。
 ```
 
 #### 戻り値
@@ -215,10 +225,24 @@ buyerId          送信された利用者ID（送信された場合のみ）
     }
 }
 ```
+
+``` Note::
+  webhookUrlについて
+
+  webhookUrlで指定されたURLに対しHTTP(S)によるPOSTを行い、決済情報を通知します。
+  POSTデータの内容はgetInvoiceで取得できるものと同様のデータをJSON形式にしたものとなります。
+
+  事業者様のECサイトシステム側で決済状況の確認をリアルタイムに行うためにはwebhookUrlのご利用を推奨します。
+  webhookによる通知は、ご請求に対し「着金があったとき」「入金開始となったとき」「入金完了となったとき」「有効期限切れとなったとき」「有効期限切れ後の過入金があったとき」など、決済の状態が変化する度に通知が送信されます。
+  また、webhookによる通知は、受け取り側がHTTPステータスコード200を返すまで（間隔を明けて）再送されますので、通知漏れも起こらないようになっています。
+
+  これに対しnotificationUriへの通知は決済完了時に1回しか行わず、ステータスコードにかかわらず1回しか送信されません。
+```
+
 ``` note::
 	決済完了通知(notificationUri)について
 	
-	notificationUriを設定した場合、speedで設定した状態となったタイミングで、決済完了の通知がHTTP(S)で送信されます。
+	notificationUriを設定した場合、決済完了となったタイミングで決済完了の通知がHTTP(S)で送信されます。
 ```
 
 ```eval_rst
@@ -237,9 +261,10 @@ buyerId          送信された利用者ID（送信された場合のみ）
 ```
 
 ``` warning::
-	notificationMethodにGETを設定した場合は、パラメータは送信されません。 notificationMethodにGETを設定する場合、notificationUriに注文を識別できるような工夫をして設定してください。
+  notificationMethodにGETを設定した場合は、パラメータは送信されません。 notificationMethodにGETを設定する場合、notificationUriに注文を識別できるような工夫をして設定してください。
 	
-	通知のエラー時の対応について エラー時の再送については準備中です。
+  通知のエラー時の対応について
+  notificationUriに対するエラー時の再送は行っておりません。webhookUrlによる通知の受け取りをご検討ください。
 ```
 
 ``` Note::
@@ -292,20 +317,21 @@ speed        決済スピード（送信されたものまたはデフォルト
 orderNumber  送信された注文番号（送信された場合のみ）                        str
 ============ =============================================================== ===
 ```
-* インボイスの状態(status)
-  * インボイスには下記のような「状態」があります。
-
-    1. new : 作成され、請求が開始された状態。
-    1. paid : 支払先アドレスに対して入金が行なわれ、着金した状態（speed=highの場合の決済完了タイミング）。
-    1. confirmed : 支払先アドレスに対する入金が暗号通貨ネットワーク上で1確認以上された状態（speed=mediumの場合の決済完了タイミング）。
-    1. complete : 支払先アドレスに対する入金が暗号通貨ネットワーク上で6確認以上された状態（speed=lowの場合の決済完了タイミング）。
-    1. expired : 支払先アドレスに対して入金が行なわれず、有効期限が切れた状態。
-    1. invalid : 支払先アドレスに対して入金が開始されたが、なんらかの理由で確認されなかった状態や、入金金額が不足した状態で有効期限が切れた状態。
-    1. canceled : 作成者によりキャンセルされた状態。
-
-		インボイスの状態と他に、決済完了とみなすかどうかについては、インボイス作成時に設定されたspeedに従って下記の項目が対応します。
-
-    1. settled: 決済完了日時（unixtime）、speedに応じて決済を完了とみなしたタイミングでセットされます。
+
+#### インボイスの状態(status)
+インボイスには下記のような「状態」があります。
+
+  1. new : 作成され、請求が開始された状態。
+  1. paid : 支払先アドレスに対して支払いが行なわれ、着金開始した状態。
+  1. confirmed : 支払先アドレスに対する支払いが暗号通貨ネットワーク上で1承認以上確認された状態。
+  1. complete : 支払先アドレスに対する支払いが暗号通貨ネットワーク上で3承認以上確認された状態。このタイミングで決済完了となります。また、3承認はBTCの場合で、暗号資産の種別によって必要承認数は違う値になります。
+  1. expired : 支払先アドレスに対して支払いが行なわれず、有効期限が切れた状態。
+  1. invalid : 支払先アドレスに対して支払いが開始されたが、1承認までに時間がかかりすぎてしまった場合や、額が不足した状態で有効期限が切れた状態。または有効期限切れ後に支払いされた場合。
+  1. canceled : 作成者によりキャンセルされた状態。
+
+  インボイスの状態と他に、決済完了とみなすかどうかについては、インボイス作成時に設定されたspeedに従って下記の項目が対応します。
+
+  settled: 決済完了日時（unixtime）、決済を完了とみなしたタイミング（statusがcompleteになったタイミング）でセットされます。
 
 -------------------------------------------------------------------------------------------------------------------------------------------------------------
 

diff --git a/docs/TradingAPI.md b/docs/TradingAPI.md
@@ -860,7 +860,7 @@ invalid agreement state
 
 ※「agreed」パラメータにtrueを指定して行われた全ての送金について、以下内容に同意したものとみなします。
 * 弊社の[利用規約](https://zaif.jp/terms)を遵守します。
-* イラン・北朝鮮への送金ではありません。
+* イラン・北朝鮮・ミャンマーへの送金ではありません。
 * 法令等（外為法・米国OFAC等）の規制に抵触いたしません。
 * 送金先及び送金先の実質的支配者が規制対象者ではありません。
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -59,18 +59,18 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'Zaif api document'
-copyright = 'ＣＡＩＣＡ Ｅｘｃｈａｎｇｅ Ｉｎｃ.'
+project = 'Zaif API document'
+copyright = 'Ｚａｉｆ　Ｉｎｃ．'
 author = 'fcce'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = 'v2.0.0'
+version = 'v2.1.0'
 # The full version, including alpha/beta/rc tags.
-release = 'v2.0.0'
+release = 'v2.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/requirements.txt b/requirements.txt
@@ -2,3 +2,4 @@ sphinx
 sphinx-autobuild
 sphinx_rtd_theme
 docutils<0.18
+commonmark