外贸获客智能搜索客户

概述

iReach 客户主数据检索（积分版）

按条件检索海外获客平台的客户主数据池，覆盖公司与联系人两个维度。先和用户确认检索条件，再按「先报价 → 用户确认 → 才真正调用」确认点数，一次调用即取回完整客户明细（含联系人工作邮箱），本次消耗的点数由响应里的 credit 块给出。

流程总览：取 API Key（第 1 步）→ 报价并取得用户明确同意（第 2 步）→ 确认条件后一次调用拿全量明细、并告知消耗点数（第 3～5 步）。

本技能只有一条调用通道：API Key + 点数（积分）扣费。 本技能是积分通道的独立技能（slug ireach-customer-search-credit）：按次付费（微信 Agent Pay）那套是仓库里保留的能力、当前没有任何技能在用它，本技能既不依赖它，也不是同一个技能的升级版。

什么时候用

• 用户要找某个国家、行业、地区的目标客户
• 用户需要一份潜在客户名单，或需要联系人及其工作邮箱
• 用户说「帮我找一些德国的汽车零部件公司」「美国加州做医疗设备的有哪些」

执行流程

按以下顺序执行，每一步的细节见对应章节：

1. 取 API Key：读技能目录（SKILL.md 与 config.json 所在目录）下 config.json 的 IREACH_API_KEY，回退环境变量 IREACH_API_KEY；两者任一有值即就绪。都没有时，先按「鉴权」引导用户取 Key 并写回，拿到之前不要运行检索命令（只有 --quote 查单价不受此限——它不需要 Key，见下一步）。
2. 向用户确认点数：先以 --quote 查出本次将消耗的点数，明确告知用户（例如「本次将消耗 10 点」），得到用户明确同意后才能发起真正的调用；用户未确认、或表示再想想，就不要调用。报价不需要 API Key，Key 还没配好时也能先报价；话术见「调用前怎么说（先报价、再等确认）」。（报价与条件确认的先后可自定：点数只与技能有关、与条件无关，改几次条件都还是同一次调用、扣同一份点数；推荐先把条件谈定再报价，免得用户确认了点数又要改条件。）
3. 确认检索条件：先跑 scripts/list_filters.py 拿到真实可用的筛选字段与常见取值，再据此和用户确认检索条件，不要凭记忆编造国家或行业名称（见「标准流程」第一、二步）。
4. 调用：脚本一次调用内完成鉴权、扣点与检索（命令见「用 API Key 调用」）。只需要带 Key 这一个鉴权头，不要再携带任何按次付费相关的请求头。
5. 交付并转述扣点：把渲染好的客户明细交给用户，并按响应里的 credit 块如实转述本次消耗的点数与结算后余额；credit 缺失时不提点数，不要编造。

任一步异常按「异常处理」对号入座，不要自行判定失败。

鉴权

Key 取技能目录（SKILL.md 与 config.json 所在目录）下 config.json 里的 IREACH_API_KEY 字段，回退到环境变量 IREACH_API_KEY；两者任一有值即视为就绪。config.json 形如：

{ "IREACH_API_KEY": "你的密钥" }

请求头以 X-API-Key 为推荐（后端两种都收，推荐第一种）：

X-API-Key: ck_live_xxxxxxxx

Authorization: Bearer ck_live_xxxxxxxx

推荐 X-API-Key：后端 SkillCreditGuard 读的就是这个名字；而 Authorization 在网关 / 代理层常被别的中间件占用，写成裸 Authorization: <key>（不带 Bearer）更容易被拦下或改写。不要写成裸 Authorization。

运行脚本前，先按下面四步确认 Key 就绪。任何时候都不要编造或猜测 Key。

1. 检查是否已有 Key。 读技能目录下的 config.json，看 IREACH_API_KEY 是否为非空字符串；没有再看环境变量 IREACH_API_KEY。任一有值即视为就绪，直接进入后续流程——脚本按同样顺序取 Key，所以你通常不需要手动传 --api-key。
2. 缺失则引导用户获取。 都没有时停下来，提示用户前往积分中心 <https://www.ireach.cc/credit>：用手机号 + 短信验证码登录 → 在「API Key」里创建一把（明文只显示这一次，要当场复制保存，关掉就只能重置）。让用户把拿到的 Key 直接发给你；在拿到 Key 之前不要运行检索命令——不带 Key 的调用必然是 401，白跑一趟（--quote 只查单价、不需要 Key，随时可以先跑）。
3. 拿到后写回。 收到 Key 后，把它写入技能目录下 config.json 的 IREACH_API_KEY 字段（保留文件其它内容），然后再运行脚本。用户只配置这一次，之后调用不必再向他索取。
4. 鉴权失败时（HTTP 401 CREDIT_KEY_REJECTED）。 多半是 Key 被吊销或写错了。提示用户重新到积分中心获取一把新 Key，按第 3 步覆盖写入 config.json 后重试；不要拿同一个失效 Key 反复重跑——重跑多少次都还是 401。

⚠️ config.json 是本机凭据文件：不要提交到 git、不要贴进日志、不要分享出去。它随包发布时只是一个空占位（"IREACH_API_KEY": ""），真实 Key 只留在使用者本机。

缺少 API Key 时怎么说

用户还没有 Key 时，把下面这段直接发给他：

检索客户数据调用的是远端的按点数计费服务，首次使用得先配置一把 API Key 🔑

👉 打开积分中心，用手机号 + 短信验证码登录后在「API Key」里创建一把：https://www.ireach.cc/credit

（Key 的明文只显示这一次，记得当场保存；关掉就看不到了，只能重置）

拿到 Key 后直接粘贴发给我，我帮你存好，以后就不用再管它了。

这个服务按点数计费，余额不足时我会提醒你。

调用前怎么说（先报价、再等确认）

每一次真正调用之前，都先按「执行流程」第 2 步报价，把点数明确告诉用户。 点数取 --quote 的实际输出，可以照下面这段话来问（示例里的数字来自服务端，不要在回答里写死）：

本次将消耗 10 点（点数由服务端按技能配置，实际以调用结果为准）。是否继续？

• 用户没明确说「继续 / 可以 / 确认」之前，不要调用。「先看看」「你觉得呢」都不算同意。
• 用户表示再想想、或直接拒绝时：不要调用，并如实说明「本次没有调用、也没有扣点」。
• 用户同意后再进入「执行流程」第 4 步调用。报价只是预估：最终实际消耗以成功响应里的 credit.points 为准（服务端可能调价），按第 5 步如实转述。

报价命令（不需要 API Key：只读单价，不扣点、不查客户数据）：

python3 scripts/search.py --quote
# 本次将消耗 10 点（单价由服务端配置，实际以调用结果里的 credit 块为准）。确认后我再发起调用。

它请求的是 GET https://www.ireach.cc/jeecg-boot/openapi/skill/leads/search/price，成功时返回 data.pointsPerCall。因为不需要 Key、也不扣点，Key 还没配好时也能先报价。报价失败（该技能未开放按点调用 / 技能不存在或未部署 / 网络不通）时按「异常处理」对号入座，不要因此发起调用。

唯一的调用通道：API Key + 点数（积分）扣费

没有免费预览：不带 Key 的请求一律被拒（HTTP 401，CREDIT_KEY_REJECTED），不存在"先免费看有没有命中"这一步。用户付出点数买到的就是完整明细，因此拿到响应后应当正常呈现明细内容。

用 API Key 调用

Key 从哪来见「鉴权」：技能目录 config.json 的 IREACH_API_KEY，回退环境变量 IREACH_API_KEY。都没有就先按「鉴权」把 Key 拿到并写回，别急着发起调用（不带 Key 必然是 401，白跑一趟）。

请求头二选一（推荐第一种）：

X-API-Key: ck_live_xxxxxxxx

Authorization: Bearer ck_live_xxxxxxxx

完整请求示例（路径就写这一段，不要加域名前缀）：

POST /openapi/skill/leads/search
X-API-Key: ck_live_xxxxxxxx
Content-Type: application/json

{"industry":"制造业","country":"美国"}

请求体里的条件参数按「标准流程」第二步的规则组装：每个条件都是一个字符串（不是数组），包含匹配，与脚本的 --country / --industry 参数一一对应；pageNo 是数字。除上面这一个 Key 头之外，不要携带任何按次付费相关的请求头（按次付费那套是仓库里保留的能力、当前没有任何技能在用它）——带上那些头只会让服务端按别的语义处理这次请求，那不是你要的结果。

脚本 scripts/search.py 封装了这次请求，参数与上面 body 的字段一一对应：

python3 scripts/search.py --country Germany --industry automotive

上面这条命令没有传 --api-key：脚本会依次读技能目录 config.json 的 IREACH_API_KEY、环境变量 IREACH_API_KEY。需要显式覆盖时（例如自动化 / CI 场景，或本机临时换一把 Key）再加 --api-key ck_live_xxxxxxxx，它的优先级最高。

报价（--quote）单独一条命令，不需要 Key：它只读服务端为该技能配置的点数单价，不扣点、不调用检索接口，所以 Key 还没配好时也可以先跑：

python3 scripts/search.py --quote

输出是一句话（点数取接口返回的 data.pointsPerCall，不要写死）：「本次将消耗 10 点（单价由服务端配置，实际以调用结果里的 credit 块为准）。确认后我再发起调用。」把它转述给用户、拿到确认后再执行上面的调用命令（见「调用前怎么说（先报价、再等确认）」）。

成功响应（HTTP 200，code 为 SUCCESS）直接就是完整客户明细，不需要再"取明细"第二次调用：

{
  "code": "SUCCESS",
  "data": {
    "pageNo": 1,
    "records": [
      { "name": "...", "country": "...", "region": "...", "industry": "...",
        "staffCount": "...", "establishTime": "...", "officialWebsite": "...",
        "address": "...", "phone": "...", "customerTags": "...",
        "contacts": [ { "name": "...", "position": "...", "workEmail": "..." } ] }
    ],
    "disclaimer": "..."
  },
  "credit": { "points": 10, "balanceAfter": 90, "bizNo": "CK2026..." }
}

credit 是本次调用的点数结算信息，只在积分通道调用成功时出现：

点数单价由服务端按技能配置，不要在回答里写死具体点数（改价只需改数据库一行、不发版）。把 credit 如实转述给用户，例如「本次消耗 10 点，余额 90 点」——点数一律取 credit.points 与 credit.balanceAfter 的实际值。credit 字段缺失时就不要提点数，不要编造。

点数是预扣后结算的：调用发起时先按单价预扣，业务失败会自动返还，不需要也不能让用户手工申请退款。若因余额不足被拒绝，如实告知「点数不足」并给出可用的余额方向信息，不要重复重试。

错误码（两种都必须如实转述给用户，不要自行改写文案）：

用户没有 Key 时，引导他自取，不要替他申请（Key 绑在用户自己的账号上，你无法代建）：

1. 打开积分中心入口 <https://www.ireach.cc/credit>，用手机号 + 短信验证码登录；
2. 在「API Key」里创建一把，明文只显示这一次，要当场复制保存（关掉就再也看不到，只能重置）；
3. 把 Key 发给你，由你写回技能目录的 config.json（见「鉴权」第 3 步）。

⚠️ 若积分中心入口当前不可用：不要让用户反复重试，不要自行猜测或编造网址，

也不要改用按次付费顶上（那套能力当前没有任何技能在用）。如实告知「当前无法自助获取 API Key」，并请用户联系服务方获取。

未携带 Key 时的服务端原文

不带 Key 的调用会得到下面这条 401，可以原样转述给用户：

该技能按点数（积分）计费，需要 API Key：请在请求头携带 X-API-Key；还没有 Key 时，请先到积分中心用手机号登录并创建一把

标准流程

第一步：拉取可筛字段

python3 scripts/list_filters.py

输出当前可用的筛选字段与常见取值（带命中数）。不要凭记忆编造国家或行业名称——用这一步拿到的真实值去和用户确认条件。常用字段：

list_filters.py 打的是匿名免费的元数据端点 /openapi/skill/leads/meta，不属于计费通道：它不需要 Key、不扣点，也不会触发任何一次付费调用。

第二步：把用户的话组装成参数

条件是可选的，可以只传一个，也可以组合多个（组合越严命中越少）。

第三步：报价、取得用户确认后，一次调用取回完整明细

先按「调用前怎么说（先报价、再等确认）」报出点数并拿到用户的明确同意——没同意就不调用。同意后用同一套条件执行一次：

python3 scripts/search.py --country Germany --industry automotive

一次调用就拿到完整明细，不需要第二次「取明细」调用。

输出是渲染好的可读明细，最多 5 条，含公司全字段与关联联系人（姓名 / 职位 / 工作邮箱），末尾带免责声明。把它整理后原样呈现给用户——这次调用已经扣了点，用户买到手的就是这份明细，没有"只回答有没有命中"的隐藏规则。同时把输出里的点数结算信息一并告知用户（例如「本次消耗 10 点，余额 90 点」）。

需要更多结果时翻页：在条件后加 --page-no 2。翻页是一次新的调用、会再扣一次点数，发起前要重新报价并再次取得用户同意。

异常处理

脚本用退出码区分「拿到了可用信息」和「这次没拿到」。0 与 1 是两个脚本共用的口径（2 只在 search.py 这类解析命令行参数的脚本上出现）：

• 0：服务端给出了可操作结果（成功、缺 Key / Key 无效、业务拒绝、参数不合法、触发限流等）——这些结果都带有明确的下一步
• 1：网络或解析失败，或服务端返回 404 / 5xx 这类环境不可用
• 2：没取到 API Key——--api-key、技能目录 config.json 的 IREACH_API_KEY、环境变量 IREACH_API_KEY 三级都没有（脚本会打印含积分中心链接的引导话术），或命令行参数用法错误（--page-no 不是数字，由 argparse 直接结束）。两者都属于"命令没配好"，不是业务失败，不要当作重试信号

注意 401 在本技能里不是"环境不可用"，而是可操作的业务态：本技能按点数计费，没带 Key 就是 401，提示用户去取 Key 即可（所以退出码是 0）。

退出码为 1 时，不要把输出当成查询结果，按输出提示处置。

--quote（只查单价）的退出码只用 0 和 1：0 = 报价拿到了；1 = 报价没拿到（400 该技能未开放按点调用 / 404 技能不存在或未部署 / 网络或解析失败，都属环境或配置问题）。报价不需要 Key，所以不会出现退出码 2，2 只属于真正调用那一路。

能力边界

• 只读检索，不支持新增、修改、认领、导出等任何写操作。
• 只检索平台公共数据池的公司与联系人维度。
• 没有免费预览：不带 API Key 一律 401；用户按点数买到的是完整明细，技能层正常呈现。
• 单次调用最多呈现 5 条客户明细；需要更多可翻页，页码上限 50，翻页会再扣一次点数（发起前要重新报价并取得同意）。
• 点数单价、扣费与失败返还全部由服务端负责，技能包不写死单价；每次调用的消耗与余额以响应里的 credit 块为准。
• 调用前先报价、用户同意才扣点：没拿到明确同意时不调用，也就没有任何扣点与结算流水。
• 数据来源于公开渠道，使用时请遵守当地数据保护法规。