クーポン新規作成API
概要
POSTされたデータを使用して、新しくクーポンを作成します。
URL
/cmapi/v2/coupons/
メソッド
POST
リクエスト
リクエストパラメータ
なし
リクエストボディ
基底オブジェクト
| キー | 型 | 必須 | デフォルト | 許容値 | 説明 | 詳細 | 備考 |
|---|---|---|---|---|---|---|---|
| providers | 数値配列 | - | [] | 数値 | クーポン利用可能店舗ID | 利用可能店舗のIDを指定。 指定がない（空配列）場合は「全店舗」となる。 |
※ 配列内には数値が1つのみ指定可能。 |
| is_distributable | 真偽値 | o | - | - | 限定クーポンとするかどうか | true:限定クーポン false:通常クーポン |
- |
| name | 文字列 | o | - | 1文字以上30文字以下 | クーポン名 | - | 推奨 20文字以内 |
| short_description | 文字列 | o | - | 1文字以上100文字以下 | クーポン概要説明 | - | 推奨 60文字以内 |
| description | 文字列 | - | "" | 1000文字以内 | クーポン利用条件 | - | - |
| priority | 数値 | - | 0 | 9999以下 | 表示順ポイント | クーポン一覧画面での表示優先順位。値の大きい順に上から表示される。 | - |
| user_usable_count | 数値 | - | null | 1以上 | 1人あたり使えるクーポン枚数 | 1人が1つのクーポンを使用可能な回数。 null を指定した場合は「無制限」となる。 |
- |
| total_usable_count | 数値 | - | null | 1以上 | クーポン利用上限枚数 | 全ユーザに対する、1つのクーポンの利用上限枚数。 null を指定した場合は「無制限」となる。 |
- |
| user_distributable_count | 数値 | - | 0 | 1以上 | 【限定クーポン用パラメータ】 1人あたり配布できるクーポン枚数 |
1人に配布可能な1つの限定クーポンの枚数。 限定クーポンの場合は、指定必須 null 不可。 |
通常クーポンの場合は、利用されません。 |
| total_distributable_count | 数値 | - | null | 1以上 | 【限定クーポン用パラメータ】 全体のクーポン配布上限枚数 |
全ユーザに対する、1つの限定クーポンの配布上限枚数。 null の場合は「無制限」となる。 |
通常クーポンの場合は、利用されません。 |
| visible_start_at | 文字列 | o | - | - | 表示開始日時 | 「yyyy-mm-dd hh:MM:ss」の形式で指定。 | - |
| visible_end_at | 文字列 | o | - | - | 表示終了日時 | 「yyyy-mm-dd hh:MM:ss」の形式で指定。 | - |
| usable_start_at | 文字列 | o | - | - | 有効開始日時 | 「yyyy-mm-dd hh:MM:ss」の形式で指定。 | - |
| usable_end_at | 文字列 | o | - | - | 有効終了日時 | 「yyyy-mm-dd hh:MM:ss」の形式で指定。 | - |
| usable_days | 数値 | - | null | 0以上 | 【限定クーポン用パラメータ】 配布後有効日数 |
限定クーポンを受け取った時点を起点とした限定クーポンの有効期限を設定する。「配布後有効日数」より「有効終了日時」が優先される。 nullを指定した場合は、配布後有効期限無しとなる。 |
通常クーポンの場合は、利用されません。 有効日数が適用される場合の時刻は「23:59:59」までとなる。 |
| is_open | 真偽値 | - | false | - | ステータス | ユーザにクーポンを公開するか、非公開とするかのステータス。 true : 公開 false : 非公開 |
「非公開」の場合、ユーザには表示されない。 |
| additional_items | オブジェクト | o | - | - | 任意追加項目 | 「リクエスト "additional_items" オブジェクト」を参照。 | - |
リクエスト "additional_items" オブジェクト
- "additional_items" には、 FANSHIP システム公式の 5 項目の他に、ユーザ独自の項目を付与することが可能です。
- ユーザ独自の項目が付与されていた場合、"additional_items" に値が登録されます。
- "additional_items" オブジェクト内のキー名の命名規則については次の通り(value については特に制限を設けません)。
- FANSHIP システム ：
[A-Za-z][A-Za-z0-9_\-]* - ユーザ独自 ：
_[A-Za-z0-9_\-]+
- FANSHIP システム ：
※ユーザ独自項目（以下記載の 5 項目以外）をご利用される場合は、必ずご相談ください。
| キー | 型 | 必須 | デフォルト | 最大 | 説明 | 詳細 | 備考 |
|---|---|---|---|---|---|---|---|
| image | 文字列 | - | - | - | クーポン画像 | クーポン画像データのフルパス（https:// .... ）を指定。 | 画像指定に関する仕様については「画像登録」シートを参照。 |
| thumbnail | 文字列 | - | - | - | サムネイル | サムネイル画像データのフルパス（https:// ... ）を指定。 | 画像指定に関する仕様については「画像登録」シートを参照。 |
| couponCode | 文字列 | - | - | 20 | クーポンコード | 英数字のみ指定可能。 クーポンの利用時に認証コードの入力を必須とする場合に設定。 |
couponCode と couponCodeList はどちらか一方しか登録できない。 |
| couponCodeList | 文字配列 | - | - | 20 (クーポンコード 1 件あたり) | クーポンコードリスト | 英数字のみ指定可能。 クーポンの利用時に認証コードの入力を必須とする場合に設定。 リスト形式で、クーポンコードを最大 2,000 件まで登録可能。 |
couponCode と couponCodeList はどちらか一方しか登録できない。 |
| couponCodeVisible | 真偽値 | - | - | - | クーポンコード表示設定 | クーポンコードをアプリ画面に表示するかどうか。 true : 表示 false : 非表示 |
couponCode または couponCodeList を指定した場合は必須。 couponCodeList を指定した場合、リストの要素が 1 件である時のみ true を設定可能。 |
リクエストのサンプル
{
"providers": [1],
"is_distributable": true,
"name": "クーポン名",
"short_description": "概要説明",
"description": "詳細説明",
"priority": 1,
"user_usable_count": 1,
"total_usable_count": 1,
"user_distributable_count": 1,
"total_distributable_count": 10000,
"visible_start_at": "2019-03-26 00:00:00",
"visible_end_at": "2222-12-31 23:59:59",
"usable_start_at": "2019-03-26 00:00:00",
"usable_end_at": "2222-12-31 23:59:59",
"usable_days": 1,
"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
}
}
レスポンス
メディアタイプ
application/json
成功時レスポンス
http status 201 を返却し、作成したリソースを指し示す Location ヘッダを返却
レスポンスのサンプル
なし