Square APIとは

付録A　Square API用語集

A.1 Square APIとは

Square APIは、Squareが提供している決済、注文、商品、在庫、顧客などの機能を、独自のWebサイトやアプリから利用するための仕組みです。

Squareの開発者向けプラットフォームでは、決済だけでなく、注文管理、商品カタログ、在庫管理、顧客管理などの機能がAPIとして提供されています。これらを部品として組み合わせることで、独自のECサイトや業務システムを構築できます。

攻略本風に言えば、Square APIは**「Squareが持っている決済・注文・在庫管理の能力を、自分のアプリから呼び出すための魔法一覧」**です。

---

A.1.1 Square APIの役割

APIとは、Application Programming Interfaceの略です。

簡単に言えば、異なるシステム同士が情報をやり取りするための窓口です。

購入者が商品を選ぶ
  ↓
Next.jsからSquare APIを呼び出す
  ↓
Squareが決済や注文を処理する
  ↓
処理結果がNext.jsへ返る

たとえば、自社ECで決済リンクを作りたい場合、Next.jsからSquareのAPIへ次のような情報を送ります。

・商品
・数量
・金額
・注文情報
・決済後の戻り先URL

Squareはその情報を受け取り、決済に必要な処理を行います。

Next.js：
この注文の決済画面を作ってください

Square：
決済画面を作成しました
このURLを購入者へ案内してください

このように、Square APIは自社ECとSquareをつなぐ役割を持ちます。

Square APIで扱える代表的な機能です。

Payments API：
支払いを処理する

Checkout API：
決済リンクや決済ページを作る

Orders API：
注文内容を管理する

Catalog API：
商品情報を管理する

Inventory API：
在庫数を管理する

Customers API：
顧客情報を管理する

Subscriptions API：
定期購入を管理する

SquareのAPIリファレンスには、各APIのエンドポイント、入力項目、返されるデータ、エラーなどの詳細情報が掲載されています。Square APIは、安全な決済処理やSquare製品との連携などに利用できます。

Square APIを使うと、Squareの既製ECサイトだけを利用するのではなく、自分で作ったデザインや購入導線からSquareの機能を呼び出せます。

自社で作る部分：
商品ページ
カート
ブランドデザイン
記事
会員機能
管理画面

Squareに任せる部分：
決済処理
支払い状態
Square側の注文情報
返金処理

たとえば、次のようなECを作れます。

・食品EC
・工芸品EC
・ギフトEC
・定期購入EC
・イベントチケット販売
・相談予約
・講座販売

売るものが変わっても、基本的な流れは同じです。

商品やサービスを選ぶ
  ↓
注文を作る
  ↓
Squareで決済する
  ↓
結果を自社ECへ戻す

APIでは、こちらから送る情報をリクエスト、Squareから返ってくる情報をレスポンスと呼びます。

リクエスト：
Squareへ送る情報

レスポンス：
Squareから返ってくる結果

支払いを作成する場合のイメージです。

リクエスト：
10,000円の支払いを作ってください

レスポンス：
支払いを作成しました
Payment IDは「PAYMENT-XXXX」です
状態はCOMPLETEDです

APIの処理に成功した場合は、作成された支払いや注文などのデータが返ります。

失敗した場合は、エラー内容が返ります。

成功：
Payment、Order、Customerなどが返る

失敗：
認証エラー、入力エラー、在庫不足などが返る

SquareのAPI Explorerでは、ブラウザ上からSquare APIへリクエストを送り、実際のリクエスト内容とレスポンス内容を確認できます。Sandboxと本番環境のリソースを使ってAPIの動作を試せます。

---

A.1.2 Square Developer Dashboardとは

現在のSquare公式ドキュメントでは、開発者向けの管理画面はDeveloper Consoleと呼ばれています。

以前の記事や会話では「Square Developer Dashboard」と表現されることがありますが、本付録では基本的に「Developer Console」と表記します。

Developer Consoleは、Square APIと接続するアプリケーションを管理する場所です。

Developer Console
  ↓
Squareアプリケーション
  ↓
認証情報
Webhook
APIバージョン
Location
ログ

Developer Consoleでは、主に次の設定を行います。

・Squareアプリケーションの作成
・Application IDの確認
・Access Tokenの確認
・Location IDの確認
・SandboxとProductionの切り替え
・Webhook URLの登録
・Webhookイベントの選択
・APIバージョンの確認
・APIログの確認
・OAuth設定

Square公式では、Developer Consoleを、アプリケーション、権限、認証情報、Webhook、APIログなどを管理する場所として説明しています。各アプリケーション画面では、SandboxとProductionを切り替えて、それぞれの設定を確認できます。

Squareアプリケーションとは、自分が開発するシステムをSquare側に登録したものです。

自社EC
  ↓
Squareアプリケーションとして登録
  ↓
Square APIを利用できる

Squareアプリケーションを作ると、API接続に必要な情報が発行されます。

・Application ID
・Access Token
・Application Secret
・Location ID
・Webhook Signature Key

これらの情報には、それぞれ役割があります。

Application ID：
どのアプリケーションか識別する

Access Token：
Square APIへアクセスするための認証情報

Location ID：
どの店舗・拠点の処理か識別する

Webhook Signature Key：
WebhookがSquareから届いたことを確認する

Developer ConsoleのCredentials画面に表示されるAccess Tokenは、Squareアカウントのデータを更新できる重要な認証情報です。Square公式でも、他人と共有しないよう注意されています。

初心者は、まず次の4か所を確認します。

1. Credentials
2. Locations
3. Webhooks
4. API Logs

Credentialsでは、Application IDやAccess Tokenを確認します。

Locationsでは、店舗を識別するLocation IDを確認します。

Webhooksでは、決済完了などの通知を受け取るURLを設定します。

API Logsでは、Square APIへ送ったリクエストと、その結果を確認します。

APIが動かない
  ↓
API Logsを見る
  ↓
送信内容とエラーを確認する

Developer Consoleは、日常の注文処理をする場所ではありません。

あくまで、開発者がAPI連携を設定・確認する場所です。

---

A.1.3 Square APIとSquare Dashboardの違い

Square APIとSquare Dashboardは、役割が異なります。

Square API：
プログラムからSquareを操作する仕組み

Square Dashboard：
人がブラウザから店舗業務を管理する画面

Square Dashboardは、Squareを利用する店舗や事業者向けの管理画面です。

Square公式では、Square Dashboardを、注文、取引、在庫、顧客、レポートなどの日常業務を管理するための画面として説明しています。

Square Dashboardで確認できる代表的な情報です。

・決済履歴
・注文
・商品
・在庫
・顧客
・売上レポート
・入金
・店舗情報

一方、Square APIは画面ではありません。

Next.jsなどのプログラムからSquareの機能を呼び出すための仕組みです。

Square Dashboard：
スタッフが操作する

Square API：
プログラムが操作する

Squareには、似た名前の管理画面が複数あります。

初心者はここで混乱しやすいため、次のように整理します。

名称	主に使う人	主な役割
Developer Console	開発者	API認証情報、Webhook、ログ、アプリ設定
Square Dashboard	店舗・事業者	売上、注文、在庫、顧客、日常業務
Sandbox Square Dashboard	開発者	テスト環境の注文や決済結果を確認

Developer Consoleは、システムの配線を設定する場所です。

Square Dashboardは、実際の店舗業務を管理する場所です。

Developer Console：
システム設定室

Square Dashboard：
店舗運営室

本書では、Next.jsで独自の管理画面も作ります。

そのため、管理画面は全部で3種類あると考えると分かりやすくなります。

Developer Console：
Square APIの設定

Square Dashboard：
Square側の決済・店舗業務確認

自社管理画面：
自社ECの注文・発送・商品管理

たとえば、注文の確認方法です。

自社管理画面：
発送先や管理メモを確認する

Square Dashboard：
決済が完了しているか確認する

Developer Console：
APIやWebhookが正常に届いたか確認する

問題が起きたときは、それぞれを見る場所が違います。

決済結果を見たい：
Square Dashboard

Webhookエラーを見たい：
Developer Console

発送状況を見たい：
自社管理画面

この違いを覚えておくと、トラブル時に迷いにくくなります。

---

A.1.4 Sandbox環境とProduction環境

Square APIには、主に2つの環境があります。

Sandbox：
開発・テスト用

Production：
実際の販売用

Sandboxは、実際のお金や本番データへ影響を与えずに、Square APIを試すための独立したテスト環境です。

Sandboxでは、テスト用の販売者アカウント、カード番号、支払いトークンなどを使って、決済、注文、在庫、定期購入、Webhookなどを試せます。Sandbox内のカードは実際には請求されず、Sandbox APIの利用にも決済手数料は発生しません。

Sandboxでの決済：
実際のお金は動かない

Sandboxでの商品：
本番商品には影響しない

Sandboxの注文：
本番注文には表示されない

SandboxのAPI接続先です。

https://connect.squareupsandbox.com

ProductionのAPI接続先です。

https://connect.squareup.com

Square SDKを使う場合は、URLを直接指定する代わりに、クライアント作成時にSandboxまたはProductionの環境を指定します。

Productionは、本番販売で使用する環境です。

Productionでは、実際の購入者、商品、注文、決済、在庫が扱われます。

Productionで決済
  ↓
実際にカードへ請求
  ↓
実際の売上として記録

Productionでは、決済処理に通常のSquareの手数料などが発生します。Sandboxとは異なり、実際の事業データを扱うため、設定やテストを慎重に行う必要があります。

SandboxとProductionの情報は分かれています。

Sandbox Access Token
Production Access Token

Sandbox Location ID
Production Location ID

Sandbox Webhook
Production Webhook

Sandboxで作成した商品や注文は、Productionには引き継がれません。

また、Sandbox Location IDとProduction Location IDは別の値です。Square公式でも、SandboxのLocationはProductionのLocationとは無関係であると説明されています。

悪い組み合わせ：

Sandbox Access Token
  ＋
Production Location ID

結果：
APIエラー

正しい組み合わせです。

Sandbox：
Sandbox Token
Sandbox Location ID
Sandbox API URL

Production：
Production Token
Production Location ID
Production API URL

Next.jsでは、環境変数を使って切り替えます。

SQUARE_ENVIRONMENT=sandbox
SQUARE_ACCESS_TOKEN=Sandbox用Access Token
SQUARE_LOCATION_ID=Sandbox用Location ID

本番では次のように変更します。

SQUARE_ENVIRONMENT=production
SQUARE_ACCESS_TOKEN=Production用Access Token
SQUARE_LOCATION_ID=Production用Location ID

コードに直接書くのではなく、Vercelやローカル環境の環境変数で管理します。

Sandboxは非常に便利ですが、本番と完全に同じ画面・機能が提供されるとは限りません。

Square公式でも、Sandbox Square Dashboardは本番Square Dashboardの一部機能だけを提供しており、本番と異なる点や利用できない機能があると説明しています。

そのため、次の順番で確認します。

1. Sandboxで開発
2. Sandboxで正常系テスト
3. Sandboxで失敗系テスト
4. Productionへ切り替え
5. 本番で少額決済テスト
6. 注文・Webhook・メールを確認
7. 一般公開

Sandboxは練習場です。

Productionは実際のお金が動く本番フィールドです。

---

A.1.5 APIを利用したECシステムの全体像

最後に、Square APIを使ったECシステム全体の流れを確認します。

本書で作る基本構成です。

購入者
  ↓
Next.jsの商品ページ
  ↓
カート
  ↓
Next.jsのサーバー処理
  ↓
自社DBにpending注文を作成
  ↓
Square APIで決済リンクを作成
  ↓
Squareの決済画面
  ↓
決済完了
  ↓
Square Webhook
  ↓
自社DBをpaidへ更新
  ↓
在庫更新
  ↓
メール通知
  ↓
管理画面で発送対応

役割ごとに整理します。

購入者が商品を探し、カートに入れ、購入手続きへ進む画面です。

・トップページ
・商品一覧
・商品詳細
・カート
・注文完了ページ

商品価格や在庫を確認し、Square APIを呼び出します。

・価格の再計算
・在庫確認
・pending注文の作成
・決済リンク作成
・Webhook受信

自社ECに必要な情報を保存します。

・商品
・注文
・注文明細
・在庫
・顧客
・配送
・メール送信履歴
・Webhook処理履歴

Squareは主に決済やSquare側の注文情報を管理します。

・決済画面
・支払い処理
・Payment ID
・Square Order ID
・返金
・決済ステータス

Square APIは、決済、コマース、顧客管理などの機能を組み合わせて独自アプリケーションを作るための部品として提供されています。

Webhookは、Square側で起きた変化を自社ECへ知らせます。

Squareで決済完了
  ↓
Webhookが届く
  ↓
自社注文をpaidへ変更

購入者が注文完了ページへ戻らない場合でも、Webhookが届けば決済結果を確認できます。

そのため、本書ではWebhookを注文確定の基準として使います。

店舗スタッフは、自社管理画面から注文や発送を確認します。

・新規注文
・決済状況
・配送先
・発送ステータス
・追跡番号
・管理メモ

Square Dashboardと自社管理画面を併用すると、次のように確認できます。

Square Dashboard：
決済が成功しているか

自社管理画面：
何をどこへ発送するか

注文や発送の状態を購入者と店舗へ伝えます。

・注文完了メール
・管理者への新規注文通知
・発送完了メール
・決済失敗通知

---

A.1のまとめ

Square APIは、Squareの決済、注文、商品、在庫、顧客などの機能を、自分で作ったWebサイトやアプリから利用するための仕組みです。

覚えておきたいポイントは、次の通りです。

1. APIは、異なるシステム同士をつなぐ窓口である
2. Square APIを使うと、独自ECからSquareの機能を呼び出せる
3. Developer Consoleでは、認証情報やWebhookを設定する
4. Square Dashboardでは、実際の売上や注文を管理する
5. Sandbox Square Dashboardでは、テスト結果を確認する
6. Sandboxはテスト環境で、実際のお金は動かない
7. Productionは本番環境で、実際の決済が行われる
8. SandboxとProductionのTokenやLocation IDは別である
9. 自社DBでは、商品、注文、在庫、配送などを管理する
10. Squareには、主に安全な決済処理を任せる

Square APIの基本は、次の一言にまとめられます。

Squareの機能を借りながら、自分だけのECサイトを作る。

すべてを自分で作る必要はありません。

決済はSquareに任せる。

商品ページや購入体験はNext.jsで作る。

注文や配送は自社DBと管理画面で管理する。

この役割分担が、Square APIを使ったEC開発の基本です。