クーポン一覧参照API
概要
リクエストパラメータに指定された値を使用して、限定・通常クーポン含めすべてのクーポン一覧を取得します。
URL
/cmapi/v2/coupons/
メソッド
GET
リクエスト
リクエストパラメータ
| パラメータ | 必須 | デフォルト | 最大 | 説明 | 詳細 | 備考 |
|---|---|---|---|---|---|---|
| page_size | - | 20 | 100 | ページ毎の件数 | - | - |
| page | - | 1 | - | ページ数 | - | - |
| sort | - | -id | - | ソート | 指定された項目でソートを行う。 降順でソートしたい場合、項目名の前に "-" を付与する。 |
現在、"id" の昇順降順のみ対応 |
| is_distributable | - | - | - | クーポン種別 | クーポン種別で絞り込み検索を行う。 指定する場合、次の2つが有効。 true: 限定クーポン false: 通常クーポン |
指定がない場合は種別に関係なくすべてのクーポン情報を返す。 |
| visible_start_at_before | - | - | - | 表示開始日以前 | 付与された「表示開始日」以前のクーポンを取得する。 | 「yyyy-mm-dd%20hh:MM:ss」の形式 |
| visible_start_at_after | - | - | - | 表示開始日以後 | 付与された「表示開始日」以後のクーポンを取得する。 | 「yyyy-mm-dd%20hh:MM:ss」の形式 |
| visible_end_at_before | - | - | - | 表示終了日以前 | 付与された「表示終了日」以前のクーポンを取得する。 | 「yyyy-mm-dd%20hh:MM:ss」の形式 |
| visible_end_at_after | - | - | - | 表示終了日以後 | 付与された「表示終了日」以後のクーポンを取得する。 | 「yyyy-mm-dd%20hh:MM:ss」の形式 |
| providers | - | - | - | 利用可能店舗 ID | 利用可能店舗で絞り込み検索を行う。 複数指定が可能。 e.g.) providers=1&providers=2 |
- |
| embed | - | - | - | 追加フィールド指定 | 追加したいフィールド名を指定する。 | preview_idのみ指定可能 |
リクエストボディ
なし
リクエストのサンプル
curl \
-X GET \
-H 'X-POPINFO-MAPI-TOKEN: ${AUTH_TOKEN}' \
https://${domain}/cmapi/v2/coupons/?page_size=5&page=2&is_distributable=true&visible_start_at_after=2019-04-01%2012:00:00
レスポンス
メディアタイプ
application/json
レスポンスヘッダ
| キー | 説明 | 備考 |
|---|---|---|
| X-Total-Count | 総数 | |
| Link | リンク情報 | 次の形式で「次のページ」と「前のページ」の情報を付与。<next_page_url>; rel="next", <previous_page_url>; rel="previous" |
成功時レスポンス
「 基底オブジェクト」のリストを返却
基底オブジェクト
| キー | 型 | 説明 | 詳細 | 備考 |
|---|---|---|---|---|
| id | 数値 | 内部ID | - | この値は利用しないでください。 |
| uuid | 文字列 | クーポン UUID | - | - |
| is_distributable | 真偽値 | 限定クーポンかどうか | true:限定クーポン false:通常クーポン |
- |
| name | 文字列 | クーポン名 | - | - |
| short_description | 文字列 | クーポン概要説明 | - | - |
| description | 文字列 | クーポン利用条件 | - | - |
| priority | 数値 | 表示順ポイント | - | - |
| user_usable_count | 数値 | 1人あたり使えるクーポン枚数 | - | - |
| total_usable_count | 数値 | クーポン利用上限枚数 | - | - |
| user_distributable_count | 数値 | 1人あたり配布できるクーポン枚数 | - | - |
| total_distributable_count | 数値 | クーポン配布上限枚数 | - | - |
| visible_start_at | 文字列 | 表示開始日時 | 「yyyy-mm-dd hh:MM:ss」の形式 | - |
| visible_end_at | 文字列 | 表示終了日時 | 「yyyy-mm-dd hh:MM:ss」の形式 | - |
| usable_start_at | 文字列 | 有効開始日時 | 「yyyy-mm-dd hh:MM:ss」の形式 | - |
| usable_end_at | 文字列 | 有効終了日時 | 「yyyy-mm-dd hh:MM:ss」の形式 | - |
| usable_days | 数値 | 配布後有効日数 | - | - |
| is_open | 真偽値 | ステータス | ユーザにクーポンを公開するか、非公開とするかのステータス。 true : 公開 false : 非公開 |
|
| additional_items | オブジェクト | 任意追加項目 | 「レスポンス "additional_items" オブジェクト」を参照。 | - |
| counter_distributed | 数値 | 配布数 | - | - |
| counter_favorite | 数値 | お気に入り登録数 | - | - |
| counter_used | 数値 | 利用数 | - | - |
| custom_url | 文字列 | 配布用カスタムURL | - | - |
| providers | 数値配列 | クーポン利用可能店舗ID | - | - |
| created_at | 文字列 | 作成日時 | 「yyyy-mm-dd hh:MM:ss」の形式 | - |
| updated_at | 文字列 | 更新日時 | 「yyyy-mm-dd hh:MM:ss」の形式 | - |
| preview_id | 文字列 | 配布前限定クーポン参照用ID | クエリパラメータにembed=preview_id指定されたときのみ |
レスポンス "additional_items" オブジェクト
- ユーザ独自の項目が登録されていた場合、FANSHIP システム公式の 5 項目の他に、ユーザ独自の項目も含めて返す。
| キー | 型 | 説明 | 詳細 | 備考 |
|---|---|---|---|---|
| image | 文字列 | クーポン画像 | クーポン画像データのフルパス（https:// ... ） | 画像指定に関する仕様については「画像登録」シートを参照。 |
| thumbnail | 文字列 | サムネイル | サムネイル画像データのフルパス（https:// ... ） | 画像指定に関する仕様については「画像登録」シートを参照。 |
| couponCode | 文字列 | クーポンコード | 英数字のみ指定可能。クーポンの利用時に認証コードの入力を必須とする場合に設定。 | couponCode と couponCodeList はどちらか一方しか登録できない。 |
| couponCodeList | 文字配列 | クーポンコードリスト | 英数字のみ指定可能。 クーポンの利用時に認証コードの入力を必須とする場合に設定。 リスト形式で、クーポンコードを最大 2,000 件まで登録可能。 |
couponCode と couponCodeList はどちらか一方しか登録できない。 |
| couponCodeVisible | 真偽値 | クーポンコード表示設定 | クーポンコードをアプリ画面に表示するかどうか。 true : 表示 false : 非表示 |
- |
レスポンスのサンプル
[
{
"id": 546,
"uuid": "859a89fe-1a20-42db-9d89-4c50a7da394e",
"is_distributable": true,
"name": "クーポン名1",
"short_description": "概要説明1",
"description": "詳細説明1",
"priority": 3,
"user_usable_count": 1,
"total_usable_count": 1,
"user_distributable_count": 1,
"total_distributable_count": 10000,
"visible_start_at": "2019-03-26T00:00:00",
"visible_end_at": "2222-12-31T23:59:59",
"usable_start_at": "2019-03-26T00:00:00",
"usable_end_at": "2222-12-31T23:59:59",
"usable_days": null,
"is_open": false,
"additional_items": {
"image": "https://${domain}/storage/1/image/2019/03/26/072128329898/qJnAg8rh6C.png/",
"thumbnail": "https://${domain}/storage/1/image/2019/03/26/072128329898/8rqgJnh6AC.png/",
"couponCodeList": ["1234", "abc", "xxx123"],
"couponCodeVisible": false
"_user_custom_key_1": "user_custom_value",
"_user_custom_key_2": 2
},
"counter_distributed": 0,
"counter_favorite": 0,
"counter_used": 0,
"custom_url": "{{ url_scheme }}://jp.demo.if.coupon/coupons/?uuid=8c122739-beeb-4a4d-99af-9cc23a1befd4&action=distribute",
"providers": [1],
},
{
"id": 547,
"uuid": "859a89fe-1a20-42db-9d89-4c50a7da789a",
"is_distributable": false,
"name": "クーポン名2",
"short_description": "概要説明2",
"description": "詳細説明2",
"priority": 4,
"user_usable_count": 1,
"total_usable_count": 1,
"user_distributable_count": 1,
"total_distributable_count": 10000,
"visible_start_at": "2019-03-26T00:00:00",
"visible_end_at": "2222-12-31T23:59:59",
"usable_start_at": "2019-03-26T00:00:00",
"usable_end_at": "2222-12-31T23:59:59",
"usable_days": null,
"is_open": false,
"additional_items": {
"image": "https://${domain}/storage/1/image/2019/03/26/072128329898/qJnAg8rh6C.png/",
"thumbnail": "https://${domain}/storage/1/image/2019/03/26/072128329898/8rqgJnh6AC.png/",
"_user_custom_key_1": "user_custom_value",
"_user_custom_key_2": 2
},
"counter_distributed": 0,
"counter_favorite": 0,
"counter_used": 0,
"custom_url": "",
"providers": [],
}
]