¶ Qoo10（日本站）平台对接操作指南
适用对象：使用易抵达对接 Qoo10 日本站（QAPI）的客户。本文介绍如何在 Qoo10 卖家后台获取 API 凭证、在易抵达配置 Qoo10 抓单接口并完成授权、抓取待发货订单，以及发货后把转单号回传给 Qoo10。
¶ 一、能力概述
易抵达对接 Qoo10 日本站，支持：
- 抓单：自动抓取 Qoo10 店铺「待发货」订单，转换为易抵达运单（一个订单对应一票运单）。
- 发货回传：易抵达获取转单号后，自动把承运商、转单号回传到 Qoo10 订单（对应 Qoo10 的「发货处理」）。
- 承运商映射：把易抵达承运商名映射成 Qoo10 官方承运商名后回传。
说明：Qoo10 订单进入易抵达后，走易抵达自有的收货渠道打单链路生成转单号/面单；易抵达不调用 Qoo10 侧的运费试算/转单接口，也暂不抓取 Qoo10 物流轨迹。
¶ 二、前置：在 Qoo10 卖家后台获取 API 凭证
对接 Qoo10 需要两项凭证：API ID 和 Certification Key（认证密钥）。在 Qoo10 卖家后台（QSM / WING）获取：
- 登录 Qoo10 卖家后台。
- 进入 API 管理 → 「API IDの発行/照会」（API ID 发行/查询） 页面。
- 选择 OPEN API 用途，按页面要求填写企业名称、网址、IP 地址等信息后生成凭证。
- 复制生成的 API ID 与 完整的 Certification Key，稍后填入易抵达。
⚠️ 注意事项：
- 一个店铺同一时间只能授权给一个 ERP。如果店铺此前已授权给其他系统，需要先在 Qoo10 后台解除旧授权或重新发放新密钥。
- 台湾本土店铺暂不支持 API 授权。
- Certification Key 较长，请务必复制完整，不要截断。
① 进入开发者页：在 Qoo10 卖家后台（QSM）左下角点击「QAPI 開発ガイド」。
② 申请 API ID：在「サービス紹介 / QAPIの利用方法」按 STEP 01 点击「API IDの発行/照会」。
③ 发行并复制凭证：在「API IDの発行/照会」页面发行后，复制 API ID 与 Certification Key（认证密钥有效期 1 年）。
¶ 三、在易抵达配置 Qoo10 抓单接口
¶ 入口
菜单 → 抓单接口，打开「抓单对接设置」。
在「抓单对接设置」列表中点击左下角 「添加」 新建接口（列表里也能看到已建接口的类型、最近抓取状态/时间）。
¶ 步骤 1：基本信息
在「编辑设置 → 基本」标签页：
- 类型：选择 Qoo10。
- 名称：填写便于识别的接口名称，例如「Qoo10 日本站店铺」。
- 间隔时间（分钟）：抓单自动执行的间隔；留空则按系统默认。
¶ 步骤 2：参数页 → 发起授权
切换到 「参数」 标签页，可以看到：
- 店铺站点：日本站（api.qoo10.jp）
- 授权状态：未授权（绿色「已授权」/ 红色「未授权」）
点击 「Qoo10授权」 按钮，打开授权弹窗。
¶ 步骤 3：在授权弹窗中填写并校验
在「Qoo10授权」弹窗中依次填写（均为必填）：
| 字段 | 说明 |
|---|---|
| 客户 | 选择该接口归属的客户（员工操作时需选择；客户自己登录时自动锁定为本人） |
| 收货渠道 | 选择抓单订单进入易抵达后默认使用的收货渠道 |
| API ID | 粘贴在 Qoo10 后台获取的 API ID |
| 认证密钥（Certification Key） | 粘贴完整的 Certification Key |
填好后点击 「授权并校验」。系统会实时校验凭证连通性：
- 校验成功 → 提示「授权成功，请点击保存完成接口配置」，参数页授权状态变为已授权。
- 校验失败 → 弹窗保持打开并给出失败原因（如凭证无效、店铺已授权其他 ERP 等），请核对后重试。
提示：授权信息会先暂存在当前接口，点击「保存」后才真正写入系统。所以即使名称等还没填全，也可以先完成授权，再补齐信息后保存。
¶ 步骤 4：保存接口
回到「编辑设置」，确认名称等信息无误后点击 「保存」。接口创建完成。
¶ 四、抓单
在「抓单对接设置」列表中选中该 Qoo10 接口，点击 「立即抓单」 即可手动抓取一次；配置了间隔时间后系统也会自动抓取。
抓单规则：
- 只抓取 Qoo10 店铺中待发货的订单（「配送要請」「配送準備」状态）。
- 一个 Qoo10 订单对应一票易抵达运单；同一订单的多个商品行会合并到这一票运单。
- 抓取成功的订单会进入易抵达，带入收件人、地址、商品、数量等信息，客户单号为 Qoo10 的订单号。
¶ 五、承运商映射（可选）
发货回传默认会把运单自身的承运商名透传给 Qoo10。如果易抵达的承运商名与 Qoo10 官方承运商名不一致，可配置映射：
- 进入 系统参数 → 「Qoo10 设置」。
- 维护「易抵达承运商 → Qoo10 承运商名」的映射关系并保存。
回传时：命中映射 → 用映射后的 Qoo10 承运商名；未配置或未命中 → 透传运单承运商名。
¶ 六、发货回传
Qoo10 抓单来源的运单，无需单独配置回传接口（系统按抓单接口的凭证自动完成回传）。
¶ 自动回传
运单获取到转单号后，会自动触发回传：把转单号 + 承运商回传给 Qoo10（对应 Qoo10 的「发货处理 / SetSendingInfo」）。其中承运商可经「Qoo10 设置」里的承运商映射转换为 Qoo10 官方承运商名。回传成功后，Qoo10 后台该订单即可看到发货 / 物流信息。
¶ 回传失败怎么办
若回传失败，可在该运单上查看 报文 与 运单日志，定位具体失败原因（如转单号为空、承运商缺失、Qoo10 返回错误等）。
¶ 手动重新回传
如需重新回传，可手动操作：在主列表勾选运单 → 点击下方的「运单回传」按钮即可。
说明：手动回传会用运单当前已有的转单号 + 承运商重新回传一次（不会重新去获取转单号）。因此请确保运单已打单并已有转单号再手动回传；若运单尚无转单号，回传会被拦截。
¶ 七、常见问题
| 问题 | 处理 |
|---|---|
| 抓单接口类型下拉里没有「Qoo10」 | 该机构尚未启用 Qoo10，请联系易抵达开通 |
| 授权失败：凭证无效 | 核对 API ID 与 Certification Key 是否完整、未截断 |
| 授权失败：店铺已授权其他 ERP | Qoo10 限制一个店铺只能授权一个 ERP，请在 Qoo10 后台解除旧授权或重新发放密钥 |
| 抓不到订单 | 确认 Qoo10 店铺中确有「待发货（配送要請/配送準備）」状态的订单 |
| 回传失败 | 确认运单已获取转单号、承运商已配置；可在运单回传日志查看具体原因 |