异步任务队列
异步任务投递、延时回调、周期重复 Webhook,无需自建消息队列
本接口是「定时 Webhook 调度器」:你把回调地址和自定义数据交给我们,到时间后平台会 POST 通知你的业务系统。无需自建 RabbitMQ、Redis 或定时任务服务。
支持四种模式:
1. submit — 尽快执行(通常 1 分钟内)
2. delay — 延时 N 秒或指定 run_at 时间后执行
3. repeat — 按 interval 周期重复回调,可设次数上限
4. status / cancel — 查询或取消任务
典型场景:订单超时取消、延时提醒、周期心跳检测、异步通知第三方。
支持四种模式:
1. submit — 尽快执行(通常 1 分钟内)
2. delay — 延时 N 秒或指定 run_at 时间后执行
3. repeat — 按 interval 周期重复回调,可设次数上限
4. status / cancel — 查询或取消任务
典型场景:订单超时取消、延时提醒、周期心跳检测、异步通知第三方。
调用地址:https://api.ynlskj.com.cn/gateway/queue
请求方法:POST
在其他地方怎么调用
- 请求地址用上面的调用地址,把 JSON 放在请求体里
- 方法用
POST - API Key 只能放在请求头
X-API-Key,不要写进网址,也不要写进 Query 框 - Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key
参数说明
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
action | Body JSON | 是 | submit 立即投递、delay 延时回调、repeat 周期重复、status 查询、cancel 取消 |
callback_url | Body JSON | 创建时是 | 到期后平台 POST 通知的地址,须公网 https/http,不能是内网 IP |
payload | Body JSON | 否 | 业务自定义 JSON 对象,回调时原样带回,最大 64KB |
delay | Body JSON | delay 时 | 延时秒数,10 秒~7 天。也可用 run_at 指定执行时间 |
interval | Body JSON | repeat 时 | 重复间隔秒数,60 秒~1 天 |
times | Body JSON | repeat 时否 | 最多执行几次,默认 0 表示不限(受 until 或 30 天上限约束),最大 1000 |
until | Body JSON | 否 | repeat 的截止时间,如 2026-12-31 23:59:59 |
task_id | Body JSON | status/cancel 时 | 单次任务 ID,格式 q_xxx |
schedule_id | Body JSON | status/cancel 时 | 周期计划 ID,格式 s_xxx |
X-API-Key | Header | 是 | 你的 API Key |
怎么用(3 步上手)
- 创建任务:POST 本接口,传入
callback_url(你业务系统的接收地址)和payload(自定义数据) - 等待执行:平台后台每分钟扫描到期任务,到时间后向
callback_url发 POST 请求 - 业务处理:你的接口收到回调后,根据
payload里的订单号等字段执行业务逻辑,返回 HTTP 200 即可
典型场景:订单 15 分钟未支付自动取消、注册后 24 小时发提醒、每 5 分钟心跳检测、异步通知第三方系统。
请求示例
| 场景 | Body 示例 |
|---|---|
| 立即回调 | {"action":"submit","callback_url":"https://你的域名/api/webhook","payload":{"order_id":"ORDER123"}} |
| 60 秒后回调 | {"action":"delay","callback_url":"https://你的域名/api/webhook","delay":60,"payload":{"order_id":"ORDER123","event":"timeout_cancel"}} |
| 指定时间执行 | {"action":"delay","callback_url":"https://你的域名/api/webhook","run_at":"2026-08-23 18:00:00","payload":{"remind":"付款"}} |
| 每 5 分钟重复 10 次 | {"action":"repeat","callback_url":"https://你的域名/api/webhook","interval":300,"times":10,"payload":{"heartbeat":true}} |
| 查询单次任务 | {"action":"status","task_id":"q_xxxxxxxxxxxxxxxxxxxxxxxx"} |
| 查询周期计划 | {"action":"status","schedule_id":"s_xxxxxxxxxxxxxxxxxxxxxxxx"} |
| 取消未执行任务 | {"action":"cancel","task_id":"q_xxxxxxxxxxxxxxxxxxxxxxxx"} |
| 取消周期计划 | {"action":"cancel","schedule_id":"s_xxxxxxxxxxxxxxxxxxxxxxxx"} |
回调说明(你的接口会收到什么)
任务到期后,平台向 callback_url 发送 POST JSON,Content-Type 为 application/json。
| 事件 | 触发时机 | Body 示例 |
|---|---|---|
task.completed | submit / delay 执行成功 | {"event":"task.completed","task_id":"q_xxx","status":"success","payload":{"order_id":"ORDER123"},"timestamp":1690000000} |
task.failed | 回调你的地址失败(非 2xx 或超时) | {"event":"task.failed","task_id":"q_xxx","status":"failed","payload":{...},"timestamp":1690000000} |
schedule.tick | repeat 每次执行 | {"event":"schedule.tick","schedule_id":"s_xxx","task_id":"q_xxx","run_no":1,"times_done":1,"times_limit":10,"interval":300,"payload":{...},"timestamp":1690000000} |
schedule.completed | repeat 达到次数或截止时间 | {"event":"schedule.completed","schedule_id":"s_xxx","times_done":10,"times_limit":10,"payload":{...},"timestamp":1690000000} |
请求头附带 X-Queue-Task-Id、X-Queue-Timestamp、X-Queue-Signature。建议用 task_id / schedule_id 做幂等去重,避免重复处理。你的接口应尽快返回 2xx,耗时逻辑放后台异步执行。
任务状态
| status | 含义 |
|---|---|
pending | 已创建,等待执行(可 cancel) |
running | 正在回调你的地址 |
success | 回调成功 |
failed | 回调失败(会自动重试,最多 3 次) |
cancelled | 已取消 |
active | 周期计划运行中(仅 schedule) |
completed | 周期计划已结束(仅 schedule) |
限制说明
- 延时最短 10 秒,最长 7 天;周期间隔 60 秒~1 天
- 每账号最多 50 个活跃周期计划;单次 repeat 最多 1000 次或 30 天内
callback_url必须是公网地址,不支持 localhost / 内网 IP- 创建任务扣 1 次;周期任务每次执行再扣 1 次
返回说明
| 字段 | 说明 |
|---|---|
ret | ok 成功,err 失败 |
data.task_id | 单次任务 ID(submit / delay),格式 q_xxx |
data.schedule_id | 周期计划 ID(repeat),格式 s_xxx |
data.status | 任务或计划状态,见上文「任务状态」 |
data.callback_url | 回调地址 |
data.payload | 你提交的业务数据 |
data.run_at | 预计执行时间(单次任务) |
data.next_run_at | 下次执行时间(周期计划) |
data.interval / times_limit / times_done | 周期计划的间隔、上限、已执行次数 |
errmsg | 失败时的错误说明,如 callback_url 无效、次数不足等 |
msg | 本站提示,如「次数充足,剩余 99 次」或「次数不足,剩余 0 次」 |
remain_quota | 本次调用后的剩余次数 |
可直接复制的代码
未登录时示例只显示「你的密钥」。登录后会自动填入你自己的 Key,不会展示别人的。
<?php
$ch = curl_init('https://api.ynlskj.com.cn/gateway/queue');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['X-API-Key: 你的密钥', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => '{
"action": "delay",
"callback_url": "https://你的域名/api/order/webhook",
"delay": 60,
"payload": {
"order_id": "ORDER123",
"event": "timeout_cancel"
}
}',
]);
echo curl_exec($ch);
请求参数演示
{"action":"delay","callback_url":"https://你的域名/api/order/webhook","delay":60,"payload":{"order_id":"ORDER123","event":"timeout_cancel"}}
响应演示
{"ret":"ok","data":{"action":"delay","task_id":"q_xxxxxxxxxxxxxxxxxxxxxxxx","mode":"delay","task_type":"webhook","status":"pending","callback_url":"https://你的域名/api/order/webhook","payload":{"order_id":"ORDER123","event":"timeout_cancel"},"run_at":"2026-08-23 12:01:00","delay":60}}