Signal 号码查询 API:先分清 true / false / null

发布于 2026年8月23日 · 更新于2026年10月16日

访问日志里这次请求是成功的。GET https://api.opendata-api.com/api/project/signal/check 返回 HTTP 200,网关信封 code 也是 200,任务却把号码写成了「未注册」。正文是 "registered": null,message 里写着超时。这才是 Signal 号码查询 API 真正要处理的失败:HTTP 成功包着一次未判定的检查,下游把 null 当成了 no。名单清洗、渠道路由、去重都会在这一步分叉——把不确定写成未注册,后面所有补全和统计都会跟着错。

打开本页或复制示例不会发出查询。真正执行命令才会,并且会扣点数。授权 Key 不要写进日志、截图和仓库。登录 后从控制台复制,服务端用环境变量 OPENDATA_API_KEY 读取;curl 里的占位符是 YOUR_API_KEY。查询 URL 带着 Key,不要把整段链接贴进工单。先诊断信封和三态,再写调用代码。

null 不等于未注册

check 是轻量接口:国际格式的 number,前面的 + 可有可无,接口会归一成数字。国家区号必须带。网关拆包成功后,真正要分类的只有号码、e164 和 registered。

registered 是三态,不是布尔:

  • true:已注册 Signal。
  • false:未注册。这是干净的未命中,不要当超时重试。
  • null:暂时无法判断。message 会说明原因(常见是超时)。进队列,不要落成未注册。

HTTP 状态和网关 code 跟 registered 不在同一层。缺 Key、Key 无效、参数校验失败、传输失败,会表现为 HTTP 4xx/5xx,或网关 code 不是 200。这类信封里没有 Signal 结论——该补凭证或重试传输,不要写 false。HTTP 2xx 且网关 code: 200 只说明检查送达了,这时才读 registered。送达的 null 仍是业务结果:不确定,不是崩溃。空结果、未判定、HTTP 失败、业务失败,四件事不要合成一个「查失败」开关。

开头那种事故,多半是把 Python 的真值判断用在了三态上。None 和 False 都是假值,if not registered 会把「不确定」和「未注册」写成同一条。分类必须用 is True / is False / is None。返回还可能包成多层 {"code": ..., "data": {...}},先拆到内层记录再判断。拆包时若网关 code 不是 200,停在信封层,不要继续读内层当结论。号码带空格、缺区号,看起来像业务未命中,其实是入参没归一——先清格式,再谈三态。

下面的号码只是文档里的示例形态,不保证能查到注册。

curl --get "https://api.opendata-api.com/api/project/signal/check" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "number=15551234567"

先看 registered,再花 ACI/PNI

user-info 仍吃 number。号码已注册时,才可能返回公开身份:ACI(账号 UUID)和 PNI(手机号标识,通常写成 PNI:<uuid>),以及可选的明文元数据(identityKey、unrestrictedUnidentifiedAccess、capabilities、badges),外加机器状态(如 found / not_found / timeout)、可读的 message 和 durationMs。ACI 跟账号走,PNI 跟当前手机号走;人换号以后,用 ACI 还能对上同一条身份,用号码则对不上。

只有 check 得到 registered is True 才调用它。干净的 false 没有身份可取;null 更不是放行令牌——你连在不在 Signal 上都不知道。对这两类行去打 user-info,既浪费点数,又会把超时和未命中写进同一列。机器状态是身份查询自己的结论,不要拿它去覆盖已经分好的 registered 三态。user-info 若自己也超时,按不确定处理这条身份,不要回写成未注册。

fieldsEncrypted 为 true 时,显示名、简介、头像被 Signal 藏起来了:它们用只有联系人才有的资料密钥做了端到端加密。这是 Signal 的隐私设计,不是接口缺字段。不要对外承诺能给陌生号码补姓名或头像。

已经存了 ACI,就用 profile 按 ACI 刷新明文元数据,不必再解析手机号。这条路径只给 identityKey、unidentifiedAccess、unrestrictedUnidentifiedAccess、capabilities、badges 和 uuid(与 ACI 相同)。对非联系人,姓名、简介、头像不会出现。人会换号,ACI 要留下来。

curl --get "https://api.opendata-api.com/api/project/signal/user-info" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "number=15551234567"

curl --get "https://api.opendata-api.com/api/project/signal/profile" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "aci=3bc3a597-297d-4f8c-821a-13aaa9ede5ea"

这是请求形态,不是「15551234567 一定已注册」或「示例 ACI 一定还在」的保证。

只重试不确定的行

名单是成批失败的。每次 check 拆成三个桶,各桶一条策略,不要用同一个重试循环去打整表:

  • true:落成已注册;需要身份再打一次 user-info。按号码缓存并记下时间,不要每次打开页面都查。身份落库后,刷新元数据走 profile,不要再拿手机号重跑一遍完整查询。
  • false:落成未注册。干净未命中就是做完的工作。名单要长期维护,按计划复查,不要因为上次 HTTP 200 就立刻再打。
  • null:落成不确定,带上 message。只重试 check,退避、封顶。仍是 null 就保持不确定,绝不要为了结单改成 false。报表里单独留一列「未判定」,别并进未注册率。

HTTP 401/403 不要当超时重试。Key 错了或缺 number 的网关失败,睡两秒也不会变成 true。传输失败可以重试同一条 check;业务上的干净 false 不能。批量时先去重、先归一,同一号码不要并行打两次——并发重试会把点数打穿,结论还是那一个三态。

import os
import time

import requests

BASE = "https://api.opendata-api.com/api/project/signal"
KEY = os.environ["OPENDATA_API_KEY"].strip()


def get(operation, **params):
    try:
        response = requests.get(
            f"{BASE}/{operation}",
            params={"key": KEY, **params},
            timeout=30,
        )
    except requests.RequestException:
        raise RuntimeError("Transport failure; inspect redacted logs") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    body = response.json()
    while isinstance(body, dict) and "code" in body and isinstance(
        body.get("data"), (dict, list)
    ):
        if body.get("code") != 200:
            raise RuntimeError(f"Gateway failure: {body.get('message')}")
        body = body["data"]
    return body


def lookup(number, retries=2):
    last_message = None
    for attempt in range(retries + 1):
        data = get("check", number=number)
        registered = data.get("registered")
        if registered is True:
            return {
                "number": number,
                "registered": True,
                "identity": get("user-info", number=number),
            }
        if registered is False:
            return {"number": number, "registered": False}
        last_message = data.get("message")
        time.sleep(2 * (attempt + 1))
    return {"number": number, "registered": None, "reason": last_message}


# Documented example number — not a guaranteed registration.
print(lookup("15551234567"))

流程只认三态。其余字段原样保存,缺 badges 也不该打断整批。重试结束后仍是 registered is None,那是诚实的遗留,不是函数写错了。

和 WhatsApp、Telegram 怎么分工

Signal 回答的是注册与稳定标识,不是「这个人显示名是什么」。WhatsApp、Telegram 公开的面不同:Signal 的 null 不是跳过它们的理由,true 也不是。只要问在不在 Signal 上,用 check;要 ACI/PNI 去做重,用 user-info。不要指望 Signal 给出头像或简介去填 CRM——那条路在非联系人上走不通,该问别的渠道就去问别的渠道。

Viber 见 Viber 号码查询。Telegram 的存在性、用户名、简介和头像走 24 小时 userHash,见 Telegram 号码检测。多渠道一起判断,跟 线索核验工作流。各渠道的失败形态也不一样:Signal 的坑是三态 null,别把别家的存在性字段套过来当布尔用。

Signal 默认不向非联系人公开资料,所以这次查询是注册与身份信号,不是资料补全源。接口说明:check、user-info、profile。产品页:Signal 号码校验。单次费用见定价。