YappliCRMでは、顧客（会員）にポイントを付与し、ランクなどの会員プログラムに活用できます。ここでは、顧客のポイント付与履歴の取得、ポイントの付与・加減算、ポイント計算をおこなうエンドポイント群を説明します。すべてのエンドポイントで Authorization: Bearer {access_token} が必須です。また、リクエストボディを送信するエンドポイント（ポイント付与・ポイント計算）では、Content-Type: application/json も併せて指定してください。
ポイント付与履歴
GET/api/ext/users/{id}/points
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
id |
String | ○ | YappliCRMの顧客ID |
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 | デフォルト |
|---|---|---|---|---|
per_page |
Integer | - | 1ページあたりの件数（最大 1000） |
50 |
page |
Integer | - | ページ番号 | 1 |
レスポンス（成功時 200）
{
"points": [
{
"id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"point": 100,
"title": "購入ポイント付与",
"detail": null,
"remarks": null,
"expired_at": "2027-01-15 23:59:59",
"created_at": "2026-07-27 15:14:12",
"updated_at": "2026-07-27 15:14:12"
},
{
"id": "d2b3c4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
"point": -50,
"title": "クーポン利用による減算",
"detail": null,
"remarks": "外部システムからの減算処理",
"expired_at": null,
"created_at": "2026-08-01 09:00:00",
"updated_at": "2026-08-01 09:00:00"
}
],
"total": 2,
"per_page": 50,
"current_page": 1,
"last_page": 1
}Point Object
| フィールド | 型 | 説明 |
|---|---|---|
id |
String | ポイント履歴ID |
point |
Integer | 付与ポイント数（マイナス値の場合は減算） |
title |
String | ポイント付与のタイトル。アプリのポイント履歴画面等で、エンドユーザー向けの表示項目として利用されることが多い項目です |
detail |
String | 非推奨（Deprecated）：現在この項目に値が設定されることはなく、常に null が返却されます。将来のバージョンでレスポンスから削除される予定のため、この項目には依存しないでください |
remarks |
String | 備考 |
expired_at |
DateTime | 有効期限（Y-m-d H:i:s形式）。リクエスト時に日付のみ（Y-m-d）を指定した場合、その日の23:59:59が設定されます。有効期限が設定されていない場合はnull |
created_at |
DateTime | 作成日時（Y-m-d H:i:s形式） |
updated_at |
DateTime | 更新日時（Y-m-d H:i:s形式） |
レスポンス（失敗時）
HTTPステータス：400
{
"status": false,
"errors": "Member is not found"
}指定した id の顧客が存在しない場合に返却されます。アクセストークンが無効な場合のエラー形式は顧客一覧と同様です。詳細は エラーコード一覧 を参照してください。
ポイント有効期限一覧
GET/api/ext/users/{id}/points/expired_list
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 | デフォルト |
|---|---|---|---|---|
per_page |
Integer | - | 1ページあたりの件数（最大 1000） |
50 |
page |
Integer | - | ページ番号 | 1 |
レスポンス（成功時 200）
{
"points": [
{
"expired_at": "2027-01-15 23:59:59",
"point": "100"
}
],
"total": 1,
"per_page": 50,
"current_page": 1,
"last_page": 1
}| フィールド | 型 | 説明 |
|---|---|---|
expired_at |
DateTime | 有効期限（Y-m-d H:i:s形式） |
point |
String | 当該期限で失効するポイント数。数値ではなく 文字列 で返却されます |
注意点：このエンドポイントのpointは常に文字列型で返却されます（例："100"）。数値として扱う場合は、外部システム側で数値型への変換が必要です。対象となる有効期限付きポイントが0件の場合は、pointsが空配列（[]）、totalが0になります（"--"という文字列は返却されません）。
レスポンス（失敗時）
HTTPステータス：400
{
"status": false,
"errors": "Member is not found"
}指定した id の顧客が存在しない場合に返却されます。詳細は エラーコード一覧 を参照してください。
ポイント付与（加算・減算）
POST/api/ext/users/{id}/points
point に負の値を指定することで、ポイントの減算もおこなえます。
リクエストパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
point |
Integer | ○ | 付与するポイント数（負の値で減算） |
title |
String | - | ポイント付与のタイトル。アプリのポイント履歴画面等で、エンドユーザー向けの表示項目として利用されることが多い項目です |
expired_at |
Date | - | 有効期限（Y-m-d形式で指定）。省略した場合の挙動は後述の「有効期限の延長ルール」を参照 |
remarks |
String | - | 備考 |
リクエスト例
curl -X POST "{{APP_URL}}/api/ext/users/{id}/points" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"point": 500,
"title": "キャンペーンポイント付与",
"expired_at": "2027-03-31",
"remarks": "春の新生活応援キャンペーン"
}'レスポンス（成功時 200）
顧客情報（顧客詳細のMember Objectと同形式。ただし external_ids は含まれません）を返却します。
{
"member": {
"id": "a25b7276-e23a-4972-a6de-1452c944406f",
"unique_id": "U12345",
"pin": null,
"login_id": "user@example.com",
"rank": "gold",
"column01": null,
"column02": null,
"column03": null,
"column04": null,
"column05": null,
"column06": null,
"column07": null,
"column08": null,
"column09": null,
"column10": null,
"column11": null,
"column12": null,
"column13": null,
"column14": null,
"column15": null,
"column16": null,
"secret_question": null,
"secret_answer": null,
"point": 500,
"total_point": 500,
"logined": 0,
"enabled": 1,
"memo": null,
"ud_id": null,
"point_geted_at": "2026-07-27 16:14:32",
"point_used_at": "--",
"point_expired_at": "2027-03-31",
"point_expired_point": "--",
"logined_at": null,
"created_at": "2026-07-27 16:14:21",
"updated_at": "2026-07-27 16:14:32"
}
}特に以下の3項目は、ポイント残高の状況を確認する上で重要です。
| フィールド | 型 | 説明 |
|---|---|---|
point_used_at |
Date / String | 初回ポイント使用日。「最終使用日」ではなく最も古い（初回の）使用日が返却されます。未設定時は null ではなく "--" という文字列で返却されます |
point_expired_at |
String | 今後失効するポイントのうち、もっとも近い有効期限日（YYYY-MM-DD 形式。期間の制限を受けません）。今後失効する予定のポイントが1件もない場合は "--" という文字列で返却されます（例：ポイントの獲得履歴がない、保有ポイントを使い切っている、有効期限付きのポイントがすべて期限切れ、有効期限のないポイントのみを保有している、のいずれかに該当する場合） |
point_expired_point |
String | 管理画面の「直近失効ポイント表示」設定で指定した期間内に失効するポイント数の合計。デフォルト設定（「直近」）の場合は、もっとも近い失効日に失効するポイント数です。値がある場合も常に文字列型で返却され、1,000以上の場合はカンマ区切り（例："1,234"）になります。該当するポイントがない場合は同様に "--" という文字列で返却されます |
この3項目が返却されるのはYappliCRMのポイント機能を利用しているクライアントのみで、ポイント機能を利用していないクライアントでは "--" ではなくキー自体がレスポンスに含まれません。
point_expired_atとpoint_expired_pointは、集計する範囲が異なるため、必ずセットで値が入る・"--"になるわけではありません。point_expired_pointの集計期間（「直近失効ポイント表示」設定）よりも先の日付にしか失効ポイントがない場合、point_expired_atには日付が入っていてもpoint_expired_pointは"--"になります（例：設定が「直近30日」で、もっとも近い失効日が2ヶ月先の場合、point_expired_atは日付を返しつつpoint_expired_pointは"--"になります）。
ランク設定は当社担当者側での設定が必要な項目のため、アプリでランクプログラムを構築する際は、事前に当社担当者へご相談ください。
ポイント減算時の消込順序
ポイントを減算する際、以下の優先順位で消し込まれます。
- 有効期限が最も早いポイントから消し込まれる
- 同じ有効期限のポイントが複数ある場合は、その中でも付与タイミングが早いものから消し込まれる
- 最後に、有効期限が設定されていないポイントが消し込まれる
有効期限の延長ルール
YappliCRMのポイント期限タイプには「ポイント単位」と「最終付与日」があります。いずれか一方が設定されます。この設定は当社担当者が設定します。
- ポイント単位：ポイントごとに個別の有効期限が設定されます。付与タイミングで「付与された日から設定した期限分を延長した日の
23:59:59」が有効期限として設定され、以降は更新されません。 - 最終付与日：
expired_atを指定せずにポイントが付与されると、その時点の残存ポイントの有効期限が、「新たに付与された日から設定した期限分を延長した日の23:59:59」に一括更新されます。ただし、以下のポイントは更新対象外です。expired_atを明示的に指定して付与したポイント（後述）- 無期限のポイント（期限付きに変わることはありません）
- 失効済み・使い切ったポイント（復活しません）
まとめると、以下のようになります。
expired_atを指定しない場合：有効期限の挙動は「ポイント期限タイプ」設定に従います（前述のとおり）。expired_atを明示的に指定した場合：ポイント期限タイプの設定に関わらず、指定したexpired_atで有効期限が固定されます。このポイントの有効期限は、その後どのような操作（別のポイント付与など）をおこなっても変更されません。
レスポンス（失敗時）
HTTPステータス：400
{
"status": false,
"errors": ["Member is not found"]
}指定した id の顧客が存在しない場合に返却されます。
point に整数以外の値を指定した場合は、以下のエラーが返却されます。
{
"status": false,
"errors": ["pointには、整数を指定してください。"]
}point を指定しなかった場合は、以下のエラーが返却されます。
{
"status": false,
"errors": ["pointは、必ず指定してください。"]
}point に指定可能な範囲（-999999〜999999）を超える値を指定した場合は、以下のようなエラーが返却されます。
{
"status": false,
"errors": ["pointには、-999999以上の数字を指定してください。"]
}ポイント機能を利用していないクライアントの場合は、以下のエラーが返却されます。
{
"status": false,
"errors": "Not available for points"
}point に負の値（減算）を指定し、保有ポイントが不足している場合は、以下のエラーが返却されます。errors はフィールド名をキーにしたオブジェクト形式で返却される点に注意してください（他のエラーとは形式が異なります）。
{
"status": false,
"errors": {
"point": ["保有ポイントが不足しています。"]
}
}詳細は エラーコード一覧 を参照してください。
ポイント計算
POST/api/ext/users/{id}/points/calculation
購入金額等から、ランクに応じた付与率でポイント付与額を計算し、実際に付与します。ランクに応じた付与率は当社担当者が設定します。
リクエストパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
amount |
Integer | ○ | ポイント計算の元になる金額等の数値 |
title |
String | - | ポイント付与のタイトル。アプリのポイント履歴画面等で、エンドユーザー向けの表示項目として利用されることが多い項目です |
expired_at |
Date | - | 有効期限（Y-m-d形式で指定）。省略した場合の挙動はポイント付与（加算・減算）の「有効期限の延長ルール」と同様です |
remarks |
String | - | 備考 |
リクエスト例
curl -X POST "{{APP_URL}}/api/ext/users/{id}/points/calculation" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"amount": 2000,
"title": "購入によるポイント計算付与",
"remarks": "オンラインストア注文No.12345"
}'レスポンス（成功時 200）
顧客情報（顧客詳細のMember Objectと同形式。ただし external_ids は含まれません）を返却します。
{
"member": {
"id": "a25b8891-a58d-4dc7-b629-6d7e37933b25",
"unique_id": "U12345",
"pin": null,
"login_id": "user@example.com",
"rank": "silver",
"column01": null,
"column02": null,
"column03": null,
"column04": null,
"column05": null,
"column06": null,
"column07": null,
"column08": null,
"column09": null,
"column10": null,
"column11": null,
"column12": null,
"column13": null,
"column14": null,
"column15": null,
"column16": null,
"secret_question": null,
"secret_answer": null,
"point": 20,
"total_point": 20,
"logined": 0,
"enabled": 1,
"memo": null,
"ud_id": null,
"point_geted_at": "2026-07-27 17:16:22",
"point_used_at": "--",
"point_expired_at": "2028-07-26",
"point_expired_point": "--",
"logined_at": null,
"created_at": "2026-07-27 17:16:09",
"updated_at": "2026-07-27 17:16:22"
}
}上記の例では、amount: 2000に対してsilverランクの付与率（1%）が適用され、20ポイントが付与されています。title・remarksに指定した値は、ポイント付与履歴の該当するPoint Objectにもそのまま反映されます。
計算方法について
現行の付与率計算は、「金額 × ランクごとの付与率」という単一のレートを掛け合わせる方式です（基礎付与分・ランク上乗せ分・期間施策上乗せ分を分けて計算する仕組みはありません）。付与率はクライアント・ランクごとの設定によります。
上記の掛け算の結果、小数点以下が発生した場合は切り捨てとなります（例：amount: 1050 に付与率1%を適用した場合、計算上は10.5ポイントですが、実際に付与されるのは10ポイントです）。
レスポンス（失敗時）
HTTPステータス：400
{
"status": false,
"errors": ["Member is not found"]
}指定した id の顧客が存在しない場合に返却されます。
amount に不正な値（文字列等）を指定した場合は、以下のエラーが返却されます。
{
"status": false,
"errors": ["amountには、整数を指定してください。"]
}amount を指定しなかった場合は、以下のエラーが返却されます。
{
"status": false,
"errors": ["amountは、必ず指定してください。"]
}amount に指定可能な範囲（1〜999999999）を超える値を指定した場合は、以下のようなエラーが返却されます。
{
"status": false,
"errors": ["amountには、999999999以下の数字を指定してください。"]
}ポイント機能を利用していないクライアントの場合は、以下のエラーが返却されます。
{
"status": false,
"errors": "Not available for points"
}詳細は エラーコード一覧 を参照してください。