1
sequenceDiagram
2
    participant App as 业务程序
3
    participant BJ as 白鲸平台
4
    participant Biz as 目标业务系统
5

6
    Note over App,BJ: token 永久有效，换一次后长期缓存复用
7
    App->>BJ: /api/login 换 token，仅首次
8
    BJ-->>App: data.token
9
    App->>BJ: /api/getPhone&channelId=渠道ID
10
    BJ-->>App: data.mobile
11
    App->>Biz: 用该号码触发发送短信
12
    loop 每次间隔 1 秒以上，最多 100 次
13
        App->>BJ: /api/getCode&phoneNum=号码
14
        BJ-->>App: code 为空则继续
15
    end
16
    alt 读到验证码
17
        App->>Biz: 提交验证码完成流程
18
    else 始终读不到
19
        App->>BJ: /api/phoneCollectAdd 拉黑该号码
20
        App->>BJ: /api/release 结束共享
21
    end

1
# -*- coding: utf-8 -*-
2
"""白鲸数据共享平台最小可用客户端。"""
3
import json
4
import os
5
import re
6
import threading
7
import time
8

9
import httpx
10

11
BASE_URL = "https://api.qc86.shop/api"
12
OPERATOR = {0: "全部", 5: "虚拟", 4: "非虚拟"}
13
RELEASE_STATUS = 2
14
COLLECT_TYPE = 0
15
MIN_INTERVAL = 1.2                      # 官方要求 1s 以上
16
CONFIG_FILE = "baijing_config.json"
17

18
_API_LOCK = threading.RLock()
19

20

21
class BaijingError(Exception):
22
    pass
23

24

25
class BaijingClient:
26
    def __init__(self, config_file: str = CONFIG_FILE, timeout: float = 20.0):
27
        self.config_file = config_file
28
        cfg = {}
29
        if os.path.exists(config_file):
30
            try:
31
                cfg = json.load(open(config_file, encoding="utf-8"))
32
            except Exception:
33
                cfg = {}
34
        self.username = (cfg.get("username") or os.environ.get("BJJ_USER") or "").strip()
35
        self.password = (cfg.get("password") or os.environ.get("BJJ_PASS") or "").strip()
36
        self.channel_id = str(cfg.get("channelId") or "").strip()
37
        self.sid = str(cfg.get("sid") or "").strip()
38
        self.project_code = str(cfg.get("code") or "").strip()
39
        self._token = (cfg.get("token") or "").strip()
40
        self._last_call = 0.0
41
        self.http = httpx.Client(timeout=timeout)
42

43
    # ---------- 底层 ----------
44
    def _throttle(self) -> None:
45
        """限速，调用方需持有 _API_LOCK。"""
46
        wait = MIN_INTERVAL - (time.time() - self._last_call)
47
        if wait > 0:
48
            time.sleep(wait)
49
        self._last_call = time.time()
50

51
    def _call(self, api: str, params: dict) -> dict:
52
        with _API_LOCK:
53
            self._throttle()
54
            try:
55
                r = self.http.get(f"{BASE_URL}/{api}", params=params,
56
                                  headers={"User-Agent": "baijing-client/1.0"})
57
                data = r.json()
58
            except Exception as e:
59
                raise BaijingError(f"请求失败({api}): {type(e).__name__}: {e}")
60
        if not isinstance(data, dict):
61
            raise BaijingError(f"返回异常({api}): {str(data)[:120]}")
62
        return data
63

64
    @staticmethod
65
    def _check(data: dict, api: str) -> dict:
66
        if data.get("success") and str(data.get("status")) == "200":
67
            return data
68
        raise BaijingError(f"{api} 失败: {data.get('msg') or data}")
69

70
    def _save_token(self, token: str) -> None:
71
        self._token = token
72
        with _API_LOCK:
73
            cfg = {}
74
            if os.path.exists(self.config_file):
75
                try:
76
                    cfg = json.load(open(self.config_file, encoding="utf-8"))
77
                except Exception:
78
                    cfg = {}
79
            cfg["token"] = token
80
            json.dump(cfg, open(self.config_file, "w", encoding="utf-8"),
81
                      ensure_ascii=False, indent=2)
82

83
    # ---------- 基础接口 ----------
84
    def login(self, force: bool = False) -> str:
85
        """token 永久有效：有缓存就直接用，force=True 才真正请求登录接口。"""
86
        with _API_LOCK:
87
            if self._token and not force:
88
                return self._token
89
            if not self.username or not self.password:
90
                raise BaijingError("缺少凭据：请配置 username/password 或设置 BJJ_USER/BJJ_PASS")
91
            data = self._call("login", {"username": self.username,
92
                                        "password": self.password})
93
            self._check(data, "登录")
94
            token = str((data.get("data") or {}).get("token") or "").strip()
95
            if not token:
96
                raise BaijingError(f"登录成功但未返回 token: {str(data)[:160]}")
97
            self._save_token(token)
98
            return token
99

100
    def get_wallet(self) -> dict:
101
        return self._check(self._call("getWallet", {"token": self.login()}), "查询余额")
102

103
    # ---------- 付费接口 ----------
104
    def _channel(self, channel_id: str | None = None) -> str:
105
        cid = str(channel_id or self.channel_id or "").strip()
106
        if not cid:
107
            raise BaijingError("缺少渠道ID：请在后台「接收数据」页点「获取API参数」获取 channelId")
108
        return cid
109

110
    def get_phone(self, channel_id: str | None = None, phone_num: str | None = None,
111
                  operator: int | None = None, scope: str | None = None,
112
                  scope_black: str | None = None) -> dict:
113
        """取临时号码，一次最多 20 个。"""
114
        p = {"token": self.login(), "channelId": self._channel(channel_id)}
115
        if phone_num:
116
            p["phoneNum"] = phone_num
117
        if operator:
118
            p["operator"] = operator        # 0全部 5虚拟 4非虚拟
119
        if scope:
120
            p["scope"] = scope
121
        if scope_black:
122
            p["scope_black"] = scope_black
123
        return self._check(self._call("getPhone", p), "取号")
124

125
    def get_code(self, phone: str, channel_id: str | None = None) -> dict:
126
        """读一次共享数据。"""
127
        return self._check(self._call("getCode", {"token": self.login(),
128
                                                  "channelId": self._channel(channel_id),
129
                                                  "phoneNum": phone}), "读取共享数据")
130

131
    def blacklist(self, phone: str, channel_id: str | None = None) -> dict:
132
        return self._check(self._call("phoneCollectAdd",
133
                                      {"token": self.login(),
134
                                       "channelId": self._channel(channel_id),
135
                                       "phoneNo": phone,
136
                                       "type": COLLECT_TYPE}), "拉黑号码")
137

138
    def release(self, phone: str, channel_id: str | None = None,
139
                status: int = RELEASE_STATUS) -> dict:
140
        return self._check(self._call("release",
141
                                      {"token": self.login(),
142
                                       "channelId": self._channel(channel_id),
143
                                       "phoneNo": phone,
144
                                       "status": status}), "结束共享")
145

146
    # ---------- 高层封装 ----------
147
    @staticmethod
148
    def extract_code(resp: dict) -> str:
149
        data = resp.get("data") or {}
150
        code = str(data.get("code") or "").strip()
151
        if code:
152
            return code
153
        text = str(data.get("modle") or "")
154
        m = re.search(r"\b(\d{4,8})\b", text) or re.search(r"(\d{4,8})", text)
155
        return m.group(1) if m else ""
156

157
    def wait_code(self, phone: str, channel_id: str | None = None,
158
                  timeout: float = 180.0, interval: float = 1.5) -> str | None:
159
        """轮询读码：最多 100 次，每次间隔 1 秒以上。"""
160
        deadline = time.time() + timeout
161
        attempt = 0
162
        while time.time() < deadline:
163
            attempt += 1
164
            try:
165
                resp = self.get_code(phone, channel_id)
166
            except BaijingError:
167
                resp = {}
168
            code = self.extract_code(resp)
169
            if code:
170
                return code
171
            if attempt >= 100 or time.time() >= deadline:
172
                break
173
            time.sleep(interval)
174
        return None
175

176

177
if __name__ == "__main__":
178
    c = BaijingClient()
179
    print("余额:", c.get_wallet().get("data"))
180
    info = c.get_phone(operator=4)              # 只要非虚拟号
181
    phone = str((info.get("data") or {}).get("mobile"))
182
    print("取号:", phone)
183
    print("读码:", c.wait_code(phone, timeout=60) or "（60 秒内未收到）")