cbs-4px-merchant-cli 0.0.7 → 0.0.8

package/skill/reference/onboarding.md

@@ -0,0 +1,573 @@
+# `fmc onboarding` command
+
+商家入驻：实名认证 → 开通物流品牌 → 申请并签署合同。
+
+> `onboarding auth *` 与 `onboarding brand open` 是**写操作**，默认会在终端二次确认。
+> 非交互环境（管道、CI、AI Agent）必须显式加 `-y`，否则命令会拒绝执行并以退出码 1 结束。
+> 想先看请求内容而不真正发送，用 `--dry-run`。
+>
+> 实名认证会提交姓名、身份证号、银行卡号等个人敏感信息。这些参数在 `--verbose` /
+> `--dry-run` 的打印里会被遮蔽为 `****`，但**真实值仍会随请求发送**——不要把它们写进
+> shell 历史或日志文件。
+
+## 该走哪条认证路径
+
+先用 `onboarding progress` 看当前节点，再按客户类型选命令：
+
+| 客户类型 | 经济主体 | 认证命令 |
+| --- | --- | --- |
+| 中国大陆（0） | 个人 | `auth indiv` → `auth code` |
+| 中国大陆（0） | 企业 | `auth indiv --agent` → `auth code --agent` → `auth organ`（必要时 `auth remit`） |
+| 港澳台（1）/ 海外（2） | 个人 / 企业 | `auth gat`（提交资料后走人工审核） |
+
+认证通过后：`brand list` → `brand open` → `contract list` → `contract url`。
+
+## Command details
+
+### `fmc onboarding progress`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding progress` |
+| **Description** | 查询入驻进度（实名认证 / 合同申请 / 合同签署 / 当前节点） |
+| **Usage** | `fmc onboarding progress [flags]` |
+
+需要 API Key 认证。入驻相关问题的**第一条命令**——先看卡在哪个节点。
+
+#### Options
+
+无额外参数。
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding progress
+```
+
+```bash
+fmc onboarding progress --output json
+```
+
+#### Output (text mode)
+
+```
+入驻进度
+──────────────────────────────────────────────────
+  实名认证    已完成
+  合同申请    已完成
+  合同签署    未完成
+  当前节点    待签署合同
+  客户类型    中国大陆 (0)
+  经济主体    企业 (2)
+```
+
+`当前节点` 可能为：`待实名认证` / `待申请合同` / `待签署合同` / `品牌已开通`。
+
+---
+
+### `fmc onboarding customer-type`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding customer-type` |
+| **Description** | 查询可选客户类型 |
+| **Usage** | `fmc onboarding customer-type [flags]` |
+
+需要 API Key 认证。`0` 大陆、`1` 港澳台、`2` 海外；`← 当前` 标记当前生效的类型。
+
+#### Options
+
+无额外参数。
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding customer-type
+```
+
+#### Output (text mode)
+
+```
+可选客户类型
+──────────────────────────────────────────────────
+
+  0  中国大陆 ← 当前
+  1  港澳台
+  2  海外
+```
+
+---
+
+### `fmc onboarding auth schedule`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding auth schedule` |
+| **Description** | 查询实名认证进度与认证类型 |
+| **Usage** | `fmc onboarding auth schedule [flags]` |
+
+需要 API Key 认证。比 `progress` 更细：能看出是否停在"待对公打款验证"。
+
+#### Options
+
+无额外参数。
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding auth schedule
+```
+
+#### Output (text mode)
+
+```
+实名认证进度
+──────────────────────────────────────────────────
+  认证状态    待对公打款验证 (4)
+  认证类型    企业认证 (1)
+  客户类型    中国大陆 (0)
+```
+
+认证状态：`0` 未开始、`1` 进行中、`2` 已完成、`3` 认证失败、`4` 待对公打款验证。
+
+---
+
+### `fmc onboarding auth indiv`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding auth indiv` |
+| **Description** | 发起个人实名认证，返回 flowId |
+| **Usage** | `fmc onboarding auth indiv --name <name> --cert-number <no> --mobile <mobile> --auth-type <type> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。仅中国大陆客户。
+
+命令返回的 `flowId` 是下一步 `auth code` 的入参，**必须记下来**。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--name <name>` | string | yes | 姓名 |
+| `--cert-number <no>` | string | yes | 身份证号 |
+| `--mobile <mobile>` | string | yes | 手机号 |
+| `--auth-type <type>` | string | yes | 认证方式：`0` 手机号验证、`1` 银行卡验证 |
+| `--bank-card <no>` | string | no | 银行卡号（`--auth-type 1` 时必填） |
+| `--agent` | boolean | no | 作为企业认证中的经办人实名认证 |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 个人客户，手机号验证
+fmc onboarding auth indiv --name 张三 --cert-number 440301199001011234 \
+  --mobile 13800138000 --auth-type 0
+```
+
+```bash
+# 银行卡验证
+fmc onboarding auth indiv --name 张三 --cert-number 440301199001011234 \
+  --mobile 13800138000 --auth-type 1 --bank-card 6222021234567890123
+```
+
+```bash
+# 企业认证的第一步：经办人实名
+fmc onboarding auth indiv --name 张三 --cert-number 440301199001011234 \
+  --mobile 13800138000 --auth-type 0 --agent
+```
+
+#### Output (text mode)
+
+```
+  ✔ 已发起个人实名认证
+    flowId      FLOW20260831001
+
+  验证码下发后，用 auth code --flow-id <flowId> --auth-code <code> 完成认证
+```
+
+---
+
+### `fmc onboarding auth code`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding auth code` |
+| **Description** | 提交验证码完成个人实名认证 |
+| **Usage** | `fmc onboarding auth code --auth-code <code> --flow-id <id> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--auth-code <code>` | string | yes | 短信或银行卡验证码 |
+| `--flow-id <id>` | string | yes | `auth indiv` 返回的 flowId |
+| `--auth-type <type>` | string | no | 认证方式：`0` 手机号、`1` 银行卡 |
+| `--agent` | boolean | no | 经办人认证（与 `auth indiv --agent` 对应） |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding auth code --flow-id FLOW20260831001 --auth-code 123456
+```
+
+```bash
+fmc onboarding auth code --flow-id FLOW20260831001 --auth-code 123456 --agent -y
+```
+
+#### Output (text mode)
+
+```
+  ✔ 验证码校验通过
+```
+
+---
+
+### `fmc onboarding auth organ`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding auth organ` |
+| **Description** | 发起企业实名认证 |
+| **Usage** | `fmc onboarding auth organ --name <name> --cert-number <no> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+前置条件：经办人已通过 `auth indiv --agent` + `auth code --agent` 完成个人实名。
+若返回后 `auth schedule` 显示"待对公打款验证"，用 `auth remit` 收尾。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--name <name>` | string | yes | 企业名称 |
+| `--cert-number <no>` | string | yes | 统一社会信用代码 |
+| `--cert-type <type>` | string | no | 证件类型 |
+| `--agent-account-id <id>` | string | no | 经办人账号 ID |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding auth organ --name 深圳市某某科技有限公司 \
+  --cert-number 91440300MA5XXXXXXX
+```
+
+#### Output (text mode)
+
+```
+  ✔ 已发起企业实名认证
+
+  待对公打款验证时，用 auth remit --flow-id <flowId> --amount <分> 完成
+```
+
+---
+
+### `fmc onboarding auth gat`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding auth gat` |
+| **Description** | 提交港澳台 / 海外客户实名资料，进入人工审核 |
+| **Usage** | `fmc onboarding auth gat --customer-profile <code> --entity <code> --name <name> --mobile <mobile> --email <email> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+港澳台与海外客户不走线上实名，提交资料后进入人工审核，**无法加速**；用
+`onboarding progress` / `onboarding auth schedule` 查进度。中国大陆客户请用 `auth indiv`。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--customer-profile <code>` | string | yes | 客户类型：`1` 港澳台、`2` 海外 |
+| `--entity <code>` | string | yes | 经济主体：`1` 个人、`2` 企业 |
+| `--name <name>` | string | yes | 个人姓名或企业名称 |
+| `--mobile <mobile>` | string | yes | 手机号 |
+| `--email <email>` | string | yes | 邮箱 |
+| `--contact-name <name>` | string | no | 联系人姓名（企业） |
+| `--legal-person <name>` | string | no | 法人姓名（企业） |
+| `--cert-number <no>` | string | no | 企业证件号（企业） |
+| `--country <name>` | string | no | 国家名称 |
+| `--country-code <code>` | string | no | 国家编码 |
+| `--alpha2-code <code>` | string | no | 国家二字码 |
+| `--state <name>` | string | no | 省 |
+| `--state-code <code>` | string | no | 省编码 |
+| `--city <name>` | string | no | 市 |
+| `--city-code <code>` | string | no | 市编码 |
+| `--county <name>` | string | no | 区 / 县 |
+| `--county-code <code>` | string | no | 区 / 县编码 |
+| `--address <address>` | string | no | 详细地址 |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 香港个人客户
+fmc onboarding auth gat --customer-profile 1 --entity 1 \
+  --name CHAN TAI MAN --mobile 85298765432 --email chan@example.com \
+  --country 中国香港 --alpha2-code HK --address "Kwun Tong, Kowloon"
+```
+
+```bash
+# 海外企业客户
+fmc onboarding auth gat --customer-profile 2 --entity 2 \
+  --name "Example Trading LLC" --mobile 12025550123 --email ops@example.com \
+  --contact-name "John Smith" --legal-person "John Smith" \
+  --country 美国 --alpha2-code US --state California --city "Los Angeles" \
+  --address "123 Main St" -y
+```
+
+#### Output (text mode)
+
+```
+  ✔ 资料已提交，进入人工审核队列
+
+  人工审核无法加速，用 progress / auth schedule 查看进度
+```
+
+---
+
+### `fmc onboarding auth remit`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding auth remit` |
+| **Description** | 校验企业对公打款金额 |
+| **Usage** | `fmc onboarding auth remit --flow-id <id> --amount <cents> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+金额单位是**分**，不是元——传 `1` 表示 1 分。校验有重试次数限制，填错会消耗次数，
+所以确认后再提交。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--flow-id <id>` | string | yes | 认证流程 ID |
+| `--amount <cents>` | string | yes | 打款金额，单位：分 |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 收到 0.37 元打款 → 传 37
+fmc onboarding auth remit --flow-id FLOW20260831001 --amount 37
+```
+
+#### Output (text mode)
+
+```
+  ✔ 打款金额校验通过
+```
+
+---
+
+### `fmc onboarding brand list`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding brand list` |
+| **Description** | 查询可开通品牌及支持的认证方式 |
+| **Usage** | `fmc onboarding brand list [flags]` |
+
+需要 API Key 认证。`brand open` 的 `--service-code` 从这里取。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--customer-type <code>` | string | no | 客户类型（`0` 大陆、`1` 港澳台、`2` 海外），默认当前客户类型 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding brand list
+```
+
+```bash
+fmc onboarding brand list --customer-type 1 --output json
+```
+
+#### Output (text mode)
+
+```
+可开通品牌与认证方式
+────────────────────────────────────────────────────────────
+
+  DSS  递四方直发
+    介绍        跨境直发物流服务
+    认证方式    0(个人认证)  1(企业认证)
+
+  FPX  递四方专线 [不可选]
+    介绍        需线下签约
+```
+
+---
+
+### `fmc onboarding brand open`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding brand open` |
+| **Description** | 开通物流品牌并申请合同 |
+| **Usage** | `fmc onboarding brand open --service-code <code> --country <name> --address <addr> --customer-name <name> --contact-name <name> --mobile <mobile> --email <email> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+前置条件：中国大陆客户且已完成实名认证。开通后合同即进入申请流程，
+用 `contract list` / `contract url` 继续。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--service-code <code>` | string | yes | 品牌编码（如 `DSS`，从 `brand list` 获取） |
+| `--country <name>` | string | yes | 国家（如：中国） |
+| `--address <address>` | string | yes | 详细地址 |
+| `--customer-name <name>` | string | yes | 客户名称 |
+| `--contact-name <name>` | string | yes | 联系人姓名 |
+| `--mobile <mobile>` | string | yes | 手机号 |
+| `--email <email>` | string | yes | 邮箱 |
+| `--customer-type <code>` | string | no | 客户类型 |
+| `--state <name>` | string | no | 省 |
+| `--city <name>` | string | no | 市 |
+| `--county <name>` | string | no | 区 / 县 |
+| `--legal-name <name>` | string | no | 企业法人姓名（企业客户必填） |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding brand open --service-code DSS \
+  --country 中国 --state 广东省 --city 深圳市 --county 南山区 \
+  --address "科技园某某大厦 1001" \
+  --customer-name 深圳市某某科技有限公司 --legal-name 张三 \
+  --contact-name 李四 --mobile 13800138000 --email ops@example.com
+```
+
+#### Output (text mode)
+
+```
+  ✔ 品牌开通与合同申请已提交
+
+  用 contract list 查看合同，contract url <合同编号> 获取签署链接
+```
+
+---
+
+### `fmc onboarding contract list`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding contract list` |
+| **Description** | 查询 DSS 直发品牌的合同列表 |
+| **Usage** | `fmc onboarding contract list [flags]` |
+
+需要 API Key 认证。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--page <num>` | number | no | 页码，默认 1 |
+| `--size <num>` | number | no | 每页数量，默认 10，最大 100 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding contract list
+```
+
+```bash
+fmc onboarding contract list --page 2 --output json
+```
+
+#### Output (text mode)
+
+```
+合同列表
+────────────────────────────────────────────────────────────
+
+  CT20260801001
+    合同名称    递四方直发服务合同
+    品牌        递四方直发
+    客户        深圳市某某科技有限公司
+    状态        待签署 (1)
+    有效期      2026-09-01 ~ 2027-08-31
+    申请时间    2026-08-01 11:05:00
+
+  共 1 份合同
+```
+
+合同状态：`0` 草稿、`1` 待签署、`2` 已过期、`3` 驳回、`4` 签署中、`6` 拒签、
+`7` 已归档、`8` 拒签-已重新签署、`9` 已撤销、`10` 待授权、`12` 审核中。
+
+---
+
+### `fmc onboarding contract url`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding contract url` |
+| **Description** | 获取合同签署链接或下载链接 |
+| **Usage** | `fmc onboarding contract url <contractCode> [flags]` |
+
+需要 API Key 认证。
+
+签署中的合同返回**签署链接**，其余状态返回**下载链接**。每次调用都会生成新链接，
+**请勿频繁调用**。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<contractCode>` | string | yes | 合同编号（从 `contract list` 获取） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding contract url CT20260801001
+```
+
+```bash
+fmc onboarding contract url CT20260801001 --output json
+```
+
+#### Output (text mode)
+
+```
+合同链接
+──────────────────────────────────────────────────
+  合同编号    CT20260801001
+  链接        https://esign.example.com/sign/abc123
+
+  签署中的合同返回签署链接，其余状态返回下载链接；请勿频繁调用
+```