域名状态查询API

接口概述

提供域名在各主流平台的拦截/封禁状态检测服务。接口采用子类型设计，通过 sub_type 参数指定检测目标平台，支持批量检测多个 URL。 每个子类型拥有独立的资源包（API 调用次数），互不干扰、独立扣费。

批量统一走批次异步：一次提交多个 URL（>1 条）时，接口会将整批域名记录为一个 批次任务（返回 task_id），检测在后台异步执行， 调用方通过查询批次结果接口轮询获取整批状态。 只有单条查询支持同步等待返回。

子类型说明

通过 sub_type 参数选择要检测的目标平台：

批次异步规则

接口地址

请求方式

请求参数

参数传递方式

请求示例

// JSON 请求示例 — 微信批量检测（自动转批次异步）
{
    "api_key": "your_api_key",
    "sub_type": "wechat",
    "urls": [
        "https://www.baidu.com",
        "https://www.example.com"
    ]
}

// cURL 示例 — 批量提交（返回 task_id 后轮询取结果）
curl -X POST /api/domain_check_api.php \
     -H "api_key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"sub_type":"wechat","urls":["https://www.baidu.com","https://www.example.com"]}'

// 单条同步检测（QQ 直接出结果；微信最多等 wait_timeout 秒）
curl -X POST /api/domain_check_api.php \
     -H "api_key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"sub_type":"qq","urls":["https://www.baidu.com"]}'

// 需要上游原始响应调试时，加 include_raw 参数
curl -X POST /api/domain_check_api.php \
     -H "api_key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"sub_type":"wechat","urls":["https://www.baidu.com"],"include_raw":true,"wait_timeout":8}'

响应示例

{
    "code": 0,
    "message": "success",
    "data": {
        "sub_type": "wechat",
        "sub_type_name": "微信拦截检测",
        "async": true,
        "auto_async": true,
        "task_id": "p_3_1761820800_a1b2c3",
        "results": [
            {
                "url": "https://www.baidu.com",
                "sub_type": "wechat",
                "status": "async",
                "message": "已提交 UI 检测队列，请通过 task_id 查询结果",
                "raw_response": null,
                "task_id": "p_3_1761820800_a1b2c3"
            },
            {
                "url": "https://www.example.com",
                "sub_type": "wechat",
                "status": "async",
                "message": "已提交 UI 检测队列，请通过 task_id 查询结果",
                "raw_response": null,
                "task_id": "p_3_1761820800_a1b2c3"
            }
        ],
        "request_count": 2,
        "billed_count": 2,
        "refund_count": 0,
        "async_count": 2,
        "remaining_credits": 45
    }
}

{
    "code": 0,
    "message": "success",
    "data": {
        "sub_type": "qq",
        "sub_type_name": "QQ 拦截检测",
        "async": false,
        "auto_async": false,
        "task_id": null,
        "results": [
            {
                "url": "https://www.baidu.com",
                "sub_type": "qq",
                "status": "normal",
                "message": "域名正常",
                "raw_response": null
            }
        ],
        "request_count": 1,
        "billed_count": 1,
        "refund_count": 0,
        "async_count": 0,
        "remaining_credits": 97
    }
}

{
    "code": 0,
    "message": "success",
    "data": {
        "sub_type": "qq",
        "sub_type_name": "QQ 拦截检测",
        "async": false,
        "auto_async": false,
        "task_id": null,
        "results": [
            {
                "url": "https://example-timeout.com",
                "sub_type": "qq",
                "status": "unknown",
                "message": "QQ 检测第三方接口请求失败: HTTP 0, curl=Operation timed out after 10000 milliseconds",
                "raw_response": null
            }
        ],
        "request_count": 1,
        "billed_count": 0,
        "refund_count": 1,
        "async_count": 0,
        "remaining_credits": 98
    }
}

{
    "code": 1004,
    "message": "域名检查·QQ 调用次数不足，剩余 0 次，需要 2 次",
    "data": null
}

响应字段说明

顶层结构

data 对象字段

results 数组元素字段

结果状态说明

查询批次结果

批次任务（task_id）的整批结果通过本接口轮询获取。建议每 2~3 秒查询一次， 直到 task_state 变为 done。任务保留 24 小时。

请求方式

请求参数

请求示例

curl "/api/domain_check_status.php?task_id=p_3_1761820800_a1b2c3&api_key=your_api_key"

响应示例

{
    "code": 0,
    "message": "success",
    "data": {
        "task_id": "p_3_1761820800_a1b2c3",
        "task_state": "partial",
        "progress": { "done": 1, "total": 2 },
        "sub_type": "wechat",
        "sub_type_name": "微信拦截检测",
        "results": [
            {
                "url": "https://www.baidu.com",
                "sub_type": "wechat",
                "status": "normal",
                "message": "放行"
            },
            {
                "url": "https://www.example.com",
                "sub_type": "wechat",
                "status": "async",
                "message": "检测中，请稍后查询"
            }
        ],
        "billed_count": 2,
        "refund_count": 0,
        "remaining_credits": 45
    }
}

响应字段说明

扣费规则

• 按子类型独立扣费：wechat 扣 domain_check_wechat 资源包；qq 扣 domain_check_qq 资源包；douyin 扣 douyin 资源包，互不干扰
• 按 URL 条数扣费：批量检测 5 个 URL 扣 5 次
• 检测前检查余额：资源包不足时整批拒绝，直接返回 1004 错误，不会先检测再扣费
• 同步完成正常扣；异步入队预扣（入队即扣，拿到结果后不再重复扣）
• 失败自动退费：检测失败（unknown）、任务过期的条目自动退回资源包，响应中体现为 billed_count（实扣）与 refund_count（已退）
• 响应包含剩余次数：remaining_credits 返回扣费后的剩余量

错误码说明

调用示例

PHP 示例（批量提交 + 轮询取结果）

<?php
$apiKey = "your_api_key";
$base   = "http://your-domain";

// 1. 批量提交（>1 条自动转批次异步）
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$base/api/domain_check_api.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "api_key"  => $apiKey,
    "sub_type" => "wechat",
    "urls"     => ["https://www.baidu.com", "https://www.example.com"],
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$submit = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($submit['code'] !== 0) {
    exit("提交失败: [{$submit['code']}] {$submit['message']}\n");
}

$taskId = $submit['data']['task_id'];

// 2. 轮询批次结果（单条同步场景 task_id 为 null 时直接用 results）
if ($taskId) {
    while (true) {
        sleep(3);
        $r = json_decode(file_get_contents(
            "$base/api/domain_check_status.php?task_id=$taskId&api_key=$apiKey"
        ), true);
        if ($r['code'] !== 0) exit("查询失败: {$r['message']}\n");
        echo "进度: {$r['data']['progress']['done']}/{$r['data']['progress']['total']}\n";
        if ($r['data']['task_state'] === 'done') {
            $submit = $r;
            break;
        }
    }
}

foreach ($submit['data']['results'] as $item) {
    echo $item['url'] . " -> " . $item['status'] . " (" . $item['message'] . ")\n";
}
echo "剩余次数: " . $submit['data']['remaining_credits'] . "\n";
?>

Python 示例（批量提交 + 轮询取结果）

import requests, time

base    = "http://your-domain"
api_key = "your_api_key"

# 1. 批量提交（>1 条自动转批次异步）
submit = requests.post(f"{base}/api/domain_check_api.php", json={
    "api_key":  api_key,
    "sub_type": "wechat",
    "urls": ["https://www.baidu.com", "https://www.example.com"],
}).json()

if submit["code"] != 0:
    raise SystemExit(f"提交失败: [{submit['code']}] {submit['message']}")

task_id = submit["data"]["task_id"]

# 2. 轮询批次结果
if task_id:
    while True:
        time.sleep(3)
        r = requests.get(f"{base}/api/domain_check_status.php",
                         params={"task_id": task_id, "api_key": api_key}).json()
        p = r["data"]["progress"]
        print(f"进度: {p['done']}/{p['total']}")
        if r["data"]["task_state"] == "done":
            submit = r
            break

for item in submit["data"]["results"]:
    print(f"{item['url']} -> {item['status']} ({item['message']})")
print(f"剩余次数: {submit['data']['remaining_credits']}")

JavaScript（前端）示例

const base = "http://your-domain";
const apiKey = "your_api_key";

// 1. 批量提交（>1 条自动转批次异步）
const submit = await (await fetch(`${base}/api/domain_check_api.php`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        api_key:  apiKey,
        sub_type: "wechat",
        urls: ["https://www.baidu.com", "https://www.example.com"],
    }),
})).json();

if (submit.code !== 0) throw new Error(`提交失败: ${submit.message}`);

// 2. 轮询批次结果
let final = submit;
const taskId = submit.data.task_id;
while (taskId && final.data.task_state !== "done") {
    await new Promise(r => setTimeout(r, 3000));
    final = await (await fetch(
        `${base}/api/domain_check_status.php?task_id=${taskId}&api_key=${apiKey}`
    )).json();
    console.log("进度:", final.data.progress.done, "/", final.data.progress.total);
}

final.data.results.forEach(item => {
    console.log(item.url, "->", item.status, item.message);
});
console.log("剩余次数:", final.data.remaining_credits);