pokepay_partner_ruby_sdk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 015dc3b92d9ad253a74ec83550047f20afdf6d99e3820dc313ee15a8e8e1bed5
-  data.tar.gz: 189c9ff489aa5093c5014e0d4fdb85693b3755b72b98274a06814a38efd4a037
+  metadata.gz: b462bd0f2ea7bce3ec40b034bb138999de416b4618f956042d97cce6ab592ffa
+  data.tar.gz: 887c9023e4346498b6ef4cef2e0cebd125d9b28e5d19fe0ff06ad7e489eb645d
 SHA512:
-  metadata.gz: 2f0a69b091a89ff1f71588ccb778c0433a80794b7565460106ce549204f540ccf70eeb0b99ddd1e8b51d4c05c5f8cd7db123a1417908a63ec07d2c667c1f5fd6
-  data.tar.gz: c35badfaf92b55ff5d4255e213d44dceb2ae2a3f4d5782b33f76759ff8ad0434267698f5a2b433d4f0f42c22898004e2d95e25c008770e0f964210b7cc64b5f1
+  metadata.gz: e1e978f24e716234f533e02221f9e77c6f56f892fa6be91ff998be328fcf231ba47ddad601736bd6df5c6c5a3ec28b143aeabe369dcd33601ab27eb06684c536
+  data.tar.gz: 5a722a10444c8ac32a2ed0b61408925ffc336d1367b14c2cce51c20a5b41f9d4fbcafe2042bdd16541c3184f5d15957b7cb41b85bacf226910c11f341ab67130

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pokepay_partner_ruby_sdk (0.1.0)
+    pokepay_partner_ruby_sdk (0.1.1)
       inifile (~> 3.0.0)
       json (~> 2.1.0)
       openssl (~> 2.1.2)

data/config.ini.sample

@@ -1,5 +1,5 @@
 CLIENT_ID        = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 CLIENT_SECRET    = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
-API_BASE_URL     = https://partnerapi-dev.pokepay.jp
+API_BASE_URL     = https://partnerapi-sandbox.pokepay.jp
 SSL_KEY_FILE     = /path/to/key.pem
 SSL_CERT_FILE    = /path/to/cert.pem

data/docs/index.md

@@ -1,29 +1,213 @@
-# Installation
+# Partner API SDK for Ruby
 
+## Installation
+
+rubygemsからインストールすることができます。
+```
+$ gem install pokepay_partner_ruby_sdk
 ```
-$ bundle exec rake install
+
+ロードパスの通ったところにライブラリが配置されていれば、以下のようにロードできます。
+
+```ruby
+require "pokepay_partner_ruby_sdk"
 ```
 
-# Settings
+## Getting started
 
-# Getting Started
+基本的な使い方は次のようになります。
+
+- ライブラリをロード
+- 設定ファイル(後述)から Pokepay::Client オブジェクトを作る
+- リクエストオブジェクトを作り、Pokepay::Client オブジェクトのsendメソッドに対して渡す
+- レスポンスオブジェクトを得る
 
 ```ruby
 require "pokepay_partner_ruby_sdk"
-c = Pokepay::Client.new("/path/to/config.ini")
-res = c.send(Pokepay::Request::SendEcho.new('hello'))
-res = c.send(Pokepay::Request::ListTransactions.new({'per_page'=>1}))
-res = c.send(Pokepay::Request::CreateTransaction.new(
-               "8b9fbece-73fa-494d-bad5-c7fd9e52f9a0",
-               "78e56df5-dd71-4554-86e5-b0eb8d3781cb",
-               "4b138a4c-8944-4f98-a5c4-96d3c1c415eb",
-               100,
-               200,
-               "チャージテスト"))
+client = Pokepay::Client.new("/path/to/config.ini")
+request = Pokepay::Request::SendEcho.new('hello')
+response = client.send(request)
+```
+
+レスポンスオブジェクト内にステータスコード、JSONをパースしたハッシュマップ、さらにレスポンス内容のオブジェクトが含まれています。
+
+## Settings
+
+設定はINIファイルに記述し、 Pokepay::Client のコンストラクタにファイルパスを指定します。
+
+SDKプロジェクトルートに config.ini.sample というファイルがありますのでそれを元に必要な情報を記述してください。特に以下の情報は通信の安全性のため必要な項目です。これらはパートナー契約時にお渡ししているものです。
+
+- CLIENT_ID: パートナーAPI クライアントID
+- CLIENT_SECRET: パートナーAPI クライアント秘密鍵
+- SSL_KEY_FILE: SSL秘密鍵ファイルパス
+- SSL_CERT_FILE: SSL証明書ファイルパス
+
+この他に接続先のサーバURL情報が必要です。
+
+- API_BASE_URL: パートナーAPI サーバURL
+
+また、この設定ファイルには認証に必要な情報が含まれるため、ファイルの管理・取り扱いに十分注意してください。
+
+設定ファイル記述例(config.ini.sample)
+
+```
+CLIENT_ID        = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+CLIENT_SECRET    = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+API_BASE_URL     = https://partnerapi-sandbox.pokepay.jp
+SSL_KEY_FILE     = /path/to/key.pem
+SSL_CERT_FILE    = /path/to/cert.pem
+```
+
+## Overview
+
+### APIリクエスト
+
+Partner APIへの通信はリクエストオブジェクトを作り、Pokepay::Client.send メソッドに渡すことで行われます。リクエストクラスは名前空間 Pokepay::Request 以下に定義されています。
+
+たとえば Pokepay::Request::SendEcho 送信した内容をそのまま返す処理です。
+
+```ruby
+request = Pokepay::Request::SendEcho.new('hello')
+
+response = client.send(request)
+# => #<Pokepay::Response::Response 200 OK readbody=>
+```
+
+通信の結果として、レスポンスオブジェクトが得られます。これはステータスコードとレスポンスボディ、各レスポンスクラスのオブジェクトをインスタンス変数に持つオブジェクトです。
+
+```ruby
+response.code
+# => 200
+
+response.body
+# => {"status"=>"ok", "message"=>"hello"}
+
+response.object
+# => #<Pokepay::Response::Echo:0x000055fd7cc0db20 @message="hello">
+
+response.object.message
+# => "hello"
+```
+
+エラーの場合は Net::HTTPBadRequest などのエラーレスポンスオブジェクトが返ります。エラーレスポンスもステータスコードとレスポンスボディを持ちます。
+
+```ruby
+request = Pokepay::Request::SendEcho.new(-1)
+
+response = client.send(request)
+# => #<Net::HTTPBadRequest 400 Bad Request readbody=true>
+
+response.code
+# => 400
+
+response.body
+# => {"type"=>"invalid_parameters", "message"=>"Invalid parameters", "errors"=>{"invalid"=>["message"]}}
 ```
 
-# Run test
+## API Operations
+
+### 取引一覧を取得する
+
+```ruby
+response = client.send(Pokepay::Request::ListTransactions.new(
+                         {
+                           # ページング
+                           "page"     => 1,
+                           "per_page" => 50,
 
+                           # フィルタオプション (すべて任意)
+                           # 期間指定 (ISO8601形式の文字列)
+                           "from" => "2019-01-01T00:00:00+09:00",
+                           "to"   => "2019-07-30T18:13:39+09:00",
+                           # 検索オプション
+                           "customer_id"    => "xxxxxxxxxxxxxxxxx", # エンドユーザーID
+                           "customer_name"  => "福沢",           # エンドユーザー名
+                           "transaction_id" => "24bba30c......", # 取引ID
+                           "shop_id"        => "456a820b......", # 店舗ID
+                           "terminal_id"    => "d8023185......", # 端末ID
+                           "organization"   => "pocketchange",   # 組織コード
+                           "private_money"  => "9ff644fc......", # マネーID
+                           "is_modified"    => "true",           # キャンセルされた取引のみ検索するか
+                           # 取引種別 (複数指定可)、チャージ=topup、支払い=payment
+                           "types"          => ["topup", "payment"],
+                         }))
 ```
-$ bundle exec ruby test/pokepay_partner_ruby_sdk_test.rb
+
+成功したときは Pokepay::Response::Transaction を rows に含むページングオブジェクトを返します。
+取引一覧のような大量のレスポンスが返るエンドポイントでは、一度に取得する量を制限するためにページングされています。
+
+#### 取引情報
+
+取引クラスは Pokepay::Response::Transaction で定義されています。
+
+取引オブジェクトのプロパティは以下のようになっています。
+
+- id (String): 取引ID
+- type (String): 取引種別 (チャージ=topup, 支払い=payment)
+- is_modified (真理値): 返金された取引かどうか
+- sender (Response\User): 送金者情報
+- receiver (Response\User): 受取者情報
+- sender_account (Response\Account): 送金口座情報
+- receiver_account (Response\Account): 受取口座情報
+- amount (Numeric): 決済総額 (マネー額 + ポイント額)
+- money_amount (Numeric): 決済マネー額
+- point_amount (Numeric): 決済ポイント額
+- done_at (Time): 取引日時
+- description (String): 取引説明文
+
+`sender` と `receiver` には `Pokepay::Response::User` のオブジェクトです。 以下にプロパティを示します。
+
+- id (String): ユーザー (または店舗) ID
+- name (String): ユーザー (または店舗) 名
+- is_merchant (真理値): 店舗ユーザーかどうか
+
+`senderAccount` と `receiverAccount` は `Pokepay::Response::Account` のオブジェクトです。以下にプロパティを示します。
+
+- id (String): 口座ID
+- name (String): 口座名
+- is_suspended (真理値): 口座が凍結されているかどうか
+- private_money (Response\PrivateMoney): 設定マネー情報
+
+`privateMoney` は `Pokepay::Response::PrivateMoney` のオブジェクトです。以下にプロパティを示します。
+
+- id (String): マネーID
+- name (String): マネー名
+- unit (String): マネー単位 (例: 円)
+- is_exclusive (真理値): 会員制のマネーかどうか
+- description (String): マネー説明文
+- max_balance (Numeric): 口座の上限金額
+- transfer_limit (Numeric): マネーの取引上限額
+- type (String): マネー種別 (自家型=own, 第三者型=third-party)
+- expiration_type (String): 有効期限種別 (チャージ日時起算=static, 最終利用日時起算=last-update)
+
+#### ページング
+
+ページングクラスは Pokepay::Response::Pagination で定義されています。
+
+ページングオブジェクトのプロパティは以下のようになっています。
+
+- rows : 列挙するレスポンスクラスのオブジェクトの配列
+- count : 全体の要素数
+- pagination : 以下のインスタンス変数を持つオブジェクト
+  - current : 現在のページ位置(1からスタート)
+  - per_page : 1ページ当たりの要素数
+  - max_page : 最後のページ番号
+  - has_prev : 前ページを持つかどうかの真理値
+  - has_next : 次ページを持つかどうかの真理値
+
+### チャージする
+
+```ruby
+shop_id          = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # 店舗ID
+customer_id      = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" # エンドユーザーのID
+private_money_id = "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz" # 送るマネーのID
+money_amount     = 1000                                   # チャージマネー額
+point_amount     = 0                                      # チャージするポイント額
+description      = "初夏のチャージキャンペーン"           # 取引履歴に表示する説明文
+
+response = $client.send(Pokepay::Request::CreateTransaction.new(
+                          shop_id, customer_id, private_money_id,
+                          money_amount, point_amount, description))
 ```
+
+成功したときは Pokepay::Response::Transaction を持つレスポンスオブジェクトを返します。

data/lib/pokepay_partner_ruby_sdk/version.rb

@@ -1,3 +1,3 @@
 module Pokepay
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pokepay_partner_ruby_sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Satoshi Imai
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-23 00:00:00.000000000 Z
+date: 2019-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler