Square PHP SDK README

よたか2020.09.07 17:50:26

このライブラリを使用して、Squareの支払いをアプリに統合し、カタログ、顧客、従業員、在庫、労働、場所、注文などのSquare APIでビジネスを成長させます。

必要条件：PHP 7.1以降

インストール

composer

PHP SDK は Packagist で入手できます。インストールの推奨方法は、Composerを使用する方法です。次のコマンドを実行します。

$ composer require square/square

＊KDDI ACE01 ではパスが通ってないので下記の通りコマンドを入力しました。
$ mkdir ~html/square
$ cd ~html/square
$ curl -sS https://getcomposer.org/installer | php-7.1
$ php-7.1 composer.phar require square/square

＊Coreserver では下記の通りコマンドを入力しました。
$ mkdir ~public_html/square
$ cd ~public_html/square
$ curl -sS https://getcomposer.org/installer | php
$ php71cli composer.phar require square/square

手動インストール

Composerを使用しない場合は、次のパッケージをルートPHPディレクトリに複製して手動でインストールできます。

square/square-php-sdk このパッケージには、SquareのPHP SDKが含まれています
apimatic/jsonmapper Square PHP SDK は JSON Mapper を使用して JSON 応答を動的に PHPクラスに変換します。このパッケージには、Square API で動作する JSONマッパーのカスタムバージョンがバンドルされています。
apimatic/unirest-php Square PHP SDK は、REST API HTTP クライアントである Unirest をラップします。このパッケージには、Square API で動作する Unirest のカスタムバージョンがバンドルされています。

SDKとその依存関係をダウンロードしたら、カスタムのautoload.phpファイルを作成する必要があります。作成したら、autoload.phpを要求して、SDKとその依存関係にアクセスできます。 autoload.phpの例はここにあります。

API ドキュメント

お支払い

アイテム

お客さま

ロイヤリティ

ロイヤリティ：Loyalty

ビジネス

チーム

財務

銀行口座：Bank Accounts

認可API

非推奨のAPI

使い方

Squareを初めて使用しますか？開始方法は次のとおりです。

Squareアカウントを作成します。まだお持ちでない場合は開発者アカウントにサインアップしてください。
アプリケーションを作成します。開発者ダッシュボードに移動して、最初のアプリケーションを作成します。名前を付けるだけです。本番アプリケーションでこれを行う場合は、顧客に見られるように名前を入力します。
最初のAPI呼び出しを行います。ほとんどすべてのSquare API呼び出しには、ロケーションIDが必要です。 #list_locationsへの最初の呼び出しを行います。これは、ロケーションIDを必要としないAPI呼び出しの1つです。ロケーションの詳細については、ロケーションAPIのドキュメントを参照してください。

では、最初のSquare APIを呼び出しましょう。お気に入りのテキストエディターを開き、index.phpという新しいファイルを作成して、次のコードをそのファイルにコピーします。



require 'vendor/autoload.php';

use Square\SquareClient;

use Square\LocationsApi;

use Square\Exceptions\ApiException;

use Square\Http\ApiResponse;

use Square\Models\ListLocationsResponse;

use Square\Environment;



$client = new SquareClient([

    'accessToken' => 'YOUR SANDBOX ACCESS TOKEN HERE',

    'environment' => Environment::SANDBOX,

]);



try {

    $locationsApi = $client->getLocationsApi();

    $apiResponse = $locationsApi->listLocations();



    if ($apiResponse->isSuccess()) {

        $listLocationsResponse = $apiResponse->getResult();

        $locationsList = $listLocationsResponse->getLocations();

        foreach ($locationsList as $location) {

        print_r($location);

        }

    } else {

        print_r($apiResponse->getErrors());

    }

} catch (ApiException $e) {

    print_r("Recieved error while calling Square: " . $e->getMessage());

}

次に、アクセストークンを取得し、コードで参照します。開発者ダッシュボードでアプリケーションに戻り、[サンドボックス]セクションの[サンドボックスアクセストークン]ボックスで[表示]をクリックし、そのアクセストークンをコピーして、「ここにあるサンドボックスアクセストークン」をそのトークンに置き換えます。

重要：最終的にサンドボックスでの試行から実際の本番リソースでの作業に切り替える場合、コードにアクセストークンを埋め込まないでください。運用アクセストークンを安全に保存してアクセスするようにしてください。

次にindex.phpを保存して実行します。

php -S localhost:8000

呼び出しが成功すると、次のような応答が返されます。


stdClass Object

(

  [id] => KXKXSFEKT2587

  [name] => My Location

  [address] => stdClass Object

    (

      [address_line_1] => 1455 Market Street

      [locality] => San Francisco

      [administrative_district_level_1] => CA

      [postal_code] => 94103

      [country] => US

    )

# ...

最初の通話が成功しました。そうしないと、次のようなエラーメッセージが表示されます。


Array

(

  [0] => Square\Models\Error Object

    (

      [category:Square\Models\Error:private] => AUTHENTICATION_ERROR

      [code:Square\Models\Error:private] => UNAUTHORIZED

      [detail:Square\Models\Error:private] => This request could not be authorized.

      [field:Square\Models\Error:private] =>

    )

)

このエラーは、APIの呼び出しに無効なトークンが使用された場合に返されました。

Square APIを試し、サンドボックスを使用してアプリケーションをテストした後、本番の認証情報に切り替えて、実際のSquareリソースを管理できるようにします。実際のデータのために、アクセストークンをサンドボックスから本番環境に切り替えることを忘れないでください。

SDK パターン

いくつかのパターンがわかっている場合は、SDKで任意のAPIを呼び出すことができます。ここにいくつかの重要なものがあります：

アクセストークンを取得する

Square APIを使用してSquareアカウントのリソース（支払い、注文、顧客など）を管理するには、開発者ダッシュボードでアプリケーションを作成（または既存のアプリケーションを使用）し、アクセストークンを取得する必要があります。

Square APIを呼び出すときは、アクセスキーを使用して呼び出します。アクセスキーには、特定の開発者アカウントの特定のアプリケーションがアクセスできる特定のSquareアカウントのリソースに対する特定の権限があります。ユースケースに適したアクセストークンを使用してください。 2つのオプションがあります。

自分のSquareアカウントのリソースを管理するには、Squareアカウントで作成されたアプリケーションのパーソナルアクセストークンを使用します。
他のSquareアカウントのリソースを管理するには、OAuthを使用して、管理するアカウントの所有者に依頼し、代理で作業できるようにします。 OAuthを実装するときは、Squareアカウントの所有者にアカウント内のリソースを管理する権限を要求し（アクセスする特定のリソースを定義できます）、そのアカウントのOAuthアクセストークンと更新トークンを取得します。

重要どちらの使用例でも、トークンを安全に保管してアクセスしてください。

クライアントクラスのインポートとインスタンス化

Square APIを使用するには、Clientクラスをインポートし、Clientオブジェクトをインスタンス化して、適切なアクセストークンで初期化します。方法は次のとおりです。

リソースを管理するSquareアカウントのアクセストークンを使用して、SquareClientオブジェクトをインスタンス化します。サンドボックスリソースにアクセスするには、環境をサンドボックスに設定してSquareClientを初期化します。


use Square\SquareClient;

use Square\Environment;



$client = new SquareClient([

    'accessToken' => 'YOUR SANDBOX ACCESS TOKEN HERE',

    'environment' => Environment::SANDBOX

]);

本番リソースにアクセスするには、環境を本番に設定します。


use Square\SquareClient;

use Square\Environment;



$client = new SquareClient([

    'accessToken' => 'YOUR PRODUCTION ACCESS TOKEN HERE',

    'environment' => Environment::PRODUCTION

]);

APIオブジェクトのインスタンスを取得し、そのメソッドを呼び出す

各APIはクラスとして実装されます。 ClientオブジェクトはすべてのAPIクラスをインスタンス化し、それらをプロパティとして公開するため、Square APIの使用を簡単に開始できます。 APIを操作するには、APIクラスのインスタンスでメソッドを呼び出します。方法は次のとおりです。

APIオブジェクトのメソッドを呼び出して、APIを操作します。たとえば、listCustomersを呼び出して、Squareアカウントのすべての顧客のリストを取得します。


try {

    $result = $client->getCustomersApi()->listCustomers();

} catch (ApiException $e) {

    print_r("Recieved error while calling Square: " . $e->getMessage());

}

各APIクラスのメソッドのリストについては、SDKのドキュメントを参照してください。

複雑なパラメーター（作成、更新、検索など）をRequestオブジェクトとして渡します。たとえば、create_customerを使用して新しい顧客を作成するために使用される値を含むCreateCustomerRequestを渡します。


use Square\SquareClient;

use Square\Exceptions\ApiException;

use Square\Models\CreateCustomerRequest;

use Square\Environment;



$client = new SquareClient([

    "accessToken" => "SQUARE_SANDBOX_ACCESS_TOKEN",

    "environment" => Environment::SANDBOX

]);



$customersApi = $client->getCustomersApi();



// Create customer

$request = new CreateCustomerRequest;

$request->setGivenName('Amelia');

$request->setFamilyName('Earhart');

$request->setPhoneNumber("1-252-555-4240");

$request->setNote('A customer');



try {

    $result = $customersApi->createCustomer($request);



    if ($result->isSuccess()) {

        print_r($result->getResult()->getCustomer());

    } else {

        print_r($result->getErrors());

    }

} catch (ApiException $e) {

    print_r("Recieved error while calling Square: " . $e->getMessage());

}

呼び出しが成功すると、次のような応答が表示されます。


Square\Models\Customer Object

(

    [id:Square\Models\Customer:private] => 2CN457HSFGR11CKQGHDECEZCDC

    [createdAt:Square\Models\Customer:private] => 2020-06-05T00:42:54.499Z

    [updatedAt:Square\Models\Customer:private] => 2020-06-05T00:42:54Z

    [cards:Square\Models\Customer:private] =>

    [givenName:Square\Models\Customer:private] => Amelia

    [familyName:Square\Models\Customer:private] => Earhart

    [nickname:Square\Models\Customer:private] =>

    [companyName:Square\Models\Customer:private] =>

    [emailAddress:Square\Models\Customer:private] =>

    [address:Square\Models\Customer:private] =>

    [phoneNumber:Square\Models\Customer:private] =>  1-252-555-4240

    [birthday:Square\Models\Customer:private] =>

    [referenceId:Square\Models\Customer:private] =>

    [note:Square\Models\Customer:private] => a customer

    [preferences:Square\Models\Customer:private] => Square\Models\CustomerPreferences Object

        (

            [emailUnsubscribed:Square\Models\CustomerPreferences:private] =>

        )



    [groups:Square\Models\Customer:private] =>

    [creationSource:Square\Models\Customer:private] => THIRD_PARTY

    [groupIds:Square\Models\Customer:private] =>

    [segmentIds:Square\Models\Customer:private] =>

)

2度の呼び出しを避けたい作成、更新、またはその他の呼び出しに idempotency を使用します。 idempotency のAPI呼び出しを行うには、API呼び出しのリクエストに一意の値を持つ idempotency_key を追加します。
支払いを処理するトランザクション、注文、チェックアウトなどのAPIのロケーションIDを指定します。 Squareで支払いまたは注文が作成されると、常に場所に関連付けられます。

応答を処理する

API呼び出しは、要求（ヘッダーと要求）と応答（status_code、reason_phrase、テキスト、エラー、本文、およびカーソル）の両方を記述するプロパティを含む応答オブジェクトを返します。応答にはisSuccess（）およびisError（）ヘルパーメソッドも含まれているため、呼び出しの成功または失敗を簡単に判別できます。


if ($apiResponse->isSuccess()) {

    $listLocationsResponse = $apiResponse->getResult();

} else {

    print_r($apiResponse->getErrors());

}

応答ペイロードを読み取ります。応答ペイロードは、getResultメソッドから配列として返されます。検索呼び出しの場合、単一のアイテムを含むオブジェクトは、オブジェクトの名前であるキー名（たとえば、customer）とともに返されます。リスト呼び出しの場合、オブジェクトの配列を含むオブジェクトは、オブジェクト名の複数形であるキー名で返されます（たとえば、customers）。
API応答で返されたカーソル値を確認して、リスト呼び出しで返されたすべてのアイテムを取得していることを確認してください。リストAPIを初めて呼び出すときは、カーソルを空の文字列に設定するか、APIリクエストから省略します。 API応答に値を持つカーソルが含まれている場合は、APIを再度呼び出してアイテムの次のページを取得し、カーソルが空の文字列になるまでそのAPIを繰り返し呼び出します。

テスト

まず、gemをローカルに複製し、ディレクトリに移動します。


git clone https://github.com/square/square-php-sdk.git

cd square-php-sdk

次に、ここでの指示に従ってComposerをダウンロードしていることを確認し、composer.jsonを含むディレクトリから次のコマンドを実行します。

composer install

Before running the tests, find a sandbox token in your Developer Dashboard and set a SQUARE_ACCESS_TOKEN environment variable.


$dotenv = Dotenv::create(__DIR__);

$dotenv->load();

$timeout = getenv('SQUARE_TIMEOUT');

$accessToken = getenv('SQUARE_ACCESS_TOKEN');

$environment = getenv('SQUARE_ENVIRONMENT');

$baseUrl = getenv('SQUARE_BASE_URL');

そして、テストを実行します。

php composer.phar run test

Learn more

Squareプラットフォームは、Square APIに基づいて構築されています。 Squareには他にも多くのSDKがあり、モバイルとウェブの両方でクレジットカード情報を安全に処理できるため、Square APIを介して支払いを処理できます。

また、Square APIを使用して、Squareの対面型ハードウェア製品（Square Point of SaleおよびSquare Register）で作成および管理された支払い、注文、在庫などを扱うアプリケーションまたはサービスを作成することもできます。

このページは個人的に使用するために Square の Github ページを翻訳したものです