快递停发地区查询

解决物流拦截与退件成本问题

在电商发货环节，商家经常面临偏远地区或特殊时期的快递停发问题。如果未提前确认线路可达性，直接将包裹交给快递网点，极易导致包裹在中转站被拦截并退回。这不仅产生了逆向物流成本，还可能引发消费者的客诉。为了解决这一痛点，我们需要在发货前对收件地址进行快速的可达性预检，确认主流快递网络是否能覆盖该目的地。

核心能力与调用流程

该技能专门封装了快递停发地区查询接口，核心能力包括查询7大主流快递公司在指定收件地址的可达性，并返回详细的不可达原因。

在工程实现上，调用流程非常直接：

• 提取参数：从用户请求中提取收件地址，例如 广东省深圳市南山区科技园。
• 鉴权与请求：支持通过环境变量 CHINAZ_EXPRESS_UNREACHABLE_API_KEY 或显式传递 --api-key 参数进行鉴权。
• 执行脚本：在 Skill 根目录运行 python scripts/query_express_unreachable.py --address <地址>。
• 解析结果：脚本会返回包含 code、msg、data 等字段的 JSON 结构。其中 data 数组中的 status 字段标识了可达性（0 代表不可达，1 代表可达），reason 字段则说明了具体的停发原因。

适用边界与注意事项

在使用该技能时，需要注意以下工程边界：

• 单次查询限制：接口设计为一次只查询一个目标地址。如果需要进行批量排查，必须在业务层通过循环逐条执行，不可并发单次请求。
• 密钥安全：API Key 仅用于接口鉴权，严禁在日志中输出、复述或持久化保存完整密钥。当返回 missing_api_key 时，需引导用户补充密钥。
• 数据时效性：快递停发地区具有强时效性，接口返回的数据仅供参考，不具备法律效应。若发现结果与实际不符，建议多次查询或结合人工校验。