会員連携 API
店舗の会員システム(POS など)のサーバーから、会員証の会員番号を使って次の 3 つをサブスクラインへ送れます。
- 配信対象の取り込み: 会員番号の一覧で、指定したラベルが付いている会員を置き換え・追加・削除します。そのラベルを条件にしたユーザーグループで配信できます。
- 会員ランクの反映: 会員番号ごとのランク名を送ると、会員ランクの判定に使うラベルを付け替え、ランクを再計算します。
- 店頭でのクーポンの使用: 店頭で使われたクーポンを送ると、お客様の LINE の保有クーポンを使用済みにします。
このページは、連携先のシステムを実装する開発者向けです。管理画面での設定は 外部の会員システムと連携する をご覧ください。
サーバー間の連携専用です
トークンは秘密情報です。呼び出し元のサーバーにだけ保管し、Web ページやアプリに埋め込まないでください。
事前準備
連携には、管理画面で発行する会員連携用のトークンが必要です。スコープは external_member_sync を選びます。トークンは subscline_ で始まる文字列で、発行時に一度だけ表示されます。発行の手順は 会員連携用のトークンを発行する をご覧ください。
会員ランクを反映する場合は、先に管理画面で会員ランクの判定を設定します。設定の手順は 会員ランクとユーザーグループを設定する をご覧ください。
全体の流れ
共通の仕様
| 項目 | 内容 |
|---|---|
| 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,000 件) |
| 回数の上限 | トークンごとに 1 分あたり 30 回 |
- 送り先のアカウントはトークンで決まります。リクエストでアカウントを指定する項目はありません。
- 13 桁の数字でない値、登録されていない会員番号、削除済みの会員の会員番号は、エラーにせず応答の
unmatchedMemberNumbers(クーポンの使用では行ごとのmemberNotFound)で返します。ほかの会員番号は反映されます。 - ラベルの付け外しやクーポンの使用済みでは、自動応答やお客様への LINE 通知は送られません。
- 同じ内容を何度送っても結果は変わりません。失敗したときはそのまま再送してください。
外部の会員番号で指定する
外部の会員システムで発番した会員番号で指定する場合は、本文の externalSystem に連携先の識別子を入れます。その会員番号があらかじめ会員に紐付いている必要があります。
- 識別子は、ユーザーに登録した外部会員番号の「番号の種類」です(ユーザーを追加)。英小文字で始まり、英小文字・数字・
_・-の32文字以内です。 - 会員番号は文字列のまま照合し、先頭の0も区別します(
00123と123は別の番号です)。 - 紐付いていない番号、ほかの「番号の種類」の番号、ほかのアカウントの番号は照合されず、
unmatchedMemberNumbers(クーポンの使用ではmemberNotFound)で返します。 externalSystemを省略すると、会員証の13桁の番号として照合します。
{ "labelName": "来店30日以内", "mode": "add", "externalSystem": "pos-a", "memberNumbers": ["00123", "00456"] }エラー時の応答は次のとおりです。
| コード | 意味 |
|---|---|
400 | 本文の形式が不正(mode の値が違う、件数が上限を超えたなど) |
401 | トークンが無い・無効・無効化されている |
403 | トークンに external_member_sync スコープが無い |
429 | 回数の上限を超えた。時間をおいて再送してください |
配信対象を取り込む(ラベルの付与メンバー)
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件)が入ります。
取り込んだラベルを配信の宛先にする設定は、操作マニュアルの 取り込んだラベルで配信する で説明しています。
会員ランクを反映する
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 人以上のラベルを付け外しした場合や、対象の削除済みラベルを復活させた場合は、保存後に会員ランクの再計算を 1 回始めます。再計算は応答の後も進み、結果は会員ランク画面の「最後の再計算」で確かめられます。
- 再計算でランクが変わったお客様には、会員ランクに設定したランクアップ・ランクダウン時の自動応答が、管理画面でランクを変えたときと同じように送られます。ラベルの付け外しそのものでは送られません。
応答の例:
{
"matched": 2,
"updated": 1,
"unmatchedMemberNumbers": [],
"unknownRanks": [{ "memberNumber": "0000000000789", "rankName": "ダイヤ" }]
}updated はランクのラベルを付け外しした会員の数です。削除済みラベルの復活だけなら updated は 0 ですが、再計算は始まります。
店頭で使ったクーポンを使用済みにする
PUT /api/v1/external/member-sync/coupon-uses
店頭のレジで LINE のクーポンが使われたら、会員番号・クーポンコード・使った日時を送ります。お客様の保有クーポンが使用済みになり、LINE の「保有中」から消えて「利用履歴」に利用先「店頭」として表示されます。
使用済みにしたクーポンは、お客様が配布 URL や詳細を開き直しても「使用済み」と表示され、受け取り直すことはできません。
curl --request PUT \
--url 'https://api.subscline.jp/api/v1/external/member-sync/coupon-uses' \
--header 'Authorization: Bearer subscline_xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{ "uses": [ { "memberNumber": "0000000000123", "couponCode": "WELCOME10", "usedAt": "2026-11-14T10:00:00+09:00" } ] }'| 項目 | 内容 |
|---|---|
uses[].memberNumber | 会員番号 |
uses[].couponCode | クーポンコード(管理画面のクーポンで設定した「コード」) |
uses[].usedAt | 店頭で使った日時。2026-11-14T10:00:00+09:00 のように時差を付けます(Z も可) |
externalSystem | 任意。外部の会員番号で指定するときの番号の種類 |
応答の results に、送った順で 1 行ずつ結果が入ります。
status | 意味 |
|---|---|
used | 使用済みにしました |
alreadyUsed | すでに使用済みでした(使った日時は最初の日時のまま変わりません) |
memberNotFound | 会員番号が見つかりません |
couponNotFound | そのクーポンコードのクーポンがありません |
notGranted | お客様がそのクーポンを受け取っていません |
expired | 使った日時がクーポンの有効期限を過ぎています |
invalidUsedAt | 使った日時が現在時刻より未来か、日時として読めない表記です(10 分までの未来は受け付けます。小数秒は . で区切ってください) |
応答の例:
{
"results": [
{ "memberNumber": "0000000000123", "couponCode": "WELCOME10", "status": "used" }
],
"summary": {
"received": 1,
"used": 1,
"alreadyUsed": 0,
"memberNotFound": 0,
"couponNotFound": 0,
"notGranted": 0,
"expired": 0,
"invalidUsedAt": 0
}
}- 有効期限は
usedAtの日時で判定します。期限内に使ったものなら、送るのが期限の後でも反映されます。 expiredの行は反映されません。レジで期限切れのクーポンを受け付けてしまった場合は、店舗の運用で対応してください。invalidUsedAtの行は反映されません。レジの時計がずれていないか確認し、正しい日時で送り直してください。- 店頭での使用は、管理画面のクーポン一覧の「利用回数」と、最大利用回数・お客様ごとの利用回数の判定にも 1 回ずつ数えられます。
- 店頭で使ったクーポンを、予約・オンラインショップなどのお支払いで続けて使えないようにするには、クーポンの「お客様ごとの利用回数」の上限を設定してください(例: 1 回)。上限を設定していないクーポンは、店頭で使用済みにした後も、お支払い画面でコードを入力すると使えます。
- 送信に失敗したときは、そのまま再送してください。使用済みのものは
alreadyUsedになるだけで、二重に数えられません。