アカウント連携・統合API（トークン交換・/me/identities・/account/merge）

この記事では、アプリがLINE・Apple・Googleで取得したIDトークンでレシートローラーにサインインするトークン交換と、ログイン方法を追加・解除する /api/v1/me/identities、2つのアカウントを統合する /api/v1/account/merge の仕様をまとめます。レシートローラー公式のiOS / Androidアプリと LINEミニアプリが使っているものと同じAPIです。

トークン交換（IDトークンでサインイン）

RFC 8693 のトークン交換で、プラットフォームSDKが返したIDトークンをレシートローラーのアクセストークンに交換します。ブラウザでの /oauth/authorize を経由しません。使えるのは、トークン交換を許可されたクライアントIDだけです。利用したい場合はサポートにご相談ください。

POST https://receiptroller.io/api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id={client_id}
&subject_token={IDトークン}
&subject_token_type=urn:ietf:params:oauth:token-type:id_token
&subject_issuer=line            # line | apple | google
&organization_id={店舗のビジネスアカウントID}  # 店舗独自のLINEチャネルのときだけ
&nonce={nonce}                  # SDKにnonceを渡した場合
&create_if_missing=true         # アカウントがなければ作る

成功すると、通常のトークンに issued_token_type と account_created（この呼び出しでアカウントを作ったか）が加わります。

本人確認（proof）

ログイン方法の追加・解除と統合では、トークンに加えて、今のアカウントの持ち主であることを proof で示します。

{ "type": "password", "password": "..." }
{ "type": "id_token", "issuer": "line", "idToken": "...", "nonce": null, "organizationId": null }

• アカウントのログイン方法（パスワード、またはつながっているLINE・Apple・Googleのいずれか）で示します
• ログイン方法をまだ持たないアカウント（スマホアプリで匿名で始めたもの）は proof を省略できます
• 足りないと 403 reauth_required、合わないと 403 proof_rejected が返り、どちらも使える方法を acceptedMethods で示します

ログイン方法の管理 /api/v1/me/identities

• GET /api/v1/me/identities：email、hasPassword、identities（id・provider・scope・linkedAt・lastUsedAt・canRemove）
• POST /api/v1/me/identities：{ issuer, idToken, nonce?, organizationId?, proof } でLINE・Apple・Googleを追加。すでに別のアカウントが使っていると 409 identity_belongs_to_other_account と mergeTicket が返ります
• DELETE /api/v1/me/identities/{id}：本文 { proof }。proof には解除する方法以外を使います。最後の1つは 409 last_sign_in_method
• POST /api/v1/me/identities/password/code：{ email, proof }。メールに確認コードを送ります（202）。1時間あたりの回数に上限があります（429 rate_limit_exceeded）
• POST /api/v1/me/identities/password：{ email, password, code, proof }。そのメールを別のアカウントが使っていれば 409 identity_belongs_to_other_account と mergeTicket。パスワードが条件を満たさないと 400 password_rejected

アカウントの統合 /api/v1/account/merge

統合には、もう一方のアカウントの証明を表す mergeTicket（有効期限10分）が必要です。チケットは、それを取得したアカウントのトークンでしか使えません。

1. もう一方のアカウントを証明してチケットを得る：POST /api/v1/account/merge/tickets

   { "proof": {...},
     "other": { "type": "email_code", "email": "...", "code": "..." } }
   // type は id_token / password / email_code

   確認コードは POST /api/v1/account/merge/email-code（{ email, proof }）で送ります。アカウントの有無にかかわらず 202 を返します。
2. 内容を確認する：POST /api/v1/account/merge/preview（{ mergeTicket, keep? }）。keep は current（今のアカウントを残す）か other。省略時は suggestedKeep（本人が作ったアカウント、同種なら古い方）
3. 統合する：POST /api/v1/account/merge（{ mergeTicket, keep, confirm: true }）。202 で mergeId と、残るアカウントの tokens を返します。以降はこのトークンを使ってください。同じチケットを再送しても同じ統合が返ります
4. 進み具合：GET /api/v1/account/merge/{mergeId}。status は running / completed / failed / undone。canResume が true なら POST /api/v1/account/merge/{mergeId}/resume で再開できます

POST /api/v1/account/merge/suggestions（{ proof }）は、同じ人のものと思われる別のアカウントを返します。same_line は同じLINEのIDを持つアカウントで、LINEが両方を証明しているため mergeTicket 付きです。same_email はLINEのIDトークンのメールが一致したアカウントで、チケットはなく、通常どおり証明が必要です。

実装のヒント

• エラー本文は error コードで分岐してください。errorDescription の文言は変わることがあります
• ログイン方法の追加・解除と統合は、利用者のメールとLINEに通知されます。アプリ側で別途知らせる必要はありません
• 統合はアプリからは取り消せません。30日以内であればサポートで元に戻せる場合があります

関連記事

• ネイティブモバイルアプリ向けガイド
• アクセストークンの取得と更新
• エラーコードとリトライ指針
• アカウントをまとめる（利用者向け）