关于消息订阅

访问范围

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

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

Genstore 提供 Webhook 订阅方式，帮助开发者接收平台事件通知。应用可以通过订阅特定的 Webhook 主题来接收这些事件。Genstore 提供了一套 REST APIs 用于管理 Webhook 订阅，包括注册、删除、更新和查询。

核心功能

注册 Webhook 和回调地址
删除 Webhook 订阅
更新 Webhook 订阅
查询 Webhook 列表和详情
获取 Webhook 订阅数量

WARNING

Webhook 事件通知无法保证顺序性。
通知连续失败 8 次后，系统将不再尝试发送，可能导致数据丢失。

应用场景

订单数据同步：当应用需要实时同步某一店铺的订单数据，可通过订阅 orders/create 主题，实时接收店铺新创建的订单数据。
会员数据同步：当应用需要实时同步某一店铺的会员数据时，应用可通过订阅 customers/create 主题，实时接收店铺新增的会员数据。

接口

POST /api/202412/app/webhooks: 创建 Webhook

PUT /api/202412/app/webhooks/{webhookId}: 更新 Webhook

DELETE /api/202412/app/webhooks/{webhookId}: 删除 Webhook

GET /api/202412/app/webhooks: 查询 Webhook 列表

GET /api/202412/app/webhooks/{webhookId}: 获取 Webhook 详情

GET /api/202412/app/webhooks/count: 获取 Webhook 数量

消息订阅对象

用于创建和管理消息订阅信息。

属性

webhookobject

订阅消息产生的 Webhook 对象。

- 收起属性

idnumber

Webhook 订阅的唯一数字标识符。

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

createTimestring

创建 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

updateTimestring

更新 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

消息订阅对象

bash

{
  "webhook": {
    "address": "https://apple.com/uninstall",
    "createTime": "2024-10-25T11:06:48+08:00",
    "topic": "blazeTest/event1",
    "updateTime": "2024-10-31T10:55:12+08:00",
    "id": "123456"
  }
}

`POST` 创建 Webhook

创建 Webhook。

访问范围

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

接口

POST /api/202412/app/webhooks

请求参数

webhookobject

- 收起属性

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

响应数据

webhookobject

- 收起属性

idnumber

Webhook 订阅的唯一数字标识符。

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

createTimestring

创建 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

updateTimestring

更新 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

POST /api/202412/app/webhooks

bash

curl -X POST \ 
https://{shop}.genmystore.com/api/202412/app/webhooks" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"webhook":{
		"address":"blazeTest/event1",
		"topic":"https://apple.com/uninstall"
	}
}'

响应

json

HTTP/1.1 200 OK
{
  "webhook": {
    "address": "https://apple.com/uninstall",
    "createTime": "2024-10-25T11:06:48+08:00",
    "topic": "blazeTest/event1",
    "updateTime": "2024-10-31T10:55:12+08:00",
    "id": "123456"
  }
}

`PUT` 更新 Webhook

更新 Webhook。

访问范围

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

接口

PUT /api/202412/app/webhooks/{webhookId}

请求参数

webhookIdnumber

Webhook 订阅的唯一数字标识符。

webhookobject

请求体

+ 展开属性

响应数据

webhookobject

- 收起属性

idnumber

Webhook 订阅的唯一数字标识符。

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

createTimestring

创建 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

updateTimestring

更新 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

PUT /api/202412/app/webhooks/{webhookId}

bash

curl -X PUT \ 
https://{shop}.genmystore.com/api/202412/app/webhooks/{webhookId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"webhookId":"123456",
	"webhook":{
		"address":"https://apple.com/uninstall",
		"id":"123456"
	}
}'

响应

json

HTTP/1.1 200 OK
{
  "webhook": {
    "address": "https://apple.com/unins...",
    "createTime": "2024-10-25T11:06:48+08:00",
    "topic": "blazeTest/event1",
    "updateTime": "2024-10-31T10:55:12+08:00",
    "id": "123456"
  }
}

`DELETE` 删除 Webhook

删除 Webhook。

访问范围

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

接口

DELETE /api/202412/app/webhooks/{webhookId}

请求参数

webhookIdnumber

Webhook 订阅的唯一数字标识符。

响应数据

{}

DELETE /api/202412/app/webhooks/{webhookId}

bash

curl -X DELETE \ 
https://{shop}.genmystore.com/api/202412/app/webhooks/{webhookId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

json

HTTP/1.1 200 OK
{}

`GET` 查询 Webhook 列表

查询 Webhook 列表。

访问范围

需要以下任意访问权限: write_apps read_apps

接口

GET /api/202412/app/webhooks

请求参数

addressstring

检索将 POST 请求发送到此 URI 的 Webhook 订阅。

createTimeMaxstring

检索在给定日期和时间之前创建的 Webhook 订阅（格式：2014-04-25T16：15：47-04：00）。

createTimeMinstring

检索在给定日期和时间之后创建的 Webhook 订阅（格式：2014-04-25T16：15：47-04：00）。

limitnumber

应返回的最大 Webhook 订阅数。如果该参数超出最大范围，将返回错误。

sinceIdnumber

将返回的列表限制为 ID 大于指定 since_id的 Webhook 订阅。

topicstring

显示具有给定主题的 Webhook 订阅。有关有效值，请参阅事件主题列表。

updateTimeMaxstring

检索在给定日期和时间之后更新的 Webhook（格式：2014-04-25T16：15：47-04：00）。

updateTimeMinstring

检索在给定日期和时间之前更新的 Webhook（格式：2014-04-25T16：15：47-04：00）。

响应数据

webhooksarray

- 收起属性

idnumber

Webhook 订阅的唯一数字标识符。

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

createTimestring

创建 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

updateTimestring

更新 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

GET /api/202412/app/webhooks

bash

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

响应

json

HTTP/1.1 200 OK
{
  "webhooks": [
    {
      "address": "https://apple.com/uninstall",
      "createTime": "2024-10-25T11:06:48+08:00",
      "topic": "blazeTest/event1",
      "updateTime": "2024-10-31T10:55:12+08:00",
      "id": "123456"
    }
  ]
}

`GET` 获取 Webhook 详情

获取 Webhook 详情。

访问范围

需要以下任意访问权限: write_apps read_apps

接口

GET /api/202412/app/webhooks/{webhookId}

请求参数

webhookIdnumber

Webhook 订阅的唯一数字标识符。

响应数据

webhookobject

- 收起属性

idnumber

Webhook 订阅的唯一数字标识符。

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

createTimestring

创建 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

updateTimestring

更新 Webhook 订阅的日期和时间。API 以 ISO 8601 格式返回此值。

GET /api/202412/app/webhooks/{webhookId}

bash

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

响应

json

HTTP/1.1 200 OK
{
  "webhook": {
    "address": "https://apple.com/uninstall",
    "createTime": "2024-10-25T11:06:48+08:00",
    "topic": "blazeTest/event1",
    "updateTime": "2024-10-31T10:55:12+08:00",
    "id": "123456"
  }
}

`GET` 获取 Webhook 数量

获取 Webhook 数量。

访问范围

需要以下任意访问权限: write_apps read_apps

接口

GET /api/202412/app/webhooks/count

请求参数

topicstring

触发 Webhook 的事件。您可以接收 JSON格式的数据。

addressstring

事件发生时，Webhook 订阅应将 POST 请求发送到的目标 URI。

响应数据

countnumber

现有 Webhook 订阅的计数。

GET /api/202412/app/webhooks/count

bash

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

响应

json

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

关于消息订阅

访问范围

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

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

核心功能

注册 Webhook 和回调地址
删除 Webhook 订阅
更新 Webhook 订阅
查询 Webhook 列表和详情
获取 Webhook 订阅数量

WARNING

Webhook 事件通知无法保证顺序性。
通知连续失败 8 次后，系统将不再尝试发送，可能导致数据丢失。

应用场景

订单数据同步：当应用需要实时同步某一店铺的订单数据，可通过订阅 orders/create 主题，实时接收店铺新创建的订单数据。
会员数据同步：当应用需要实时同步某一店铺的会员数据时，应用可通过订阅 customers/create 主题，实时接收店铺新增的会员数据。

消息订阅对象

接口

GET /api/202412/app/webhooks/count

产品

变体

系列

库存

类目

礼品卡

厂商

订单

履约

退货

客户

主题

店铺

市场

翻译

元字段

元字段定义

账户

交易

折扣

授权

消息订阅

关于 消息订阅 ​

消息订阅 对象 ​

属性 ​

POST 创建 Webhook ​

请求参数

响应数据

PUT 更新 Webhook ​

请求参数

响应数据

DELETE 删除 Webhook ​

请求参数

响应数据

GET 查询 Webhook 列表 ​

请求参数

响应数据

GET 获取 Webhook 详情 ​

请求参数

响应数据

GET 获取 Webhook 数量 ​

请求参数

响应数据

关于 消息订阅 ​

消息订阅 对象 ​

属性 ​

POST 创建 Webhook ​

PUT 更新 Webhook ​

DELETE 删除 Webhook ​

GET 查询 Webhook 列表 ​

GET 获取 Webhook 详情 ​

GET 获取 Webhook 数量 ​

关于消息订阅

消息订阅对象

属性

`POST` 创建 Webhook

`PUT` 更新 Webhook

`DELETE` 删除 Webhook

`GET` 查询 Webhook 列表

`GET` 获取 Webhook 详情

`GET` 获取 Webhook 数量

关于消息订阅

消息订阅对象

属性

`POST` 创建 Webhook

`PUT` 更新 Webhook

`DELETE` 删除 Webhook

`GET` 查询 Webhook 列表

`GET` 获取 Webhook 详情

`GET` 获取 Webhook 数量