メインコンテンツまでスキップ

ECポイントの仕様とポイント更新・履歴取得API

Kurocoのメンバーが保有するECポイントの管理仕様と、外部システムからポイントを操作・参照するためのAPIについて説明します。

  • ポイント更新API（ECPoint::update）: メンバーのポイントを付与・消費します。
  • ポイント履歴取得API（ECPoint::history）: メンバーのポイント履歴と現在残高を取得します。

ポイントの基本概念​

  • メンバーごとにポイント残高（合計ポイント）を持ちます。
  • 残高の増減はすべてポイント履歴に記録され、ポイント履歴が正式な記録です。メンバーの「更新履歴」にはポイントの変更は記録されません。
  • ポイントの付与はロット（付与1件）単位で管理され、各ロットは「残ポイント」（そのロットの未消費分）を持ちます。
  • 消費は失効期限の近いロットから順に充当されます。失効期限のないロットは最後に充当されます。

ポイントステータスと性質​

確定ポイント仮ポイント失効ポイント
残高に含まれる✅❌❌
消費に利用できる✅❌❌
仮ポイント確定バッチの対象❌✅（確定日到来で確定になり残高に加算）❌
ポイント失効バッチの対象✅（失効日超過で未消費分のみ失効）❌❌

ポイントの確定・失効バッチ​

  • 仮ポイント確定バッチ: 確定日が到来した仮ポイントを確定にし、残高に加算します。
  • ポイント失効バッチ（日次）: 失効日（expire_date）を過ぎた確定ロットの未消費分だけを失効させます。すでに使った分が二重に差し引かれることはありません。失効時はポイント履歴に「ポイント失効(...)」という消費履歴が追加されます。

残高がロットの未消費分より少ない場合（履歴の直接編集などで残高とロットが一致しなくなった場合）は、残高の範囲内でのみ減算されます。残高がマイナスになることはなく、この場合もロットは失効になります。

バッチの実行タイミングはデフォルトのバッチ処理 一覧（ec_fix_point / ec_expire_point）を参照してください。

注記

EC注文が1件もないサイトでも、ポイント履歴があれば確定・失効バッチは動作します。API/CSVで運用するポイントも失効・確定されます。

ポイント操作の経路一覧​

どの経路でポイントを操作しても、残高の変更には必ずポイント履歴が残ります。

操作経路残高への反映ポイント履歴メンバー更新履歴残高不足の減算冪等キー
ポイント更新API（ECPoint::update）即時（確定）✅ 記録（理由=リクエストのreason）❌ 記録されない422エラー（何も変化しない）✅
CSVアップロード / bulk_upsert API上書き✅ 差分を記録（理由=「CSVで更新」）❌ 記録されない—（上書きのため常に成功）❌
メンバー編集画面のポイント詳細（行追加・確定）即時✅ 記録（理由=入力した内容）❌ 記録されないエラー表示（反映されない）❌
メンバー編集画面の合計ポイント欄編集不可（表示のみ）————
member/update API（メンバー情報更新API）更新不可（ec_pointはエラー）————
EC注文・キャンペーン等の既存機能従来どおり✅ 記録❌ 記録されない従来どおり❌

ポイント更新API（ECPoint::update）​

メンバーのポイントを外部システムから増減するAPIです。

エンドポイント設定​

管理画面のAPI設定でエンドポイントを作成して利用します。

項目内容
モデルECPoint
オペレーションupdate
HTTPメソッドPOST
注意

ポイントを発行できるAPIのため、必ず認証必須で運用してください。認証なしでの公開は不正なポイント発行につながります。

リクエストパラメータ​

リクエストボディは application/json 形式です。

パラメータ必須説明
member_id✅対象メンバーID
point✅増減ポイント（整数のみ。小数や数値以外はエラー）。正の値=付与、負の値=消費。0は指定不可。絶対値の上限は2,000,000,000
reason✅更新理由。ポイント履歴に記録され、ポイント履歴取得APIや管理画面に表示されます
expire_date-付与分の失効日（例: 2030-12-31）
idempotency_key-冪等キー（最大255文字）。冪等キーを参照してください

付与と消費の挙動​

付与（point > 0）消費（point < 0）
残高への反映即時加算（確定ポイントとして付与され、仮ポイントにはなりません）即時減算
履歴の記録先付与ポイント（add_point）＋残ポイント使用ポイント（use_point）
expire_date✅ 有効（省略時は無期限。過去日を指定した場合は次回失効バッチで失効します）❌ 無視されます
残高不足—422エラー。残高・履歴とも一切変化しません
充当順—失効期限の近い付与分から消費されます

レスポンス​

フィールド説明
point更新後の残高
ec_point_history_id作成されたポイント履歴のID

エラー​

コード条件
400JSONスキーマ違反（未知のパラメータ、型不正など）
401認証エラー
404メンバーが存在しない
422pointが0・整数でない・上限超過 / reasonが空 / expire_dateが不正な日付 / idempotency_keyが255文字超 / 残高不足 / 冪等キーの誤った再利用

冪等キー（idempotency_key）​

通信タイムアウト等でリトライした際の二重付与・二重減算を防ぐ仕組みです。外部連携では指定を推奨します。キーには注文番号+操作種別など一意な文字列を指定します。

再送パターン結果
同一キー × 同一内容（member_id / point / expire_date が同じ）再適用されない。初回と同じ ec_point_history_id と現在残高を返します（200）。タイムアウト時は同じキーでそのまま再送すれば安全です
同一キー × 異なる内容（member_id / point / expire_date のいずれかが違う）422エラー（キーの使い回しとして拒否され、何も変化しません）
キー未指定・空文字冪等チェックなし（毎回適用されます）
同一キーの同時並行リクエスト一方のみ適用され、もう一方は初回結果を返します

ポイント履歴取得API（ECPoint::history）​

メンバーのポイント履歴と現在残高を取得するAPIです。

エンドポイント設定​

項目内容
モデルECPoint
オペレーションhistory
HTTPメソッドGET

利用パターンとパラメータ​

利用パターン指定するパラメータ備考
管理・サーバー間連携（任意のメンバー）member_idメンバー不存在は404
メンバー向けマイページ（本人のみ）self_only=1member_id は無視されます。未ログインは401
ページングcnt（1ページ件数）/ pageID（ページ番号）cnt は省略時20件
件数のみonly_count=1list は空になり、pageInfo は totalCnt のみ、total_point は返却されません

レスポンス​

フィールド説明
total_point現在の残高
pageInfototalCnt / perPage / pageNo / totalPageCnt
list履歴の配列（新しい順）

list の主なフィールドは以下のとおりです。

フィールド説明
add_point / add_reason付与ポイントと理由
use_point / use_reason消費ポイントと理由
point_status1=確定 / 2=仮 / 3=失効
remaining_point付与ロットの未消費残。消費や失効で減少します
fix_date確定日
expire_date失効予定日（無期限の場合はnull）
inst_ymdhi / update_ymdhi作成・更新日時（ISO 8601）
注記

管理者名などの内部情報や他システムの冪等キーはレスポンスに含まれません。

メンバーCSVアップロード・bulk_upsert APIでのポイント上書き​

メンバーCSVアップロードの ec_point 列でポイント残高を上書きできます（bulk_upsert APIも同じ挙動です）。

CSVの内容残高ポイント履歴
ec_point 列があり、現在より大きい値上書き✅ 差分を付与として記録（理由=「CSVで更新」）
ec_point 列があり、現在より小さい値上書き✅ 差分を消費として記録
ec_point 列があり、現在と同じ値変化なし記録されない
ec_point 列があり空欄 ＋ 空更新設定ONクリア（空）✅ 従来残高の全額を消費として記録
新規メンバーの行に ec_point あり初期値として設定✅ 初期残高を付与として記録
ec_point 列がない一切変化しない（従来どおり）記録されない
注記

残高の上書き後にポイント履歴の記録に失敗した行がある場合は、「会員データは更新されましたが、ポイント履歴の記録に失敗しました。」というエラーが表示されます。この場合、該当行のメンバーデータ（残高の上書きを含む）自体は更新されています。

アップロード手順はメンバーアップロードを参照してください。

管理画面（メンバー編集）でのポイント操作​

  • 合計ポイントの直接編集欄は廃止され、表示のみになります。
  • ポイント詳細（履歴）テーブルに**「残ポイント」列**が追加され、確定付与ロットの未消費残（消費・失効の進み具合）が確認できます。

ポイント詳細への行追加のステータス別挙動は以下のとおりです。

追加する行のステータス残高への反映備考
確定 × 付与即時加算残ポイント付きのロットとして記録されます
確定 × 消費即時減算残高不足の場合は保存前にエラーになり、メンバー情報を含めて保存されません
仮反映されない確定バッチで確定日到来時に加算されます
失効反映されない記録のみ
備考
  • 確定ステータスの行では、付与と消費を同じ行に同時に入力できません。
  • 確定ステータスの既存の履歴行は編集・削除できません。また、既存行のステータスを確定へ変更することもできません。仮ポイントの確定は仮ポイント確定バッチで行われます。

画面の項目説明はメンバーを参照してください。

注意事項・制限​

  • member/update API（メンバー情報更新API）では ec_point は更新できません（リクエストに含めるとエラーになります）。ポイントの外部操作は、ポイント更新API / bulk_upsert API / CSVアップロードのいずれかを使用してください。
  • ポイント失効バッチで失効するのは「未消費分のみ」です。使用済み分を含む全額が失効する挙動ではありません。

関連ドキュメント​

サポート

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。

フォームから問い合わせをする
Slackコミュニティに参加する