認証ガイド

レシートローラー APIはOAuth 2.0 認可コードフローを使用します。 サードパーティの開発者がアプリを登録し、ビジネスオーナーがアクセスを許可すると、開発者はトークンを取得してAPIを呼び出すことができます。

ステップ1：アプリを登録する

1. レシートローラーアカウントにログインします
2. ビジネスアカウント詳細 → ⋮ メニュー → 開発者アプリ に移動します
3. アプリを作成 をクリックします
4. アプリ名、リダイレクトURI、必要なAPIスコープを入力・選択します
5. 作成後、client_id と client_secret が発行されます

ステップ2：ビジネスオーナーを認可画面にリダイレクトする

ビジネスオーナーがアプリにアカウントを連携する際、ブラウザを以下のURLにリダイレクトします：

GET https://your-domain/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_REDIRECT_URI
    &response_type=code
    &scope=store.products.read store.orders.read
    &state=RANDOM_STATE_STRING

ビジネスオーナーには、アプリ名と要求されるアクセス権限が表示された同意画面が表示されます。許可または拒否を選択できます。

ステップ3：認可コードを受け取る

許可された場合、ビジネスオーナーのブラウザが redirect_uri にリダイレクトされます：

GET https://your-app.com/callback
    ?code=AUTHORIZATION_CODE
    &state=RANDOM_STATE_STRING

拒否された場合：

GET https://your-app.com/callback
    ?error=access_denied
    &state=RANDOM_STATE_STRING

ステップ4：コードをトークンに交換する

サーバーサイドから（ブラウザではなく）、以下のPOSTリクエストでコードをアクセストークンに交換します：

POST /api/v1/auth/token
Content-Type: application/json

{
    "grantType": "authorization_code",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirectUri": "YOUR_REDIRECT_URI"
}

成功レスポンス（200）：

{
    "accessToken": "aBcDeFgH1234567890...",
    "refreshToken": "xYzAbCdEfG098765...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "scope": "store.products.read store.orders.read"
}

ステップ5：APIを呼び出す

アクセストークンを Authorization ヘッダーに含めてリクエストします：

GET /api/v1/store/products
Authorization: Bearer aBcDeFgH1234567890...
Content-Type: application/json

APIは、アプリを認可したビジネスアカウントに紐づくデータを返します。承認されたスコープで許可されたデータのみアクセス可能です。

ステップ6：期限切れトークンをリフレッシュする

アクセストークンの有効期限が切れた場合、リフレッシュトークンを使用して新しいトークンペアを取得します：

POST /api/v1/auth/token
Content-Type: application/json

{
    "grantType": "refresh_token",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "refreshToken": "xYzAbCdEfG098765..."
}

レスポンス形式はステップ4と同じです。古いアクセストークンとリフレッシュトークンは無効化され、新しいペアが返されます。

トークンの取り消し

アクセストークンまたはリフレッシュトークンを取り消すには：

POST /api/v1/auth/revoke
Content-Type: application/json

{
    "token": "取り消すトークン",
    "clientId": "YOUR_CLIENT_ID"
}

ビジネスオーナーは、アカウント設定からいつでもアプリのアクセスを取り消すことができます。

エラーレスポンス

利用可能なスコープ

Store（店舗）

CRM（顧客関係管理）

SNS / アナリティクス

フロー図

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│  あなたのアプリ │     │ ビジネス      │     │  ReceiptRoller   │
│  （開発者）    │     │ オーナー      │     │  プラットフォーム  │
└──────┬───────┘     └──────┬───────┘     └────────┬─────────┘
       │                    │                      │
       │  1. /oauth/authorize にリダイレクト         │
       │───────────────────►│─────────────────────►│
       │                    │                      │
       │                    │  2. 同意画面を表示     │
       │                    │◄─────────────────────│
       │                    │                      │
       │                    │  3. 許可する           │
       │                    │─────────────────────►│
       │                    │                      │
       │  4. ?code=認可コード でリダイレクト          │
       │◄───────────────────│◄─────────────────────│
       │                    │                      │
       │  5. POST /api/v1/auth/token               │
       │  （code + client_id + client_secret）      │
       │──────────────────────────────────────────►│
       │                                           │
       │  6. { accessToken, refreshToken }         │
       │◄──────────────────────────────────────────│
       │                                           │
       │  7. GET /api/v1/store/products            │
       │  Authorization: Bearer {accessToken}      │
       │──────────────────────────────────────────►│
       │                                           │
       │  8. { data: [...] }                       │
       │◄──────────────────────────────────────────│

セキュリティのベストプラクティス

• client_secret はサーバーサイドにのみ保管してください。フロントエンドのコードやモバイルアプリには絶対に含めないでください。
• CSRF攻撃を防ぐため、state パラメータを必ず検証してください。
• モバイルアプリやシングルページアプリケーションでは、PKCE（code_challenge / code_verifier）を使用してください。
• トークンは安全に保管してください。アクセストークンをログに記録したり、URLに含めたりしないでください。
• サービスの中断を避けるため、有効期限が切れる前にトークンのリフレッシュを実装してください。
• アプリが実際に必要とするスコープのみをリクエストしてください。