异步任务队列

异步任务投递、延时回调、周期重复 Webhook,无需自建消息队列

本接口是「定时 Webhook 调度器」:你把回调地址和自定义数据交给我们,到时间后平台会 POST 通知你的业务系统。无需自建 RabbitMQ、Redis 或定时任务服务。

支持四种模式:
1. submit — 尽快执行(通常 1 分钟内)
2. delay — 延时 N 秒或指定 run_at 时间后执行
3. repeat — 按 interval 周期重复回调,可设次数上限
4. status / cancel — 查询或取消任务

典型场景:订单超时取消、延时提醒、周期心跳检测、异步通知第三方。

调用地址:https://api.ynlskj.com.cn/gateway/queue

请求方法:POST

在其他地方怎么调用

  1. 请求地址用上面的调用地址,把 JSON 放在请求体里
  2. 方法用 POST
  3. API Key 只能放在请求头 X-API-Key,不要写进网址,也不要写进 Query 框
  4. Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key

参数说明

参数位置必填说明
actionBody JSONsubmit 立即投递、delay 延时回调、repeat 周期重复、status 查询、cancel 取消
callback_urlBody JSON创建时是到期后平台 POST 通知的地址,须公网 https/http,不能是内网 IP
payloadBody JSON业务自定义 JSON 对象,回调时原样带回,最大 64KB
delayBody JSONdelay 时延时秒数,10 秒~7 天。也可用 run_at 指定执行时间
intervalBody JSONrepeat 时重复间隔秒数,60 秒~1 天
timesBody JSONrepeat 时否最多执行几次,默认 0 表示不限(受 until 或 30 天上限约束),最大 1000
untilBody JSONrepeat 的截止时间,如 2026-12-31 23:59:59
task_idBody JSONstatus/cancel 时单次任务 ID,格式 q_xxx
schedule_idBody JSONstatus/cancel 时周期计划 ID,格式 s_xxx
X-API-KeyHeader你的 API Key

怎么用(3 步上手)

  1. 创建任务:POST 本接口,传入 callback_url(你业务系统的接收地址)和 payload(自定义数据)
  2. 等待执行:平台后台每分钟扫描到期任务,到时间后向 callback_url 发 POST 请求
  3. 业务处理:你的接口收到回调后,根据 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.completedsubmit / 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.tickrepeat 每次执行{"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.completedrepeat 达到次数或截止时间{"event":"schedule.completed","schedule_id":"s_xxx","times_done":10,"times_limit":10,"payload":{...},"timestamp":1690000000}

请求头附带 X-Queue-Task-IdX-Queue-TimestampX-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 次

返回说明

字段说明
retok 成功,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}}

在线调试

登录后可在线调试。调试会真实调用网关并消耗次数。

去登录