关于 礼品卡

访问范围

需要多个访问范围—请参阅每个端点以了解访问范围要求。

需要访问受保护的客户数据。

礼品卡是 Genstore 支付解决方案中的重要组成部分，它允许客户购买和使用预付金额，为在线商店提供灵活的支付选项，Genstore 提供了一系列 RESTful 接口，用于实现礼品卡的全面管理功能创建、更新、失效、查询等操作，方便商家便捷地管理和追踪礼品卡使用情况。

核心功能

• 基础操作：创建礼品卡、更新礼品卡、失效礼品卡
• 信息查询：查询礼品卡详情、查询礼品卡列表、统计礼品卡数量

应用场景

• 礼品卡销售：店铺管理员可推出数字礼品卡项目、定制卡片设计和面额、管理促销规则，扩展支付选择并创造新的收入来源。
• 礼品卡生命周期管理：客服团队可高效处理礼品卡发行、处理余额更新、管理卡片状态变更，确保礼品卡交易的安全性和准确性。
• 礼品卡数据分析：业务分析师可追踪礼品卡表现指标、生成使用报告、分析购买模式，优化礼品卡项目并提升客户参与度。

接口

POST /api/202412/gift_cards: 创建礼品卡

POST /api/202412/gift_cards/{giftCardId}/disable: 禁用礼品卡

PUT /api/202412/gift_cards/{giftCardId}: 更新礼品卡

GET /api/202412/gift_cards/search: 搜索礼品卡

GET /api/202412/gift_cards/count: 查询礼品卡数量

GET /api/202412/gift_cards/{giftCardId}: 查询礼品卡详情

礼品卡 对象

礼品卡对象

属性

giftCardobject

礼品卡信息。

- 收起属性

customerIdobject

当前礼品卡分配给的客户的客户ID。

idnumber

礼品卡ID。

codestring

礼品卡编码。

lastCharactersstring

code的最后四位字符。

balancenumber

礼品卡余额。

initialValuenumber

礼品卡初始金额。

orderIdobject

关联的订单ID。

lineItemIdobject

关联的订单物品。

currencystring

礼品卡面值对应币种。

noteobject

当前礼品卡的备注信息。

disableTimeobject

礼品卡禁用时间。

expireTimestring

当前礼品卡的到期时间，null为永不过期。

createTimestring

礼品卡创建时间。

updateTimestring

礼品卡更新时间。

userIdobject

用户在admin界面上创建礼品卡时的管理员账户ID。

礼品卡 对象

{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

POST 创建礼品卡

创建礼品卡。

访问范围

需要以下任意访问权限: write_gift_card

接口

POST /api/202412/gift_cards 

请求参数

giftCardobject

- 收起属性

customerIdnumber

当前礼品卡分配给的客户的客户ID。

codestring

礼品卡码。

initialValuenumber

礼品卡初始余额。

notestring

当前礼品卡的备注信息，字符数量限制500。

expireTimenumber

当前礼品卡的到期时间。

响应数据

giftCardobject

礼品卡信息。

- 收起属性

customerIdobject

当前礼品卡分配给的客户的客户ID。

idnumber

礼品卡ID。

codestring

礼品卡编码。

lastCharactersstring

code的最后四位字符。

balancenumber

礼品卡余额。

initialValuenumber

礼品卡初始金额。

orderIdobject

关联的订单ID。

lineItemIdobject

关联的订单物品。

currencystring

礼品卡面值对应币种。

noteobject

当前礼品卡的备注信息。

disableTimeobject

礼品卡禁用时间。

expireTimestring

当前礼品卡的到期时间，null为永不过期。

createTimestring

礼品卡创建时间。

updateTimestring

礼品卡更新时间。

userIdobject

用户在admin界面上创建礼品卡时的管理员账户ID。

POST /api/202412/gift_cards

curl -X POST \ 
https://{shop}.genmystore.com/api/202412/gift_cards" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"giftCard":{
		"note":"this is gift card",
		"code":"fehjignfjeingx",
		"expireTime":"2027-12-04T21:20:50+08:00",
		"customerId":"20000012619",
		"initialValue":"100"
	}
}'

响应

HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

POST 禁用礼品卡

禁用礼品卡。

访问范围

需要以下任意访问权限: write_gift_card

接口

POST /api/202412/gift_cards/{giftCardId}/disable 

请求参数

giftCardIdnumber

礼品卡ID。

响应数据

giftCardobject

礼品卡信息。

- 收起属性

customerIdobject

当前礼品卡分配给的客户的客户ID。

idnumber

礼品卡ID。

codestring

礼品卡编码。

lastCharactersstring

code的最后四位字符。

balancenumber

礼品卡余额。

initialValuenumber

礼品卡初始金额。

orderIdobject

关联的订单ID。

lineItemIdobject

关联的订单物品。

currencystring

礼品卡面值对应币种。

noteobject

当前礼品卡的备注信息。

disableTimeobject

礼品卡禁用时间。

expireTimestring

当前礼品卡的到期时间，null为永不过期。

createTimestring

礼品卡创建时间。

updateTimestring

礼品卡更新时间。

userIdobject

用户在admin界面上创建礼品卡时的管理员账户ID。

POST /api/202412/gift_cards/{giftCardId}/disable

curl -X POST \ 
https://{shop}.genmystore.com/api/202412/gift_cards/{giftCardId}/disable" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"giftCardId":""
}'

响应

HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

PUT 更新礼品卡

更新礼品卡。

访问范围

需要以下任意访问权限: write_gift_card

接口

PUT /api/202412/gift_cards/{giftCardId} 

请求参数

giftCardobject

- 收起属性

balancenumber

礼品卡余额。

notestring

当前礼品卡的到期时间。

expireTimenumber

当前礼品卡的备注信息，字符数量限制500。

响应数据

giftCardobject

礼品卡信息。

- 收起属性

customerIdobject

当前礼品卡分配给的客户的客户ID。

idnumber

礼品卡ID。

codestring

礼品卡编码。

lastCharactersstring

code的最后四位字符。

balancenumber

礼品卡余额。

initialValuenumber

礼品卡初始金额。

orderIdobject

关联的订单ID。

lineItemIdobject

关联的订单物品。

currencystring

礼品卡面值对应币种。

noteobject

当前礼品卡的备注信息。

disableTimeobject

礼品卡禁用时间。

expireTimestring

当前礼品卡的到期时间，null为永不过期。

createTimestring

礼品卡创建时间。

updateTimestring

礼品卡更新时间。

userIdobject

用户在admin界面上创建礼品卡时的管理员账户ID。

PUT /api/202412/gift_cards/{giftCardId}

curl -X PUT \ 
https://{shop}.genmystore.com/api/202412/gift_cards/{giftCardId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"giftCard":{
		"note":"this is gift card",
		"expireTime":"2024-12-16T16:33:12.033",
		"balance":"100"
	}
}'

响应

HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

GET 搜索礼品卡

礼品卡列表搜索能力。

访问范围

需要以下任意访问权限: read_gift_card write_gift_card

接口

GET /api/202412/gift_cards/search 

请求参数

limitnumber

分页数量限制，默认限制 50。

sinceIdstring

起始资源 ID，主要用于首页中从 sinceId 开始查询分页。

statusstring

礼品卡状态。枚举值：enabled：已启用；disabled：已禁用；expired: 已过期。

pageTokenstring

代表某一分页的游标，默认情况下返回首页数据。

lastCharactersstring

代码的最后四个字符。

响应数据

giftCardsarray

礼品卡信息。

- 收起属性

customerIdnumber

当前礼品卡分配给的客户的客户ID。

idnumber

礼品卡ID。

codestring

礼品卡编码。

lastCharactersstring

code的最后四位字符。

balancenumber

礼品卡余额。

initialValuenumber

礼品卡初始金额。

orderIdstring

关联的订单ID。

lineItemIdobject

关联的订单物品。

currencyobject

礼品卡面值对应币种。

noteobject

当前礼品卡的备注信息。

disableTimeobject

礼品卡禁用时间。

expireTimeobject

当前礼品卡的到期时间，null为永不过期。

createTimestring

礼品卡创建时间。

updateTimestring

礼品卡更新时间。

userIdnumber

用户在admin界面上创建礼品卡时的管理员账户ID。

GET /api/202412/gift_cards/search

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/gift_cards/search" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

HTTP/1.1 200 OK
{
  "giftCards": [
    {
      "note": "this is gift card",
      "code": "fehjignfjeingx",
      "orderId": "300139485001998",
      "lineItemId": "300139485001998",
      "updateTime": "2024-12-16T17:04:38.004",
      "userId": "20000012584",
      "lastCharacters": "ingx",
      "expireTime": "2027-12-04",
      "balance": "100.00",
      "createTime": "2024-12-16T17:04:38.004",
      "customerId": "20000012619",
      "currency": "USD",
      "id": "201462125",
      "initialValue": "100.00",
      "disableTime": "2024-12-16T17:17:03.017"
    }
  ]
}

GET 查询礼品卡数量

查询礼品卡的数量。

访问范围

需要以下任意访问权限: read_gift_card write_gift_card

接口

GET /api/202412/gift_cards/count 

请求参数

{}

响应数据

countnumber

礼品卡数量。

GET /api/202412/gift_cards/count

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/gift_cards/count" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

HTTP/1.1 200 OK
{
  "count": "44"
}

GET 查询礼品卡详情

查询单个礼品卡详情。

访问范围

需要以下任意访问权限: read_gift_card write_gift_card

接口

GET /api/202412/gift_cards/{giftCardId} 

请求参数

{}

响应数据

giftCardobject

礼品卡信息。

- 收起属性

customerIdobject

当前礼品卡分配给的客户的客户ID。

idnumber

礼品卡ID。

codestring

礼品卡编码。

lastCharactersstring

code的最后四位字符。

balancenumber

礼品卡余额。

initialValuenumber

礼品卡初始金额。

orderIdobject

关联的订单ID。

lineItemIdobject

关联的订单物品。

currencystring

礼品卡面值对应币种。

noteobject

当前礼品卡的备注信息。

disableTimeobject

礼品卡禁用时间。

expireTimestring

当前礼品卡的到期时间，null为永不过期。

createTimestring

礼品卡创建时间。

updateTimestring

礼品卡更新时间。

userIdobject

用户在admin界面上创建礼品卡时的管理员账户ID。

GET /api/202412/gift_cards/{giftCardId}

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/gift_cards/{giftCardId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

关于 礼品卡

访问范围

需要多个访问范围—请参阅每个端点以了解访问范围要求。

需要访问受保护的客户数据。

礼品卡是 Genstore 支付解决方案中的重要组成部分，它允许客户购买和使用预付金额，为在线商店提供灵活的支付选项，Genstore 提供了一系列 RESTful 接口，用于实现礼品卡的全面管理功能创建、更新、失效、查询等操作，方便商家便捷地管理和追踪礼品卡使用情况。

核心功能

• 基础操作：创建礼品卡、更新礼品卡、失效礼品卡
• 信息查询：查询礼品卡详情、查询礼品卡列表、统计礼品卡数量

应用场景

• 礼品卡销售：店铺管理员可推出数字礼品卡项目、定制卡片设计和面额、管理促销规则，扩展支付选择并创造新的收入来源。
• 礼品卡生命周期管理：客服团队可高效处理礼品卡发行、处理余额更新、管理卡片状态变更，确保礼品卡交易的安全性和准确性。
• 礼品卡数据分析：业务分析师可追踪礼品卡表现指标、生成使用报告、分析购买模式，优化礼品卡项目并提升客户参与度。

礼品卡 对象

礼品卡对象

属性

POST 创建礼品卡

创建礼品卡。

访问范围

需要以下任意访问权限: write_gift_card

接口

POST /api/202412/gift_cards 

POST 禁用礼品卡

禁用礼品卡。

访问范围

需要以下任意访问权限: write_gift_card

接口

POST /api/202412/gift_cards/{giftCardId}/disable 

PUT 更新礼品卡

更新礼品卡。

访问范围

需要以下任意访问权限: write_gift_card

接口

PUT /api/202412/gift_cards/{giftCardId} 

GET 搜索礼品卡

礼品卡列表搜索能力。

访问范围

需要以下任意访问权限: read_gift_card write_gift_card

接口

GET /api/202412/gift_cards/search 

GET 查询礼品卡数量

查询礼品卡的数量。

访问范围

需要以下任意访问权限: read_gift_card write_gift_card

接口

GET /api/202412/gift_cards/count 

GET 查询礼品卡详情

查询单个礼品卡详情。

访问范围

需要以下任意访问权限: read_gift_card write_gift_card

接口

GET /api/202412/gift_cards/{giftCardId}