UpKuaJing 联系方式有效性校验

通过 UpKuaJing 开放平台 API 校验联系方式的有效性。本能力提供三类检测接口：手机号有效性、邮箱有效性与域名有效性。

概览

本能力通过以下方式接入 UpKuaJing 的联系方式有效性检测服务：

• 手机号有效性校验（phone_validity_check.py）：校验手机号码的有效性、类型及 WhatsApp 状态
• 邮箱有效性校验（email_validity_check.py）：校验邮箱地址的有效性
• 域名有效性校验（domain_validity_check.py）：校验域名的有效性与安全状态

脚本运行方式

环境准备

1. 检查 Python 版本：python --version
2. 安装依赖：pip install -r requirements.txt

脚本所在目录：scripts/*.py
运行示例：python scripts/*.py

重要提示：始终使用直接脚本调用方式，例如 python scripts/phone_validity_check.py。禁止使用 shell 复合命令，如 cd scripts && python phone_validity_check.py。

三类检测 API

手机号有效性校验（phone_validity_check.py）

校验手机号码的有效性、类型及 WhatsApp 状态。

参数说明：参见 Phone Validity API 文档

使用示例：

# 校验单个手机号
python scripts/phone_validity_check.py --phones "+8613812345678"

# 校验多个手机号
python scripts/phone_validity_check.py --phones "+8613812345678 +14155551234 +442071234567"

邮箱有效性校验（email_validity_check.py）

校验邮箱地址的有效性。

参数说明：参见 Email Validity API 文档

使用示例：

# 校验单个邮箱
python scripts/email_validity_check.py --emails "test@example.com"

# 校验多个邮箱
python scripts/email_validity_check.py --emails "test@example.com valid@gmail.com invalid-email"

域名有效性校验（domain_validity_check.py）

校验域名的有效性与安全状态。

参数说明：参见 Domain Validity API 文档

使用示例：

# 校验单个域名
python scripts/domain_validity_check.py --domains "google.com"

# 校验多个域名
python scripts/domain_validity_check.py --domains "google.com fake-domain-xyz123456.com github.com"

API Key 与 UpKuaJing 账户

• API Key：存储于 ~/.upkuajing/.env 文件中，键名为 UPKUAJING_API_KEY
• 首次校验：若未设置，将提示用户手动提供或前往 UpKuaJing 开放平台申请

API Key 未配置

首次运行时检查 ~/.upkuajing/.env 文件是否存在 UPKUAJING_API_KEY；
若未设置该变量，则提示用户选择以下任一操作：

1. 用户已有 API Key：由用户自行提供（需手动写入 ~/.upkuajing/.env 文件）
2. 用户尚未申请：引导用户前往 UpKuaJing 开放平台完成申请
   等待用户做出明确选择后继续执行；

账户充值

当 API 响应返回余额不足时，需向用户清晰说明情况并引导其完成充值：

1. 创建充值订单（执行 auth.py --new_rec_order）
2. 根据订单响应结果，向用户提供支付页面 URL，并引导用户打开该链接完成支付；待用户确认支付成功后继续后续流程；

获取账户信息

使用以下命令查询当前 UPKUAJING_API_KEY 对应的账户信息：auth.py --account_info

费用说明

所有有效性校验类 API 调用均产生费用。
最新价格信息：用户可查阅《详细价格说明》文档，或执行：python scripts/auth.py --price_info（返回全部接口的完整定价信息）

费用确认原则

任何会产生费用的操作，必须先明确告知用户并等待其显式确认；不得在通知消息中同步执行该操作。

工作流

决策指引

错误处理

• API Key 无效或不存在：检查 ~/.upkuajing/.env 文件中 UPKUAJING_API_KEY 是否已正确配置
• 余额不足：引导用户进行账户充值
• 参数错误：必须首先查阅 references/ 目录下的对应 API 文档，从中获取准确的参数名与格式，严禁凭猜测构造参数

API 文档参考

• 手机号有效性：查阅 references/phone-api.md
• 邮箱有效性：查阅 references/email-api.md
• 域名有效性：查阅 references/domain-api.md

注意事项

• 所有文件路径统一使用正斜杠（/），兼容所有操作系统平台
• 禁止猜测参数名称：必须从文档中获取准确的参数名与格式
• 禁止在响应中输出技术参数格式：不得以代码形式展示参数，需转换为自然语言表达
• 禁止估算或猜测费用：须通过 python scripts/auth.py --price_info 获取准确的价格信息

相关能力

您可能还会用到的其他 UpKuaJing 能力：

• linkedin-person-search — 从 LinkedIn 数据源搜索人员
• global-company-person-search — 从全球企业数据库搜索人员
• linkedin-company-search — 从 LinkedIn 数据源搜索企业
• global-company-search — 从全球企业数据库搜索企业
• global-company-shareholder — 查询全球企业数据库中的股东列表
• global-company-employee — 查询全球企业数据库中的员工列表
• global-company-person-colleague — 查询全球企业数据库中的同事列表
• global-company-person-alumni — 查询全球企业数据库中的校友列表
• global-company-person-experience — 查询全球企业数据库中的工作经历列表
• global-company-person-education — 查询全球企业数据库中的教育经历列表
• global-company-person-school-detail — 查询全球企业数据库中的学校详情
• upkuajing-global-company-people-search — 全球企业与人员联合搜索
• upkuajing-customs-trade-company-search — 海关贸易企业搜索
• upkuajing-map-merchants-search — 基于地图的商户搜索
• upkuajing-email-tool — 发送邮件及管理邮件任务
• upkuajing-sms-tool — 发送短信及管理短信任务
• upkuajing-contact-info-validity-check — 联系方式有效性校验
• phone-validity-check — 手机号有效性校验
• email-validity-check — 邮箱地址有效性校验
• domain-validity-check — 域名有效性与安全状态校验