推送 API

POST 参数、响应和调用示例。

更新于 2026/10/31 21:16:41

请求参数

POST /api/push/{token}

登录后在推送页面复制专属地址，将完整地址作为请求 URL。支持 application/json 和 application/x-www-form-urlencoded，以下示例使用 JSON。

参数	位置	类型	必填	说明
token	URL 路径	string	是	专属地址中的完整 Token，不放在请求体中
title	请求体	string	是	去掉两端空白后为 1–100 个字符
content	请求体	string	是	不能为空或仅含空白，最多 32 KiB UTF-8 文本，支持文本、Markdown 和安全 HTML

请求头 Content-Type 设为 application/json。可选请求头 Idempotency-Key 最多 128 字节；在服务配置的幂等窗口内（默认 24 小时），同一用户相同标识和内容复用原推送记录，不重复发送或扣量；相同标识用于不同内容返回 HTTP 409。不提供该请求头时，每次请求独立计量。

JSON 请求示例

{
  "title": "任务完成",
  "content": "处理成功"
}

content 中的换行使用 JSON 转义 \n，例如 "content": "## 运行结果\n\n处理成功"。

返回值说明

响应为 JSON。HTTP 200 和 202 的 code 均为 0，具体推送结果需要同时查看 HTTP 状态和 data.status。错误响应包含 code、message、request_id，不包含 data。

字段	类型	说明
code	integer	HTTP 200/202 时为 `0`；错误时为 HTTP 状态码 × 100 + 1，例如 HTTP 429 对应 `42901`
message	string	本次结果说明或错误原因
request_id	string	推送请求标识，用于定位问题；复用幂等记录时返回原推送标识
data	object	仅在 HTTP 200/202 时返回的推送结果和当前额度信息
data.status	string	`accepted`：微信已受理；`unknown`：结果待确认，请勿直接重发
data.request_id	string	与外层 `request_id` 相同的推送请求标识
data.daily_limit	integer	当前有效的每日总额度
data.used_today	integer	今日微信已明确受理的条数
data.reserved_today	integer	今日待确认请求占用的条数
data.remaining_today	integer	当前可用条数，按每日总额度减去已用和待确认占用计算，最低为 `0`
data.plan_name	string	当前有效的额度名称，例如“免费版”
data.source	string	当前额度来源：`free`（免费）、`paid`（付费）或 `override`（手动额度）
data.paid_until	string 或 null	付费权益到期时间，未有付费记录时为 `null`；当前有效额度仍以 `source` 和 `daily_limit` 为准

JSON 返回示例

微信已受理（HTTP 200）

{
  "code": 0,
  "message": "已提交微信",
  "request_id": "9cf6f21feae34312a9072c28b6bd1c44",
  "data": {
    "status": "accepted",
    "request_id": "9cf6f21feae34312a9072c28b6bd1c44",
    "daily_limit": 40,
    "used_today": 1,
    "reserved_today": 0,
    "remaining_today": 39,
    "plan_name": "免费版",
    "source": "free",
    "paid_until": null
  }
}

结果待确认（HTTP 202）

{
  "code": 0,
  "message": "结果待确认，请勿重复发送",
  "request_id": "be83c4735a324101affb34d95aa7f63b",
  "data": {
    "status": "unknown",
    "request_id": "be83c4735a324101affb34d95aa7f63b",
    "daily_limit": 40,
    "used_today": 0,
    "reserved_today": 1,
    "remaining_today": 39,
    "plan_name": "免费版",
    "source": "free",
    "paid_until": null
  }
}

额度不足（HTTP 429）

{
  "code": 42901,
  "message": "今日额度不足",
  "request_id": "452d8b8bd3b14983a0a1735dd28f467b"
}

上述额度为示例，实际数值以接口返回为准。微信已受理不代表用户已阅读；结果待确认时会保留一次额度占用。

状态说明

HTTP 状态	说明
200	微信已受理，`data.status` 为 `accepted`
202	结果待确认，`data.status` 为 `unknown`，请勿直接重发
400	参数格式、标题或内容不合法，或幂等标识超过长度限制
401	Token 无效或已重置
403	当前用户未关注服务号
409	同一幂等标识用于不同内容，或发生并发冲突
429	今日额度不足或请求过于频繁，以 `message` 说明为准
500	服务处理异常，可凭 `request_id` 联系管理员
502	微信明确拒绝推送
503	推送配置未完成或服务暂不可用

JavaScript 调用示例

以下示例使用 Node.js 18 或以上版本，以 .mjs 文件运行。先将推送页面复制的完整地址配置到环境变量 QINGWA_PUSH_URL。

const pushURL = process.env.QINGWA_PUSH_URL
if (!pushURL) throw new Error('请先设置 QINGWA_PUSH_URL')

const response = await fetch(pushURL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: '任务完成', content: '处理成功' }),
  signal: AbortSignal.timeout(15000)
})

console.log('HTTP 状态：', response.status)
console.log(JSON.stringify(await response.json(), null, 2))

Go 调用示例

配置环境变量 QINGWA_PUSH_URL 后，使用 Go 标准库发送请求。

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
    "strings"
    "time"
)

func main() {
    pushURL := os.Getenv("QINGWA_PUSH_URL")
    if pushURL == "" {
        log.Fatal("请先设置 QINGWA_PUSH_URL")
    }

    client := &http.Client{Timeout: 15 * time.Second}
    payload := strings.NewReader(`{"title":"任务完成","content":"处理成功"}`)
    response, err := client.Post(pushURL, "application/json", payload)
    if err != nil {
        log.Fatal(err)
    }
    defer response.Body.Close()

    body, err := io.ReadAll(response.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("HTTP 状态：", response.StatusCode)
    fmt.Println(string(body))
}

Java 调用示例

使用 Java 11 或以上版本的标准库，配置环境变量 QINGWA_PUSH_URL，将代码保存为 QingwaPush.java。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class QingwaPush {
    public static void main(String[] args) throws Exception {
        String pushURL = System.getenv("QINGWA_PUSH_URL");
        if (pushURL == null || pushURL.isBlank()) {
            throw new IllegalArgumentException("请先设置 QINGWA_PUSH_URL");
        }

        String payload = "{\"title\":\"任务完成\",\"content\":\"处理成功\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create(pushURL))
            .timeout(Duration.ofSeconds(15))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8))
            .build();

        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println("HTTP 状态：" + response.statusCode());
        System.out.println(response.body());
    }
}

Python 调用示例

使用 Python 3 标准库，配置环境变量 QINGWA_PUSH_URL 后即可调用，无需安装额外依赖。

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

payload = json.dumps(
    {"title": "任务完成", "content": "处理成功"},
    ensure_ascii=False,
).encode("utf-8")
request = Request(
    os.environ["QINGWA_PUSH_URL"],
    data=payload,
    headers={"Content-Type": "application/json"},
    method="POST",
)

try:
    with urlopen(request, timeout=15) as response:
        print("HTTP 状态：", response.status)
        print(response.read().decode("utf-8"))
except HTTPError as error:
    with error:
        print("HTTP 状态：", error.code)
        print(error.read().decode("utf-8"))

四种示例均会输出 HTTP 状态和响应正文。若发生超时或返回 HTTP 202，先保留请求信息并核对结果，不要直接自动重发。