查询通知列表

使用此端点按筛选条件查询 webhook 通知列表。

可用环境

生产环境

https://api.gateway.com.br/dispatcher

端点

• 方法：GET
• 端点：/request
• 认证方式：Bearer token

查询参数

ℹ️ 使用 ISO 日期

startDate 和 endDate 必须以带时间的 ISO date string 格式传入。

示例：

• 2026-03-24T12:00:00.000Z

ℹ️ 查询字符串中的数组

status 和 tags 支持传入多个值。

示例：

• status=SENT&status=FAILED
• tags=PAID&tags=CANCELLED

名称	类型	必填	说明	校验规则
startDate	string	否	筛选的起始日期	必须为带时间的 ISO date string
endDate	string	否	筛选的结束日期	必须为带时间的 ISO date string
referenceId	string	否	通知的关联 ID	不能为空
status	string[] (enum) - RECEIVED, SENT, FAILED, ERROR	否	用于筛选的状态列表	必须为非空数组
tags	string[]	否	用于筛选的标签列表	必须为非空的字符串数组

请求示例（包含全部字段）

cURL

curl --request GET \
--url "https://api.gateway.com.br/dispatcher/request?startDate=2026-03-01T00:00:00.000Z&endDate=2026-03-24T23:59:59.999Z&referenceId=6d66e879-0345-44c9-9146-3cfc81842684&status=RECEIVED&status=SENT&status=FAILED&status=ERROR&tags=PAID&tags=CANCELLED" \
--header 'Authorization: Bearer your-jwt-token'

JavaScript

const params = new URLSearchParams({
  startDate: '2026-03-01T00:00:00.000Z',
  endDate: '2026-03-24T23:59:59.999Z',
  referenceId: '6d66e879-0345-44c9-9146-3cfc81842684'
});

params.append('status', 'RECEIVED');
params.append('status', 'SENT');
params.append('status', 'FAILED');
params.append('status', 'ERROR');
params.append('tags', 'PAID');
params.append('tags', 'CANCELLED');

const response = await fetch(`https://api.gateway.com.br/dispatcher/request?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
});

const data = await response.json();

成功响应

字段	类型	必填	说明
total	number	是	总条数
totalPages	number	是	总页数
currentPage	number	是	当前页
perPage	number	是	每页条数
data	array	是	通知列表

data 中每一项的字段

字段	类型	必填	说明
id	string (UUID)	是	通知的标识
referenceId	string	是	通知的关联 ID
url	string	是	通知的目标地址
status	string (enum) - RECEIVED, SENT, FAILED, ERROR	是	通知的状态
tags	string[]	是	通知关联的标签
createdAt	string (ISO)	是	创建时间
userId	string (UUID)	是	负责用户的标识
storeId	string (UUID)	是	店铺的标识

响应示例

{
  "total": 2,
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 10,
  "data": [
    {
      "id": "553e8400-e29b-41d4-a716-446655440000",
      "referenceId": "6d66e879-0345-44c9-9146-3cfc81842684",
      "url": "https://api.example.com/webhooks/order-events",
      "status": "SENT",
      "tags": ["PAID", "CANCELLED"],
      "createdAt": "2026-03-24T10:00:00.000Z",
      "userId": "11111111-1111-1111-1111-111111111111",
      "storeId": "22222222-2222-2222-2222-222222222222"
    },
    {
      "id": "663e8400-e29b-41d4-a716-446655440001",
      "referenceId": "4ef9706d-5ea3-4f07-b282-c6be9ac83c9b",
      "url": "https://api.example.com/webhooks/billing-events",
      "status": "FAILED",
      "tags": ["CANCELLED", "webhook"],
      "createdAt": "2026-03-24T11:00:00.000Z",
      "userId": "33333333-3333-3333-3333-333333333333",
      "storeId": "44444444-4444-4444-4444-444444444444"
    }
  ]
}

可能的错误

状态码	说明	处理方式
401	凭据无效	请检查您的 token
403	无权限或未授权	请检查用户的权限范围
404	未找到任何通知	请调整查询的筛选条件
422	数据无效或缺失	请检查参数格式
500	内部错误	请联系技术支持