Square 取引データとレシートローラー取引データのマッピング
Square API から取得した取引データを、レシートローラーの取引データモデルにマッピングする仕組みの技術解説です。フィールド単位の対応表、ステータスコードの変換、支払い方法の正規化、明細・顧客・スタッフ情報の解決、タイムゾーンと冪等性の扱いなど、内部仕様を理解したい開発者・運用担当者向けに整理しています。
本記事はレシートローラー側の SquarePaymentMapper の挙動をまとめたものです。一般的な「Square と連携する」「同期するとどうなる」といった操作手順は Square の POS 連携設定 をご覧ください。フィールド単位の正規モデル仕様は PosTransactionDto 仕様（フィールドリファレンス） を参照してください。
基本構造
Square と レシートローラーでは、取引データの粒度に違いがあります。
- Square 側は Payment（支払い）と Order（注文）の 2 つに分かれています。Payment が決済情報、Order が明細情報を持ちます
- レシートローラー側は 1 つの PosTransactionDto に支払い + 明細 + 顧客 + スタッフを集約します
- 取得時は Payment を起点に、関連する Order・TeamMember・Customer を追加で取りに行きます
主要フィールドの対応表
| レシートローラー側 | Square 側 | 備考 |
|---|---|---|
TransactionId | Payment.id | Square の支払い ID をそのまま採用。冪等な upsert のキーになります |
ExternalTransactionId | Payment.id | 同上（外部参照用に重複保持） |
TransactionDateTime | Payment.created_at | ISO 8601 文字列 → UTC DateTime へ変換 |
Currency | Payment.amount_money.currency | 通貨コード。既定 JPY |
TotalAmount | Payment.amount_money.amount | JPY はそのまま、他通貨は smallest unit (cents) → 主単位に変換 |
TaxAmount | Payment.tax_money.amount | 同上 |
SubtotalAmount | 計算値 | amount - tax |
DiscountAmount | Payment.discount_money.amount | 同上 |
TipAmount | Payment.tip_money.amount | チップ。ある場合のみ |
PaymentMethod | Payment.card_details の有無 | カードデータがあれば CreditCard、なければ Other（主たるテンダー。内訳は下記 Payments） |
Payments[] | Payment 1 件 + card_details.card | テンダー内訳。Method / Amount（total_money）/ Brand（card_brand）/ Last4（last_4） |
Status | Payment.status | 下記「ステータス対応表」 |
ReceiptNumber | Payment.receipt_number | Square が発番 |
ReceiptUrl | Payment.receipt_url | 顧客向けレシート URL。構造化フィールドに保持（以前は Notes に格納していましたが廃止） |
ExternalIds | order_id / location_id / customer_id | ベンダー横断 ID（ProviderOrderId / LocationId / ProviderCustomerId） |
StaffId | Payment.team_member_id | 未割当の場合は空 |
StaffName | TeamMember.display_name | 別途 TeamMembers API で解決 |
Source | 固定値 "API" または "Webhook" | 取得経路に応じて |
RawJson | Payment + Order の生ペイロード | モデル化していないフィールド（カード fingerprint 等）も復元できるよう保管。API では返しません |
LineItems | Order.line_items[] | 別途 Orders API で解決。下記「明細のマッピング」 |
ステータス対応表
Square Payment.status | レシートローラー Status | 意味 |
|---|---|---|
COMPLETED | Completed | 会計完了 |
CANCELED | Voided | キャンセル |
FAILED | Voided | 失敗（売上には含めません） |
| その他 | Pending | 処理中・未確定 |
金額の通貨変換
Square の Money オブジェクトは通貨ごとに最小単位の扱いが異なります。
- JPY: 1 円が最小単位。
amountをそのまま採用 - USD・EUR など: 1 セントが最小単位。
amount / 100で主単位に変換
レシートローラー側はすべて主単位 (decimal) で保持し、通貨コードを Currency に保持します。
明細のマッピング
Square の Payment には明細情報が含まれていないため、関連する Order を別途取得して明細を展開します。Order が取得できなかった場合（権限不足・API エラー・OAuth トークン期限切れなど）は明細なしで取引が保存され、後から再同期で補完できます。
レシートローラー LineItem | Square Order.line_items[] | 備考 |
|---|---|---|
ProductName | name + variation_name | バリエーションがあれば「商品名 (バリエーション名)」形式 |
Quantity | quantity | 文字列を整数にパース。失敗時は 1 |
UnitPrice | base_price_money.amount | 通貨変換あり |
Subtotal | total_money.amount | 取得できない場合は UnitPrice × Quantity |
TaxRate | 計算値 | (total_tax_money / (total_money - total_tax_money)) × 100 を小数 1 桁で四捨五入 |
TaxAmount | total_tax_money.amount | 明細単位の税額。税率だけでなく金額も保持します |
DiscountAmount | total_discount_money.amount | 明細単位の割引額 |
CatalogObjectId | catalog_object_id | Square カタログとの連携 ID |
Modifiers | modifiers[] | オプション・モディファイア（name + total_price_money） |
Category | — | 現状は常に空。Square Catalog API での解決は将来検討 |
顧客マッチキーの抽出
レシートローラーの自動配信パイプライン（CRM 連携）に渡すため、Square 側の顧客識別子を抽出します。
- 主キー:
Payment.customer_id（Square Customer Directory の顧客 ID）。取引にはExternalIds.ProviderCustomerIdとしても保持します - フォールバック:
Payment.card_details.card.fingerprint（カード番号のハッシュ。PAN ではなく Square が生成した安定識別子。RawJson内に保持し、API では返しません）
電話番号・メールは Square Payment には含まれないため、Customer Directory への追加 API 呼び出しが必要です。現状はカード fingerprint で十分マッチするケースが多いため省略しています。
OAuth トークンの自動リフレッシュ
Square OAuth アクセストークンは約 30 日で期限切れになります。Webhook 経路では、明細・スタッフ名取得の直前に terminal.AccessToken の有効期限を確認し、60 秒以内に切れる場合は RefreshToken で自動更新します（更新後は端末レコードに永続化）。これにより長期間 webhook 駆動の店舗でも明細の取りこぼしが起きません。
冪等性
同じ取引が複数回届いた場合（Square 側のリトライ・手動同期と Webhook の重複など）も、Payment.id をキーにした upsert で安全に再保存されます。レシートローラー側で重複レシートが発行されることはありません。
関連記事
- Square の POS 連携設定 — 連携手順
- スマレジ取引データとのマッピング — スマレジ版
- PosTransactionDto 仕様（フィールドリファレンス） — 各フィールドの詳細
-
SquareのPOS連携設定SquareのPOSをレシートローラーと連携する手順を説明します。OAuth認証で簡単に接続でき、会計データがリアルタイムで同期されます。
-
Square連携による従業員同期Square POSで登録済みのチームメンバーをレシートローラーの従業員として一括同期する方法を説明します。二重登録の手間を省けます。
-
Square スタッフデータとレシートローラースタッフデータのマッピングSquare Team Member がレシートローラーのスタッフデータ（StaffDto）にどう関連付けられるかを説明します。手動リンクの運用方法、取引データの担当者解決ロジック、Team Member API の主要フィールドまでまとめています。
-
スマレジ・Square との会員情報双方向同期レシートローラーの会員情報は、連携している POS（スマレジ・Square など）と双方向で同期されます。本記事では、双方向同期の仕組み、同期される項目、同期のタイミング、競合時の優先順位、対応 POS、設定方法、トラブルシューティングをご案内します。
-
Square 顧客データとレシートローラー顧客データのマッピングSquare Customer Directory がレシートローラーの顧客データ（CrmCustomerDto）にどう変換されるかをフィールド単位で説明します。given_name / family_name の対応、住所の分解ロジック、reference_id の扱いまでまとめています。