店舗顧客APIは OAuth Bearer トークン で認証し、トークンに紐づく組織（その組織の店舗の顧客）に対して操作できます。

事前準備

• アクセストークンを取得（組織に対して認可されたトークン）
• 必要なスコープ
  • 読み取り（一覧・詳細）: store.customers.read
  • 書き込み（作成・削除）: store.customers.write
• すべてのリクエストに以下を付与

  Authorization: Bearer {ACCESS_TOKEN}
  

ベースURL: https://receiptroller.io

1. 新規顧客の作成（POST）

curl -X POST 'https://receiptroller.io/api/v1/store/customers' \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
        "id": "TEST-001",
        "name": "山田 太郎",
        "email": "taro@example.com",
        "gender": "male",
        "birthDate": "1990-05-12",
        "loyaltyRank": "Gold",
        "tags": ["coffee_lover", "frequent_buyer"]
      }'

→ 200 で作成された顧客が返ります。name は「姓 名」を半角スペースで分割して保存されます。loyaltyRank は会員レベル（Standard / Silver / Gold / Platinum 等）です。

2. 顧客一覧の取得（GET）

curl 'https://receiptroller.io/api/v1/store/customers' \
  -H 'Authorization: Bearer {TOKEN}'

絞り込みも可能：

例：

curl 'https://receiptroller.io/api/v1/store/customers?loyaltyRank=Gold&minSpend=100000' \
  -H 'Authorization: Bearer {TOKEN}'

→ 200 で配列が返ります。該当なしの場合は空配列 [] です。

3. 顧客詳細の取得（GET /{id}）

id には内部の顧客ID、または 会員コード のどちらでも指定できます。

curl 'https://receiptroller.io/api/v1/store/customers/TEST-001' \
  -H 'Authorization: Bearer {TOKEN}'

→ 200 で顧客プロフィール（氏名・メール・会員レベル・累計購入額・来店回数・最終来店日・タグ）が返ります。

存在しないIDの場合は 404：

{
  "error": "customer_not_found",
  "message": "No customer found for 'XXX' in this organization.",
  "id": "XXX"
}

4. 顧客の削除（DELETE /{id}）

curl -X DELETE 'https://receiptroller.io/api/v1/store/customers/TEST-001' \
  -H 'Authorization: Bearer {TOKEN}'

→ 204 No Content（ソフト削除）。存在しない場合は 404（customer_not_found）。

補足

• トークンの組織が所有する顧客のみ操作できます。別組織のIDは 404 になります（組織境界で保護）。
• 401: トークンなし／無効　403: スコープ不足
• 購入履歴 GET /{id}/purchases は現在 501 を返します（CRM顧客とレシートの紐付けは別途対応予定）。代わりに累計購入額・来店回数・最終来店日は顧客詳細で取得できます。