GetContact CLI

GetContact CLI 是一个 Python 项目，可通过 GetContact API 查询电话号码信息，无需安卓应用或浏览器。

支持的功能：

查看号码档案（GetContact 显示的名称、标签数量、邮箱等）
查看号码标签列表——其他人如何在通讯录中保存该号码
查询账户剩余搜索配额
从 CSV 文件批量查询
当账户遭遇限流（HTTP 403）时完成验证码
通过 WhatsApp 验证自行创建新凭证
保存多个账户并在其间切换

每条命令的输出会自动保存到 results/ 文件夹。

环境要求

Python 3.9 或更高版本，以及两个包：

pip install requests cryptography

已在 Windows（git-bash）和 Linux 上测试。无需构建步骤，无需编辑配置文件。

运行

菜单模式（用于日常使用）

python gtc.py

不带任何参数时，程序会显示带编号的功能列表：

选择功能：
  1. 查询号码档案（所有者名称）
  2. 查询号码标签（他人保存的名称）
  3. 账户剩余配额
  4. 从 CSV 文件批量查询
  5. 解除封锁 / 验证码
  6. 查看已保存的账户
  7. 添加新账户（需要 WhatsApp）
  0. 退出

选择编号，输入目标手机号码，结果立即显示。完成后程序返回菜单，因此可以连续进行多次查询，无需重新输入命令。如果某次查询失败——号码格式错误、配额耗尽、网络中断——错误信息会显示，菜单仍保持活动。

命令模式（用于脚本）

python gtc.py search 08123456789                  # 档案
python gtc.py search 08123456789 -t tags          # 标签列表
python gtc.py search 08123456789 --json           # 原始响应
python gtc.py quota
python gtc.py batch nomor.csv --delay 2
python gtc.py cred list

所有号码均按印尼格式规范化为 E.164：08… 变为 +628…，62… 变为 +62…，已以 + 开头的号码保持不变。

命令

命令	用途
`search <号码>`	查询单个号码。`-t profile`（默认）或 `-t tags`，`--json` 获取原始响应。
`batch <文件.csv>`	查询 CSV 中的所有号码。`-o` 指定输出路径，`--delay` 设置请求间隔（默认 1.5 秒）。
`quota`	查询 `search` 和 `numberDetail` 的剩余配额，以及重置日期。
`captcha`	显示验证码并发送答案。在账户被临时封锁时使用。
`generate <号码>`	注册新设备并通过 WhatsApp 验证。将结果保存为凭证。
`cred list \| add \| use \| remove`	管理已保存的凭证。

-a/--account 标志适用于所有命令，用于选择活动凭证以外的其他凭证。

`batch` 的 CSV 格式

每行一个号码。如果第一行包含名为 phone、phone_number、phonenumber 或 nomor 的标题，则使用该列；否则读取第一列。

phone,nama
08123456789,Budi
081298765432,Siti

结果 CSV 包含 phone,status,displayName,tagCount,tags,error 列。某个号码失败不会终止整个进程——该行会标记为 error，其余部分继续运行。

凭证

凭证保存在 ~/.config/gtc/credentials.json，在 POSIX 系统上权限为 600。内容包括令牌、Diffie-Hellman 交换得到的 finalKey 以及 clientDeviceId——这三项足以使用 GetContact 账户，因此请像对待密码一样对待此文件。

添加已有凭证：

python gtc.py cred add akun1 --final-key <hex> --token <token> --phone +628...
python gtc.py cred use akun1

从零创建新凭证：

python gtc.py generate 08123456789

此命令注册一个虚拟设备，通过 Diffie-Hellman 协商加密密钥，然后通过 VerifyKit 请求号码所有权验证。过程中会显示一个 WhatsApp 链接和代码；使用相应号码发送该消息，等待双勾，然后按 Enter。生成的凭证会立即保存。

存储位置可通过 GTC_CONFIG_DIR 修改。

results 文件夹

每次执行命令时，屏幕显示的内容也会写入 results/，文件名包含时间戳：

results/20260820-101307-search-08123456789.txt
results/20260820-100248-quota.txt
results/20260820-101512-batch.csv

使用 --json 时扩展名为 .json。batch 命令未指定 -o 时也会自动将 CSV 写入此处。已保存文件的路径会打印到 stderr，因此 stdout 保持干净，便于管道处理。此文件夹位于 .gitignore 中，因为它包含他人的电话号码数据。

可通过 GTC_RESULTS_DIR 更改位置。尚无轮转或自动删除功能——如果文件夹变大，请手动清理。

环境变量

变量	功能
`GTC_CONFIG_DIR`	`credentials.json` 的位置。默认 `~/.config/gtc`。
`GTC_RESULTS_DIR`	输出位置。默认是 `gtc.py` 旁边的 `results/`。
`GTC_NO_BANNER`	设置任意值以隐藏启动横幅和日志。

工作原理

该客户端模拟 GetContact Android 8.4.0 应用。每个请求：

使用账户的 finalKey 对 JSON 载荷进行 AES-256-ECB 加密，然后作为 {"data": "<base64>"} 发送。
x-req-signature 头包含使用固定应用密钥对 <时间戳>-<原始载荷> 进行的 HMAC-SHA256。
包含 data 字段的响应在解析前使用相同密钥解密。

finalKey 本身来自注册时的 Diffie-Hellman 交换：客户端发送其公钥，服务器回复其公钥，共享密钥的 SHA-256 即成为 AES 密钥。DH 参数（p = 900719898367，g = 7）已嵌入代码并通过验证。

查询使用两个端点，命名具有误导性：/v2.8/search 返回档案，而 /v2.8/number-detail 返回标签列表。此映射曾一度颠倒，现已在 api_search() 中修正。

注册使用 VerifyKit（api.verifykit.com）作为验证提供商，采用类似的 HMAC 和 AES 方案，但使用不同的密钥。

限制

默认国家为印度尼西亚（COUNTRY = "id"）。国外号码必须完整书写并带 +国家代码，部分响应可能不正确。
搜索配额取决于账户订阅。配额耗尽会报错，而不是返回空结果。
请求过快会触发验证码。在 batch 中增加 --delay，若已触发则使用 captcha 命令。
HMAC 密钥和应用版本是静态的。如果 GetContact 更改这两者，必须更新 gtc.py 顶部的常量。

使用说明

此工具通过伪装成官方客户端访问 GetContact 的私有 API，这几乎肯定违反其服务条款。返回的数据也是他人的个人数据。请仅用于您有权检查的号码，遵守适用的数据保护法规，并自行承担风险。与 GetContact 无任何关联。