pokepay_partner_ruby_sdk 0.3.2 → 0.3.6

data/docs/event.md

@@ -0,0 +1,308 @@
+# Event
+
+<a name="create-external-transaction"></a>
+## CreateExternalTransaction: ポケペイ外部取引を作成する
+ポケペイ外部取引を作成します。
+
+ポケペイ外の現金決済やクレジットカード決済に対してポケペイのポイントを付けたいというときに使用します。
+
+
+```RUBY
+response = $client.send(Pokepay::Request::CreateExternalTransaction.new(
+                          "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",               # shop_id: 店舗ID
+                          "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",               # customer_id: エンドユーザーID
+                          "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",               # private_money_id: マネーID
+                          6907,                                                 # amount: 取引額
+                          description: "たい焼き(小倉)",                              # 取引説明文
+                          metadata: "{\"key\":\"value\"}",                      # ポケペイ外部取引メタデータ
+                          products: [{"jan_code":"abc",
+ "name":"name1",
+ "unit_price":100,
+ "price": 100,
+ "quantity": 1,
+ "is_discounted": false,
+ "other":"{}"}],                                                                # 商品情報データ
+                          request_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",   # リクエストID
+                          done_at: "2023-08-17T17:06:58.000000Z"                # ポケペイ外部取引の実施時間
+))
+```
+
+
+
+### Parameters
+**`shop_id`** 
+  
+
+店舗IDです。
+
+ポケペイ外部取引が行なう店舗を指定します。
+
+```json
+{
+  "type": "string",
+  "format": "uuid"
+}
+```
+
+**`customer_id`** 
+  
+
+エンドユーザーIDです。
+
+エンドユーザーを指定します。
+
+```json
+{
+  "type": "string",
+  "format": "uuid"
+}
+```
+
+**`private_money_id`** 
+  
+
+マネーIDです。
+
+マネーを指定します。
+
+```json
+{
+  "type": "string",
+  "format": "uuid"
+}
+```
+
+**`amount`** 
+  
+
+取引金額です。
+
+```json
+{
+  "type": "integer",
+  "minimum": 0
+}
+```
+
+**`description`** 
+  
+
+取引説明文です。
+
+任意入力で、取引履歴に表示される説明文です。
+
+```json
+{
+  "type": "string",
+  "maxLength": 200
+}
+```
+
+**`metadata`** 
+  
+
+ポケペイ外部取引作成時に指定され、取引と紐付けられるメタデータです。
+
+任意入力で、全てのkeyとvalueが文字列であるようなフラットな構造のJSONで指定します。
+
+```json
+{
+  "type": "string",
+  "format": "json"
+}
+```
+
+**`products`** 
+  
+
+一つの取引に含まれる商品情報データです。
+以下の内容からなるJSONオブジェクトの配列で指定します。
+
+- `jan_code`: JANコード。64字以下の文字列
+- `name`: 商品名。256字以下の文字列
+- `unit_price`: 商品単価。0以上の数値
+- `price`: 全体の金額(例: 商品単価 × 個数)。0以上の数値
+- `quantity`: 商品の個数。この値が指定された場合、priceから算出される個数よりも優先されます。
+- `is_discounted`: 賞味期限が近いなどの理由で商品が値引きされているかどうかのフラグ。boolean
+- `other`: その他商品に関する情報。JSONオブジェクトで指定します。
+
+```json
+{
+  "type": "array",
+  "items": {
+    "type": "object"
+  }
+}
+```
+
+**`request_id`** 
+  
+
+取引作成APIの羃等性を担保するためのリクエスト固有のIDです。
+
+取引作成APIで結果が受け取れなかったなどの理由で再試行する際に、二重に取引が作られてしまうことを防ぐために、クライアント側から指定されます。指定は任意で、UUID V4フォーマットでランダム生成した文字列です。リクエストIDは一定期間で削除されます。
+
+リクエストIDを指定したとき、まだそのリクエストIDに対する取引がない場合、新規に取引が作られレスポンスとして返されます。もしそのリクエストIDに対する取引が既にある場合、既存の取引がレスポンスとして返されます。
+
+```json
+{
+  "type": "string",
+  "format": "uuid"
+}
+```
+
+**`done_at`** 
+  
+
+ポケペイ外部取引が実際に起こった時間です。
+時間帯指定のポイント付与キャンペーンでの取引時間の計算に使われます。
+デフォルトではCreateExternalTransactionがリクエストされた時間になります。
+
+```json
+{
+  "type": "string",
+  "format": "date-time"
+}
+```
+
+
+
+成功したときは
+[ExternalTransactionDetail](./responses.md#external-transaction-detail)
+を返します
+
+### Error Responses
+|status|type|ja|en|
+|---|---|---|---|
+|400|invalid_parameters|項目が無効です|Invalid parameters|
+|403|unpermitted_admin_user|この管理ユーザには権限がありません|Admin does not have permission|
+|410|transaction_canceled|取引がキャンセルされました|Transaction was canceled|
+|422|customer_user_not_found||The customer user is not found|
+|422|shop_user_not_found|店舗が見つかりません|The shop user is not found|
+|422|private_money_not_found||Private money not found|
+|422|invalid_metadata|メタデータの形式が不正です|Invalid metadata format|
+|422|customer_account_not_found||The customer account is not found|
+|422|shop_account_not_found||The shop account is not found|
+|422|account_suspended|アカウントは停止されています|The account is suspended|
+|422|account_closed|アカウントは退会しています|The account is closed|
+|422|account_can_not_topup|この店舗からはチャージできません|account can not topup|
+|422|account_currency_mismatch|アカウント間で通貨が異なっています|Currency mismatch between accounts|
+|422|account_pre_closed|アカウントは退会準備中です|The account is pre-closed|
+|422|account_not_accessible|アカウントにアクセスできません|The account is not accessible by this user|
+|422|terminal_is_invalidated|端末は無効化されています|The terminal is already invalidated|
+|422|same_account_transaction|同じアカウントに送信しています|Sending to the same account|
+|422|transaction_has_done|取引は完了しており、キャンセルすることはできません|Transaction has been copmpleted and cannot be canceled|
+|422|transaction_invalid_done_at|取引完了日が無効です|Transaction completion date is invalid|
+|422|transaction_invalid_amount|取引金額が数値ではないか、受け入れられない桁数です|Transaction amount is not a number or cannot be accepted for this currency|
+|422|account_restricted|特定のアカウントの支払いに制限されています|The account is restricted to pay for a specific account|
+|422|account_balance_not_enough|口座残高が不足してます|The account balance is not enough|
+|422|c2c_transfer_not_allowed|このマネーではユーザ間マネー譲渡は利用できません|Customer to customer transfer is not available for this money|
+|422|account_transfer_limit_exceeded|取引金額が上限を超えました|Too much amount to transfer|
+|422|account_balance_exceeded|口座残高が上限を超えました|The account balance exceeded the limit|
+|422|account_money_topup_transfer_limit_exceeded|マネーチャージ金額が上限を超えました|Too much amount to money topup transfer|
+|422|account_total_topup_limit_range|期間内での合計チャージ額上限に達しました|Entire period topup limit reached|
+|422|account_total_topup_limit_entire_period|全期間での合計チャージ額上限に達しました|Entire period topup limit reached|
+|422|coupon_unavailable_shop|このクーポンはこの店舗では使用できません。|This coupon is unavailable for this shop.|
+|422|coupon_already_used|このクーポンは既に使用済みです。|This coupon is already used.|
+|422|coupon_not_received|このクーポンは受け取られていません。|This coupon is not received.|
+|422|coupon_not_sent|このウォレットに対して配信されていないクーポンです。|This coupon is not sent to this account yet.|
+|422|coupon_amount_not_enough|このクーポンを使用するには支払い額が足りません。|The payment amount not enough to use this coupon.|
+|422|coupon_not_payment|クーポンは支払いにのみ使用できます。|Coupons can only be used for payment.|
+|422|coupon_unavailable|このクーポンは使用できません。|This coupon is unavailable.|
+|503|temporarily_unavailable||Service Unavailable|
+
+
+
+---
+
+
+<a name="refund-external-transaction"></a>
+## RefundExternalTransaction: ポケペイ外部取引をキャンセルする
+取引IDを指定して取引をキャンセルします。
+
+発行体の管理者は自組織の直営店、または発行しているマネーの決済加盟店組織での取引をキャンセルできます。
+キャンセル対象のポケペイ外部取引に付随するポイント還元キャンペーンも取り消されます。
+
+取引をキャンセルできるのは1回きりです。既にキャンセルされた取引を重ねてキャンセルしようとすると `transaction_already_refunded (422)` エラーが返ります。
+
+```RUBY
+response = $client.send(Pokepay::Request::RefundExternalTransaction.new(
+                          "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",               # event_id: 取引ID
+                          description: "返品対応のため"                                # 取引履歴に表示する返金事由
+))
+```
+
+
+
+### Parameters
+**`event_id`** 
+  
+
+
+```json
+{
+  "type": "string",
+  "format": "uuid"
+}
+```
+
+**`description`** 
+  
+
+
+```json
+{
+  "type": "string",
+  "maxLength": 200
+}
+```
+
+
+
+成功したときは
+[ExternalTransactionDetail](./responses.md#external-transaction-detail)
+を返します
+
+
+
+---
+
+
+<a name="get-external-transaction-by-request-id"></a>
+## GetExternalTransactionByRequestId: リクエストIDからポケペイ外部取引を取得する
+リクエストIDを指定してポケペイ外部取引を取得します。
+
+発行体の管理者は自組織発行のマネーに紐付くポケペイ外部取引を取得できます。
+
+```RUBY
+response = $client.send(Pokepay::Request::GetExternalTransactionByRequestId.new(
+                          "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"                # request_id: リクエストID
+))
+```
+
+
+
+### Parameters
+**`request_id`** 
+  
+
+
+```json
+{
+  "type": "string",
+  "format": "uuid"
+}
+```
+
+
+
+成功したときは
+[ExternalTransactionDetail](./responses.md#external-transaction-detail)
+を返します
+
+
+
+---
+
+
+