外部の会員システムから配信対象と会員ランクを送る（会員連携 API）

店舗の会員システム（POS など）のサーバーから、会員証の会員番号を使って次の 2 つをサブスクラインへ送れます。

• 配信対象の取り込み: 会員番号の一覧で、指定したラベルが付いている会員を置き換え・追加・削除します。そのラベルを条件にしたユーザーグループで配信できます。
• 会員ランクの反映: 会員番号ごとのランク名を送ると、会員ランクの判定に使うラベルを付け替え、ランクを再計算します。

このページは、連携先のシステムを実装する開発者と、サブスクラインの設定を行う管理者向けです。

サーバー間の連携専用です

トークンは秘密情報です。呼び出し元のサーバーにだけ保管し、Web ページやアプリに埋め込まないでください。

全体の流れ

1. 会員連携用のトークンを発行する

場所: 管理画面サイドバー「設定」>「AI/MCP連携」

ROOT 権限のアカウントで操作してください

このタブは ROOT 権限のアカウントにのみ表示されます。

1. 「接続を作成」を押します。
2. 接続名（例: 会員システム連携）を入力します。
3. スコープで external_member_sync を選びます。このスコープは他のスコープと一緒に選べません。選ぶと他のチェックは外れます。
4. 「作成する」を押すと、トークン（subscline_ で始まる文字列）が一度だけ表示されます。控えて、会員システムのサーバーに設定してください。

発行手順の画面は MCPコネクター と同じです。トークンが漏れた場合は、同じ画面で無効化または再発行してください。

2. 共通の仕様

項目	内容
URL	https://api.subscline.jp/api/v1/external/member-sync/...
メソッド	PUT
認証	Authorization: Bearer subscline_xxxxxxxxxxxx
ヘッダー	Content-Type: application/json
会員番号	会員証のバーコードに表示される 13 桁の数字（例: 0000000000123）。外部の会員システムで発番した会員番号も使えます（下記）
1 回の上限	会員番号 50,000 件
回数の上限	トークンごとに 1 分あたり 30 回

• 送り先のアカウントはトークンで決まります。リクエストでアカウントを指定する項目はありません。
• 13 桁の数字でない値、登録されていない会員番号、削除済みの会員の会員番号は、エラーにせず応答の unmatchedMemberNumbers で返します。ほかの会員番号は反映されます。
• ラベルの付け外しでは、ラベルをきっかけにした自動応答やお客様への LINE 通知は送られません。
• 同じ内容を何度送っても結果は変わりません。失敗したときはそのまま再送してください。

外部の会員番号で指定する

外部の会員システムで発番した会員番号で指定する場合は、本文の externalSystem に連携先の識別子を入れます。その会員番号があらかじめ会員に紐付いている必要があります。

• 識別子は、ユーザーに登録した外部会員番号の「番号の種類」です（ユーザーを追加）。英小文字で始まり、英小文字・数字・_・- の32文字以内です。
• 会員番号は文字列のまま照合し、先頭の0も区別します（00123 と 123 は別の番号です）。
• 紐付いていない番号、ほかの「番号の種類」の番号、ほかのアカウントの番号は照合されず、unmatchedMemberNumbers で返します。
• externalSystem を省略すると、会員証の13桁の番号として照合します。

{ "labelName": "来店30日以内", "mode": "add", "externalSystem": "pos-a", "memberNumbers": ["00123", "00456"] }

エラー時の応答は次のとおりです。

コード	意味
400	本文の形式が不正（mode の値が違う、件数が上限を超えたなど）
401	トークンが無い・無効・無効化されている
403	トークンに external_member_sync スコープが無い
429	回数の上限を超えた。時間をおいて再送してください

3. 配信対象を取り込む（ラベルの付与メンバー）

PUT /api/v1/external/member-sync/labels/members

curl --request PUT \
  --url 'https://api.subscline.jp/api/v1/external/member-sync/labels/members' \
  --header 'Authorization: Bearer subscline_xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{ "labelName": "来店30日以内", "mode": "replace", "memberNumbers": ["0000000000123", "0000000000456"] }'

項目	内容
labelName	ラベル名（100 文字まで）。無ければ作ります
mode	replace / add / remove（下表）
memberNumbers	会員番号の配列
externalSystem	任意。外部の会員番号で指定するときの番号の種類

mode	動き
replace	送った会員だけがラベルを持つ状態にします。一覧に無い会員からはラベルを外します
add	送った会員にラベルを付けます。ほかの会員はそのままです
remove	送った会員からラベルを外します。ラベルが無ければ何もしません

応答の例:

{
  "labelId": 321,
  "labelName": "来店30日以内",
  "matched": 2,
  "added": 1,
  "removed": 5,
  "unmatchedMemberNumbers": []
}

matched は会員が見つかった件数、added と removed は実際に付けた・外した件数です。

replace で全員から外れる事故を防ぐ仕組み

replace は「送った一覧がそのラベルの全員」という意味です。抽出に失敗した場合などに全員が外れないよう、次の場合は 422 を返し、何も変更しません。

• 空の一覧を送り、allowEmpty: true を付けていない。全員から外したいときだけ "allowEmpty": true を付けてください。
• 一覧はあるが、一致する会員が0件だった（会員番号の形式ミスや externalSystem の指定違いなど）。応答の unmatchedMemberNumbers に一致しなかった番号（先頭最大100件）が入ります。

取り込んだラベルで配信するには、ユーザーグループ の絞り込み条件「ラベル」にこのラベルを指定したグループを作り、配信の宛先に選びます。

4. 会員ランクを反映する

PUT /api/v1/external/member-sync/member-ranks

curl --request PUT \
  --url 'https://api.subscline.jp/api/v1/external/member-sync/member-ranks' \
  --header 'Authorization: Bearer subscline_xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{ "changes": [ { "memberNumber": "0000000000123", "rankName": "ゴールド" }, { "memberNumber": "0000000000456", "rankName": null } ] }'

項目	内容
changes[].memberNumber	会員番号
externalSystem	任意。外部の会員番号で指定するときの番号の種類
changes[].rankName	会員ランク名。null はランクを外します

• 会員ランクごとに 外部ランク:<ランク名> というラベルを使います（例: 外部ランク:ゴールド）。無ければ作ります。
• 送った会員の 外部ランク: で始まるラベルを外し、指定したランクのラベルだけを付けます。null のときはすべて外します。
• 管理画面の会員ランクに無いランク名は反映せず、応答の unknownRanks で返します。
• 同じ会員番号が複数あるときは、後の行を使います。
• 1 人以上のラベルが変わったら、会員ランクの再計算を始めます。再計算は応答の後に進み、結果は会員ランク画面の「最後の再計算」で確かめられます。
• 再計算でランクが変わったお客様には、会員ランクに設定したランクアップ・ランクダウン時の自動応答が、管理画面でランクを変えたときと同じように送られます。ラベルの付け外しそのものでは送られません。

応答の例:

{
  "matched": 2,
  "updated": 1,
  "unmatchedMemberNumbers": [],
  "unknownRanks": [{ "memberNumber": "0000000000789", "rankName": "ダイヤ" }]
}

updated はランクのラベルが実際に変わった会員の数です。

5. 会員ランクとユーザーグループを設定する

会員ランクは、ユーザーグループの条件でお客様ごとに自動で判定されます（会員ランク）。この API はランクを直接書き換えず、判定に使うラベルを付け替えます。管理者は最初に次を設定してください。

1. 会員ランクの名前を、会員システムから送るランク名と完全に一致させます。
2. ランクごとにユーザーグループを作り、絞り込み条件「ラベル」に 外部ランク:<ランク名> を指定します。ラベルは最初の送信で作られます。先に管理画面の ラベル で同じ名前のラベルを作っておくこともできます。
3. 会員ランクの判定グループに、2 のユーザーグループを設定します。

「ランクのラベル」には外部ランクのラベルを選ばないでください

会員ランクの「ランクのラベル」は、ランクが決まったお客様に付けるラベルです。外部ランク: のラベルを選ぶと、判定の材料と判定の結果が同じラベルになり、会員システムから送ったラベルと再計算で付け替えたラベルの区別がつかなくなります。別のラベルを選ぶか「ラベルを付けない」にしてください。

関連ページ

• MCPコネクター（トークンの発行画面）
• ユーザーグループ
• 会員ランク