# 统一接收分发中转接口设计文档

---

> **维护说明（重要）**：
> 本文档是**面向三方系统对接**的统一中转 API 规范，只描述对外接口契约（请求/响应信封、路由规则、Data 业务字段、响应格式等），**不含各落地仓库的内部实现细节**（状态机、数据库结构、RPA 交互、内部端点等）。
> 其他项目 / 仓库在更新本文档时，**只允许补齐第 4 点（Data 业务字段结构）中的 data 数据字段及说明**，不得新增或维护落地实现章节。

---

## 1. 概述

### 1.1 设计目标

构建一个**国家无关**的接收分发中转接口：接收来自 SaaS 系统的推送请求，根据 `Country` + `PushType` 自动路由到对应国家的处理逻辑，完成文件生成 / 状态更新等操作后返回统一格式响应。

**核心架构：**

```
SaaS 系统
   │ POST 请求
   ▼
api.php（新增：统一中转入口 + 路由）
   │
   ├── 参数校验（ / Country / PushType / Data ）
   ├── 加载 countries/{Country}.php
   ├── 调用 {PushType} 方法
   │
   ▼
国家处理类（de.php / fr.php / be.php / gb.php / it.php ...）
   │
   ├── 调用外部 API（INSEE / ERIC / Playwright ...）
   ├── 生成文件 → 上传 OSS → 更新 DB
   │
   ▼
Response::json() → 统一 JSON 返回 SaaS
```

### 1.2 技术选型

| 项目     | 选型                                                 |
| -------- | ---------------------------------------------------- |
| 数据库   | SQL Server（PDO）                                    |
| 路由方式 | `Country` 类 + `{PushType}` 方法动态调用             |
| 响应格式 | JSON（`{code, msg, data}`）                          |
| 架构模式 | 接收-分发-中转（Relay Pattern）                      |

---

## 2. 接口规格

### 2.1 基本信息

| 项目           | 值                                                         |
| -------------- | ---------------------------------------------------------- |
| **接口名称**   | 统一接收分发中转接口                                       |
| **请求方式**   | POST                                                       |
| **Content-Type** | application/json            |
| **入口文件**   | `api.php`      |
| **本地测试**   | `http://rpa.test.fix.usaeu.com/app_withdrawn/api.php`     |
| **生产地址**   | `http://rpa.fix.usaeu.com/app_withdrawn/api.php`          |

### 2.2 请求参数

| 参数       | 类型   | 必填 | 说明                                                         |
| ---------- | ------ | ---- | ------------------------------------------------------------ |
| `PushType` | string | 是   | 推送类型（国家__业务大类__业务小类，直接作为方法名，如 `DE_VAT_REGISTER_FILE`） |
| `Country`  | string | 是   | 国家二字码（DE / FR / BE / GB / IT ...）                     |
| `Data`     | object | 否   | 业务数据（**扁平业务字段**：键为业务字段名，见 [4. Data 结构](#4-data-业务字段结构)；兼容旧格式 `modules` + `formInfo`） |
| `files`    | array  | 否   | 文件生成结果数组（**注册受理专用**，如 `DE_VAT_REGISTER` / `FR_VAT_REGISTER` / `IT_VAT_REGISTER_ANR3` / `BE_EPR_REGISTER_PACK`，由文件生成流程回填或 SaaS 直接提供）：每项含 `url`（OSS 相对路径）/`name`（文件名）/`type`（见 §5.2）/`pushType`（生成来源）；**直接落库不再下载上传**。德国=五合一文件（`N_IN_ONE_FILE`），法国=5 类自动生成 PDF（`AUTHORIZATION_LETTER` 等英文枚举），意大利 ANR3=税号证书 PDF（`TAX_CERTIFICATE`，下游下载后 OCR 提取），比利时 EPR=授权书 `MANDAT` + 会员合同 `MEMBERSHIP` |
| `bizParam` | object | 否   | 业务标识信息（顶层，与 `PushType`/`Country`/`Data` 同级），原样回传。字段要求按 PushType 确定；不得把其他流程的文件命名或防重字段套用于法国流程 |

**请求体示例（扁平业务字段）：**

```json
{
  "PushType": "DE_VAT_REGISTER_FILE",
  "Country": "DE",
  "bizParam": {
    "BusinessSerialNumber": "DVAT12312312312312313",
    "BusinessId": 123456,
    "projectId": 1
  },
  "Data": {
    "NameCN": "枝江市霞陆逊商贸有限公司",
    "NameEng": "zhijiangshixialuxunshangmaoyouxiangongsi",
    "RegNumber": "91420583MADDMTJE7M",
    "LegalPersonName": "刘振华",
    "LegalPersonIdNumber": "510681198706252865",
    "BusinessLicensePic": "[{\"fileUrl\":\"common-test/2026/08/06/019baf3f-801e-45aa-bf6d-a80c2b07e15d.jpg\",\"fileName\":\"DownAnnexesFileByFileUrl.jpg\"}]",
    "StoreFBAAcitveSetSetScreenShot": "[{\"fileUrl\":\"common-test/2026/08/07/8388e6e0-87fd-4bd0-b881-392fbd7d6bb2.png\",\"fileName\":\"4359bc31121b45fd974bf91f0e1dff1b.png\"}]"
  }
}
```

### 2.3 响应格式

**sync 模式成功响应（实时处理，直接返回文件相对路径）：**

```json
{
    "code": 200,
    "msg": "成功",
    "data": {
        "files": [
            {
                "url": "common-test/generatefile/2026/de_declar_delay/DEV2026081417170019_395_alle Anhänge in einem Dokument.pdf",
                "name": "DEV2026081417170019_395_alle Anhänge in einem Dokument.pdf",
                "type": "N_IN_ONE_FILE"
            }
        ]
    },
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": 123456
    }
}
```

> `data` 为**对象** `{files}`：`files` 为文件数组，每项含 `url`（OSS 相对路径）、`name`（文件名）、`type`（文件类型枚举，见 [5.2 文件类型枚举](#52-文件类型枚举)）；无文件时 `files` 返回空数组 `[]`。
>
> DE_VAT_REGISTER_FILE（德国VAT注册五合一文件生成）最终**只返回一个文件（`type=N_IN_ONE_FILE`）**，中间处理文件（授权书/营业执照/身份证/邮件授权/截图）不上传。
>
> `url` 返回 **OSS 相对路径（不含域名）**，域名由 SaaS 侧拼接，完整 URL 形如 `https://usaeu-1259285998.cos.ap-guangzhou.myqcloud.com/{相对路径}`。路径前缀由 `New_OSSDelay_FILE_PATH` 配置决定（测试：`common-test/generatefile/2026/de_declar_delay/`，生产：`common/generatefile/2026/de_declar_delay/`）。
>
> `bizParam` 为**请求原样回传**（请求顶层 `bizParam`，兼容 `Data.bizParam`），不管里面有多少个字段均原样返回；其字段用途按 PushType 定义：例如 DE 文件命名可使用 `BusinessSerialNumber`/`BusinessId`；FR-LEKO 仅因现有 OSS 目录需要 `BusinessSerialNumber`，FR-CITEO 当前无固定必填子字段。

**async 模式成功响应（异步受理，`data` 为 `null`，文件生成完成后另行通知/查询获取）：**

```json
{
  "code": 200,
  "msg": "success",
  "ProcessMode": "async",
  "data": null,
  "bizParam": {
    "BusinessSerialNumber": "DVAT12312312312312313",
    "BusinessId": 123456
  }
}
```

**注册受理成功响应（DE_VAT_REGISTER / FR_VAT_REGISTER，数据落库，`data` 为落库结果对象）：**

```json
{
  "code": 200,
  "msg": "插入记录成功",
  "data": null,
  "bizParam": {
    "BusinessSerialNumber": "DVAT12312312312312313",
    "BusinessId": 123456
  }
}
```

> 注册受理由转发层（de.php / fr.php）透传到各仓库 `server/vat_new_register_auto.php`，**ProcessMode 默认 `async`**（受理即返回，供 RPA 门户注册消费）；`data` 为null`，`bizParam` 原样回传；注册完成后 RPA 侧按阶段回调 SaaS 统一结果通知接口（见 §14）。
>
> 幂等：同一业务单号（德国 `bizParam.BusinessSerialNumber`，法国 `Data.Code`）重复推送时更新已有记录；德国版对已成功（`status=2`）记录直接跳过。
>
> 受理失败返回 `code=400`（校验错误分号拼接），`data=null`。

**失败响应：**

```json
{
  "code": 400,
  "msg": "缺少必需参数：PushType",
  "data": null,
  "bizParam": {
        "BusinessSerialNumber": "DEV2026081417170019",
        "Businessld": 395,
        "deliveryId": 1
    }
}
```

### 2.4 状态码说明

| code | 含义                       | 示例                                          |
| ---- | -------------------------- | --------------------------------------------- |
| 200  | 请求成功                   | 文件生成完成                       |
| 400  | 请求参数错误 / 业务处理失败 | 缺少参数 / 国家不支持 / 当前状态不允许操作    |
| 500  | 服务器内部错误             | 数据库连接失败 / 国家类加载异常               |

### 2.5 路由规则

```
方法名 = PushType
命名格式：{国家二字码}_{业务大类}_{REGISTER(注册还是申报)}_{业务小类}_{业务细分小类}
后缀约定：
  - 末尾带 _FILE        → 自动生成文件（生成文件并上传 OSS，本系统处理）
  - 末尾不带 _FILE      → 去门户网站自动注册（RPA 直接操作门户网站完成注册/申报）

示例:
  PushType="DE_VAT_REGISTER_FILE" → 德国 VAT 注册（自动生成文件）
  PushType="DE_VAT_REGISTER"      → 德国 VAT 注册（门户网站自动注册）
  PushType="DE_EPR_REGISTER_PACK_FILE" → 德国 EPR 包装法注册（自动生成文件）
  PushType="DE_EPR_REGISTER_PACK"      → 德国 EPR 包装法注册（门户网站自动注册）
```

入口 `api.php`自动：
1. 加载 `countries/{Country}.php`
2. 实例化类
3. 调用对应方法（方法名 = PushType）
4. 返回结果

---

## 3. PushType 枚举（方法名）

`PushType` 即方法名，格式为 `{国家二字码}_{业务大类}_{REGISTER(注册还是申报)}_{业务小类}_{业务细分小类}` 往后拼接。

**命名段说明：**

| 段 | 取值示例 | 说明 |
| --- | --- | --- |
| `{国家二字码}` | `DE` / `FR` / `ES` / `IT` / `BE` / `SE` | 国家二字码 |
| `{业务大类}` | `VAT` / `EPR` | 业务大类 |
| `{REGISTER(注册还是申报)}` | `REGISTER` / `DECLARE` | 注册或申报 |
| `{业务小类}` | `PACK` / `WEEE` / `HAGUE` / `LEKO` / `CITEO` / `REFASHION` | 业务小类（可省略） |
| `{业务细分小类}` | `CONTRACT` / `030` | 业务细分小类（可省略） |
| 后缀 `_FILE` | `_FILE` | **加 `_FILE` = 自动生成文件**；**不加 = 去门户网站自动注册** |

> **后缀约定**：`PushType` 末尾带 `_FILE` 表示「自动生成文件」流程（生成 PDF/DOCX 并上传 OSS 后回传 URL）；不带 `_FILE` 表示「门户网站自动注册」流程（RPA 登录门户网站完成注册/申报）。同一业务可有 `_FILE` 与不带 `_FILE` 两个 PushType 并存。

### 3.1 自动生成文件（带 `_FILE`）

| PushType | 说明 |
| --- | --- |
| `DE_VAT_REGISTER_FILE` | 德国 VAT 注册五合一文件生成（返回 1 个文件：`N_IN_ONE_FILE`） |
| `FR_VAT_REGISTER_FILE` | 法国 VAT 注册生成文件（返回 5 个文件：`AUTHORIZATION_LETTER` / `COMPANY_ARTICLES_ORIGINAL` / `ID_CARD_MERGED` / `BUSINESS_LICENSE_MERGED` / `ARTICLES_TRANSLATION`） |
| `SE_EPR_REGISTER_PACK_FILE` | 瑞典 EPR 包装法文件生成（POA 授权书 + 中国公司营业执照合并件 → vat_api_se_client/server/se_new_epr_pack_auto_file_api.php，接口取数模式替代原 server/epr_auto_file.php 直连 SaaS 库，见 §4.4.18） |
| `BE_EPR_REGISTER_PACK_FILE` | 比利时 EPR 包装法文件生成（POA 授权书 + FostPlus 会员合同 → vat_api_se_client/server/be_new_epr_pack_auto_file_api.php，接口取数模式替代原 server/be_epr_pack_auto_file.php 直连 SaaS 库） |
| `AT_EPR_REGISTER_PACK_FILE` | 奥地利 EPR 注册文件生成（授权书 → vat_api_se_client/server/at_new_epr_pack_auto_filer_api.php，接口取数模式替代原 job/at_epr_pack_auto_file.php 直连 SaaS 库，按契约回写 SaaS 状态 6/7） |
| `FR_EPR_REGISTER_WEEE_FILE` | 法国 EPR 的 WEEE 注册（授权书 + EPR_Ecologic 注册数据 CSV → vat_api_fr_client/server/new_epr_weee_file_api.php，**接口取数模式**替代原 server/epr_weee_query_api.php 直连 SaaS 库，见 §4.4.20） |
| `FR_EPR_REGISTER_WEEE_CONTRACT_FILE` | 法国 EPR 的 WEEE 添加合同注册（授权书 + EPR_Ecologic 添加合同 CSV → vat_api_fr_client/server/new_epr_weee_contract_file_api.php，**接口取数模式**替代原 server/epr_weee_contract_api.php 直连 SaaS 库，见 §4.4.21） |
| `FR_EPR_REGISTER_PACK_FILE` | 法国包装注册文件 |
| `FR_EPR_REGISTER_电气_FILE` | 法国电气注册文件（后缀待改英文） |
| `ES_EPR_REGISTER_HAGUE_FILE` | 西班牙 EPR 海牙文件生成（盖章要求/海牙待认证/APODERAMIENTO/030） |
| `ES_EPR_REGISTER_030_FILE` | 西班牙 EPR030 文件生成（030文件） |
| `ES_VAT_REGISTER_HAGUE_FILE` | 西班牙 VAT 海牙文件生成（海牙待认证/030） |
| `IT_EPR_REGISTER_FILE` | 意大利 EPR 注册文件生成 |
| `FR_EPR_REGISTER_LEKO_FILE` | 法国 LEKO 注册文件生成（LEKO/POA） |
| `FR_EPR_REGISTER_CITEO_FILE` | 法国 CITEO 注册文件生成（POA） |
| `FR_EPR_REGISTER_REFASHION_FILE` | 法国纺织法注册文件生成（POA） |

### 3.2 门户网站自动注册（不带 `_FILE`）

| PushType | 说明 |
| --- | --- |
| `DE_VAT_REGISTER` | 德国 VAT 注册（门户自动注册受理 → vat_new_register_auto.php；请求须携带顶层 `files` 五合一文件） |
| `DE_VAT_APPLICATION_DELAY` | 德国 VAT 申报延缓（门户自动申报受理 → vat_new_Application_Delay.php；月报自动生成延缓申报确认函 PDF 并上传 OSS，**接口取数模式**替代原 job 直连 SaaS 库） |
| `DE_EPR_REGISTER_PACK` | 德国 EPR 包装法注册（门户自动注册受理 → de_new_epr_pack_register_api.php，落库 pack_de_register `pack_type=0`；注册邮箱受理时自动创建/沿用，**接口取数模式**替代原 job 直连 SaaS 库） |
| `BE_EPR_REGISTER_PACK` | 比利时 EPR 包装法注册（门户自动注册受理 → be_new_epr_pack_register_api.php，落库 pack_be_register；请求须携带顶层 `files`，type=MANDAT 授权书 + type=MEMBERSHIP 会员合同，**接口取数模式**替代原 job 直连 SaaS 库） |
| `DE_EPR_CANCEL_PACK` | 德国 EPR 包装法注销（门户自动注销受理 → de_new_epr_pack_cancel_api.php，落库 pack_de_register `pack_type=1`；关联注册记录字段由调用方直接传入，**接口取数模式**替代原 job 直连 SaaS 库） |
| `FR_VAT_REGISTER` | 法国 VAT 注册（门户自动注册受理 → vat_new_register_auto.php；请求须携带顶层 `files` 5 类自动生成 PDF） |
| `IT_VAT_REGISTER_AA7` | 意大利 VAT 注册（AA7 税表，门户自动注册受理 → vat_api_it_client 接口；请求须携带 Data 完整业务字段，**接口取数模式**替代原 job 直连 SaaS 库） |
| `IT_VAT_REGISTER_ANR3` | 意大利 VAT 注册（ANR3 税表，欧盟公司，门户自动注册受理 → vat_api_it_client 接口；请求须携带顶层 `files` 税号证书 PDF，下游下载后 OCR 提取） |
| `FR_EPR_REGISTER_WEEE` | 法国 EPR 的 WEEE 注册（门户网站自动注册） |
| `IT_EPR_REGISTER` | 意大利 EPR 注册（门户网站自动注册） |

> 其余业务如需门户网站自动注册，按同样命名规则去掉 `_FILE` 后缀即可；门户注册类 PushType 由 RPA 直接操作门户网站完成，不生成文件。
>
> 差不多就是这样子往后拼接就好了。

---

## 4. Data 业务字段结构

### 4.1 结构概述

`Data` 为**扁平业务字段对象**：键为业务字段名（与 `vat_query_api.php` 的 DEVAT_Register / Base_Customer_Company 字段名一致），值为字段值。文件类字段的值为 JSON 数组字符串（推荐）或原生 JSON 数组，两种格式均可，含 `fileUrl`（OSS 相对路径）+ `fileName`。

```
Data
├── 普通字段   { 业务字段名: 值 }                       例: "NameCN": "枝江市霞陆逊商贸有限公司"
├── 文件字段   { 业务字段名: "[{fileUrl,fileName}]" 或 [{fileUrl,fileName}] }   例: "BusinessLicensePic": "[{\"fileUrl\":...,\"fileName\":...}]"
└── 数组字段   { 业务字段名: [值,...] }                 例: "RegisteredCapitalCurrency": ["1","2"]
```

> **兼容旧格式**：若 `Data` 携带 `modules` + `formInfo`（动态表单 GUID 结构），接口按 GUID → 业务字段映射兼容解析（代码 `buildDataFromFormLegacy`）。

### 4.2 字段类型

| 类型 | 值格式 | 说明 |
| ---- | ------ | ---- |
| 普通字段 | `"string"` / `"1"` / `"2024-03-22"` | 直接作为业务字段值 |
| 数组字段 | `["1","2"]` | 以逗号连接后使用（如注资币种） |
| 文件字段 | `"[{\"fileUrl\":\"...\",\"fileName\":\"...\"}]"` 或 `[{"fileUrl":"...","fileName":"..."}]` | JSON 数组字符串或原生 JSON 数组（两种格式均可），含 `fileUrl`（OSS 相对路径）+ `fileName` |

### 4.3 文件类字段清单

| 业务字段名 | 用途 |
| ---------- | ---- |
| `BusinessLicensePic` | 工商营业执照 |
| `LegalPersonIdNumberFrontPic` | 证件正面照 |
| `LegalPersonIdNumberBackPic` | 证件反面照 |
| `LegalSignedFile` | 上传签名文件 |
| `StoreFBAAcitveSetSetScreenShot` | FBA 开启截图 |
| `StoreWarehouseAddressScreenShot` | 仓库地址截图 |
| `StoreOtherSetScreenShot` | 店铺其他截图 |
| `StoreOverseaWarehouseContract` | 海外仓合同 |
| `StoreSellerProfileScreenShot` | 店铺主页截图 |
| `UploadFile1` | 英国 VAT 注册：法人证件（文件名含 passport/identity card/drive license，必填）→ 落库 `upload_file_path1` |
| `UploadFile2` | 英国 VAT 注册：支持文件 1（文件名含 bank statement/credit card statement/electricity bill 等关键词，首个匹配）→ 落库 `upload_file_path2` |
| `UploadFile3` | 英国 VAT 注册：支持文件 2（文件名含支持文件关键词的次个匹配，仅在存在第二个支持文件时传，非必填）→ 落库 `upload_file_path3` |

### 4.4 Data 业务字段说明（通用总表）

> 字段**只增不减**，所有国家 / 流程共用（括号标注适用流程：DE=德国 VAT、ES=西班牙海牙、FR-LEKO=法国 LEKO、FR-CITEO=法国 CITEO，未标注为通用字段）。**字段名不允许更改，只允许修改说明信息**。
>
> 本总表汇总多个国家和流程，表内“必填”不代表每个 PushType 都要求该字段。法国 LEKO/CITEO 必须以紧随其后的法国专属最小字段表和 §4.4.7/§4.4.8 为准，不继承 DE/ES/IT 的必填字段。
>
> **受理落库公共约定（各 vat_api_* server 的 new 受理接口，见 §4.4.10~4.4.13 / §4.4.15~4.4.17）**：落库记录统一携带 `is_new=1`（1-新 SaaS 走接口推送，区别于 0-老 SaaS 直连库的 job 记录）与 `saas_request`（本次接口请求的完整 JSON，供审计 / 重放 / 问题排查）。

**法国 LEKO/CITEO 最小字段表（覆盖通用总表的必填标记）：**

| 流程 | 固定 Data | 条件 Data | bizParam |
| ---- | ---- | ---- | ---- |
| `FR_EPR_REGISTER_LEKO` | `NameEng`、`RegAddressEng`、`CompanyAddressLine1En`、`CompanyAddressPostcode`、`CityEngName`、`CountryTwoCode`、`RegNumber`、`LegalPersonFullNamePinYin`、`LegalPersonEmail`、`LegalPersonPhone`、`LegalPersonGender` | CN：`AreaName`；FR：`RegisteredCapital`、`RegisteredCapitalCurrency`；EU：`VATNumber` | 对象必传；仅 `BusinessSerialNumber` 必填 |
| `FR_EPR_REGISTER_CITEO` | `NameEng`、`CountryTwoCode`、`CityEngName`、`RegAddressEng`、`LegalPersonFullNamePinYin` | EU 且非 FR：`VATNumber`；其他国家：`RegNumber` | 对象必传；无固定必填子字段 |

> `InseeLegalForm`、`InseeNafCode`、`InseeSiret` 不在 Data 请求字段中；法国 LEKO 的对应值由服务端 INSEE 查询派生。`CompanyAddressLine2En` 不参与当前法国文件生成。其他字段即使作为扩展信息传入，也不参与本次法国文件内容、INSEE 查询或校验。

**公司信息：**

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `NameCN` | 字符串 | 是 | 企业中文名称 |
| `NameEng` | 字符串 | 是 | 企业英文全称（不能含中文；FR-LEKO 最长 50 个字符） |
| `RegNumber` | 字符串 | 条件必填 | 营业执照号码；ES 香港公司豁免；FR-LEKO 必填；FR-CITEO 在非欧盟公司或法国公司时必填 |
| `RegisteredCapital` | 字符串 | 条件必填 | 注册资本；FR-LEKO 且公司国家二字码为 `FR` 时必填 |
| `RegisteredCapitalCurrency` | 数组/字符串 | 条件必填 | 注资币种（如 `["1","2"]`）；FR-LEKO 且公司国家二字码为 `FR` 时必填 |
| `EstablishmentDate` | 日期 | 否 | 成立日期（YYYY-MM-DD） |
| `CityEngName` | 字符串 | 是 | 公司所在城市（英文）；FR-LEKO/FR-CITEO 生成时去除末尾“市”或 `shi` |
| `RegAddressEng` | 字符串 | 是 | 注册地址（英文，不能含中文）；FR-LEKO/FR-CITEO POA 模板输入 |
| `CompanyAddressLine1En` | 字符串 | 条件必填 | 公司地址第一行（英文）；FR-LEKO 必填且最长 100 个字符 |
| `CompanyAddressLine2En` | 字符串 | 否 | 公司地址第二行（英文）（ES/FR-LEKO 可选存档） |
| `CompanyAddressPostcode` | 字符串 | 条件必填 | 公司地址邮编；FR-LEKO 必填 |
| `CompanyAddressProvinceEn` | 字符串 | 是 | 公司地址省份（英文）（ES） |
| `CompanyCountry` | 字符串 | 是 | 公司所在国家（**国家二字码**，如 `CN`/`HK`）；与 `Country` 语义不同、独立必填，**不互为兜底**；**不参与香港公司判定**（即使为 `HK` 也不影响判定）；中文名/英文名由系统按国家数据字典解析，找不到对应国家报数据错误（ES） |
| `Country` | 字符串 | 是 | 公司注册国家（**国家二字码**，如 `CN`/`HK`）；**公司类型判定字段**：`HK`=香港公司（海牙流程），非 `HK`（如 `CN`）=大陆公司；DE/FR/GB/IT 流程以此标识公司国家；ES 流程与 `CompanyCountry` 独立必填（2026-08-29 起不再兼容二者取其一），**判定仅认本字段，缺失或为空时不兜底 `CompanyCountry`**；中文名/英文名由系统按国家数据字典解析，找不到对应国家报数据错误（ES） |
| `AreaName` | 字符串 | 条件必填 | 公司省份/州；FR-LEKO 的 `CountryTwoCode=CN` 时必填，`HK` 服务端统一使用 `香港`，其他非 CN/HK 国家缺省使用大写国家二字码 |
| `LocalTaxNumber` | 字符串 | 否 | 本土税号（DE） |
| `VATNumber` | 字符串 | 条件必填 | VAT 税号；FR-LEKO 在欧盟国家时必填；FR-CITEO 在欧盟国家且国家不为 `FR` 时必填并作为 BusinessLicenseNo；ES 可缺省为空串 |
| `ExpectedSalesYear1` | 字符串 | 否 | 注册后第一年预计销售额（欧元）（DE） |
| `ExpectedSalesYear2` | 字符串 | 否 | 注册后第二年预计销售额（欧元）（DE） |
| `DELogisticsSituation` | 字符串 | 否 | 海外仓详细地址（DE） |
| `ProductsRange` | 字符串 | 否 | 产品销售类型（DE）；兼容旧字段名 `ProductsRange` |
| `BusinessPlatform_En` | 字符串 | 否 | 销售平台（1=亚马逊，2=速卖通，3=EBAY）（DE） |
| `ShopName` | 字符串 | 否 | 店铺名称（DE） |
| `ShopUrl` | 字符串 | 否 | 店铺链接（DE） |
| `ShopAccount` | 字符串 | 否 | 店铺 Seller ID(Token)（DE） |
| `SignatureDate` | 日期 | 否 | 签发日期（YYYY-MM-DD）（DE） |

**法人信息：**

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `LegalPersonName` | 字符串 | 是 | 法人中文姓名 |
| `LegalPersonNamePinyin` | 字符串 | 条件必填 | 法人英文名（拼音，不能含中文）；与 `LegalPersonSurnamePinyin` 拆分自旧字段 `LegalPersonFullNamePinYin`；FR-LEKO/FR-CITEO 用于模板和自动签名；ES 海牙必填。**法人拼音兼容（各 vat_api_* server 的 new 受理/文件接口）**：请求优先传旧全名 `LegalPersonFullNamePinYin`（兼容旧调用方，原样采纳）；未传时服务端按「名 姓」拼接（`LegalPersonNamePinyin` + `LegalPersonSurnamePinyin`，如 `ZHENHUA` + `LIU` → `ZHENHUA LIU`），保证旧字段下游/校验/签名可用 |
| `LegalPersonSurnamePinyin` | 字符串 | 条件必填 | 法人英文姓（拼音，不能含中文）；与 `LegalPersonNamePinyin` 拆分自旧字段 `LegalPersonFullNamePinYin`；FR-LEKO/FR-CITEO 用于模板和自动签名；ES 海牙必填。**法人拼音兼容（各 vat_api_* server 的 new 受理/文件接口）**：请求优先传旧全名 `LegalPersonFullNamePinYin`（兼容旧调用方，原样采纳）；未传时服务端按「名 姓」拼接（`LegalPersonNamePinyin` + `LegalPersonSurnamePinyin`），保证旧字段下游/校验/签名可用 |
| `LegalPersonEmail` | 字符串 | 条件必填 | 法人邮箱；FR-LEKO 必填 |
| `LegalPersonPhone` | 字符串 | 条件必填 | 法人手机号码；FR-LEKO 必填，写入 LEKO XLSX 时移除 `+` 并将连字符替换为空格 |
| `LegalPersonGender` | 字符串 | 条件必填 | 性别；FR-LEKO 必填，`2` 映射为 `MRS`，其他值映射为 `MR`；ES 兼容 `1`/`男`/`H`/`HOMBRE` 与 `2`/`女`/`M`/`MUJER`，受理时规范化为 `H`(男)/`M`(女) |
| `Nationality` | 字符串 | 否 | 民族（`1`=汉 HAN，`2`=回 HUI），身份证翻译件使用 |
| `LegalPersonIdNumber` | 字符串 | 是 | 证件号码 |
| `LegalPersonIdStartDate` | 日期 | 是 | 证件有效期开始时间（YYYY-MM-DD） |
| `LegalPersonIdEndDate` | 日期 | 是 | 证件有效期截止时间（YYYY-MM-DD） |
| `LegalPersonIDCardType` | 字符串 | 是 | 法人证件类型：`1`/`身份证`/`IDCard` → `IDCard`；`2`/`护照`/`Passport` → `Passport`（受理时规范化）（ES） |
| `LegalPersonCountry` | 字符串 | 是 | 法人国籍（国家二字码，如 `CN`；ES 流程由系统按国家数据字典解析中文名/英文名，找不到对应国家报数据错误） |
| `LegalPersonAddressPostcode` | 字符串 | 是 | 法人地址邮箱 |
| `LegalPersonBirthDate` | 日期 | 是 | 法人出生日期（YYYY-MM-DD） |
| `LegalPersonCityEngName` | 字符串 | 是 | 法人所在城市（英文） |
| `LegalPersonAddressProvinceEn` | 字符串 | 是 | 法人地址省份（英文）（ES） |
| `LegalPersonIDCardAddress` | 字符串 | 否 | 证件地址（中文原值，与 `LegalPersonIDCardAddressEng` 二选一） |
| `LegalPersonIDCardAddressEng` | 字符串 | 否 | 证件地址（拼音/英文） |

**流程控制：**

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `AR` | 字符串 | 是 | 授权机关模板：`M`=原模板，`O`=Onesea模板（ES；海牙授权书与 030 文件模板选择共用） |
| `SpecsName` | 字符串 | 否（无需传） | es_haiya 的产品规格名称（含"免海牙"触发免海牙流程）；**本系统无免海牙流程，该字段无需传、传了也忽略**——本系统 SpecsName 为内部数值字段（source 流程 = GeneralTemplateEPR.HagueType 1/2/3；API 流程 = HagueType，大陆固定 1）（ES） |
| `HagueType` | 数字 | 否 | 香港公司：`1`=包装法、`2`=包装法+VAT（需查册文件）、`3`=VAT（无需查册文件）；不传按 `0` 处理（跳过查册文件，VAT 语义）（ES） |
| `BusinessCode` / `Code` | 字符串 | 否 | 业务编码（用于文件名）；文件名不含唯一因子，结果唯一性由 `bizParam.BusinessSerialNumber` 子目录保证（见 §5.1/§13.2） |
| `BusinessLicenseDirection` | 数字 | 否 | 营业执照方向：`1`=横版范围、`2`=横版提示、`3`=竖版范围、`4`=竖版提示；不传则自动检测（OCR 判定）（ES） |
| `F_Mobile` | 数字 | 是 | 顾问手机号（企业微信通知接收人）；来源：Base_User.F_Mobile |

**文件字段：**

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `BusinessLicensePic` | 文件 | 是 | 营业执照原件（大陆）；BR 文件（商业登记证，香港） |
| `LegalPersonIdNumberFrontPic` | 文件 | 是 | 证件正面照 |
| `LegalPersonIdNumberBackPic` | 文件 | 是 | 证件反面照 |
| `LegalSignedFile` | 文件 | 免海牙是；030 是 | 法人签名文件（`ES_EPR_REGISTER_030_FILE` 必填，海牙流程非必填） |
| `CreditReportPic` | 文件 | 大陆是/香港否 | 企业信用报告（ES） |
| `BusinessCRFile` | 文件 | 香港是 | CR 文件（注册证书）（ES） |
| `BRFooterPic` | 文件 | 香港是 | BR 脚码（ES） |
| `CRSignerPic` | 文件 | 香港是 | CR 签发人（ES） |
| `CompanyParticularsPic` | 文件 | 香港且 `HagueType=1/2` | 查册文件（ES） |
| `StoreFBAAcitveSetSetScreenShot` | 文件 | 否 | FBA 开启截图（DE） |
| `StoreWarehouseAddressScreenShot` | 文件 | 否 | 仓库地址截图（DE） |
| `StoreOtherSetScreenShot` | 文件 | 否 | 店铺其他截图（DE） |
| `StoreOverseaWarehouseContract` | 文件 | 否 | 海外仓合同（DE） |
| `StoreSellerProfileScreenShot` | 文件 | 否 | 店铺主页截图（DE） |

> **字段取值规则**（ES 海牙）：
> - `LegalPersonCountry` / `Country`（公司注册国家，ES 判定字段）/ `CompanyCountry`（公司所在国家）只传**国家二字码**（如 `CN`/`HK`，ES 三个国家字段必填且互不兜底）；中文名、英文名由系统按国家数据字典解析，**找不到对应国家报数据错误**；`LegalPersonCountry_en` / `CompanyCountry_en` / `CompanyCountryCode` 等派生字段不再由调用方传值
> - 法人英文名拆分字段：`LegalPersonNamePinyin`（名）+ `LegalPersonSurnamePinyin`（姓）必填，系统按「名 姓」拼接（如 `ZHENHUA` + `LIU` → `ZHENHUA LIU`）供文档生成使用；旧字段 `LegalPersonFullNamePinYin` 兼容保留（各 new 受理/文件接口优先取已传全名，未传时按拆分字段拼接，不再「一刀切拒绝」）
> - `LegalPersonIDCardType` 统一规范化为 `IDCard` / `Passport`
> - `LegalPersonGender` 受理时规范化为 `H`(男) / `M`(女)，由传入值映射：`1`/`男`/`H`/`HOMBRE` → `H`；`2`/`女`/`M`/`MUJER` → `M`

**bizParam 字段说明：**

| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| `BusinessSerialNumber` | 字符串/数字 | 通用业务流水号；是否必填及是否参与路径/防重由 PushType 决定。ES 海牙（`ES_VAT_REGISTER_HAGUE_FILE`）：参与生成结果 OSS 唯一性子目录（`es_vat_haiya/{业务流水号}/`，2026-09-02 起，缺省回退 `BusinessId`） |
| `BusinessId` | 字符串/数字 | 通用业务 ID；是否必填由 PushType 决定 |
| `Businessld` | 字符串/数字 | `BusinessId` 的兼容旧拼写，仅对声明支持该兼容键的流程生效 |

法国最小 bizParam 契约：`FR_EPR_REGISTER_LEKO` 仅要求 `BusinessSerialNumber`，用于现有 LEKO OSS 隔离目录；`FR_EPR_REGISTER_CITEO` 无固定必填子字段。两个流程均原样回传完整 bizParam，`BusinessId`/`Businessld` 不参与当前法国文件内容、INSEE 查询或实际 OSS 目录。

**法国 LEKO 服务端 INSEE 派生字段（不是 Data 请求字段）：**

| 内部字段 | 来源/规则 | 用途 |
| ---- | ---- | ---- |
| `_insee.legal_form` | SIREN 响应首个期间的法律形式代码经现有映射表解析 | LEKO XLSX J 列 |
| `_insee.naf_code` | SIREN 响应首个期间的活动代码去除 `.` | LEKO XLSX L 列 |
| `_insee.siret_siege` | SIREN 与总部 NIC 拼接 | LEKO XLSX O 列 |
| `_insee.adresse_siege` | 有总部 SIRET 时查询 SIRET 端点并格式化地址 | 当前保留在服务端结果，XLSX 不使用 |

调用方不得通过 `InseeLegalForm`、`InseeNafCode`、`InseeSiret` 覆盖上述官方查询结果。

> 类型说明：`文件` 类字段的值为 JSON 数组字符串，含 `fileUrl`（OSS 相对路径）+ `fileName`；`日期` 格式 `YYYY-MM-DD`；`数组` 字段以逗号连接后使用。

### 4.4.1 德国VAT注册文件生成
> **PushType**：`DE_VAT_REGISTER_FILE`；**Country**：`DE`

**请求体即 `德国vat注册文件.json` 全文**（顶层含 `PushType` / `Country` / `bizParam` / `Data`；`bizParam` 为业务标识，用途按 PushType 定义见 §2.2，原样回传），`Data` 为扁平业务字段（键=业务字段名，含公司 / 法人 / 店铺 / 业务字段）。注册受理版（`DE_VAT_REGISTER`，Data 同构 + `files` 五合一文件）见 [4.4.10](#4410-德国vat注册自动受理)。

#### 邮件授权邮箱取值规则（Base_Customer / Base_Agent 表，仅查库版）

来源：[vat_query_api.php#L750-L761](file:///d:/phpstudy_pro/WWW/vat_api_de_client/server/vat_query_api.php#L750-L761)（`generateEMailKommNEU` 邮件授权文件写入 `$TaxEmail`）

```sql
SELECT t.TaxEmail, c.Isagent
FROM Base_Customer c
JOIN Base_Agent t ON t.CustomerID = c.ID
WHERE c.ID = :fId ORDER BY t.CreationDate DESC
```

| 字段名   | 来源表        | 说明                                                        |
| -------- | ------------- | ----------------------------------------------------------- |
| Isagent  | Base_Customer | 是否代理（`'True'` 表示代理）                               |
| TaxEmail | Base_Agent    | 代理税务对接邮箱（多代理时取 `CreationDate DESC` 最新一条） |

取值规则：

- 散客（`Isagent != 'True'` 或无代理记录）：固定邮箱 `vat03@seamew.de`；
- 代理（`Isagent = 'True'`）：使用 `Base_Agent.TaxEmail`；
- 接口版（vat_new_file_api.php）不查此表，邮件授权文件固定使用散客邮箱 `vat03@seamew.de`（见「五」差异表）。

```json
{
    "PushType": "DE_VAT_REGISTER_FILE",
    "Country": "DE",
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": "123456"
    },
    "Data":  {
        "LegalPersonSurnamePinyin": "LIU",
        "LegalPersonIdNumberBackPic": [
            {
                "fileUrl": "common-test/2026/08/27/4c58e975-91fe-4e59-abb4-45647d4844b2.jpg",
                "fileName": "DownAnnexesFileByFileUrl (2).jpg"
            }
        ],
        "LegalPersonIdStartDate": "2019-04-15",
        "LegalPersonCountry": "CN",
        "LegalPersonNamePinyin": "ZHENHUA",
        "LegalPersonIdEndDate": "2039-04-15",
        "Nationality": "HAN",
        "LegalPersonPhone": "+86 13422222222",
        "LegalPersonAddressPostcode": "666666",
        "LegalPersonAddressLine1En": "No. 43, Group 4, Defense Village",
        "LegalPersonBirthDate": "1987-06-25",
        "LegalSignedFile": "[{\"fileUrl\":\"common-test/2026/08/27/dae4aeda-6c5e-4cd3-adde-8bd614317db8.png\",\"fileName\":\"签名.png\"}]",
        "LegalPersonIdNumber": "510681198706252865",
        "LegalPersonAddressProvinceEn": "Sichuan ",
        "LegalPersonGender": "1",
        "LegalPersonCityEngName": "Guanghan",
        "LegalPersonName": "刘振华",
        "LegalPersonIDCardAddress": "四川省广汉市和兴镇国防村4组43号",
        "LegalPersonIDCardAddressEng": "No. 43, Group 4, Defense Village, Huixing Town, Guanghan City, Sichuan Province",
        "LegalPersonIDCardType": "IDCARD",
        "LegalPersonIdNumberFrontPic": [
            {
                "fileUrl": "common-test/2026/08/27/22696aa2-e931-4dc5-a2cd-510db0d2d16d.jpg",
                "fileName": "DownAnnexesFileByFileUrl (1).jpg"
            }
        ],
        "__extraFile": "[{\"fileUrl\":\"common-test/2026/08/27/08a58ddd-32b9-4849-a39e-0a1ed7bbaa94.png\",\"fileName\":\"e62ec40c4ccb456fbc911cfac02b54fb.png\"}]",
        "LocalTaxNumber": null,
        "Code": null,
        "VATTaxNumber": null,
        "ExpectedSalesYear2": "3124",
        "ExpectedSalesYear1": "1234",
        "__attachments": "[{\"fileUrl\":\"common-test/2026/08/27/8d3528c7-7516-4bd8-9b04-44b560e4191d.png\",\"fileName\":\"logo.png\"}]",
        "DELogisticsSituation": "No. 43, Group 4, Defense Village, Huixing Town, Guanghan City, Sichuan Province",
        "ProductsRange": "Product sales type",
        "BusinessPlatform_En": "TIKTOK",
        "StoreFBAAcitveSetSetScreenShot": "[{\"fileUrl\":\"common-test/2026/08/27/d3286939-8f8e-4789-9463-39721682d3d8.gif\",\"fileName\":\"1.gif\"}]",
        "ShopName": "name of shop",
        "ShopUrl": "https://test-cloud.usaeu.com/order/handle-business?data=FkcACwYPSDRBRFYZRFU-XkcXWBgRFkBXQntST19cW0ZQ",
        "ShopAccount": "123456789",
        "StoreWarehouseAddressScreenShot": "[{\"fileUrl\":\"common-test/2026/08/27/9eb2dca4-6113-466a-815d-149931dc6782.gif\",\"fileName\":\"2.gif\"}]",
        "StoreOtherSetScreenShot": "[{\"fileUrl\":\"common-test/2026/08/27/651fee18-b721-4897-83a6-18927c63d392.png\",\"fileName\":\"avatar200.png\"}]",
        "StoreOverseaWarehouseContract": [
            {
                "fileUrl": "common-test/2026/08/27/af88148a-1484-483f-8cda-c4db8ee0c6d7.png",
                "fileName": "4359bc31121b45fd974bf91f0e1dff1b.png"
            }
        ],
        "CreditReportPic": null,
        "EstablishmentDate": "2024-03-22",
        "RegisteredCapital": "10000",
        "NameCN": "枝江市霞陆逊商贸有限公司",
        "NameEng": "Ji Jiang City Xialu Sun Trading Co., Ltd.",
        "RegAddressEng": "No. 82, 2nd floor, Group 6, Jiangjiaopo Village, Anfushi Town, Zhijiang City, Yichang City, Hubei Province (Self-reported)",
        "CityEngName": "Zhijiang",
        "RegNumber": "91420583MADDMTJE7M",
        "CompanyAddressPostcode": "666666",
        "RegisteredCapitalCurrency": "CNY",
        "CompanyAddressLine1En": "No. 82, 2nd floor, Group 6, Jiangjiaopo Village, Anfushi Town, Zhijiang City, Yichang City, Hubei Province (Self-reported)",
        "Country": "CN",
        "BusinessLicensePic": [
            {
                "fileUrl": "common-test/2026/08/27/9abb02ef-4c2d-4c39-baa0-6f5b65d99bf4.jpg",
                "fileName": "DownAnnexesFileByFileUrl.jpg"
            }
        ]
    }
}
```

### 4.4.2 西班牙VAT海牙
> **PushType**：`ES_VAT_REGISTER_HAGUE_FILE`；**Country**：`ES`

**请求体即 `西班牙VAT海牙.json` 全文**（顶层含 `PushType` / `Country` / `Data` / `bizParam`）：

```json
{
    "PushType": "ES_VAT_REGISTER_HAGUE_FILE",
    "Country": "ES",
    "Data": {
        "LegalPersonIdNumberBackPic": "[{\"fileUrl\":\"common-test/2026/08/06/ad9ba397-3a41-443c-8c96-d567f9f567c3.jpg\",\"fileName\":\"DownAnnexesFileByFileUrl (2).jpg\"}]",
        "LegalPersonIdStartDate": "2019-04-15",
        "LegalPersonIdEndDate": "2039-04-15",
        "Nationality": "1",
        "LegalPersonNamePinyin": "ZHENHUA",
        "LegalPersonSurnamePinyin": "LIU",
        "LegalPersonPhone": "8618117939375",
        "LegalPersonBirthDate": "1987-06-25",
        "LegalSignedFile": "[{\"fileUrl\":\"common-test/2026/08/06/60198b6f-122a-4c74-ae64-07502628b828.png\",\"fileName\":\"DownAnnexesFileByFileUrl.png\"}]",
        "LegalPersonIdNumber": "510681198706252865",
        "LegalPersonEmail": "liu5zhen7h7ua@outlook.com",
        "LegalPersonGender": "1",
        "LegalPersonName": "刘振华",
        "LegalPersonIDCardAddressEng": "hexing zhen guofang cun 4 zu 43 hao hexing zhen,guanghan shi,sichuan sheng,618300,CN",
        "LegalPersonIdNumberFrontPic": "[{\"fileUrl\":\"common-test/2026/08/06/d257b28a-ea62-4197-b912-dffed75617af.jpg\",\"fileName\":\"DownAnnexesFileByFileUrl (1).jpg\"}]",
        "LocalTaxNumber": "本土税号",
        "CompanyAddressLine1En": "No. W82, 2nd floor, Group 6, Jiangjiaopo Village, Anfu Temple, Zhijiang City, Yichang City, Hubei Province",
        "EstablishmentDate": "2024-03-22",
        "RegisteredCapital": "100000.00",
        "CityEngName": "Zhi Jiang",
        "NameEng": "zhijiangshixialuxunshangmaoyouxiangongsi",
        "NameCN": "枝江市霞陆逊商贸有限公司",
        "RegNumber": "91420583MADDMTJE7M",
        "CompanyAddressPostcode": "443200",
        "RegisteredCapitalCurrency": [
            "1",
            "2"
        ],
        "Country": "CN",
        "CompanyCountry": "CN",
        "BusinessLicensePic": "[{\"fileUrl\":\"common-test/2026/08/06/019baf3f-801e-45aa-bf6d-a80c2b07e15d.jpg\",\"fileName\":\"DownAnnexesFileByFileUrl.jpg\"}]",
        "AR": "M",
        "SpecsName": "海牙",
        "RegAddressEng": "No. W82, 2nd floor, Group 6, Jiangjiaopo Village, Anfu Temple, Zhijiang City, Yichang City, Hubei Province",
        "CompanyAddressLine2En": "",
        "CompanyAddressProvinceEn": "Hubei",
        "LegalPersonCityEngName": "Guang Han",
        "LegalPersonIDCardType": "1",
        "LegalPersonCountry": "CN",
        "LegalPersonAddressProvinceEn": "Sichuan",
        "BusinessCode": "",
        "Code": "",
        "CreditReportPic": "[{\"fileUrl\":\"common-test/2026/08/07/credit_report.pdf\",\"fileName\":\"credit_report.pdf\"}]",
        "HagueType": "",
        "BusinessCRFile": "",
        "BRFooterPic": "",
        "CRSignerPic": "",
        "CompanyParticularsPic": ""
    },
    "bizParam": {
        "BusinessSerialNumber": "EVAT12312312312312313",
        "Businessld": 789012
    }
}
```


### 4.4.3 西班牙EPR海牙
> **PushType**：`ES_EPR_REGISTER_HAGUE_FILE`；**Country**：`ES`

**请求体即 `西班牙EPR海牙.json` 全文**（顶层含 `PushType` / `Country` / `Data` / `bizParam`）：

```json
{
    "PushType": "ES_EPR_REGISTER_HAGUE_FILE",
    "Country": "ES",
    "Data": {
        "LegalPersonSurnamePinyin": "WANG",
        "LegalPersonIdNumberBackPic": [{
            "fileUrl": "common-test\/2026\/08\/29\/f053473e-e49a-4b2b-a645-5ad7f50ccb4a.png",
            "fileName": "反面.png"
        }],
        "LegalPersonIdStartDate": "2024-09-06",
        "LegalPersonCountry": "CN",
        "LegalPersonNamePinyin": "ZICHENG",
        "LegalPersonIdEndDate": "2044-09-06",
        "Nationality": "汉",
        "LegalPersonPhone": "+86 18820990915",
        "LegalPersonBirthDate": "1996-05-17",
        "LegalSignedFile": "[{\"fileUrl\":\"common-test\/2026\/08\/29\/5bf8ec07-bc40-4186-af3e-dd4115026ec0.png\",\"fileName\":\"正面.png\"}]",
        "LegalPersonIdNumber": "650203199605170718",
        "LegalPersonAddressProvinceEn": "hongkong",
        "LegalPersonEmail": "460082351@qq.com",
        "LegalPersonGender": "男",
        "LegalPersonCityEngName": "hongkong",
        "LegalPersonName": "王子成",
        "LegalPersonIDCardAddressEng": null,
        "LegalPersonIDCardType": "IDCARD",
        "LegalPersonIdNumberFrontPic": [{
            "fileUrl": "common-test\/2026\/08\/29\/c3598158-3760-4b8d-81ea-2a83b13bdea8.png",
            "fileName": "正面.png"
        }],
        "__extraFile": null,
        "LocalTaxNumber": null,
        "Code": null,
        "VATTaxNumber": null,
        "AR": "M",
        "HagueType": "",
        "BusinessCRFile": "",
        "RegAddressEng": "RM 93, ZONE 2, 27\/F EGL TOWER，83 HUNG TO RD，KWUN TONG，HONG KONG，999077HK",
        "CreditReportPic": null,
        "BusinessConstitutionFile": null,
        "EstablishmentDate": null,
        "RegisteredCapital": null,
        "CompanyAddressLine2En": null,
        "BRFooterPic": "",
        "CRSignerPic": "",
        "NameCN": "香港機車迷貿易有限公司",
        "NameEng": "HONG KONG MOTOFANS TRADING LIMITED",
        "CityEngName": "distrito de Yuhang",
        "RegNumber": "80684478",
        "CompanyCountry": "HK",
        "CompanyAddressPostcode": "311100",
        "RegisteredCapitalCurrency": null,
        "CompanyAddressLine1En": "barrio de Yuhang",
        "CompanyAddressProvinceEn": "HONG KONG",
        "Country": "HK",
        "BusinessLicensePic": [{
            "fileUrl": "common-test\/2026\/08\/29\/961313a2-815c-49aa-a758-cf87556ad758.pdf",
            "fileName": "CR文件.pdf"
        }],
        "CompanyParticularsPic": ""
    },
    "bizParam": {
        "BusinessSerialNumber": "EVAT12312312312312313",
        "BusinessId": 789012
    }
}
```

> 异步受理：受理即返回 `{code:200, msg:'success', ProcessMode:'async', data:null, bizParam}`，文件由后台生成，完成后经统一结果回调接口通知调用方（见 §13）。
>
> - 文件校验（2026-09-08 起，受理阶段即做真实访问，失败 400 且错误消息带接口字段名）：香港公司 `BusinessCRFile`/`BusinessLicensePic`(BR)/`BRFooterPic`/`CRSignerPic`/`CompanyParticularsPic`（HagueType=1/2）受理即**真实下载**（COS 桶对象走签名 URL `q-sign`；私桶对象直连 403 时签名后可访问，下载失败报「…文件下载失败: <URL>」）；大陆公司 `CreditReportPic` 受理时下载并校验为有效企业信用报告（非有效 PDF 时 400「…文件内容校验失败…」）；身份证/营业执照仍为 URL 探测、生成阶段按需下载。注意事项：`EPR_API_TEST_LOCAL_FILES` 只覆盖消费端、不能豁免受理校验——文件 URL 须从**受理机器**可访问
> - 必填：§4.4 总表标注「是」的全量业务字段（国家字段只传二字码，`*_en`/`CompanyCountryCode` 由系统从国家字典解析，不再由调用方传值）+ `AR`（`M`/`O`）；`LegalSignedFile` 海牙流程非必填
> - 大陆公司（`Country` 非 `HK`，公司注册国家判定；`CompanyCountry` 为公司所在国家，非判定依据）：另需 `RegNumber`/`BusinessLicensePic`/`CreditReportPic`
> - 香港公司（`Country` = `HK`，公司注册国家判定）：`HagueType` 可选（`1`=包装法、`2`=包装法+VAT、`3`=VAT；`1`/`2` 另需 `CompanyParticularsPic` 查册文件；不传按 `0` 处理、查册文件非必须，对齐 es_haiya），文件用 `BusinessLicensePic`（BR 商业登记证）/`BusinessCRFile`/`BRFooterPic`/`CRSignerPic`，无需信用报告；无 `RegNumber` 豁免
> - 防重：同 BusinessSerialNumber / BusinessId+同 PushType 存在未终态任务则 400 拒绝

### 4.4.4 西班牙EPR030
> **PushType**：`ES_EPR_REGISTER_030_FILE`；**Country**：`ES`；030 文件生成

**请求体即 `西班牙EPR030.json` 全文**（顶层含 `PushType` / `Country` / `Data` / `bizParam`，`Data` 与 §4.4.3 海牙示例完全一致，仅 `PushType` 不同）：

```json
{
    "PushType": "ES_EPR_REGISTER_030_FILE",
    "Country": "ES",
    "Data": {
        "LegalPersonSurnamePinyin": "WANG",
        "LegalPersonIdNumberBackPic": [{
            "fileUrl": "common-test\/2026\/08\/29\/f053473e-e49a-4b2b-a645-5ad7f50ccb4a.png",
            "fileName": "反面.png"
        }],
        "LegalPersonIdStartDate": "2024-09-06",
        "LegalPersonCountry": "CN",
        "LegalPersonNamePinyin": "ZICHENG",
        "LegalPersonIdEndDate": "2044-09-06",
        "Nationality": "汉",
        "LegalPersonPhone": "+86 18820990915",
        "LegalPersonBirthDate": "1996-05-17",
        "LegalSignedFile": "[{\"fileUrl\":\"common-test\/2026\/08\/29\/5bf8ec07-bc40-4186-af3e-dd4115026ec0.png\",\"fileName\":\"正面.png\"}]",
        "LegalPersonIdNumber": "650203199605170718",
        "LegalPersonAddressProvinceEn": "hongkong",
        "LegalPersonEmail": "460082351@qq.com",
        "LegalPersonGender": "男",
        "LegalPersonCityEngName": "hongkong",
        "LegalPersonName": "王子成",
        "LegalPersonIDCardAddressEng": null,
        "LegalPersonIDCardType": "IDCARD",
        "LegalPersonIdNumberFrontPic": [{
            "fileUrl": "common-test\/2026\/08\/29\/c3598158-3760-4b8d-81ea-2a83b13bdea8.png",
            "fileName": "正面.png"
        }],
        "__extraFile": null,
        "LocalTaxNumber": null,
        "Code": null,
        "VATTaxNumber": null,
        "AR": "M",
        "HagueType": "",
        "BusinessCRFile": "",
        "RegAddressEng": "RM 93, ZONE 2, 27\/F EGL TOWER，83 HUNG TO RD，KWUN TONG，HONG KONG，999077HK",
        "CreditReportPic": null,
        "BusinessConstitutionFile": null,
        "EstablishmentDate": null,
        "RegisteredCapital": null,
        "CompanyAddressLine2En": null,
        "BRFooterPic": "",
        "CRSignerPic": "",
        "NameCN": "香港機車迷貿易有限公司",
        "NameEng": "HONG KONG MOTOFANS TRADING LIMITED",
        "CityEngName": "distrito de Yuhang",
        "RegNumber": "80684478",
        "CompanyCountry": "HK",
        "CompanyAddressPostcode": "311100",
        "RegisteredCapitalCurrency": null,
        "CompanyAddressLine1En": "barrio de Yuhang",
        "CompanyAddressProvinceEn": "HONG KONG",
        "Country": "HK",
        "BusinessLicensePic": [{
            "fileUrl": "common-test\/2026\/08\/29\/961313a2-815c-49aa-a758-cf87556ad758.pdf",
            "fileName": "CR文件.pdf"
        }],
        "CompanyParticularsPic": ""
    },
    "bizParam": {
        "BusinessSerialNumber": "EVAT12312312312312313",
        "Businessld": 789012
    }
}
```

> 异步受理：受理即返回 async 信封，文件由后台 / RPA 生成后经统一结果回调接口通知调用方（见 §13）。`Data` 字段集与海牙流程（§4.4.3）完全相同（§4.4 总表「是」，国家字段只传二字码），**文件字段仅 `LegalSignedFile` 必填且不做文件检查**（`SpecsName`/`HagueType` 及其余文件字段传了也不校验）；**`AR` 必填（M/O）**——030 文件也按授权机构选模板（M=原 mokj 模板，O=Onesea 模板，与海牙授权书一致）。

### 4.4.5 法国VAT注册文件生成
> **PushType**：`FR_VAT_REGISTER_FILE`；**Country**：`FR`

法国VAT注册文件生成（`FR_VAT_REGISTER_FILE`）生成5个独立文件，支持中国/香港公司，根据公司是否为欧盟成员/英国/北爱选择不同模板（KJ中文模板/MOKJ法文模板）。

**请求体即 `法国vat注册文件.json` 全文**（顶层含 `PushType` / `Country` / `Data` / `bizParam`，`files` 传空数组即可，文件生成接口不使用）。注册受理版（`FR_VAT_REGISTER`，Data 同构 + `files` 5类自动生成 PDF）见 [4.4.11](#4411-法国vat注册自动受理)。

**生成文件（5个）：**

| 文件序号 | 字段名 | 文件类型 | 说明 |
| -------- | ------ | -------- | ---- |
| 1 | Mandat | 授权书 | 授权书翻译模板（非欧盟用KJ中文模板，欧盟/英国/北爱用MOKJ法文模板） |
| 2 | Status_FR | 章程翻译件 | 章程法语翻译模板 |
| 3 | ID | 身份证合并件 | 法人身份证正反面合并+压缩 |
| 4 | Gewerbeschein | 营业执照或BR文件 | 营业执照（大陆）/ BR+CR+NNC1合并（香港，NNC1可选） |
| 5 | Status | 公司章程原件文件 | 本国章程原件（必须为PDF格式，自动压缩） |

**必填字段说明：**

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `NameEng` | 字符串 | 是 | 企业英文全称（不能含中文） |
| `CompanyAddressLine1En` | 字符串 | 是 | 公司注册地址英文（不能含中文） |
| `CityEngName` | 字符串 | 是 | 公司所在城市英文（不能含中文） |
| `LegalPersonNamePinyin` | 字符串 | 是 | 法人英文名（拼音，不能含中文） |
| `LegalPersonSurnamePinyin` | 字符串 | 是 | 法人英文姓（拼音，不能含中文） |
| `LegalPersonBirthDate` | 日期 | 是 | 法人出生日期（YYYY-MM-DD） |
| `LegalPersonCityEngName` | 字符串 | 是 | 法人所在城市英文（不能含中文） |
| `LegalPersonCountry` | 字符串 | 是 | 法人国籍（英文，不能含中文） |
| `LegalPersonAddressLine1En` | 字符串 | 是 | 法人地址英文（不能含中文） |
| `LegalPersonEmail` | 字符串 | 是 | 法人邮箱（不允许下划线） |
| `TaxEffectiveDate` | 日期 | 是 | 税务生效日期（YYYY-MM-DD） |
| `FirstPendingSaveBusinessTime` | 日期 | 是 | 首次保存业务时间 |
| `LegalPersonPhone` | 字符串 | 是 | 法人联系电话 |
| `RegisteredCapital` | 字符串 | 是 | 注册资本 |
| `EstablishmentDate` | 日期 | 是 | 公司成立日期 |
| `ProductRange` | 字符串 | 是 | 产品说明（英文） |
| `BusinessConstitutionFile` | 文件 | 是 | 本国章程（必须为PDF格式） |
| `BusinessLicensePic` | 文件 | 是 | 营业执照照片（大陆）；BR商业登记证（香港） |
| `LegalPersonIdNumberFrontPic` | 文件 | 是 | 法人身份证正面 |
| `LegalPersonIdNumberBackPic` | 文件 | 是 | 法人身份证反面 |
| `LegalSignedFile` | 文件 | 否 | 法人签名文件（不提供则自动生成） |
| `BusinessCRFile` | 文件 | 香港是 | CR文件（公司注册证书，香港公司必填） |
| `BusinessNNC1File` | 文件 | 否 | NNC1文件（法团成立表格，香港公司可选） |
| `IsEUMember` | 数字 | 否 | 是否欧盟成员（1=是，0=否），决定模板选择 |
| `CountryTwoCode` | 字符串 | 否 | 国家二字码（GB=英国，NI=北爱），决定模板选择 |

**请求体即 `法国vat注册文件.json` 全文**（顶层含 `PushType` / `Country` / `Data` / `bizParam`，`files` 传空数组即可）：

```json
{
	"PushType": "FR_VAT_REGISTER_FILE",
	"Country": "FR",
	"Data": {
		"LegalPersonSurnamePinyin": "Zhu",
		"LegalPersonIdNumberBackPic": [{
			"fileUrl": "common-test/2026/08/23/b87d393f-589c-452f-bf35-47bdfa058906.jpg",
			"fileName": "身份证反面-1.jpg"
		}],
		"LegalPersonIdStartDate": "2019-08-05",
		"LegalPersonCountry": "CN",
		"LegalPersonNamePinyin": "Menglong",
		"LegalPersonIdEndDate": "2039-08-05",
		"Nationality": "汉",
		"LegalPersonPhone": "+86 17304425200",
		"LegalPersonBirthDate": "1988-09-19",
		"LegalSignedFile": null,
		"LegalPersonIdNumber": "420281198809193219",
		"LegalPersonEmail": "MenlongDLtHk@outlook.com",
		"LegalPersonGender": "男",
		"LegalPersonName": "朱梦龙",
		"LegalPersonIDCardAddress": "湖北省大冶市陈贵镇铜山口村张泗朱湾136号",
		"LegalPersonIDCardAddressEng": "hubeishengdayeshichenguizhentongshankoucunzhangsizhuwan136hao",
		"LegalPersonIDCardType": "IDCARD",
		"LegalPersonIdNumberFrontPic": [{
			"fileUrl": "common-test/2026/08/23/f136c0ff-d693-4f57-9837-102b121c8de7.jpg",
			"fileName": "身份证正面.jpg"
		}],
		"__extraFile": null,
		"LocalTaxNumber": "20260825",
		"Code": "0825",
		"VATTaxNumber": "FR0825",
		"TaxEffectiveDate": "2025-01-01",
		"ProductsRange": "electronic products childrens toys",
		"BusinessPlatform_En": "Amazon",
		"ShopName": "MENGLONGDA TECHNOLOGY",
		"ShopUrl": "https://www.amazon.it/sp?ie=UTF8&seller=A102OL1SHPTA29",
		"ShopAccount": "A102OL1SHPTA29",
		"BusinessConstitutionFile": "[{\"fileUrl\":\"common-test/2026/08/23/19b30cb7-6329-4e68-8c9f-d75076ecf7d2.pdf\",\"fileName\":\"Statuts dates et signes.pdf\"}]",
		"EstablishmentDate": "2025-11-24",
		"RegisteredCapital": "10000",
		"NameEng": "HONG KONG MENGLONGDA TECHNOLOGY CO., LIMITED",
		"RegAddressEng": "33-35 Au Pui Wan Street, Century Industrial Centre Room D4, Flat I, 4/F,Sha Tin Hong Kong 999077 HK",
		"CityEngName": "Century Industrial Centre",
		"RegNumber": "79244348",
		"CompanyAddressPostcode": "999077",
		"RegisteredCapitalCurrency": "CNY",
		"CompanyAddressLine1En": "33-35 Au Pui Wan Street",
		"Country": "HK",
		"BusinessLicensePic": [{
			"fileUrl": "common-test/2026/08/23/b3ea5f07-98a2-4abd-8399-bb0f163416b9.pdf",
			"fileName": "BR-香港夢灌達科技有限公司.pdf"
		}],
		"FirstPendingSaveBusinessTime": "2026-08-25"
	},
	"bizParam": {
		"deliveryId": 57827,
		"pushType": "FR_VAT_REGISTER_FILE",
		"operatorId": 93,
		"operatorTime": "2026-08-26 20:30:18",
		"BusinessSerialNumber": "FR2026082509563715",
		"BusinessId": "57827"
	},
	"files": []
}
```

> **模板选择规则**：
> - 非欧盟/非英国/非北爱公司（如中国、香港）：使用 **KJ中文模板**（KJ-Mandat-CN.docx、KJ-Status-CN.docx）
> - 欧盟成员/英国/北爱公司：使用 **MOKJ法文模板**（MOKJ-Mandat.docx、MOKJ-Status.docx）
> - 若未上传签名文件（`LegalSignedFile`），系统将根据 `Code` 末位数字自动生成签名

### 4.4.6 意大利EPR注册
> **PushType**：`IT_EPR_REGISTER`；**Country**：`IT`

**请求体即 `意大利EPR注册.json` 全文**（顶层含 `PushType` / `Country` / `bizParam` / `Data`）：

```json
{
    "PushType": "IT_EPR_REGISTER",
    "Country": "IT",
    "bizParam": {
        "BusinessId": 789012,
        "BusinessSerialNumber": "IT-2026-0001"
    },
    "Data": {
        "NameEng": "Test Company Ltd",
        "RegAddressEng": "No.1 Test Road, Chaoyang District",
        "CompanyAddressPostcode": "100000",
        "Country": "中国",
        "CountryEn": "China",
        "CountryTwoCode": "CN",
        "RegNumber": "91110000MA01TEST1X",
        "VATNumber": "",
        "LegalPersonFullNamePinYin": "Xiaoming WANG",
        "LegalPersonPhone": "86-13488979214",
        "LegalPersonEmail": "legal@test-company.com",
        "LegalPersonBirthDate": "1990-01-15",
        "CompanyAddressProvinceEn": "Beijing",
        "CityEngName": "Beijing",
        "LegalPersonCityEngName": "Beijing",
        "F_Mobile": "13488979214",
        "LegalSignedFile": "[{\"fileUrl\":\"https://file.usaeu.com/annexes/signature_2026.png\",\"fileName\":\"signature_2026.png\"}]"
    }
}
```

> 注：`CountryEn`（英文国家名，用于 DeepL 翻译）与 `CountryTwoCode`（国家二字码，用于 CN/HK 判定与 VAT 解析）为意大利流程**新增必填字段**，§4.4 通用总表中无此两项；`LegalSignedFile` 为 URL 或 `[{"fileUrl":...}]` JSON 数组字符串，原样透传下游。

### 4.4.7 法国 LEKO 注册
> **PushType**：`FR_EPR_REGISTER_LEKO`；**Country**：`FR`

API_Flow 直接使用 `Data` 生成 LEKO XLSX 与 POA PDF，不按 `Id` 或 `EprRegInfoId` 查询 source 库。对法国公司，服务端继续使用现有 `InseeApiClient` 调用 INSEE 官方 SIRENE API 获取法律形式、NAF/APE 和总部 SIRET；这三项不是请求字段。

```json
{
    "PushType": "FR_EPR_REGISTER_LEKO",
    "Country": "FR",
    "bizParam": {
        "BusinessSerialNumber": "FREPR2026000001"
    },
    "Data": {
        "NameEng": "EXAMPLE COMPANY SAS",
        "RegAddressEng": "10 Rue Exemple, 75001 Paris, France",
        "CompanyAddressLine1En": "10 Rue Exemple",
        "CompanyAddressPostcode": "75001",
        "CityEngName": "Paris",
        "CountryTwoCode": "FR",
        "AreaName": "Ile-de-France",
        "RegNumber": "123 456 789 R.C.S. Paris",
        "RegisteredCapital": "10000.00",
        "RegisteredCapitalCurrency": "EUR",
        "LegalPersonFullNamePinYin": "MING LI",
        "LegalPersonEmail": "legal@example-company.fr",
        "LegalPersonPhone": "8613800000000",
        "LegalPersonGender": "1",
        "VATNumber": "FR00123456789"
    }
}
```

LEKO 最小输入：固定字段为 `NameEng`、`RegAddressEng`、`CompanyAddressLine1En`、`CompanyAddressPostcode`、`CityEngName`、`CountryTwoCode`、`RegNumber`、`LegalPersonFullNamePinYin`、`LegalPersonEmail`、`LegalPersonPhone`、`LegalPersonGender`；`CountryTwoCode=CN` 时增加 `AreaName`；欧盟公司增加 `VATNumber`；`CountryTwoCode=FR` 时增加 `RegisteredCapital` 与 `RegisteredCapitalCurrency`。`CompanyAddressLine2En` 和 `InseeLegalForm`/`InseeNafCode`/`InseeSiret` 不属于最小请求字段。`NameEng` 最长 50 个字符，`CompanyAddressLine1En` 最长 100 个字符。

INSEE 查询规则与当前项目一致：仅法国公司查询；从 `RegNumber` 删除非数字字符后取前 9 位作为 SIREN，只有长度恰为 9 时调用 `https://api.insee.fr/api-sirene/3.11/siren/{SIREN}`。服务端从首个 `periodesUniteLegale` 映射法律形式、去除句点的 NAF 和 `SIREN + nicSiegeUniteLegale`，有总部 SIRET 时再调用 `/siret/{SIRET}`。HTTP 非 200 抛错；最多尝试 5 次、间隔 6 秒，最终失败则本次文件生成失败。非 FR 或无法形成 9 位 SIREN 时不调用 INSEE，并沿用 XLSX 默认值 `Autre / Other`、空 NAF、空 SIRET。

成功响应为同步模式；`data.file1` 是 LEKO XLSX 完整 OSS URL，`data.file2` 是 POA PDF 完整 OSS URL，未使用的 `file3` 至 `file10` 为空字符串。
> 测试数据样例即本目录 `法国LEKO注册文件.json` 全文（与本节示例一致，可通过生产校验器）。

### 4.4.8 法国 CITEO 注册
> **PushType**：`FR_EPR_REGISTER_CITEO`；**Country**：`FR`

API 流程直接使用 `Data` 生成 CITEO POA PDF，不接受仅传 `Id` 或 `EprRegInfoId` 后查询 source 库的方式。

```json
{
    "PushType": "FR_EPR_REGISTER_CITEO",
    "Country": "FR",
    "bizParam": {},
    "Data": {
        "NameEng": "EXAMPLE COMPANY SAS",
        "CountryTwoCode": "FR",
        "CityEngName": "Paris",
        "RegAddressEng": "10 Rue Exemple, 75001 Paris, France",
        "LegalPersonFullNamePinYin": "MING LI",
        "RegNumber": "123456789"
    }
}
```

CITEO 最小输入：固定字段为 `NameEng`、`CountryTwoCode`、`CityEngName`、`RegAddressEng` 和 `LegalPersonFullNamePinYin`。欧盟公司且国家不为法国时，增加 `VATNumber` 并作为 `BusinessLicenseNo`；非欧盟公司或法国公司增加 `RegNumber`。当前生成器不需要 AreaName、地址行/邮编、资本、法人联系方式/性别或 INSEE 字段。

成功响应为同步模式；`data.file1` 是 CITEO POA PDF 完整 OSS URL，未使用的 `file2` 至 `file10` 为空字符串。
> 测试数据样例即本目录 `法国CITEO注册文件.json` 全文（与本节示例一致，可通过生产校验器）。

### 4.4.9 英国VAT注册
> **PushType**：`GB_VAT_REGISTER`；**Country**：`GB`

英国 VAT 注册数据接收（`GB_VAT_REGISTER`）：接收 SaaS 推送的英国 VAT 注册业务数据，校验并转换后落库，注册邮箱由服务端自动创建（`registrationvat{N}@usaeu.com`）。

**请求体即 `英国VAT注册.json` 全文**（顶层含 `PushType` / `Country` / `bizParam` / `Data`，`Data` 为扁平业务字段）：

```json
{
    "PushType": "GB_VAT_REGISTER",
    "Country": "GB",
    "bizParam": {
        "BusinessSerialNumber": "POVAT20260824000001",
        "BusinessId": 123456
    },
    "Data": {
        "NameEng": "ZhiJiangShiXiaLuXunShangMaoYouXianGongSi",
        "VATStartDate": "2026-10-01",
        "RegNumber": "91420583MADDMTJE7M",
        "Country": "CN",
        "CompanyAddressLine1En": "No. W82, 2nd floor, Jiangjiaopo",
        "CompanyAddressLine2En": "Anfu Temple, Zhijiang City",
        "CityEngName": "Zhi Jiang",
        "CompanyAddressProvinceEn": "Hubei Province",
        "CompanyAddressPostcode": "443200",
        "LegalPersonNamePinyin": "ZHENHUA",
        "LegalPersonSurnamePinyin": "LIU",
        "LegalPersonBirthDate": "1987-06-25",
        "LegalPersonAddressLine1En": "hexing zhen guofang cun 4 zu",
        "LegalPersonAddressLine2En": "guanghan shi, sichuan sheng",
        "LegalPersonCityEngName": "Guang Han",
        "LegalPersonAddressProvinceEn": "Sichuan",
        "LegalPersonAddressPostcode": "618300",
        "LegalPersonCountry": "CN",
        "LegalPersonPhone": "8618117939375",
        "ProductsRange": "Home goods",
        "AnnualGMV": "10000",
        "NeedRequestEORI": 1,
        "BusinessCode": "GBVAT20260824000001",
        "Code": "POVAT20260824000001",
        "LinkedSalesContactName": "Sales Zhang",
        "LinkedSalesContactPhone": "13900000000",
        "UploadFile1": "[{\"fileUrl\":\"common-test/2026/08/06/ad9ba397-3a41-443c-8c96-d567f9f567c3.jpg\",\"fileName\":\"passport.jpg\"}]",
        "UploadFile2": "[{\"fileUrl\":\"common-test/2026/08/07/26bd44df-e802-431c-af44-62ebd6e76c20.pdf\",\"fileName\":\"bank statement.pdf\"}]",
        "UploadFile3": "[{\"fileUrl\":\"common-test/2026/08/07/1c1345cb-c588-491a-8f28-17968c49e3e0.pdf\",\"fileName\":\"electricity bill.pdf\"}]"
    }
}
```

> 注：`VATStartDate` 须为距当前日期 ±3 个月内的日期，示例为文档编写日期附近的有效值；文件字段为统一格式 `[{fileUrl, fileName}]`（JSON 数组字符串或原生数组，`fileUrl` 仅支持 https 或内部文件服务相对路径；**绝对 https 地址提交时做 HEAD 探测（5s 超时）确认文件真实存在**，网络错误/HTTP ≥400 报 400「文件不存在或无法访问」，内部相对路径跳过探测），**文件名按关键词分类**（与 source 流程 `FileService` 一致）：`UploadFile1` 第一个附件为法人证件（文件名含 passport/identity card/drive license，护照/身份证/驾驶证）→ `upload_file_path1`，必填；`UploadFile2`/`UploadFile3` 为支持文件（文件名含 bank statement/credit card statement/electricity bill/water bill/property fee bill/telephone bill/gas bill/broadband bill/property ownership certificate/birth certificate/social security certificate 关键词），**匹配多个则多个文件一并递交**（首个 → `upload_file_path2`，次个 → `upload_file_path3`），`UploadFile3` 仅有第二个支持文件时填写、非必填；文件名未命中任何关键词报数据错误。旧字段名 `LegalPersonIdDocumentPic`/`SupportingDocumentPic1`/`SupportingDocumentPic2` 已废弃不再接受：提交视为对应上传文件字段未传，直接报 400「缺少上传文件字段（UploadFile1/UploadFile2/UploadFile3）」（与未传新字段相同）。
>
> **GB 字段取值规则**：`Country` / `LegalPersonCountry` 只传**国家二字码**（如 `CN`/`HK`），中文名/英文名不再由调用方传值，系统从 `cache/countries.json` 国家字典解析英文名（字典原始名归一为目标库规范名，与 sync 流程写入值一致），找不到对应国家报数据错误；法人英文名为 `LegalPersonNamePinyin`（名）+ `LegalPersonSurnamePinyin`（姓）两字段，旧字段 `LegalPersonFullNamePinYin` 已废弃，不再接受。

---

### 4.4.10 德国VAT注册自动受理
> **PushType**：`DE_VAT_REGISTER`；**Country**：`DE`

**请求体即 `德国vat注册.json` 全文**：`Data` 与文件生成版（§4.4.1）同构，另携带顶层 `files`（五合一文件生成结果，`url` 为 OSS 相对路径，**直接落库不再下载/上传**）。转发层（countries/de.php）透传到 `vat_api_de_client/server/vat_new_register_auto.php` 落库 `vat_de_register`（rpa 库），供门户自动注册消费。

```json
{
    "PushType": "DE_VAT_REGISTER",
    "Country": "DE",
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "pushType": "DE_VAT_REGISTER",
        "BusinessId": "123456"
    },
    "Data": {
        "LegalPersonSurnamePinyin": "CHAO",
        "LegalPersonIdNumberBackPic": [{
            "fileUrl": "common-test/2026/08/23/79266a53-ef03-4077-9315-4ad40c0e8d6d.jpg",
            "fileName": "80614db5-df9c-46e3-bb79-6fa107eefc24.jpg"
        }],
        "LegalPersonIdStartDate": "2024-02-19",
        "LegalPersonCountry": "CN",
        "LegalPersonNamePinyin": "XUYANG",
        "LegalPersonIdEndDate": "2034-02-19",
        "Nationality": "HAN",
        "LegalPersonPhone": "+86 15202482253",
        "LegalPersonAddressPostcode": "6578568",
        "LegalPersonAddressLine1En": "wuhedadao110",
        "LegalPersonBirthDate": "1998-10-03",
        "LegalSignedFile": "[{\"fileUrl\":\"common-test/2026/08/23/0544d5bb-b25c-4624-b5bf-7d3377f83a7f.png\",\"fileName\":\"IMG_4803.png\"}]",
        "LegalPersonIdNumber": "610481199810032210",
        "LegalPersonAddressProvinceEn": "gungdong",
        "LegalPersonGender": "0",
        "LegalPersonCityEngName": "shenzhen",
        "LegalPersonName": "晁旭阳",
        "LegalPersonIDCardAddress": "陕西省兴平市赵村镇晁庄村5组567号",
        "LegalPersonIDCardAddressEng": "shanxishengxingpingshizhaocunzhenyaozhangcun5zu567hao",
        "LegalPersonIDCardType": "IDCARD",
        "LegalPersonIdNumberFrontPic": [{
            "fileUrl": "common-test/2026/08/23/a034654a-c6dc-4288-8286-20d6bcf331b5.jpg",
            "fileName": "967db462-5e31-435f-8427-5554f1622547.jpg"
        }],
        "LocalTaxNumber": "87698798",
        "VATTaxNumber": "DE897889",
        "ExpectedSalesYear2": "20000",
        "ExpectedSalesYear1": "10000",
        "__attachments": "",
        "DELogisticsSituation": "DTM1 - Amazon Logistik Werne GmbH Raiffeisenstrasse 7 - 59368 - Werne, Germany",
        "ProductsRange": "household",
        "BusinessPlatform_En": "Amazon",
        "StoreFBAAcitveSetSetScreenShot": "[{\"fileUrl\":\"common-test/2026/08/23/f37d6757-eda4-4788-a63a-3518bce0a324.png\",\"fileName\":\"Fulfilment by Amazon Settings.png\"}]",
        "ShopName": "TANGLIXIA",
        "ShopUrl": "https://www.amazon.co.uk/sp?ie=UTF8&seller=AS9VCVVH2NHDI",
        "ShopAccount": "AS9VCVVH2NHDI",
        "StoreWarehouseAddressScreenShot": "[{\"fileUrl\":\"common-test/2026/08/23/c4a6039b-4eb0-476b-beab-899070933bcf.png\",\"fileName\":\"SendtOAmaZOn.png\"}]",
        "StoreOtherSetScreenShot": "[{\"fileUrl\":\"common-test/2026/08/23/bdba34d3-3f26-4849-ac14-b0e0c05edbeb.png\",\"fileName\":\"店铺前台截图.png\"}]",
        "CreditReportPic": "[{\"fileUrl\":\"common-test/2026/08/23/0d16928b-0acf-456c-884c-ed84b3b47ea4.png\",\"fileName\":\"Fulfilment by Amazon Settings.png\"}]",
        "EstablishmentDate": "2026-05-12",
        "RegisteredCapital": "100000",
        "NameEng": "yantaitanglixiashangmaoyouxiangongsi",
        "NameCN": "烟台棠梨下商贸有限公司",
        "RegAddressEng": "fu shan qu, hui li zhen zhen hong da jie 19hao 3089shi , yan tai shi , shan dong , 265500, CN",
        "CityEngName": "shenzhen",
        "RegNumber": "91370611MAKDGB0TXU",
        "CompanyAddressPostcode": "265500",
        "RegisteredCapitalCurrency": "CNY",
        "CompanyAddressLine1En": "hui li zhen zhen hong da jie 19hao 3089",
        "Country": "CN",
        "BusinessLicensePic": [{
            "fileUrl": "common-test/2026/08/23/87993443-f9cb-4ad0-a48c-a856d9815e21.jpg",
            "fileName": "b6941b80-7272-4802-9dc6-54ef534fe282.jpg"
        }]
    },
    "files": [
        {
            "url": "common-test/generatefile/2026/de_declar_delay/DVAT12312312312312313_123456_alle Anhänge in einem Dokument.pdf",
            "name": "DVAT12312312312312313_123456_alle Anhänge in einem Dokument.pdf",
            "type": "N合1文件",
            "pushType": "DE_VAT_REGISTER_FILE"
        }
    ]
}
```

**受理流程（vat_new_register_auto.php）：**

1. **入口校验**：`PushType` ∈ {`DE_VAT_REGISTER`, `DE_VAT_REGISTER_FILE`}、`Country=DE`、`Data` 非空数组。
2. **构建数据行**：`Country` 二字码→中文名（`CN`→中国、`HK`→香港）；**法人拼音兼容**——优先已传 `LegalPersonFullNamePinYin`（原样采用），缺失时按「名 姓」拼接 `LegalPersonNamePinyin`+`LegalPersonSurnamePinyin` → `LegalPersonFullNamePinYin`。
3. **国家限制**：仅支持 `中国` / `香港`，否则 400。
4. **文件字段归一**：原生数组统一转 JSON 字符串后参与校验；香港公司 CR/BR 证件必填校验。
5. **字段格式校验**：必填、中文字符、日期、金额、性别枚举、Amazon/FBA 与海外仓合同互斥等（规则同 vat_new_file_api.php）。
6. **中文转英 + 手机号格式化**：英文字段剔除中文；法人手机号按公司国家格式化（中国 +86、香港 +852/+86）。
7. **五合一文件校验**：从 `files` 取 `type=N_IN_ONE_FILE`（兼容 `N合1文件`，无匹配取第一项）的 `url`，直接使用 OSS 相对路径。
8. **落库**：按 `order_serial_number`（`bizParam.BusinessSerialNumber` ?: `Code`）查重——`status=2`（已成功）跳过；存在则更新；不存在则插入；返回自增 `id`。
9. **响应**：200 + `{order_serial_number, record_id, combined_attachment_path}` + 原样回传 `bizParam`。

---

### 4.4.11 法国VAT注册自动受理
> **PushType**：`FR_VAT_REGISTER`；**Country**：`FR`

**请求体即 `法国vat注册.json` 全文**：`Data` 与文件生成版（§4.4.5）同构，另携带顶层 `files`（5 类自动生成 PDF，`type` 为英文枚举，与文件生成接口返回一致，缺任一报「缺少必要的自动生成PDF文件(files)」）。转发层（countries/fr.php）透传到 `vat_api_fr_client/server/vat_new_register_auto.php` 落库 `vat_fr_register`（rpa 库），供门户自动注册消费。

```json
{
    "PushType": "FR_VAT_REGISTER",
    "Country": "FR",
    "Data": {
        "LegalPersonSurnamePinyin": "Zhu",
        "LegalPersonIdNumberBackPic": [{
            "fileUrl": "common-test/2026/08/23/b87d393f-589c-452f-bf35-47bdfa058906.jpg",
            "fileName": "身份证反面-1.jpg"
        }],
        "LegalPersonIdStartDate": "2019-08-05",
        "LegalPersonCountry": "CN",
        "LegalPersonNamePinyin": "Menglong",
        "LegalPersonIdEndDate": "2039-08-05",
        "Nationality": "汉",
        "LegalPersonPhone": "+86 17304425200",
        "LegalPersonBirthDate": "1988-09-19",
        "LegalSignedFile": null,
        "LegalPersonIdNumber": "420281198809193219",
        "LegalPersonEmail": "MenlongDLtHk@outlook.com",
        "LegalPersonGender": "男",
        "LegalPersonName": "朱梦龙",
        "LegalPersonIDCardAddress": "湖北省大冶市陈贵镇铜山口村张泗朱湾136号",
        "LegalPersonIDCardAddressEng": "hubeishengdayeshichenguizhentongshankoucunzhangsizhuwan136hao",
        "LegalPersonIDCardType": "IDCARD",
        "LegalPersonIdNumberFrontPic": [{
            "fileUrl": "common-test/2026/08/23/f136c0ff-d693-4f57-9837-102b121c8de7.jpg",
            "fileName": "身份证正面.jpg"
        }],
        "__extraFile": null,
        "LocalTaxNumber": "20260825",
        "Code": "0825",
        "VATTaxNumber": "FR0825",
        "TaxEffectiveDate": "2025-01-01",
        "ProductsRange": "electronic products childrens toys",
        "BusinessPlatform_En": "Amazon",
        "ShopName": "MENGLONGDA TECHNOLOGY",
        "ShopUrl": "https://www.amazon.it/sp?ie=UTF8&seller=A102OL1SHPTA29",
        "ShopAccount": "A102OL1SHPTA29",
        "BusinessConstitutionFile": "[{\"fileUrl\":\"common-test/2026/08/23/19b30cb7-6329-4e68-8c9f-d75076ecf7d2.pdf\",\"fileName\":\"Statuts dates et signes.pdf\"}]",
        "EstablishmentDate": "2025-11-24",
        "RegisteredCapital": "10000",
        "NameEng": "HONG KONG MENGLONGDA TECHNOLOGY CO., LIMITED",
        "RegAddressEng": "33-35 Au Pui Wan Street, Century Industrial Centre Room D4, Flat I, 4/F,Sha Tin Hong Kong 999077 HK",
        "CityEngName": "Century Industrial Centre",
        "RegNumber": "79244348",
        "CompanyAddressPostcode": "999077",
        "RegisteredCapitalCurrency": "CNY",
        "CompanyAddressLine1En": "33-35 Au Pui Wan Street",
        "Country": "HK",
        "BusinessLicensePic": [{
            "fileUrl": "common-test/2026/08/23/b3ea5f07-98a2-4abd-8399-bb0f163416b9.pdf",
            "fileName": "BR-香港夢灌達科技有限公司.pdf"
        }],
        "FirstPendingSaveBusinessTime": "2026-08-25"
    },
    "files": [
        {
            "url": "common-test/generatefile/2026/fr_declar/Mandat-HONG KONG MENGLONGDA TECHNOLOGY CO., LIMITED.pdf",
            "name": "Mandat-HONG KONG MENGLONGDA TECHNOLOGY CO., LIMITED.pdf",
            "type": "AUTHORIZATION_LETTER"
        },
        {
            "url": "common-test/generatefile/2026/fr_declar/0825_FR_Status.pdf",
            "name": "0825_FR_Status.pdf",
            "type": "COMPANY_ARTICLES_ORIGINAL"
        },
        {
            "url": "common-test/generatefile/2026/fr_declar/0825_FR_ID.pdf",
            "name": "0825_FR_ID.pdf",
            "type": "ID_CARD_MERGED"
        },
        {
            "url": "common-test/generatefile/2026/fr_declar/0825_FR_Kbis.pdf",
            "name": "0825_FR_Kbis.pdf",
            "type": "BUSINESS_LICENSE_MERGED"
        },
        {
            "url": "common-test/generatefile/2026/fr_declar/0825_FR_KJ_Status_FR.pdf",
            "name": "0825_FR_KJ_Status_FR.pdf",
            "type": "ARTICLES_TRANSLATION"
        }
    ],
    "bizParam": {
        "deliveryId": 57827,
        "pushType": "FR_VAT_REGISTER_FILE",
        "operatorId": 93,
        "operatorTime": "2026-08-26 20:30:18",
        "BusinessSerialNumber": "FR2026082509563715",
        "BusinessId": "57827"
    }
}
```

**受理流程（vat_new_register_auto.php）：**

1. **入口校验**：`PushType` ∈ {`FR_VAT_REGISTER`, `FR_VAT_REGISTER_FILE`}、`Country=FR`、`Data` 非空数组。
2. **构建业务记录**：`Country` 二字码→中文名（`CN`→中国、`HK`→香港）；`LegalPersonNamePinyin`+`LegalPersonSurnamePinyin` → `LegalPersonFullNamePinYin`（已传该字段则优先）；法人城市/地址缺失时用公司字段兜底；`IsEUMember` 按公司国家 ∈ 欧盟27国列表推导。
3. **国家限制**：仅支持 `中国` / `香港`，否则 400。
4. **文件字段归一**：原生数组统一转 JSON 字符串后参与校验。
5. **字段格式校验**：必填、中文字符、邮箱正则、日期格式、邮政编码长度（规则同 register.php `validateFRVATRegisterFields`；**香港分支放宽**：不强制 CR/NNC1 必填，因自动生成 PDF 已由 files 提供）。
6. **国家反查**：按法人国家二字码查 `config/country_cache.json` 得 `CountryName_fr`（如 CN→`CHINE`）与 `french_title`（如 CN→`Chinoise`）。
7. **税所配置**：公司国家非欧盟且非 GB/NI 时使用 KJ 税所常量并上传 `resources/template/KJ-ID.pdf`；欧盟（含 GB/NI）使用 MOKJ 常量。
8. **5 类 PDF 提取**：按 `type` 映射提取 files 中的 url（`AUTHORIZATION_LETTER`→mandat、`ARTICLES_TRANSLATION`→章程翻译件、`ID_CARD_MERGED`→身份证合并件、`BUSINESS_LICENSE_MERGED`→营业执照合并件、`COMPANY_ARTICLES_ORIGINAL`→公司章程原件）。
9. **落库**：按 `tid`（`Data.Code`）查重——存在则更新、不存在则插入 `vat_fr_register`（SqlServerDb 内置 86 字段方法，常量覆盖由 vat_constants.php 处理）；成功后按 tid 查回 `id`。
10. **响应**：200 + `{tid, record_id}` + 原样回传 `bizParam`。

---

### 4.4.12 意大利VAT注册自动受理（AA7）
> **PushType**：`IT_VAT_REGISTER`（AA7）；**Country**：`IT`

**请求体（接口取数模式）**：SaaS 推送方调用本接口，`Data` 携带 AA7 注册所需业务字段（即原 job 定时任务从 `VATBusinessRecord` / `Base_Customer_Company` 联查出的字段，现由调用方直接推送，**不再由中转层直连 SaaS 库取数**）；`bizParam` 携带订单标识。转发层（countries/it.php）透传到 `vat_api_it_client` 下游接口落库 `it_profis_register`（rpa 库），供门户自动注册（PROFIS）消费。

```json
{
    "PushType": "IT_VAT_REGISTER_AA7",
    "Country": "IT",
    "bizParam": {
        "BusinessSerialNumber": "POVAT20260421000235",
        "BusinessId": "3301",
        "VATRegInfoId": "88012"
    },
    "Data": {
        "NameCN": "米兰星光贸易有限公司",
        "NameEng": "MILAN STAR TRADING S.R.L.",
        "RegAddressEng": "Via Roma 1, 20121 Milano",
        "RegAddressProvince": "15201",
        "RegAddressCity": "152",
        "RegNumber": "12345678901",
        "Country": "中国",
        "CountryName_en": "China",
        "CountryTwoCode": "CN",
        "LegalPersonSurnamePinyin": "WANG",
        "LegalPersonNamePinyin": "Xiaoming",
        "LegalPersonPhone": "+86 13800000000",
        "LegalPersonEmail": "legal@test.com",
        "LegalSignedFile": "[{\"fileUrl\":\"https://file.usaeu.com/annexes/signature.png\",\"fileName\":\"signature.png\"}]"
    }
}
```

**受理流程（vat_api_it_client 下游接口）：**

1. **入口校验**：`PushType` = `IT_VAT_REGISTER_AA7`、`Country=IT`、`Data` 非空数组。
2. **香港特殊处理**：`Country='香港'` 时强制 `CompanyAddressProvinceEn='HONGKONG'`、`CityEngName='HONGKONG'`（绕过区域反查）。
3. **字段校验**（packFieldFormats，规则见下表）；校验失败→rpa 库 `it_profis_register` 置 `status=-1` + 写入 `msg`，SaaS 库 `VATRegInfo` 置 `PushTaxBureauStatus=-1` + `PushTaxBureauErrorMsg`；校验通过继续。
4. **幂等查重**：按 `tid`（`bizParam.BusinessSerialNumber`）查 `it_profis_register`——已存在且 `status=2`（成功）直接跳过；存在则更新；不存在则插入。
5. **省份/城市反查**：`CompanyAddressProvinceEn` 缺失时用 `RegAddressProvince`（区域 ID）查 `Base_Area.F_QuickQuery` 得省份拼音/简写；城市同理（`CityEngName` 缺失时用 `RegAddressCity`）。
6. **落库**：按字段映射表写入 `it_profis_register`（`status=0` 待处理、`manual_type=0`、`retry_count=0`），返回自增 `id`。
7. **响应**：200 + `{tid, record_id}` + 原样回传 `bizParam`。

**校验规则（packFieldFormats）：**

| 字段 | 校验规则 | 错误提示 |
| --- | --- | --- |
| `NameEng` | 必填 | 公司英文名称 不能为空 |
| `RegAddressEng` | 必填 | 公司地址 不能为空 |
| `RegNumber` | 必填 | 公司营业执照号 不能为空 |
| `Country` | 必填 | 公司注册所在国 不能为空 |
| `RegNumber` | 正则 `^[a-zA-Z0-9 ]+$` | 公司营业执照号只能包含数字、英文字母和空格 |
| `CompanyAddressProvinceEn` / `RegAddressProvince` | 二选一必填；用 `RegAddressProvince` 时必须为数字（区域 ID） | 公司注册所在省份 不能为空 / 异常 |
| `CityEngName` / `RegAddressCity` | 二选一必填；用 `RegAddressCity` 时必须为数字 | 公司所在城市 不能为空 / 异常 |

**落库字段映射**（`it_profis_register`）：

| 目标字段 | 来源 | 说明 |
| --- | --- | --- |
| `tid` | `bizParam.BusinessSerialNumber` | 订单流水号 |
| `businessID` | `bizParam.BusinessId` | 业务单 ID |
| `VATRegInfoId` | `bizParam.VATRegInfoId` | 注册信息表 ID（状态回写用） |
| `country` | `Data.Country` | 国家（中文） |
| `saas_country` | `Data.CountryName_en` | 国家英文名 |
| `company_name_en` | `Data.NameEng`（trim） | 公司英文名 |
| `company_name_cn` | `Data.NameCN` | 公司中文名 |
| `regAddressEng` | `Data.RegAddressEng`（trim） | 公司地址 |
| `cityEngName` | `Data.CityEngName` 或反查结果（trim） | 城市 |
| `provinceEng` | `Data.CompanyAddressProvinceEn` 或反查结果（trim） | 省份 |
| `register_num` | `Data.RegNumber`（trim） | 公司营业执照号 |
| `status` | 固定 `0` | 0=待处理 |
| `type` | 固定 `0` | 类型 |
| `retry_count` | 固定 `0` | 重试次数 |
| `manual_type` | 固定 `0` | 手动类型 |
| `created_time` / `updated_time` | `date('Y-m-d H:i:s')` | 创建/更新时间 |

---

### 4.4.13 意大利VAT注册自动受理（ANR3）
> **PushType**：`IT_VAT_REGISTER_ANR3`；**Country**：`IT`

**请求体（接口取数模式）**：SaaS 推送方调用本接口，`Data` 携带 ANR3 注册基础业务字段（`ProfisCode` 等），**税号证书 PDF 通过顶层 `files` 传入**（证书附件不再由下游查 `Base_AnnexesFile` 获取，改由调用方直接提供 OSS 路径，下游下载后 OCR 提取字段）；`bizParam` 携带订单标识。转发层（countries/it.php）透传到 `vat_api_it_client` 下游接口，OCR 解析后落库 `anr3_it_profis_register`（rpa 库），供门户自动注册（PROFIS）消费。

```json
{
    "PushType": "IT_VAT_REGISTER_ANR3",
    "Country": "IT",
    "bizParam": {
        "BusinessSerialNumber": "POVAT20260210000161",
        "BusinessId": "3302",
        "VATRegInfoId": "88013"
    },
    "Data": {
        "NameCN": "米兰星光贸易有限公司",
        "ProfisCode": "300001",
        "ProvinceEngName": "Lombardy",
        "LegalPersonSurnamePinyin": "ZHU",
        "LegalPersonNamePinyin": "Menglong",
        "LegalPersonCityEngName": "Milan",
        "CompanyID": "88001",
        "LocalCountryTaxNumber": ""
    },
    "files": [
        {
            "url": "https://vat-1259285998.cos.ap-guangzhou.myqcloud.com/vat_factory/fdc96d32-50ea-4aef-aa07-ab6fef6e7257/20260729/wu_1jultdktu1ndgr171qg2181114ud7.pdf",
            "name": "tax_certificate_POVAT20260210000161.pdf",
            "type": "TAX_CERTIFICATE"
        }
    ]
}
```

**受理流程（vat_api_it_client 下游接口）：**

1. **入口校验**：`PushType` = `IT_VAT_REGISTER_ANR3`、`Country=IT`、`Data` 非空数组、`files` 须携带税号证书 PDF（`type=TAX_CERTIFICATE`），缺失报「PDF税号证书附件为空」。
2. **基础字段校验**：仅 `ProfisCode`（注册 code）必填。
3. **证书 PDF 下载**：取 `files` 中证书 url（兼容原 `Base_AnnexesFile.F_FilePath` 内网盘路径，前缀按 `MAIN_SITE_PATH`→`FILE_SITE_PATH` 替换：生产 `G:/fileAnnexes`→`https://file.usaeu.com`，测试 `G:/fileAnnexesTest`→`http://testfile.usaeu.com`），下载到 `resources/anr3/{VATRegInfoId}/{tid}.pdf`；下载失败报错。
4. **PDF 文本提取（双通道降级）**：
   - 第一通道：调用 `python public/ANR3.py {pdf绝对路径}`（pdfplumber 逐页 `extract_text()`，空页尝试 `extract_tables()`），输出 JSON `{code:200, data:{text}}`；
   - 第二通道：JSON 解析失败 / `code≠200` / `data.text` 为空时降级 `PaddleOcrClient`（百度千帆 OCR，`recognizePdf()` + `extractPlainText()`）；
5. **正则解析**：按关键字正则提取 13 个字段（明细见下表），法人地址/城市/国家缺失时用公司对应字段兜底。
6. **必填校验**：13 项字段缺失报「{名称}未识别到」；失败→`VATRegInfo` 置 `PushTaxBureauStatus=-1` + 错误信息。
7. **落库**：按 `tid`（`bizParam.BusinessSerialNumber`）查 `anr3_it_profis_register`——存在则更新、不存在则插入（`status=0` 待处理、`manual_type=1`），返回自增 `id`。
8. **SaaS 反写（成功路径）**：
   - `Base_Customer_Company`：`LegalPersonFullNamePinYin` = OCR 名（去空格）+ 空格 + OCR 姓（去空格），`LegalPersonCityEngName` = OCR 法人城市；
   - `LocalCountryTaxNumber` 为空时回写 `VATBusinessRecord.LocalCountryTaxNumber` = OCR 提取的本国税号（`ocr_register_num`）。
9. **响应**：200 + `{tid, record_id}` + 原样回传 `bizParam`。

**正则解析明细（parsePdfContent，均不区分大小写）：**

| 目标字段 | 正则模式 | 说明 |
| --- | --- | --- |
| `ocr_company_vat_number` | `CODICE FISCALE :\s*(\S+)` | 公司税号（CF） |
| `ocr_company_name_en` | `DENOMINAZIONE :\s*(.+)` | 公司名称 |
| `ocr_register_num` | `CODICE ESTERO :\s*(\S+)` | **本国税号**（SaaS 反写用） |
| `ocr_company_country` | `UFFICIO COMPETENTE DELLO STATO ESTERO :\s*([^\n]+)` | 公司国家（初值） |
| `ocr_company_address_line2_en` | `SEDE LEGALE...INDIRIZZO\s*:\s*([^\n]+)` | 公司地址 |
| `ocr_company_address_city_en` | `CITTA' :\s*(.+?)\s+STATO ESTERO :` | 公司城市 |
| `ocr_company_country`（覆盖） | 截取 `CITTA'` 到 `DATI ANAGRAFICI DEL RAPPRESENTANTE` 段内匹配 `STATO ESTERO :\s*([^\n#]+)` | 精确公司国家 |
| `ocr_legal_vat_number` | `DATI ANAGRAFICI DEL RAPPRESENTANTE.*?CODICE FISCALE :\s*(\S+)(?:\s*\(PRIMA ATTRIBUZIONE\))?` | 法人税号 |
| `ocr_legal_person_gender` | `SESSO:\s*(F|M)` | 法人性别（转大写） |
| `ocr_legal_person_last_name` | `COGNOME :\s*(.+?)\s+NOME :` | 法人姓 |
| `ocr_legal_person_first_name` | `\bNOME :\s*([^\n]+)` | 法人名 |
| `ocr_legal_person_address_line1_en` | `RESIDENZA ESTERA...INDIRIZZO\s*:\s*([^\n]+)` | 法人地址 |
| `ocr_legal_person_address_city_en` | `RESIDENZA ESTERA...CITTA'\s*:\s*([^\n]+)` | 法人城市 |
| `ocr_legal_person_country` | `RESIDENZA ESTERA.*?STATO ESTERO :\s*([^\n#]+)` | 法人国家 |

**必填校验（13 项）**：公司税号 / 公司名称 / 本国税号 / 公司国家 / 公司地址 / 公司城市 / 法人税号 / 法人性别 / 法人姓 / 法人名 / 法人地址 / 法人城市 / 法人国家。

**落库字段映射**（`anr3_it_profis_register`，业务字段全部来自 OCR 结果）：

| 目标字段 | 来源 | 说明 |
| --- | --- | --- |
| `tid` | `bizParam.BusinessSerialNumber` | 订单流水号 |
| `businessID` | `bizParam.BusinessId` | 业务 ID |
| `VATRegInfoId` | `bizParam.VATRegInfoId` | 注册信息 ID |
| `ANR3_code` | `Data.ProfisCode` | 业务代码 |
| `company_name_en` | `ocr_company_name_en`（trim） | 公司英文名（OCR） |
| `company_name_cn` | `Data.NameCN`（trim） | 公司中文名（SaaS） |
| `company_country` | `ocr_company_country`（trim） | 公司注册国家（OCR） |
| `company_address_line2_en` | `ocr_company_address_line2_en`（trim） | 公司地址（OCR） |
| `company_address_city_en` | `ocr_company_address_city_en` | 公司城市（OCR） |
| `company_address_province_en` | `Data.ProvinceEngName`（trim） | 公司省份（SaaS） |
| `company_vat_number` | `ocr_company_vat_number` | 公司 VAT 号码（OCR） |
| `register_num` | `ocr_register_num` | 注册号码-本国税号（OCR） |
| `legal_person_gender` | `ocr_legal_person_gender` | 法人性别（OCR） |
| `legal_vat_number` | `ocr_legal_vat_number` | 法人 VAT 号码（OCR） |
| `legal_person_last_name` | `ocr_legal_person_last_name`（trim） | 法人姓（OCR） |
| `legal_person_first_name` | `ocr_legal_person_first_name`（trim） | 法人名（OCR） |
| `legal_person_country` | `ocr_legal_person_country` | 法人国家（OCR） |
| `legal_person_address_line1_en` | `ocr_legal_person_address_line1_en` | 法人地址（OCR） |
| `legal_person_address_city_en` | `ocr_legal_person_address_city_en` | 法人城市（OCR） |
| `manual_type` | 固定 `1` | 手动类型 |
| `status` | 固定 `0` | 0=待处理 |
| `retry_count` | 固定 `0` | 重试次数 |
| `msg` | 空串 | 消息 |
| `created_time` / `updated_time` | `date('Y-m-d H:i:s')` | 创建/更新时间 |

> 法人姓/名直接取自 OCR 的 COGNOME / NOME 字段（不再按空格拆分 "名 姓"）；已存在记录也会被更新（无 `status=2` 跳过逻辑，与 AA7 不同）。

---

### 4.4.14 意大利 PROFIS 注册接口化改造设计

> **适用 PushType**：`IT_VAT_REGISTER`（AA7）/ `IT_VAT_REGISTER_ANR3`（ANR3）
>
> 本节为**接口化改造设计说明**（代码尚未实现）：将意大利 AA7 / ANR3 PROFIS 注册的取数方式从「job 定时任务直连 SaaS 数据库」改造为「三方调用方通过本中转接口推送数据」（与德/法 VAT 注册受理一致），后续代码按本节与 §4.4.12 / §4.4.13 的契约落地。

#### 4.4.14.1 现状与问题

当前实现（`vat_api_it_client/job/`，改造前）：

```
SaaS vat_db 库（VATBusinessRecord / Base_Customer_Company / VATRegInfo / VATTaxNumber / Base_AnnexesFile）
   ↑ 直连查询（PushTaxBureauStatus=1 且 PushType=109/110）
job/aa7_profis_it_register.php（TOP 130） / job/anr3_profis_it_register.php（TOP 1）
   ↓ 校验 / OCR / 字段转换
rpa 库（it_profis_register / anr3_it_profis_register）
   ↓ 回写
SaaS vat_db 库（VATRegInfo.PushTaxBureauStatus / Base_Customer_Company / VATBusinessRecord）
```

存在问题：

1. **强耦合 SaaS 内网数据库**：job 脚本需要直连 SaaS 的 `vat_db` 库（含账号密码），中转侧无法跨网络/跨环境部署；
2. **定时轮询而非事件驱动**：依赖 `PushTaxBureauStatus=1` 轮询，存在处理延迟，且每次取数条件（PushType 109/110）与取数上限（TOP 130 / TOP 1）硬编码在脚本中；
3. **与统一中转架构不一致**：德/法已改为接口取数（SaaS 推送 → api.php → 下游落库），意大利仍走直连，维护两套模式成本高。

#### 4.4.14.2 改造目标

- **取数接口化**：SaaS 侧在数据就绪时主动调用本接口（PushType=`IT_VAT_REGISTER` / `IT_VAT_REGISTER_ANR3`），`Data` / `files` 携带全部业务数据，中转层不再直连 SaaS 库取数；
- **与德/法模式对齐**：统一「SaaS 推送 → app_withdrawn（api.php）→ countries/it.php 转发 → vat_api_it_client 下游接口 → 落库 rpa」链路，响应统一 `{code, msg, data, bizParam}`，ProcessMode 默认 `async`；
- **保留既有业务规则**：字段校验（packFieldFormats）、香港特殊处理、幂等查重、OCR 双通道提取、SaaS 反写等规则原样迁移到下游接口；
- **job 脚本下线**：改造完成后 `job/aa7_profis_it_register.php`、`job/anr3_profis_it_register.php` 不再承担取数职责（可保留作手动重跑工具或删除）。

#### 4.4.14.3 改造后数据流（目标态）

```
SaaS 调用方（原 job 取数逻辑前移到 SaaS 侧，联表后组装 Data）
   │ POST {PushType, Country, bizParam, Data, files?}
   ▼
api.php（校验 PushType/Country → 加载 countries/it.php）
   ▼
countries/it.php::IT_VAT_REGISTER / IT_VAT_REGISTER_ANR3（转发层，resolveDownstreamUrl + httpPostJson）
   ▼ 透传完整请求参数
vat_api_it_client 下游接口（server/vat_profis_register_api.php，新增）
   ├─ 入口校验 / packFieldFormats 字段校验
   ├─ AA7：香港特殊处理 → 省份/城市 Base_Area 反查 → 落库 it_profis_register
   ├─ ANR3：files 证书 PDF 下载 → OCR（python pdfplumber → PaddleOCR 降级）
   │        → 正则解析 13 字段 → 落库 anr3_it_profis_register
   │        → SaaS 反写（法人姓名/城市、本国税号）
   └─ 返回 {code, msg, data:{tid, record_id}}（ProcessMode=async）
```

#### 4.4.14.4 接口契约

| 项 | IT_VAT_REGISTER（AA7） | IT_VAT_REGISTER_ANR3（ANR3） |
| --- | --- | --- |
| 请求示例 | 见 §4.4.12 | 见 §4.4.13 |
| `bizParam` | `BusinessSerialNumber`（=tid）/ `BusinessId`（=businessID）/ `VATRegInfoId` | 同左 |
| `Data` | 公司/法人/地址业务字段（`NameEng` / `RegAddressEng` / `RegNumber` / `Country` / 省/市等） | 基础字段（`NameCN` / `ProfisCode` / `ProvinceEngName` 等），主体字段由 OCR 提取 |
| `files` | 不传 | 必传税号证书 PDF（`type=TAX_CERTIFICATE`，OSS 相对路径或完整 URL） |
| 响应 | `{code:200, data:{tid, record_id}}` + 原样回传 `bizParam` | 同左 |
| ProcessMode | 转发层默认 `async`（受理即返回） | 同左 |

#### 4.4.14.5 字段取数口径（原 SQL → 请求体）

改造后 SaaS 调用方推送的 `Data` / `bizParam` 字段，取值口径与原 job 取数 SQL 一致：

| 原 SQL 来源（vat_db 联表） | 请求体位置 | 说明 |
| --- | --- | --- |
| `br.Code` | `bizParam.BusinessSerialNumber` | 订单流水号（tid） |
| `br.ID` | `bizParam.BusinessId` | 业务单 ID（businessID） |
| `vr.Id` | `bizParam.VATRegInfoId` | 注册信息表 ID（状态回写用） |
| `br.ProfisCode`（仅 ANR3） | `Data.ProfisCode` | 业务代码（ANR3_code） |
| `c.NameEng` / `c.NameCN` | `Data.NameEng` / `Data.NameCN` | 公司中英文名 |
| `c.RegAddressEng` | `Data.RegAddressEng` | 公司地址 |
| `c.RegNumber` | `Data.RegNumber` | 公司营业执照号 |
| `c.Country` / `c.CountryName_en` | `Data.Country` / `Data.CountryName_en` | 国家中文 / 英文 |
| `c.CityEngName` / `c.RegAddressCity` | `Data.CityEngName` / `Data.RegAddressCity` | 城市（二选一） |
| `c.CompanyAddressProvinceEn` / `c.RegAddressProvince` | `Data.CompanyAddressProvinceEn` / `Data.RegAddressProvince` | 省份（二选一） |
| `vt.TaxCertificate`（仅 ANR3，原查 Base_AnnexesFile） | `files[].url` | 税号证书 PDF（`type=TAX_CERTIFICATE`） |
| `br.LocalCountryTaxNumber`（仅 ANR3） | 不推送（由下游按 OCR 结果与现状判定是否回写） | 本国税号 |

> 原 SQL 中 `LEFT JOIN` 取不到值（`c.*` 为空）时按现状由下游兜底：字段缺失按校验规则报错或按回退逻辑处理，行为与 job 版一致。

#### 4.4.14.6 状态与幂等约定

| 位置 | 状态值 | 含义 |
| --- | --- | --- |
| `VATRegInfo.PushTaxBureauStatus` | `1` | 待推送（原取数条件，改造后由 SaaS 侧维护） |
| `VATRegInfo.PushTaxBureauStatus` | `2` | 推送成功（下游落库成功后回写，清空错误信息） |
| `VATRegInfo.PushTaxBureauStatus` | `-1` | 推送失败（下游回写 `PushTaxBureauErrorMsg`） |
| `it_profis_register.status` | `0` / `2` / `-1` | 待处理 / 已成功（幂等跳过依据）/ 校验失败 |
| `anr3_it_profis_register.status` | `0` | 待处理 |

- 幂等：AA7 按 `tid` 查重，已存在且 `status=2` 直接跳过，存在则更新，不存在则插入；ANR3 按 `tid` 查重，存在则更新、不存在则插入（无跳过逻辑）。
- 失败处理：下游返回 `code=400` + 分号拼接错误信息，`data=null`；中转层原样透传。

#### 4.4.14.7 部署与代码改造清单（实施步骤）

1. **vat_api_it_client 新增下游接口** `server/vat_profis_register_api.php`：
   - 入口校验 `PushType` ∈ {`IT_VAT_REGISTER`, `IT_VAT_REGISTER_ANR3`}（ANR3 还须校验 `files` 含 `TAX_CERTIFICATE`）；
   - 迁移 `job/aa7_profis_it_register.php` 的 `packFieldFormats` / 香港处理 / `Base_Area` 反查 / `it_profis_register` 落库逻辑；
   - 迁移 `job/anr3_profis_it_register.php` 的证书下载（前缀替换）/ `ANR3.py` + PaddleOCR 双通道 / `parsePdfContent` / `anr3_it_profis_register` 落库 / SaaS 反写逻辑；
   - 返回 `{code, msg, data:{tid, record_id}}`，`bizParam` 原样回传。
2. **app_withdrawn 转发层** `countries/it.php`：新增 `IT_VAT_REGISTER` / `IT_VAT_REGISTER_ANR3` 方法（参照现有 `IT_EPR_REGISTER`：`resolveDownstreamUrl` + `httpPostJson` 透传完整请求参数）。
3. **下游地址配置** `config/downstream.php`：新增常量 `IT_VAT_REGISTER_API_URL`、`IT_VAT_REGISTER_ANR3_API_URL`（指向 vat_api_it_client 下游接口，测试/生产各一）。
4. **SaaS 侧改造**：将原 job 的取数 SQL（§4.4.12 / §4.4.13 取数字段）迁移为「推送前组装」逻辑，数据就绪后调用本接口；ANR3 证书附件按 `Base_AnnexesFile.F_FilePath` 替换为可下载 URL 放入 `files`。
5. **下线 job 定时任务**：确认推送链路稳定后，停止 `job/aa7_profis_it_register.php`、`job/anr3_profis_it_register.php` 的定时调度。

#### 4.4.14.8 待定项 / 边界说明

- **SaaS 反写方式**：ANR3 成功后需回写 `Base_Customer_Company`（法人姓名/城市）与 `VATBusinessRecord`（本国税号）。设计上**由下游直连 SaaS 库回写（保持现状）**；若后续要求下游零直连，可改为经本中转接口新增回写端点，或由 SaaS 侧在收到成功响应后自行回写。
- **OCR 依赖**：下游接口继续依赖本机 `python` + `pdfplumber`（`public/ANR3.py`）与百度千帆 OCR Key（`BAIDU_OCR_FILE_API_KEY`），部署环境需具备；
- **转发常量 fail-closed**：`IT_VAT_REGISTER_API_URL` / `IT_VAT_REGISTER_ANR3_API_URL` 未定义或为空串时返回 400（不回落 `HTTP_HOST`，防 SSRF）。

---

### 4.4.15 德国VAT申报延缓自动受理
> **PushType**：`DE_VAT_APPLICATION_DELAY`；**Country**：`DE`

**接口取数模式**：SaaS 调用方（原 job/vat_De_Application_Delay.php 取数 SQL 前移到 SaaS 侧，联表后组装 `Data`）主动调用本接口，`Data` 携带全部业务字段，中转层与下游**不再直连 SaaS 库取数**。转发层（countries/de.php）透传到 `vat_api_de_client/server/vat_new_Application_Delay.php`，校验通过后：月报（`DeclarationMethod=0`）自动生成「延缓申报确认函」PDF 并上传 OSS，数据落库 `vat_de_application_delay`（rpa 库），供门户自动申报消费。

```json
{
    "PushType": "DE_VAT_APPLICATION_DELAY",
    "Country": "DE",
    "bizParam": {
        "BusinessSerialNumber": "POVATD202605095397376",
        "BusinessId": "88013"
    },
    "Data": {
        "BusinessCode": "YR951",
        "DeclarationIntervalStart": "2025-10-01",
        "DeclarationIntervalEnd": "2025-10-31",
        "VATNumber": "15/385/78627",
        "LocalTaxNumber": "",
        "NameCN": "深圳市新润科技有限公司",
        "NameEng": "Shenzhen Xinrun Technology Co., Ltd.",
        "Country": "CN",
        "PreviousYearTotalTax": 385,
        "TaxDeposit": 35,
        "DeclarationMethod": "0"
    }
}
```

**受理流程（vat_new_Application_Delay.php）：**

1. **入口校验**：`PushType` = `DE_VAT_APPLICATION_DELAY`、`Country=DE`、`Data` 非空数组、`bizParam.BusinessSerialNumber` 必填。
2. **构建数据行**：`bizParam.BusinessSerialNumber` → `DeclareSerialNumber`（落库 `tid`）、`bizParam.BusinessId` → `DeclareId`（落库 `VATBusinessID`，即原 SQL `vi.ID`）；`Country` 二字码→中文名（`CN`→中国、`HK`→香港，未知原样）。
3. **类型转换**：`PreviousYearTotalTax` / `TaxDeposit` 空值转 `0` 并转 `float`。
4. **税号逻辑**：`VATNumber` 不以 `DE` 开头 → 直接采用；否则 `LocalTaxNumber` 不以 `DE` 开头时采用；最终赋给 `VATNumber`（与原 job 一致）。
5. **字段校验**（规则见下表）；校验失败→返回 400 + 分号拼接错误信息（**不回写 SaaS 库状态**，由调用方处理）。
6. **幂等查重**：按 `tid` + `BusinessCode` 查 `vat_de_application_delay`——已存在且 `status` ∈ {2,3} 返回 200「该记录已存在且成功，跳过」；存在则更新；不存在则插入。
7. **月报生成确认函**：`NameCN` 清洗（仅保留中文/英文）→ `ApplicationDelay_template_CN.docx` 模板变量替换（`$name`/`$vatnumber`/`$Vat_payable`/`$Payment_deadline`/`$Payment_remark`）→ LibreOffice 转 PDF → 上传 OSS（`OSSDelay_FILE_PATH`）→ `pay_file_path`；文件名 `延缓申报确认函_{BusinessCode}_{NameCN}_德国_{VATNumber}_月报_{开始}_{结束}.pdf`。季报（`DeclarationMethod=1`）跳过此步，`pay_file_path` 为空。
8. **落库**：更新/插入 `vat_de_application_delay`，`status=0` 待处理，返回自增 `id`。
9. **响应**：200 + `{tid, record_id}` + 原样回传 `bizParam`（ProcessMode 默认 `async`）；PDF 生成/OSS 上传失败返回 400。

**字段校验规则：**

| # | 规则 | 说明 |
| --- | --- | --- |
| 1 | `NameEng` / `NameCN` 必填 | 公司中英文名不能为空 |
| 2 | `NameEng` 不能含中文/日文/韩文/中文标点 | 只允许英文字母、数字、空格和英文标点（特殊字符报错，见 SAAS 售后群案例） |
| 3 | `DeclarationMethod` ∈ {`0`, `1`} | 目前只支持月报和季报延缓申报 |
| 4 | 月报延缓申报需上一年税额总额 | `PreviousYearTotalTax` 须 > 0 |
| 5 | `VATNumber` / `LocalTaxNumber` 格式 | `VATNumber` 为空且不含 `/` 时报错 |
| 6 | `VATNumber` 必须以 `15/` 开头 | 目前不支持柏林外的税局 |
| 7 | `TaxDeposit` = `ceil(PreviousYearTotalTax / 11)` | 担保金额必须等于上一年总额除以 11 向上取整的值 |

**落库字段映射**（`vat_de_application_delay`）：

| 目标字段 | 来源 | 说明 |
| --- | --- | --- |
| `tid` | `bizParam.BusinessSerialNumber` | 订单流水号（`DeclareSerialNumber`） |
| `VATBusinessID` | `bizParam.BusinessId` | VATRegInfo.ID（原 SQL `vi.ID`） |
| `BusinessCode` | `Data.BusinessCode` | 业务代码 |
| `company_name_en` | `Data.NameEng` | 公司英文名 |
| `company_name_cn` | `Data.NameCN`（清洗后） | 公司中文名（仅保留中英文） |
| `country` | `Data.Country` | 公司注册国（二字码→中文名） |
| `vat_number` | 税号逻辑后的 `VATNumber` | VAT 税号 |
| `type` | `Data.DeclarationMethod` | 类型：0-月报，1-季报 |
| `DeclarationIntervalStart` | `Data.DeclarationIntervalStart` | 申报开始时间 |
| `DeclarationIntervalEnd` | `Data.DeclarationIntervalEnd` | 申报结束时间 |
| `pay_file_path` | 月报：OSS URL；季报：空串 | 延缓申报确认函 OSS 路径 |
| `status` | 固定 `0` | 0=待处理 |
| `retry_count` | 固定 `0` | 重试次数 |
| `TaxDeposit` | `Data.PreviousYearTotalTax` | 去年总税额 |
| `created_time` / `updated_time` | `date('Y-m-d H:i:s')` | 创建/更新时间 |

> **状态回写（SaaS 侧约定）**：下游零直连 SaaS 库——`VATRegInfo.PushTaxBureauStatus` 由调用方维护：`1`=待推送（原取数条件）；收到本接口 200 → 置 `2` 并清空错误信息；收到 400 → 置 `-1` 并写 `PushTaxBureauErrorMsg`（按 `bizParam.BusinessId` 定位，`PushType='203'`）。
>
> **与 job 版行为差异**：① 校验失败/PDF 生成失败不再直连 SaaS 库回写状态，错误信息经响应透传；② 幂等跳过（status∈{2,3}）返回 200 视为成功（job 版返回字符串被误判为失败）；③ `Payment_deadline`（2026-02-10 前固定 `10`，之后当前日期+3 天）与 `Payment_remark`（`StNr {VATNumber} SVZ  2026`）逻辑原样保留。

---

### 4.4.16 德国EPR包装法注册自动受理
> **PushType**：`DE_EPR_REGISTER_PACK`；**Country**：`DE`

**请求体即 `德国EPR注册.json` 全文**（接口取数模式）：SaaS 调用方（原 job/german_pack_register.php 取数 SQL 前移到 SaaS 侧，联表后组装 `Data`）主动调用本接口，`Data` 携带注册所需业务字段（公司 / 法人 / 品类品牌 / 材质规格等），**不再由中转层 / 下游直连 SaaS 库取数**。转发层（countries/de.php）透传到 `vat_api_de_client/server/de_new_epr_pack_register_api.php`，校验通过后写入本地 `pack_de_register` 表（rpa 库，`pack_type=0` 注册），供门户自动注册（德国包装法）消费；注册邮箱由受理时自动创建（已存在则沿用）。

```json
{
    "PushType": "DE_EPR_REGISTER_PACK",
    "Country": "DE",
    "bizParam": {
        "BusinessSerialNumber": "DEPK202609020001",
        "BusinessId": "91001",
        "EPRRegInfoId": "99001"
    },
    "Data": {
        "NameCN": "德国测试贸易有限公司",
        "NameEng": "Germany Test Trading Co., Ltd.",
        "CompanyAddressLine1En": "No. 88, Central Avenue",
        "RegAddressEng": "No. 88, Central Avenue",
        "CompanyAddressPostcode": "10117",
        "CityEngName": "Berlin",
        "Country": "CN",
        "CountryName_en": "China",
        "CountryTwoCode": "CN",
        "RegNumber": "91310000MA1FL1TEST",
        "CompanyType": "Enterprise",
        "LegalPersonSurnamePinyin": "WANG",
        "LegalPersonNamePinyin": "Xiaoming",
        "LegalPersonGender": "1",
        "LegalPersonPhone": "+86 13800000000",
        "LegalPersonPhonePrefix": "+86",
        "LegalPersonPhoneNumber": "13800000000",
        "LegalPersonCountry": "CN",
        "LegalPersonIdNumber": "110101199001011234",
        "VATNumber": "DE123456789",
        "BusinessCode": "DPK2026",
        "IsRepeatRegister": "false",
        "CategoryBrandJson": "[{\"brandName\":\"ExampleBrand\"}]",
        "SpecsName": "100kg纸壳 50kg塑料"
    }
}
```

**受理流程（de_new_epr_pack_register_api.php）：**

1. **入口校验**：`PushType` = `DE_EPR_REGISTER_PACK`、`Country=DE`、`Data` 非空数组、`bizParam.BusinessSerialNumber` 必填。
2. **构建数据行**：`bizParam.BusinessSerialNumber` → `tid`（订单流水号）、`bizParam.BusinessId` → `VATBusinessID`（EPRBusinessRecord.ID）、`bizParam.EPRRegInfoId` → `EPRRegInfoID`（注册信息 ID）；`Country` 二字码→中文名（`CN`→中国、`HK`→香港，内部按中文名判断）；**法人拼音兼容**：优先已传 `LegalPersonFullNamePinYin`（原样采用），缺失时按「名 姓」拼接 `LegalPersonNamePinyin` + `LegalPersonSurnamePinyin`（如 `Xiaoming` + `WANG` → `Xiaoming WANG`）。
3. **字段校验**（packFieldFormats，规则见下表）；校验失败→返回 400 + 分号拼接错误信息（**不回写 SaaS EPRRegInfo 状态**，由调用方处理，同 DE_VAT_REGISTER 模式）。
4. **注册邮箱**：自动创建注册邮箱（规则同 job 版，已存在则沿用），随记录写入 `RegisterEmail` / `RegisterEmailPassword`。
5. **幂等查重**：按 `tid` 查 `pack_de_register`——已存在且 `status=2`（已成功）返回 200「该记录已存在且成功，跳过」；存在则更新；不存在则插入。
6. **落库**：`pack_de_register`，`status=0` 待处理、`pack_type=0`（注册）、`is_new=1`、`saas_request`=完整请求 JSON（见 §4.4 总表约定）；返回自增 `id`。
7. **响应**：200 + `msg='success'` + `ProcessMode=async` + `data=null` + 原样回传 `bizParam`（幂等跳过时 `msg='该记录已存在且成功，跳过'`，code 仍为 200）。

**字段校验规则：**

| # | 规则 | 说明 |
| --- | --- | --- |
| 1 | `NameEng` / `CompanyAddressPostcode` / `CityEngName` / `Country` / `LegalPersonFullNamePinYin`（兼容组合后）/ `LegalPersonPhonePrefix` / `LegalPersonPhoneNumber` / `LegalPersonGender` 必填 | 公司英文名 / 邮编 / 所在城市 / 注册国 / 法人英文全名 / 法人手机号前缀 / 手机号 / 性别 |
| 2 | 必填英文字段不能含中文/日文/韩文/中文标点 | 只允许英文字母、数字、空格和英文标点 |
| 3 | `CategoryBrandJson` 必填且为合法 JSON | 品类品牌数组（如 `[{"brandName":"ExampleBrand"}]`），落库前按品牌重组 |
| 4 | `LegalPersonGender` ∈ {`1`, `2`} | 1-男 / 2-女 |
| 5 | `CompanyType` ∈ {`Enterprise`, `Individual Business`, `Individual`} | 公司 / 个体工商户 / 个人 |
| 6 | `RegNumber` | 中国/香港且非个人必填（营业执照号） |
| 7 | `LegalPersonIdNumber` | 中国且 `CompanyType=Individual` 必填（法人身份证） |
| 8 | `RegAddressEng` / `CompanyAddressLine1En` | 非个人必填 `RegAddressEng`（公司地址）；中国个人必填 `CompanyAddressLine1En`（法人地址1） |

> **状态回写（SaaS 侧约定）**：下游零直连 SaaS 库——`EPRRegInfo.PushTaxBureauStatus` 由调用方维护：`1`=待推送（原取数条件，EPR 注册 `PushType='301'`）；收到本接口 200 → 置 `2` 并清空错误信息；收到 400 → 置 `-1` 并写 `PushTaxBureauErrorMsg`（按 `bizParam.EPRRegInfoId` / `BusinessId` 定位）。

---

### 4.4.17 德国EPR包装法注销自动受理
> **PushType**：`DE_EPR_CANCEL_PACK`；**Country**：`DE`

**请求体即 `德国EPR注销.json` 全文**（接口取数模式）：SaaS 调用方（原 job/german_pack_cancel.php 取数 SQL 前移到 SaaS 侧，联表后组装 `Data`）主动调用本接口，**不再由中转层 / 下游直连 SaaS 库取数**。转发层（countries/de.php）透传到 `vat_api_de_client/server/de_new_epr_pack_cancel_api.php`，校验通过后写入本地 `pack_de_register` 表（rpa 库，`pack_type=1` 注销），供门户自动注销（德国包装法）消费。

> 关联注册记录信息（`FirstEPRBusinessRecordId` 关联注册流水号、`RegNumber` 注册码、`RegisterEmail` / `RegisterEmailPassword` 注册邮箱及密码）原 job 按 `FirstEPRBusinessRecordId` 查 SaaS `EPRBusinessRecord` / `GeneralTemplateEPR` 获取，接口版由调用方在 `Data` 直接提供。

```json
{
    "PushType": "DE_EPR_CANCEL_PACK",
    "Country": "DE",
    "bizParam": {
        "BusinessSerialNumber": "DEPK202609020001",
        "BusinessId": "91001",
        "EPRRegInfoId": "99001"
    },
    "Data": {
        "NameCN": "德国测试贸易有限公司",
        "NameEng": "Germany Test Trading Co., Ltd.",
        "RegAddressEng": "No. 88, Central Avenue",
        "Country": "CN",
        "CountryName_en": "China",
        "CountryTwoCode": "CN",
        "RegNumber": "91310000MA1FL1TEST",
        "VATNumber": "DE123456789",
        "FirstEPRBusinessRecordId": "DEPK202601010001",
        "RegisterEmail": "depktest@usaeu.com",
        "RegisterEmailPassword": "TestPass123"
    }
}
```

**受理流程（de_new_epr_pack_cancel_api.php）：**

1. **入口校验**：`PushType` = `DE_EPR_CANCEL_PACK`、`Country=DE`、`Data` 非空数组、`bizParam.BusinessSerialNumber` 必填。
2. **构建数据行**：`bizParam.BusinessSerialNumber` → `tid`、`BusinessId` → `VATBusinessID`、`EPRRegInfoId` → `EPRRegInfoID`；`Country` 二字码→中文名（`CN`→中国、`HK`→香港）；公司英文地址只保留英文/数字/空格/常见英文标点。
3. **关联注册校验**（packCancelFieldFormats）：`FirstEPRBusinessRecordId` 必填（缺失→400「该注销记录没有关联的注册记录」）；`RegisterEmail` / `RegisterEmailPassword` / `RegNumber`（注册码）必填（规则见下表）；校验失败→返回 400 + 分号拼接错误信息（**不回写 SaaS EPRRegInfo 状态**，由调用方处理）。
4. **幂等查重**：按 `tid` 查 `pack_de_register`——已存在且 `status=2`（已成功）返回 200「该记录已存在且成功，跳过」；存在则更新；不存在则插入。
5. **落库**：`pack_de_register`，`status=0` 待处理、`pack_type=1`（注销）、`is_new=1`、`saas_request`=完整请求 JSON（见 §4.4 总表约定）；`vat_number` 落库时去除 `/`；返回自增 `id`。
6. **响应**：200 + `msg='success'` + `ProcessMode=async` + `data=null` + 原样回传 `bizParam`（幂等跳过时 `msg='该记录已存在且成功，跳过'`，code 仍为 200）。

**字段校验规则：**

| # | 规则 | 说明 |
| --- | --- | --- |
| 1 | `FirstEPRBusinessRecordId` 必填 | 关联注册记录流水号（原 job 以此查 SaaS 关联注册记录） |
| 2 | `RegisterEmail` 必填 | 注册邮箱（关联注册记录） |
| 3 | `RegisterEmailPassword` 必填 | 注册邮箱密码（关联注册记录） |
| 4 | `RegNumber` 必填 | 注册码（关联注册记录） |

> **状态回写（SaaS 侧约定）**：同 §4.4.16——下游零直连 SaaS 库，`EPRRegInfo.PushTaxBureauStatus` 由调用方维护：`1`=待推送（原取数条件）；收到本接口 200 → 置 `2` 并清空错误信息；收到 400 → 置 `-1` 并写 `PushTaxBureauErrorMsg`（按 `bizParam.EPRRegInfoId` / `BusinessId` 定位）。

### 4.4.18 瑞典EPR包装法文件生成
> **PushType**：`SE_EPR_REGISTER_PACK_FILE`；**Country**：`SE`

**请求体即 `瑞典EPR注册文件.json` 全文**（接口取数模式）：SaaS 调用方（原 server/epr_auto_file.php 以 EPRRegInfo.ID 直连 SaaS 库联表取数的 SQL 前移到 SaaS 侧，组装 `Data`）主动调用本接口，**不再由下游直连 SaaS 库取数**。转发层（countries/se.php）透传到 `vat_api_se_client/server/se_new_epr_pack_auto_file_api.php`，生成 POA 授权书 PDF（Power of Authority.docx 模板 + TTF 自动签名）并上传 OSS（`vat_factory/se_file/`）；公司注册国为中国（`Country=CN/中国`）时另生成营业执照合并件 PDF（执照图片下载 → BaiduOCR 识别 → 百度翻译 → 按方向模板合并），一并上传后返回文件 URL。**零 DB 依赖，不回写 SaaS 状态**（附件入库与状态流转由调用方/SaaS 侧负责，同 BE_EPR_REGISTER_PACK_FILE 模式）。

```json
{
  "PushType": "SE_EPR_REGISTER_PACK_FILE",
  "Country": "SE",
  "bizParam": {
    "BusinessSerialNumber": "POEPR202609030001",
    "BusinessId": "91001",
    "EPRRegInfoId": "99001"
  },
  "Data": {
    "NameCN": "深圳市瑞典贸易有限公司",
    "NameEng": "Shenzhen Ruidian Trading Co., Ltd.",
    "RegNumber": "91440300MA5EXAMPL1",
    "RegAddressEng": "No. 88, Central Avenue, Nanshan District, Shenzhen, Guangdong Province, China",
    "CompanyAddressLine1En": "No. 88, Central Avenue, Nanshan District",
    "CompanyAddressPostcode": "518000",
    "CityEngName": "Shenzhen",
    "Country": "CN",
    "CountryTwoCode": "CN",
    "CountryName_en": "China",
    "LegalPersonFullNamePinYin": "XIAOMING LI",
    "LegalPersonNamePinyin": "XIAOMING",
    "LegalPersonSurnamePinyin": "LI",
    "LegalPersonGender": "1",
    "LegalPersonPhone": "+86 13800138000",
    "LegalPersonEmail": "legal@example.com",
    "Code": "0",
    "BusinessLicenseDirection": "1",
    "RegisteredCapital": "1000000",
    "RegisteredCapitalCurrency": "CNY",
    "EstablishmentDate": "2018-06-15",
    "BusinessLicensePic": [
      {
        "fileUrl": "common-test/2026/08/06/019baf3f-801e-45aa-bf6d-a80c2b07e15d.jpg",
        "fileName": "019baf3f-801e-45aa-bf6d-a80c2b07e15d.jpg"
      }
    ]
  }
}
```

**生成流程（se_new_epr_pack_auto_file_api.php）：**

1. **入口校验**：`PushType` = `SE_EPR_REGISTER_PACK_FILE`、`Country=SE`、`Data` 非空数组、`bizParam.BusinessSerialNumber` 必填。
2. **构建数据行**：`bizParam.BusinessSerialNumber` → `tid`、`BusinessId` → `businessID`、`EPRRegInfoId` → `EPRRegInfoID`；`Country` 二字码→中文名（`CN`→中国、`HK`→香港），内部按中文名判断 `isChina`；**法人拼音兼容**：优先已传 `LegalPersonFullNamePinYin`（签名内容，原样采用），缺失时按「名 姓」拼接 `LegalPersonNamePinyin` + `LegalPersonSurnamePinyin`；`Code` 缺省 `'0'`（签名样式，取末位数字：0-6 原样、7→0、8→1、9→2）。
3. **字段校验**（validateFieldFormats，规则见下表）；校验失败→返回 400 + 分号拼接错误信息（**不回写 SaaS EPRRegInfo 状态**，由调用方处理）。
4. **生成 POA 授权书**（generateVollmacht）：模板 `Power of Authority.docx`，替换 `$todate`（英文日期）/ `$LegalPersonFullNamePinYin`（大写）/ `$NameEng` / `$RegAddressEng` / `$RegNumber` / `$LegalPersonPhone` / `$LegalPersonEmail`；TTF 自动签名（TTFSignatureGenerator，样式取 `Code` 末位）生成签名图片 → addSignatureToWord 嵌入 `$LegalPersonSignature`；Word 转 PDF，文件名 `POA of {NameEng}.pdf`。
5. **中国公司生成营业执照合并件**（pdfCheckFiveResult + generateGewerbeschein，仅 `Country=CN/中国`）：`BusinessLicensePic` 文件字段（原生数组 / JSON 字符串均可，fileUrl 为 OSS 相对路径或完整 URL）→ 多候选下载（完整 URL 直下；相对路径依次尝试 SaaS 桶 `usaeu-1259285998` / `file.usaeu.com` 反代 / 本地上传同桶 `vat-1259285998`）→ BaiduOCR 营业执照识别（company_type / issuing_authority / approval_date / business_scope）→ baiduTranslate 译英 → 按 `BusinessLicenseDirection` 选模板（1-横版范围 heng_fan / 2-横版提示 heng_ti / 3-竖版范围 shu_fan / 4-竖版提示 shu_ti）填充 `{{RegNumber}}` / `{{NameEng}}` / `{{RegAddressEng}}`（净化英文） / `{{LegalPersonFullNamePinYin}}` / `{{creat_date}}` / `{{Period}}` / `{{RegisteredCapital}}` / `{{companytype}}` / `{{approval_date}}` / `{{issuing_authority}}` / `{{business_scope}}` → Word 转 PDF + 执照图片转 PDF 合并，文件名 `Business License of {NameEng}.pdf`。
6. **上传 OSS 并返回**：两个 PDF 上传 `OSS_FILE_PATH`（`vat_factory/se_file/`），返回 `files`：`MANDAT`（授权书，必有）+ `BUSINESS_LICENSE_MERGED`（营业执照合并件，仅中国公司）；`id=EPRRegInfoID`、`action=''`。
7. **响应**：200 + `msg='success'` + `ProcessMode=sync` + `data={files,id,action}` + 原样回传 `bizParam`；失败 400 + `msg` + `data=null`（`bizParam` 同样原样回传）；异常时清理本地 `resources/SE_EPRfile/{EPRRegInfoId}` 目录。

**字段校验规则：**

| # | 规则 | 说明 |
| --- | --- | --- |
| 1 | `NameEng` / `RegNumber` / `RegAddressEng` / `LegalPersonFullNamePinYin` / `LegalPersonPhone` / `LegalPersonEmail` 必填 | 公司英文名 / 营业执照号 / 公司地址英文 / 法人姓名拼音（签名内容）/ 法人电话 / 法人邮箱 |
| 2 | 中国公司（`Country=CN/中国`）另必填 `BusinessLicenseDirection` / `RegisteredCapital` / `EstablishmentDate` / `BusinessLicensePic` | 营业执照方向（1-横版范围 / 2-横版提示 / 3-竖版范围 / 4-竖版提示）/ 注册资本 / 成立日期 / 营业执照图片（文件字段） |
| 3 | `EstablishmentDate` 格式 `YYYY-MM-DD`（存在时校验） | 成立日期 |
| 4 | `LegalPersonEmail` 需通过邮箱格式校验（存在时校验） | 法人邮箱 |

> **状态回写（SaaS 侧约定）**：下游零直连 SaaS 库——同 §4.4.16 前的 BE 文件生成模式，本接口**不回写** `EPRRegInfo.PushTaxBureauStatus`（生成的文件 URL 由调用方经 `files` 传入后续注册受理流程，状态流转由 SaaS 侧维护）。

---

### 4.4.19 英国CDS账号接收
> **PushType**：`GB_VAT_REGISTER_CDS_FILE`；**Country**：`GB`

英国 CDS 账号接收（`GB_VAT_REGISTER_CDS_FILE`）：接收 SaaS 推送的英国 CDS 账号凭证，异步受理（受理即返回）；RPA 定期下载该账号的 PVA/C79 海关文件，下载完成后经 §13 delivery/rpa/callback 通知（`bizParam` 原样回传定位业务；`data` 顶层含 `account_id` / `account_alias` / `file_date`（YYYYMM）/ `file_type`（PVA/C79）/ `total_postponed`（递延金额）；`data.files[].type` 使用 `CDS_PVA_FILE` / `CDS_C79_FILE` 枚举，`url` 为 COS 相对路径、域名由 SaaS 侧拼接（同 §5.1），每项另带 `date`＝申报时间首日 Y-m-d（见 §5.1）；通知失败由 RPA 重试补发，可能重复送达，接收端按 `bizParam`+`task_id` 幂等。通知数据契约详见 uk_cds 仓库接口文档）。

**请求体即 `英国CDS文件.json` 全文**（顶层含 `PushType` / `Country` / `bizParam` / `Data`）：

```json
{
    "PushType": "GB_VAT_REGISTER_CDS_FILE",
    "Country": "GB",
    "bizParam": {
        "BusinessSerialNumber": "CDS20260903000001",
        "BusinessId": 123456
    },
    "Data": {
        "AccountId": "test001",
        "Password": "password123",
        "AppKey": "appkey456789"
    }
}
```

**Data 字段（CDS 账号凭证）：**

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `AccountId` | 字符串 | 是 | CDS 账号 ID（≤50 字符，全局唯一，幂等匹配键） |
| `Password` | 字符串 | 是 | CDS 密码（≤100 字符） |
| `AppKey` | 字符串 | 是 | 平台 KEY（≤100 字符） |
| `AccountAlias` | 字符串 | 否 | 账号别名 = 对接系统内本条数据的唯一标识（≤50 字符，与老系统流程同语义，可不传） |

> **bizParam**：`BusinessSerialNumber` 必填（≤40 字符）；`BusinessId` 为**定位建议字段**——本流程的结果通知按受理 `bizParam` 原样回传定位 SaaS 内部业务，定位所需字段请在推送时放入 `bizParam`（其余附加字段均原样回传）。
>
> **幂等**：按 `Data.AccountId` 全局匹配，同账号重复推送时更新已有记录（凭证与 `bizParam` 以最新为准，下载进度不受影响）；响应 async 信封 `{code, msg, ProcessMode:'async', data:null, bizParam 原样}`，校验失败 `code=400`（错误分号拼接）。

---

### 4.4.20 法国EPR WEEE注册文件生成
> **PushType**：`FR_EPR_REGISTER_WEEE_FILE`；**Country**：`FR`

法国 EPR WEEE 注册文件生成（`FR_EPR_REGISTER_WEEE_FILE`）：**接口取数模式**——SaaS 调用方（原 server/epr_weee_query_api.php 以 EPRRegInfo.ID 直连 SaaS 库联表取数（EPRBusinessRecord / EPRRegInfo（PushType='301'）/ Base_Customer_Company / Country / ServiceItems 等，条件 `SupplierName='ECOLOGIC'`、`ServiceItemName in（'WEEE注册','运动户外注册'）`）的 SQL 前移到 SaaS 侧，组装 `Data`）主动调用本接口。转发层透传到 `vat_api_fr_client/server/new_epr_weee_file_api.php`，生成 2 个文件并上传 OSS（`New_OSS_EPR_WEEE_FILE_PATH`，production=`common/generatefile/2026/fr_epr_weee/`）后回传相对路径 URL。**零 DB 依赖，不回写 SaaS 状态**（附件入库与状态流转由调用方/SaaS 侧负责，同 BE/SE 文件生成模式）。`ProcessMode=sync`，响应 200 + `data={files}` + 原样回传 `bizParam`；校验失败 400 + 分号拼接错误信息。

**请求体即 `法国WEEE注册文件.json` 全文**（顶层含 `PushType` / `Country` / `bizParam` / `Data`）：

```json
{
    "PushType": "FR_EPR_REGISTER_WEEE_FILE",
    "Country": "FR",
    "Data": {
        "NameEng": "Yantai Tangli Xia Trading Co., Ltd",
        "RegAddressEng": "Room 3089, No. 19 Hongda Street, Huili Town, Fushan District, Yantai City, Shandong Province",
        "CompanyAddressLine1En": "No. 19 Hongda Street, Fushan District",
        "CompanyAddressPostcode": "265500",
        "CityEngName": "Yantai",
        "RegNumber": "91370611MAKDGB0TXU",
        "RegisteredCapital": "10000",
        "RegisteredCapitalCurrency": "EUR",
        "Country": "CN",
        "Code": "0825",
        "ServiceYear": 2026,
        "ServiceItemName": "WEEE注册",
        "VATNumber": "",
        "LegalPersonFullNamePinYin": "CHAO XUYANG",
        "LegalPersonName": "晁旭阳",
        "LegalPersonPhone": "+86 18820990915",
        "LegalPersonEmail": "460082351@qq.com"
    },
    "bizParam": {
        "deliveryId": 58688,
        "pushType": "FR_EPR_REGISTER_WEEE_FILE",
        "operatorId": 93,
        "logId": null,
        "operatorTime": "2026-09-05 10:00:00",
        "BusinessSerialNumber": "FRWEEE20260905000001",
        "BusinessId": "58688"
    },
    "files": []
}
```

**生成流程（new_epr_weee_file_api.php）：**

1. **入口校验**：`PushType` = `FR_EPR_REGISTER_WEEE_FILE`、`Country=FR`、`Data` 非空数组。
2. **构建数据行**（buildDataRow）：`Country` 中文映射（`中国`→CN、`香港`→HK、`法国`→FR）；`IsEUMember` Data 显式传值优先，否则按公司国家二字码（EU27 常量表）推导；**法人拼音兼容**：优先已传 `LegalPersonFullNamePinYin`（存储格式「姓 名」，原样采用），缺失时按「名 姓」拼接 `LegalPersonNamePinyin` + `LegalPersonSurnamePinyin`；`CTRegNumber = Siret ?? RegNumber`；`naf_code` / `legal_form`（缺省 `AUTRE`）双键兼容；`RegAddressEng` 缺省兜底 `CompanyAddressLine1En`；`bizParam.BusinessId`（EPRRegInfoId）→ 记录目录 `resources/EPR_WEEE_file/{BusinessId}`（回退 BusinessSerialNumber）。
3. **字段校验**（validateFieldFormats，规则见下表）；校验失败 → 返回 400 + 分号拼接错误信息，不再继续生成。
4. **INSEE 补充**：`CountryTwoCode=FR` 且 Data 未带 `NafCode` 时调用 INSEE（InseeApiClient::fetchCompanyData(CTRegNumber)）覆盖 `CTRegNumber`（siret_siege）/ `naf_code` / `legal_form`；失败仅记日志不中断（与原 epr_weee_query_api.php 一致）。
5. **生成 Vollmacht 授权书**（generateVollmacht）：模板 `resources/template/EPR_Ecologic_poa.docx`，替换 `{{date}}`（Y.m.d）/ `{{NameEng}}` / `{{RegAddressEng}}` / `{{RegNumber}}`（CTRegNumber）/ `{{LegalPersonFullNamePinYin}}` / `{{CityEngName}}`（内容去除中文逗号）；TTF 自动签名（无签名文件上传，`Code` 末位数字选字体：0-6 原样、7→0、8→1、9→2；TTFSignatureGenerator(660x160) → generateNormal(拼音, 40) 生成 `down/signature.png`）→ SignatureToWordConverter 嵌入 `{{LegalPersonSignature}}`（1.8x0.6 in）→ convertWordToPdf → ZipArchive 压 ZIP（失败回退原 PDF）；文件名 `EPR_Ecologic_{NameEng净化}.zip`（zip 内同名 .pdf，NameEng 净化=去非中英文字符）。
6. **生成 EPR_Ecologic 注册数据 CSV**（generateEPREcologicExcel，48 列 A~AV，UTF-8 BOM + 分号分隔）：表头与行数据同原 epr_weee_query_api.php（Q~U 列 SEAMEW 固定代理地址；V~Z 列 WANG / Mia / info@seamew.de / 86177 61 22 42 68 固定代理联系；AF 列 contractType=`ServiceItemName` 含「户外」→`ASL`，否则 `EEE Ménager`；AM 列 legalLastName=FullNamePinYin 首词；起始/委托日期 `01/01/{ServiceYear}`；国家名称取 country_cache.json 法语映射（Country_epr_weee_fr）；I 列 Share capital=RegisteredCapital）；文件名 `EPR_Ecologic_{NameEng净化}.csv`。
7. **上传 OSS 并返回**：两个文件依次经 new_ossfile.php HttpCosUploader（usaeu 桶）上传 `New_OSS_EPR_WEEE_FILE_PATH`，返回 `data.files`（`url` 取 `key` 相对路径，域名由 SaaS 侧拼接，同 §5.1）：`AUTHORIZATION_LETTER`（授权书）+ `WEEE_REGISTER_FILE`（注册数据 CSV）。
8. **清理记录目录**（文件已上传，中间产物全部删除 + rmdir）。
9. **响应**：200 + `msg='success'` + `ProcessMode=sync` + `data={files}` + 原样回传 `bizParam`；失败 400 + `msg` + `data=null`（`bizParam` 同样原样回传）。

**字段校验规则：**

| # | 规则 | 说明 |
| --- | --- | --- |
| 1 | `NameEng` / `RegNumber` / `CompanyAddressLine1En` / `CompanyAddressPostcode` / `CityEngName` / `ServiceYear` / `LegalPersonFullNamePinYin` / `LegalPersonEmail` 必填 | 公司英文名 / 营业执照号 / 公司英文地址 / 邮编 / 城市 / 服务年份 / 法人姓名拼音（签名内容）/ 法人邮箱 |
| 2 | `RegisteredCapital` 必填且为大于 0 的数字 | 48 列 CSV 的 I 列 Share capital* 要求 |
| 3 | `CompanyAddressLine1En` ≤ 50 字符 | 48 列 CSV 的 C 列文档限制 |

**返回 files：**

| type | 文件名 | 说明 |
| --- | --- | --- |
| `AUTHORIZATION_LETTER` | `EPR_Ecologic_{NameEng}.zip` | Vollmacht 授权书（zip 内含同名 PDF；ZIP 压缩失败回退返回 .pdf） |
| `WEEE_REGISTER_FILE` | `EPR_Ecologic_{NameEng}.csv` | Ecologic 注册数据 CSV（48 列） |

> **bizParam**：`BusinessSerialNumber` 必填（≤40 字符）；`BusinessId`（原 EPRRegInfoId）为**定位建议字段**，其余附加字段均原样回传。
>
> **状态回写（SaaS 侧约定）**：下游零直连 SaaS 库——本接口**不回写** `EPRRegInfo.PushTaxBureauStatus`（生成的文件 URL 由调用方经 `files` 传入后续注册受理流程，状态流转由 SaaS 侧维护）。

---

### 4.4.21 法国EPR WEEE添加合同注册文件生成
> **PushType**：`FR_EPR_REGISTER_WEEE_CONTRACT_FILE`；**Country**：`FR`

法国 EPR WEEE 添加合同注册文件生成（`FR_EPR_REGISTER_WEEE_CONTRACT_FILE`）：**接口取数模式**——SaaS 调用方（原 server/epr_weee_contract_api.php 以 EPRRegInfo.ID 直连 SaaS 库联表取数（PushType='305'）的 SQL 前移到 SaaS 侧，组装 `Data`）主动调用本接口。转发层透传到 `vat_api_fr_client/server/new_epr_weee_contract_file_api.php`，生成 2 个文件并上传 OSS（`New_OSS_EPR_WEEE_FILE_PATH`，同 §4.4.20）后回传相对路径 URL。**零 DB 依赖，不回写 SaaS 状态**。`ProcessMode=sync`，响应 200 + `data={files}` + 原样回传 `bizParam`；校验失败 400 + 分号拼接错误信息。

**请求体即 `法国WEEE添加合同注册文件.json` 全文**（顶层含 `PushType` / `Country` / `bizParam` / `Data`）：

```json
{
    "PushType": "FR_EPR_REGISTER_WEEE_CONTRACT_FILE",
    "Country": "FR",
    "Data": {
        "NameEng": "Yantai Tangli Xia Trading Co., Ltd",
        "RegAddressEng": "Room 3089, No. 19 Hongda Street, Huili Town, Fushan District, Yantai City, Shandong Province",
        "CompanyAddressLine1En": "No. 19 Hongda Street, Fushan District",
        "CompanyAddressPostcode": "265500",
        "CityEngName": "Yantai",
        "RegNumber": "91370611MAKDGB0TXU",
        "RegisteredCapital": "10000",
        "RegisteredCapitalCurrency": "EUR",
        "Country": "CN",
        "Code": "0825",
        "ServiceYear": 2026,
        "ServiceItemName": "运动户外注册",
        "VATNumber": "",
        "MembershipCode": "FR-ECOLOGIC-TEST-0001",
        "LegalPersonFullNamePinYin": "CHAO XUYANG",
        "LegalPersonName": "晁旭阳",
        "LegalPersonPhone": "+86 18820990915",
        "LegalPersonEmail": "460082351@qq.com"
    },
    "bizParam": {
        "deliveryId": 58689,
        "pushType": "FR_EPR_REGISTER_WEEE_CONTRACT_FILE",
        "operatorId": 93,
        "logId": null,
        "operatorTime": "2026-09-05 10:00:00",
        "BusinessSerialNumber": "FRWEEE20260905000002",
        "BusinessId": "58689"
    },
    "files": []
}
```

**与 §4.4.20（注册）的差异（new_epr_weee_contract_file_api.php）：**

1. **Membership code 获取**：`Data.MembershipCode` 非空直接使用（见上方请求体）；为空且 `RegNumber` 存在时经 Ecologic 门户查询（public/EcologicPortalPlaywright.php，最多 3 次重试、间隔 2 秒），查不到 → 400「Ecologic门户3次重试均未查询到 Membership code」；`MembershipCode` 与 `RegNumber` 均为空则按缺省空串继续（旧版同行为，测试时建议显式传 MembershipCode 绕开门户查询）。
2. **CSV 为 15 列**（generateEcologicAddContractCsv，按「添加合同excel模版.xlsx」，UTF-8 BOM + 分号分隔）：`Membership code` / Company registration number*（CTRegNumber）/ Type of contract*（`ServiceItemName` 含「户外」→`ASL` 否则 `EEE Ménager`）/ Contract effective date*（01/01/{ServiceYear}）/ Signatory 固定值（WANG / Mia / info@seamew.de / 86177 61 22 42 68）/ Equipment sold（空）/ Starting date of mandate*（01/01/{ServiceYear}）/ Reporting period*（A）/ European mandate contract（空）/ Other European mandate contract（空）/ Signatory's Function*（Director）/ Mandataire Code（固定 `A4542`）；文件名 `EPR_Ecologic_{NameEng净化}.csv`。
3. **其余流程同 §4.4.20**（入口校验 / buildDataRow / INSEE 补充 / generateVollmacht 授权书 / 上传 / 清理 / 响应信封），校验仅 8 项必填（无注册资本与 50 字符规则——15 列 CSV 无对应列）；INSEE 分支、记录目录、上传常量均一致。

**返回 files：**

| type | 文件名 | 说明 |
| --- | --- | --- |
| `AUTHORIZATION_LETTER` | `EPR_Ecologic_{NameEng}.zip` | Vollmacht 授权书（zip 内含同名 PDF；ZIP 压缩失败回退返回 .pdf） |
| `WEEE_ADD_CONTRACT_FILE` | `EPR_Ecologic_{NameEng}.csv` | Ecologic 添加合同数据 CSV（15 列） |

> **bizParam**：`BusinessSerialNumber` 必填（≤40 字符）；`BusinessId`（原 EPRRegInfoId）为**定位建议字段**，其余附加字段均原样回传。
>
> **状态回写（SaaS 侧约定）**：下游零直连 SaaS 库——本接口**不回写** `EPRRegInfo.PushTaxBureauStatus`（生成的文件 URL 由调用方经 `files` 传入后续注册受理流程，状态流转由 SaaS 侧维护）。

---

## 5. data 文件返回规范

### 5.1 规范说明

所有涉及文件生成的 PushType，返回的 `data` 统一为**对象** `{files}`，其中 `files` 为文件数组（**无文件时返回空数组 `[]`**，不是 `null`），每个元素结构：

| 字段   | 类型   | 说明                                                         |
| ------ | ------ | ------------------------------------------------------------ |
| `url`  | string | OSS 文件相对路径（不含域名，域名由 SaaS 侧拼接，完整 URL 形如 `https://usaeu-1259285998.cos.ap-guangzhou.myqcloud.com/{相对路径}`） |
| `name` | string | 上传后的完整文件名（含 tid 前缀，如 `DVAT12312312312312313_123456_xxx.pdf`） |
| `type` | string | 文件类型枚举，取值见 [5.2 文件类型枚举](#52-文件类型枚举)    |
| `date` | string | **有可能这个键名没有**。文件时间，格式 Y-m-d 比如英国CDS文件，2026-06-01就表示是6月的文件 |

示例：

```json
"data": {
  "files": [
    {
      "url": "common-test/generatefile/2026/de_declar_delay/DEV2026081417170019_395_alle Anhänge in einem Dokument.pdf",
      "name": "DEV2026081417170019_395_alle Anhänge in einem Dokument.pdf",
      "type": "N_IN_ONE_FILE",
      "date": "2026-06-01"
    }
  ]
}
```

### 5.2 文件类型枚举

`type` 字段取值（固定枚举，勿自定义）：

| 文件类型枚举           | 说明                       |
| ---------------------- | -------------------------- |
| `VAT业务申请表`        | 增值税注册申请表           |
| `营业执照或BR文件`     | 营业执照 / BR 文件         |
| `护照或法人身份证正面` | 护照或法人身份证正面       |
| `法人身份证反面`       | 法人身份证反面             |
| `CR文件(香港公司)`     | 香港公司 CR 文件           |
| `NNC1文件(香港公司)`   | 香港公司 NNC1 文件         |
| `公司章程文件`         | 公司章程文件               |
| `法人签名`             | 法人签名                   |
| `EPR业务申请表`        | EPR 业务申请表             |
| `授权代表业务申请表`   | 授权代表业务申请表         |
| `申请准备文件`         | 申请准备文件               |
| `申请回执`             | 申请回执                   |
| `申请预览`             | 申请预览                   |
| `N合1文件`             | 多文件合并的 N 合 1 文件   |
| `海牙文件-已认证`      | 已认证的海牙文件           |
| `EORI证书`             | EORI 证书                  |
| `本土税号证书`         | 本土税号证书               |
| `VAT税号证书`          | VAT 税号证书               |
| `法人税号证书`         | 法人税号证书               |
| `亚马逊证书`           | 亚马逊证书                 |
| `注册码证书`           | 注册码证书                 |
| `其他推送文件`         | 其他推送文件               |
| `授权书`               | 授权书（Mandat）           |
| `章程翻译件`           | 章程翻译件                 |
| `身份证合并件`         | 身份证合并件               |
| `营业执照合并件`       | 营业执照合并件             |
| `公司章程原件文件`     | 公司章程原件文件           |
| `普通申报回执`         | 普通申报回执               |
| `B2B申报回执`          | B2B 申报回执               |
| `延缓申报回执`         | 延缓申报回执               |
| `延缓申报确认函`       | 延缓申报确认函             |
| `其他附件`             | 其他附件                   |
| `N_IN_ONE_FILE`        | 多文件合并的 N 合 1 文件（DE_VAT_REGISTER_FILE 返回） |
| `AUTHORIZATION_LETTER` | 授权书（Mandat；FR_VAT_REGISTER_FILE / FR_EPR_REGISTER_WEEE_FILE / FR_EPR_REGISTER_WEEE_CONTRACT_FILE 文件生成返回） |
| `COMPANY_ARTICLES_ORIGINAL` | 公司章程原件文件（FR_VAT_REGISTER_FILE 返回） |
| `ID_CARD_MERGED`       | 身份证合并件（FR_VAT_REGISTER_FILE 返回） |
| `BUSINESS_LICENSE_MERGED` | 营业执照合并件（FR_VAT_REGISTER_FILE / SE_EPR_REGISTER_PACK_FILE（中国公司）返回） |
| `ARTICLES_TRANSLATION` | 章程翻译件（FR_VAT_REGISTER_FILE 返回） |
| `TAX_CERTIFICATE` | 税号证书 PDF（IT_VAT_REGISTER_ANR3 注册受理 files 输入，下游下载后 OCR 提取） |
| `MANDAT` | 授权书（Mandat；BE_EPR_REGISTER_PACK_FILE / AT_EPR_REGISTER_PACK_FILE / SE_EPR_REGISTER_PACK_FILE 文件生成返回；BE_EPR_REGISTER_PACK 注册受理 files 输入） |
| `MEMBERSHIP` | 会员合同（FostPlus；BE_EPR_REGISTER_PACK_FILE 文件生成返回；BE_EPR_REGISTER_PACK 注册受理 files 输入） |
| `CDS_PVA_FILE` | PVA 文件（GB_VAT_REGISTER_CDS_FILE 结果通知 `data.files` 返回） |
| `CDS_C79_FILE` | C79 文件（GB_VAT_REGISTER_CDS_FILE 结果通知 `data.files` 返回） |
| `WEEE_REGISTER_FILE` | WEEE/运动户外注册数据 CSV（48 列，FR_EPR_REGISTER_WEEE_FILE 文件生成返回） |
| `WEEE_ADD_CONTRACT_FILE` | WEEE 添加合同数据 CSV（15 列，FR_EPR_REGISTER_WEEE_CONTRACT_FILE 文件生成返回） |

> 德/法 VAT 注册相关接口（文件生成返回、注册受理 `files` 输入）使用**英文枚举**（表中新增的 6 项）；历史中文枚举（`授权书`、`章程翻译件`、`身份证合并件`、`营业执照合并件`、`公司章程原件文件`、`N合1文件`）保留兼容，注册受理对德国 files 不匹配 `N_IN_ONE_FILE` 时按第一项兜底。意大利 ANR3 注册受理 `files` 使用 `TAX_CERTIFICATE`（税号证书 PDF）。比利时 EPR 文件生成返回 / 注册受理 files 输入使用 `MANDAT`（授权书）+ `MEMBERSHIP`（会员合同）；奥地利 / 瑞典 EPR 文件生成返回 `MANDAT`，瑞典中国公司另返回 `BUSINESS_LICENSE_MERGED`（营业执照合并件）。英国 CDS（`GB_VAT_REGISTER_CDS_FILE`）结果通知 `data.files[].type` 使用 `CDS_PVA_FILE` / `CDS_C79_FILE`（CDS 专用，勿自定义）。法国 EPR WEEE（`FR_EPR_REGISTER_WEEE_FILE` / `FR_EPR_REGISTER_WEEE_CONTRACT_FILE`）文件生成返回 `AUTHORIZATION_LETTER`（授权书）+ `WEEE_REGISTER_FILE`（注册数据 CSV）/ `WEEE_ADD_CONTRACT_FILE`（添加合同数据 CSV）。

### 5.3 各国映射示例

| PushType | 返回文件（type 枚举） |
| -------- | --------------------- |
| `DE_VAT_REGISTER_FILE`（德国VAT注册五合一文件生成） | 只返回 1 个文件：`N_IN_ONE_FILE`（中间处理文件不上传） |
| `FR_VAT_REGISTER_FILE`（法国VAT注册文件生成） | 返回 5 个文件：`AUTHORIZATION_LETTER`、`COMPANY_ARTICLES_ORIGINAL`、`ID_CARD_MERGED`、`BUSINESS_LICENSE_MERGED`、`ARTICLES_TRANSLATION` |
| `SE_EPR_REGISTER_PACK_FILE`（瑞典EPR文件生成） | 返回 1~2 个文件：`MANDAT`（POA 授权书，必有）+ `BUSINESS_LICENSE_MERGED`（营业执照合并件，仅公司注册国为中国时返回） |
| `BE_EPR_REGISTER_PACK_FILE`（比利时EPR文件生成） | 返回 2 个文件：`MANDAT`（授权书）、`MEMBERSHIP`（FostPlus 会员合同） |
| `AT_EPR_REGISTER_PACK_FILE`（奥地利EPR文件生成） | 返回 1 个文件：`MANDAT`（授权书） |
| `FR_EPR_REGISTER_WEEE_FILE`（法国EPR WEEE注册文件生成） | 返回 2 个文件：`AUTHORIZATION_LETTER`（授权书）、`WEEE_REGISTER_FILE`（注册数据 CSV） |
| `FR_EPR_REGISTER_WEEE_CONTRACT_FILE`（法国EPR WEEE添加合同注册文件生成） | 返回 2 个文件：`AUTHORIZATION_LETTER`（授权书）、`WEEE_ADD_CONTRACT_FILE`（添加合同数据 CSV） |

> 不同国家可根据业务需求调整实际返回的文件类型，但 `type` 必须取自 [5.2 文件类型枚举](#52-文件类型枚举)。

### 5.4 新增流程文件槽契约（ES / IT / FR）

下列 7 个文件生成转发流程，relay 原样透传下游返回的 `data`（file1~file10），文件槽由下游填充；空槽为空字符串 `""`；文件槽值为**完整 OSS URL**（可直接下载）。

| PushType | file1 | file2 | file3 | file4 |
| --- | --- | --- | --- | --- |
| `ES_EPR_REGISTER_HAGUE_FILE` | 盖章要求文件（固定） | 海牙待认证文件 | APODERAMIENTO 文件 | 030文件 |
| `ES_EPR_REGISTER_030_FILE` | 030文件 | | | |
| `ES_VAT_REGISTER_HAGUE_FILE` | 海牙待认证文件 | 030文件 | | |
| `IT_EPR_REGISTER` | EPR注册文件 | | | |
| `FR_EPR_REGISTER_LEKO` | LEKO XLSX文件 | POA PDF文件 | | |
| `FR_EPR_REGISTER_CITEO` | POA PDF文件 | | | |
| `FR_EPR_REGISTER_REFASHION` | POA文件 | | | |

> 下游地址须 define 同名常量（如 `ES_EPR_REGISTER_HAGUE_FILE_API_URL`）；未定义或为空串时 **fail-closed 返 400**（不回落 `HTTP_HOST`，防 SSRF / PII 外泄）。部署时必须为每个流程 define 对应常量。
>
> `FR_EPR_REGISTER_LEKO` 与 `FR_EPR_REGISTER_CITEO` 均为同步 API 数据流。下游必须直接消费 `Data` 和 `bizParam`，不得使用 `Id`/`EprRegInfoId` 回查 source 库，也不得读写 source 库状态或附件表。source 库零读写不表示禁止外部服务：法国公司 LEKO 必须访问 INSEE 官方 SIRENE API，CITEO 不需要 INSEE。

---

## 6. ProcessMode 处理模式

> `ProcessMode` 仅作为响应参数返回（响应侧约定，不随请求体传入）。

| 模式    | 适用接口                                    | 响应内容                                               |
| ------- | ------------------------------------------- | ------------------------------------------------------ |
| `sync`  | DE_VAT_REGISTER_FILE、GB_VAT_REGISTER（英国 VAT 注册数据接收）、FR_EPR_REGISTER_LEKO、FR_EPR_REGISTER_CITEO 等同步实时处理 | `data` 直接返回 `{files}` 文件对象、落库结果 `{id, customer_email, action}` 或下游约定的 file1~file10 文件槽 |
| `async` | ES 海牙系列（`ES_VAT_REGISTER_HAGUE_FILE`/`ES_EPR_REGISTER_HAGUE_FILE`/`ES_EPR_REGISTER_030_FILE`）| 异步受理：`data=null`，文件由后台任务生成，完成后经统一结果回调接口通知调用方（见 §13） |
| `async` | DE_VAT_REGISTER、FR_VAT_REGISTER、IT_VAT_REGISTER、IT_VAT_REGISTER_ANR3、DE_VAT_APPLICATION_DELAY（注册/申报受理，转发层默认） | 受理即返回（数据已同步落库），`data` 返回落库结果对象 `{tid, record_id, ...}`，供门户自动注册消费；失败返回 400 |

**sync 流程：**

```
请求 → 校验 → 路由到国家类 → 同步处理（生成文件 / 按流程约定更新数据）
  → 普通流程返回 data {files: [{url, name, type}]}
  → file 槽流程返回 data {file1,...,file10}
  → 注册受理流程（DE_VAT_REGISTER / FR_VAT_REGISTER / IT_VAT_REGISTER / IT_VAT_REGISTER_ANR3 / DE_VAT_APPLICATION_DELAY）返回 data {tid, record_id}（转发层默认 ProcessMode=async）
```

> FR LEKO/CITEO 的 API_Flow 只生成文件并上传 OSS，不读写 source 库；其中法国公司 LEKO 在生成前通过现有 `InseeApiClient` 查询 INSEE 官方 SIRENE API，CITEO 不调用 INSEE。外部 INSEE HTTP 依赖与 source 数据库依赖必须分开统计和故障处理。两个流程均返回 file1~file10 文件槽。
>
> Source_Flow 保持现有行为不变：继续从 source 库取数，LEKO 继续使用相同 SIREN 派生、INSEE 映射及 5 次/6 秒重试，并继续执行既有状态、附件和通知处理。

**async 流程（ES 海牙系列）：**

```
请求 → 校验 → 落库任务
  → 立即返回 { ProcessMode:'async', data:null, bizParam }
海牙：后台生成海牙合并PDF
  → data{file1=盖章要求, file2=海牙待认证, file3=APODERAMIENTO，均为完整OSS URL}
  └ 最终失败（达重试上限）→ 回调调用方错误信息
030：RPA 程序生成 030 → 经统一结果回调接口通知调用方（成功/失败均通知）
```

---

## 7. 项目目录结构

```
app_withdrawn/
├── index.php                  ← 旧版接口入口（不在本文档对接范围）
├── api.php                    ← 新增：统一中转接口入口（接收 + 校验 + 路由 + 分发）
├── core/
│   ├── Database.php           ← 数据库连接（PDO 单例）
│   ├── CountryBase.php        ← 国家处理基类（execute / fetchOne）
│   └── Response.php           ← 统一 JSON 响应类
├── config/
│   └── database.php           ← SQL Server 配置
├── countries/                 ← 国家处理类（多国家扩展点）
│   ├── de.php                 ← 德国（DE_VAT_REGISTER_FILE ...）
│   ├── fr.php                 ← 法国（FR_VAT_REGISTER_FILE ...）
│   ├── be.php                 ← 比利时
│   ├── gb.php                 ← 英国
│   └── it.php                 ← 意大利
├── docs/
│   ├── UNIFIED_API_DESIGN.md  ← 本文档
│   ├── API_USAGE.md           ← 使用说明
│   └── DEVELOPER_GUIDE.md     ← 开发者指南
├── logs/                      ← 日志目录
│   └── api_YYYY-MM-DD.log
└── README.md
```

---

## 8. 扩展新国家 / 新方法

### 8.1 添加新国家

1. 在 `countries/` 下创建 `{country}.php`，类名与文件名一致（小写）
2. 继承 `CountryBase`
3. 实现对应方法，方法名 = PushType（国家__业务大类__业务小类，如 `DE_VAT_REGISTER_FILE`）

```php
<?php
// countries/es.php
class es extends CountryBase
{
    public function DE_VAT_REGISTER_FILE($params): array
    {
        // 西班牙 VAT 注册文件生成逻辑
        // 生成文件 → 上传 OSS → 返回 data {files} 对象
        return [
            'code' => 200,
            'msg' => 'success',
            'data' => [
                'files' => [
                    [
                        'url'  => 'common-test/generatefile/2026/de_declar_delay/xxx.pdf',
                        'name' => 'xxx.pdf',
                        'type' => 'N_IN_ONE_FILE',
                    ],
                    // ...
                ]
            ]
        ];
    }
}
```

### 8.2 添加新 PushType

直接在对应国家类中新增方法即可，无需修改 `api.php`。路由是动态的：

```
Country 类存在 → 方法 {PushType} 存在 → 自动调用
```

---

## 9. 新对接方法映射表

> 所有方法统一使用新命名 `PushType = {国家二字码}_{业务大类}_{业务小类}`（如 `DE_VAT_REGISTER_FILE`），`api.php` 直接以 PushType 作为方法名路由。

| Country | PushType | 方法名 | 说明 |
| ------- | -------- | ------ | ---- |
| DE | `DE_VAT_REGISTER_FILE` | `DE_VAT_REGISTER_FILE` | 德国VAT注册五合一文件生成 → vat_new_file_api.php |
| DE | `DE_VAT_REGISTER` | `DE_VAT_REGISTER` | 德国VAT注册自动受理（门户自动注册，数据落库 → vat_new_register_auto.php） |
| DE | `DE_VAT_APPLICATION_DELAY` | `DE_VAT_APPLICATION_DELAY` | 德国VAT申报延缓自动受理（门户自动申报，月报生成确认函PDF，数据落库 → vat_new_Application_Delay.php，**接口取数模式**替代原 job 直连 SaaS 库） |
| DE | `DE_EPR_REGISTER_PACK` | `DE_EPR_REGISTER_PACK` | 德国 EPR 包装法注册自动受理（门户自动注册，数据落库 pack_de_register（pack_type=0）→ de_new_epr_pack_register_api.php，注册邮箱自动创建/沿用，**接口取数模式**替代原 job 直连 SaaS 库） |
| DE | `DE_EPR_CANCEL_PACK` | `DE_EPR_CANCEL_PACK` | 德国 EPR 包装法注销自动受理（门户自动注销，数据落库 pack_de_register（pack_type=1）→ de_new_epr_pack_cancel_api.php，关联注册记录字段由调用方直接传入，**接口取数模式**替代原 job 直连 SaaS 库） |
| FR | `FR_VAT_REGISTER_FILE` | `FR_VAT_REGISTER_FILE` | 法国 VAT 注册生成文件（5 类自动生成 PDF → vat_new_file_api.php） |
| FR | `FR_VAT_REGISTER` | `FR_VAT_REGISTER` | 法国 VAT 注册自动受理（门户自动注册，数据落库 → vat_new_register_auto.php） |
| IT | `IT_VAT_REGISTER` | `IT_VAT_REGISTER` | 意大利 VAT 注册自动受理（AA7 税表，门户自动注册，数据落库 → vat_api_it_client 接口，**接口取数模式**） |
| IT | `IT_VAT_REGISTER_ANR3` | `IT_VAT_REGISTER_ANR3` | 意大利 VAT 注册自动受理（ANR3 税表，欧盟公司，税号证书 PDF 下载 + OCR 提取后落库 → vat_api_it_client 接口） |
| ES | `ES_EPR_REGISTER_HAGUE_FILE` | `ES_EPR_REGISTER_HAGUE_FILE` | 西班牙 EPR 海牙文件生成（盖章要求/海牙待认证/APODERAMIENTO/030） |
| ES | `ES_EPR_REGISTER_030_FILE` | `ES_EPR_REGISTER_030_FILE` | 西班牙 EPR030 文件生成（030文件） |
| ES | `ES_VAT_REGISTER_HAGUE_FILE` | `ES_VAT_REGISTER_HAGUE_FILE` | 西班牙 VAT 海牙文件生成（海牙待认证/030） |
| IT | `IT_EPR_REGISTER` | `IT_EPR_REGISTER` | 意大利 EPR 注册文件生成 |
| FR | `FR_EPR_REGISTER_LEKO` | `FR_EPR_REGISTER_LEKO` | 法国 LEKO 注册文件生成（LEKO/POA） |
| FR | `FR_EPR_REGISTER_CITEO` | `FR_EPR_REGISTER_CITEO` | 法国 CITEO 注册文件生成（POA） |
| FR | `FR_EPR_REGISTER_REFASHION` | `FR_EPR_REGISTER_REFASHION` | 法国纺织法注册文件生成（POA） |
| SE | `SE_EPR_REGISTER_PACK_FILE` | `SE_EPR_REGISTER_PACK_FILE` | 瑞典EPR包装法文件生成（自动生成文件，POA 授权书 + 中国公司营业执照合并件 → vat_api_se_client/server/se_new_epr_pack_auto_file_api.php，**接口取数模式**替代原 server/epr_auto_file.php 直连 SaaS 库，见 §4.4.18） |
| BE | `BE_EPR_REGISTER_PACK_FILE` | `BE_EPR_REGISTER_PACK_FILE` | 比利时EPR包装法文件生成（自动生成文件，POA 授权书 + FostPlus 会员合同 → vat_api_se_client/server/be_new_epr_pack_auto_file_api.php，**接口取数模式**替代原 server/be_epr_pack_auto_file.php 直连 SaaS 库） |
| BE | `BE_EPR_REGISTER_PACK` | `BE_EPR_REGISTER_PACK` | 比利时EPR包装法注册自动受理（门户自动注册，数据落库 pack_be_register → vat_api_se_client/server/be_new_epr_pack_register_api.php，请求须携带顶层 files（type=MANDAT + type=MEMBERSHIP），**接口取数模式**替代原 job/be_epr_pack_register.php 直连 SaaS 库） |
| FR | `FR_EPR_REGISTER_WEEE` | `FR_EPR_REGISTER_WEEE` | 法国 EPR 的 WEEE 注册（预留） |
| FR | `FR_EPR_REGISTER_WEEE_CONTRACT` | `FR_EPR_REGISTER_WEEE_CONTRACT` | 法国 EPR 的 WEEE 添加合同注册（预留） |
| FR | `FR_EPR_REGISTER_WEEE_FILE` | `FR_EPR_REGISTER_WEEE_FILE` | 法国 EPR 的 WEEE 注册文件生成（自动生成文件，授权书 + EPR_Ecologic 注册数据 CSV → countries/fr.php 方法转发 → vat_api_fr_client/server/new_epr_weee_file_api.php，**接口取数模式**替代原 server/epr_weee_query_api.php 直连 SaaS 库，见 §4.4.20） |
| FR | `FR_EPR_REGISTER_WEEE_CONTRACT_FILE` | `FR_EPR_REGISTER_WEEE_CONTRACT_FILE` | 法国 EPR 的 WEEE 添加合同注册文件生成（自动生成文件，授权书 + EPR_Ecologic 添加合同 CSV → countries/fr.php 方法转发 → vat_api_fr_client/server/new_epr_weee_contract_file_api.php，**接口取数模式**替代原 server/epr_weee_contract_api.php 直连 SaaS 库，见 §4.4.21） |
| GB | `GB_VAT_REGISTER` | `GB_VAT_REGISTER` | 英国 VAT 注册数据接收（注册邮箱自动创建） |
| GB | `GB_VAT_REGISTER_CDS_FILE` | `GB_VAT_REGISTER_CDS_FILE` | 英国 CDS 账号接收（async 受理，RPA 下载 PVA/C79 海关文件完成后经 §13 通知，见 §4.4.19） |
| NL | — | — | 预留 |

> ES 三个文件生成流程分属两个项目：`ES_VAT_REGISTER_HAGUE_FILE` 由 **es_haiya** 项目承接（public/es_hague_api.php，异步受理，EPR 海牙/030 不在该项目）；`ES_EPR_REGISTER_HAGUE_FILE` / `ES_EPR_REGISTER_030_FILE` 由 **es_haiya_epr** 项目承接（public/es_hague_api.php / es_030_api.php）。app_withdrawn 的 `*_API_URL` 常量分别指向对应下游。
| PL | — | — | 预留 |
| AT | `AT_EPR_REGISTER_PACK_FILE` | `AT_EPR_REGISTER_PACK_FILE` | 奥地利EPR包装法文件生成（自动生成文件，授权书 → vat_api_se_client/server/at_new_epr_pack_auto_filer_api.php，**接口取数模式**替代原 job/at_epr_pack_auto_file.php 直连 SaaS 库；按契约由下游回写 SaaS 库 EPRRegInfo 状态（成功 6 / 失败 7）） |
| CZ | — | — | 预留 |

---

## 10. 测试用例

### 10.1 cURL 示例

```bash
# 文件处理（德国 VAT 注册文件生成，同步模式）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "PushType": "DE_VAT_REGISTER_FILE",
    "Country": "DE",
    "bizParam": {
      "BusinessSerialNumber": "DVAT12312312312312313",
      "BusinessId": 123456
    },
    "Data": {
      "NameCN": "枝江市霞陆逊商贸有限公司",
      "BusinessLicensePic": "[{\"fileUrl\":\"common-test/2026/08/06/xxx.jpg\",\"fileName\":\"license.jpg\"}]"
    }
  }'

# 注册受理（德国 VAT 注册，数据落库，ProcessMode 默认 async；法国版换 PushType=FR_VAT_REGISTER / Country=FR，files 为 5 类自动生成 PDF）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "PushType": "DE_VAT_REGISTER",
    "Country": "DE",
    "bizParam": {
      "BusinessSerialNumber": "DVAT12312312312312313",
      "BusinessId": 123456
    },
    "Data": { ...同文件生成版... },
    "files": [
      {
        "url": "common-test/generatefile/2026/de_declar_delay/DVAT12312312312312313_123456_alle Anhänge in einem Dokument.pdf",
        "name": "DVAT12312312312312313_123456_alle Anhänge in einem Dokument.pdf",
        "type": "N_IN_ONE_FILE",
        "pushType": "DE_VAT_REGISTER_FILE"
      }
    ]
  }'

# 申报受理（德国 VAT 申报延缓，月报自动生成确认函 PDF 并上传 OSS，ProcessMode 默认 async）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "PushType": "DE_VAT_APPLICATION_DELAY",
    "Country": "DE",
    "bizParam": {
      "BusinessSerialNumber": "POVATD202605095397376",
      "BusinessId": 88013
    },
    "Data": {
      "BusinessCode": "YR951",
      "DeclarationIntervalStart": "2025-10-01",
      "DeclarationIntervalEnd": "2025-10-31",
      "VATNumber": "15/385/78627",
      "LocalTaxNumber": "",
      "NameCN": "深圳市新润科技有限公司",
      "NameEng": "Shenzhen Xinrun Technology Co., Ltd.",
      "Country": "CN",
      "PreviousYearTotalTax": 385,
      "TaxDeposit": 35,
      "DeclarationMethod": "0"
    }
  }'

# 注册受理（意大利 VAT 注册 ANR3，税号证书 PDF 经 files 传入，下游 OCR 提取后落库）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "PushType": "IT_VAT_REGISTER_ANR3",
    "Country": "IT",
    "bizParam": {
      "BusinessSerialNumber": "POVAT20260210000161",
      "BusinessId": 3302,
      "VATRegInfoId": 88013
    },
    "Data": {
      "NameCN": "米兰星光贸易有限公司",
      "ProfisCode": "300001"
    },
    "files": [
      {
        "url": "https://vat-1259285998.cos.ap-guangzhou.myqcloud.com/vat_factory/fdc96d32-50ea-4aef-aa07-ab6fef6e7257/20260729/wu_1jultdktu1ndgr171qg2181114ud7.pdf",
        "name": "tax_certificate_POVAT20260210000161.pdf",
        "type": "TAX_CERTIFICATE"
      }
    ]
  }'

# 注册受理（德国 EPR 包装法注册，落库 pack_de_register（pack_type=0），ProcessMode 默认 async；请求体即 docs/德国EPR注册.json 全文，完整字段见 §4.4.16）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/德国EPR注册.json

# 注销受理（德国 EPR 包装法注销，落库 pack_de_register（pack_type=1），ProcessMode 默认 async；请求体即 docs/德国EPR注销.json 全文，完整字段见 §4.4.17）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/德国EPR注销.json

# 或直接运行仓库测试脚本（读取同目录 json 自动发起请求）:
#   php test/test_de_epr_pack_register.php
#   php test/test_de_epr_pack_cancel.php

# 文件生成（瑞典 EPR 包装法，POA 授权书 + 中国公司营业执照合并件，ProcessMode=sync，请求体即 docs/瑞典EPR注册文件.json 全文，完整字段见 §4.4.18）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/瑞典EPR注册文件.json

# 文件生成（比利时 EPR 包装法，POA 授权书 + FostPlus 会员合同，ProcessMode=sync；请求体即 docs/比利时EPR注册文件.json 全文）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/比利时EPR注册文件.json

# 注册受理（比利时 EPR 包装法，落库 pack_be_register（is_new=1），ProcessMode 默认 async；请求须携带顶层 files（type=MANDAT + type=MEMBERSHIP），请求体即 docs/比利时EPR注册.json 全文）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/比利时EPR注册.json

# 文件生成（奥地利 EPR 注册文件，授权书，ProcessMode=sync；请求体即 docs/奥地利EPR包装法注册文件.json 全文；下游按契约回写 SaaS 状态 6/7）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/奥地利EPR包装法注册文件.json

# 或直接运行仓库测试脚本（读取同目录 json 自动发起请求）:
#   php test/test_se_epr_pack_auto_file.php
#   php test/test_be_epr_pack_auto_file.php
#   php test/test_be_epr_pack_register.php
#   php test/test_at_epr_pack_auto_file.php

# 文件生成（法国 EPR WEEE 注册 / 添加合同，授权书 + EPR_Ecologic CSV，ProcessMode=sync；请求体即 docs/法国WEEE注册文件.json / docs/法国WEEE添加合同注册文件.json 全文，完整字段见 §4.4.20 / §4.4.21；经 countries/fr.php 方法转发到 vat_api_fr_client server 接口，下游地址常量 FR_EPR_REGISTER_WEEE_FILE_API_URL / FR_EPR_REGISTER_WEEE_CONTRACT_FILE_API_URL 在 config/downstream.php 配置）
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/法国WEEE注册文件.json
curl -X POST http://localhost/app_withdrawn/api.php \
  -H "Content-Type: application/json" \
  --data-binary @docs/法国WEEE添加合同注册文件.json

# 或直接运行仓库测试脚本（读取同目录 json 自动发起请求）:
#   php test/test_fr_epr_weee_file.php
#   php test/test_fr_epr_weee_contract_file.php

```

### 10.2 Python 调用示例

```python
import requests

url = "http://localhost/app_withdrawn/api.php"

# sync 模式 — 文件处理
payload = {
    "PushType": "DE_VAT_REGISTER_FILE",
    "Country": "DE",
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": 123456
    },
    "Data": {
        "NameCN": "枝江市霞陆逊商贸有限公司",
        "BusinessLicensePic": "[{\"fileUrl\":\"common-test/2026/08/06/xxx.jpg\",\"fileName\":\"license.jpg\"}]"
    }
}


```

---

## 11. 与现有外部 API 的对接关系

| 外部系统 / API                         | 对接方式                         | 对应 PushType（新）    |
| -------------------------------------- | -------------------------------- | ---------------------- |
| `vat_api_de_client/server/vat_query_api.php` | 在本项目中创建 DE 方法调用        | `DE_VAT_REGISTER_FILE`      |
| `vat_api_de_client/server/vat_deferred_7_query_api.php` | 在本项目中创建 DE 方法调用      | `DE_VAT_DECLARE`（计划） |
| `vat_api_fr_client/server/epr_weee_contract_api.php`（FR） | 在本项目中创建 FR 方法调用       | `FR_EPR_REGISTER`（计划） |
| ERIC / ELSTER（德国税局）              | Python 子进程调用                | `DE_VAT_DECLARE`（计划） |
| INSEE API（法国）                      | HTTP API 调用                    | `FR_EPR_REGISTER`（计划） |
| 腾讯云 COS                             | SDK 上传                         | 各国家通用             |

---

## 12. 后续扩展

| 扩展项         | 说明                                               |
| -------------- | -------------------------------------------------- |
| Token 认证     | 增加 `Authorization: Bearer <token>` 校验          |
| async 回调     | ES 海牙等异步流程已实现（见 §6）：文件由后台生成，完成后经统一结果回调接口通知调用方（见 §13） |
| 限流机制       | 按国家 + PushType 维度的 QPS 限制                 |
| 任务队列       | 接入 Redis 队列实现真正的异步处理 |
| 日志增强       | 增加 PushType / Country / 耗时统计                 |
| Swagger 文档   | 生成 OpenAPI 3.0 规范文档                          |

---

## 13. SaaS 异步结果回调接口（delivery/rpa/callback）

> 异步流程（ES 海牙 030、意大利 EPR 授权书等）由 RPA 侧生成文件完成后，**回调 SaaS 平台统一结果通知接口**，将处理结果（文件/错误）通知 SaaS（示例地址 `http://192.168.1.211:8080/delivery/rpa/callback`，以实际配置为准）。

### 13.1 接口信息

| 项目 | 值 |
| ---- | ---- |
| **接口地址** | `POST https://test-cloud.usaeu.com/prod-api/delivery/rpa/callback`（以实际配置为准） |
| **请求方式** | POST |
| **Content-Type** | `application/json` |
| **超时** | 默认 10 秒，2xx 视为成功；调用方（PA 侧）发送失败自动重试（`ES_HAGUE_CALLBACK_MAX_RETRIES` 默认 3、`ES_HAGUE_CALLBACK_RETRY_DELAY` 默认 5 秒，可配），**可能产生重复 POST，接收端须按 `bizParam`+`task_id` 幂等处理（重复通知覆盖式更新，以最后为准）** |

### 13.2 请求体（回调数据）

**成功回调（data 对象内 `files` 键接文件数组，有几个文件就接几个文件项）：**

```json
{
    "code": 200,
    "msg": "success",
    "ProcessMode": "async",
    "data": {
        "task_id": 44912,
        "files": [
            {
                "url": "common-prod/generatefile/2026/es_vat_haiya/DVAT12312312312312313/DVAT12312312312312313_123456.pdf",
                "name": "DVAT12312312312312313_123456.pdf",
                "type": "海牙文件-已认证"
            },
            {
                "url": "common-prod/generatefile/2026/es_vat_haiya/DVAT12312312312312313/DVAT12312312312312313_123456_030.pdf",
                "name": "DVAT12312312312312313_123456_030.pdf",
                "type": "其他推送文件"
            }
        ]
    },
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": 123456
    }
}
```

| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| `code` | int | 处理结果：`200`=成功，非 200=失败（失败回调当前实现固定 `500`） |
| `msg` | string | 处理消息（成功 `success`，失败为错误原因） |
| `ProcessMode` | string | 处理模式：`async`（异步） |
| `data` | object/null | 成功：对象，含 `task_id`（异步任务 ID，幂等键之一）与 `files`（文件数组，有几个文件就几项；每项含 `url`（OSS 相对路径，同 §5.1——不带域名，域名由 SaaS 侧拼接；海牙文件与 030 文件同目录 `{api_flow_oss_prefix}{当前年}/es_vat_haiya/{业务流水号}/`（业务流水号 = bizParam.BusinessSerialNumber，缺省回退 BusinessId））/`name`（文件名）/`type`（文件类型枚举，见 §5.2）/`date`（文件时间 Y-m-d，仅部分业务如英国 CDS 携带，见 §5.1））；失败：`null` |
| `bizParam` | object | 业务标识信息，原样回传受理请求中的 `bizParam`（`BusinessSerialNumber` / `BusinessId`） |

**失败回调（data 统一为 null，错误原因放 msg）：**

```json
{
    "code": 500,
    "msg": "错误原因描述",
    "ProcessMode": "async",
    "data": null,
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": 123456
    }
}
```

### 13.3 响应格式（SaaS 返回）

**成功响应：**

```json
{
    "code": 200,
    "msg": null,
    "data": null
}
```

**失败响应（SaaS 校验不通过，如缺少必需参数）：**

```json
{
    "code": 400,
    "msg": "缺少必需参数：PushType",
    "data": null
}
```

> SaaS 返回 `2xx` 即视为回调成功送达；失败（非 2xx）时调用方按 `ES_HAGUE_CALLBACK_MAX_RETRIES`（默认 3）自动重试（间隔 `ES_HAGUE_CALLBACK_RETRY_DELAY` 秒），重试期间不通知业务层。**重复 POST 属正常现象**，SaaS 按 `bizParam`+`task_id` 幂等覆盖即可。

### 13.4 cURL 调用示例

```bash
curl --location --request POST 'http://192.168.1.211:8080/delivery/rpa/callback' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "code": 200,
    "msg": "success",
    "ProcessMode": "async",
    "data": {
        "task_id": 44912,
        "files": [
            {
                "url": "common-prod/generatefile/2026/es_vat_haiya/DVAT12312312312312313/DVAT12312312312312313_123456.pdf",
                "name": "DVAT12312312312312313_123456.pdf",
                "type": "海牙文件-已认证"
            }
        ]
    },
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": 123456
    }
}'
```

---

## 14. RPA 自动注册结果回调接口（rpa/autoRegisterCallback）

> SaaS 通过 `POST /rpa/autoRegister/{deliveryId}/{pushType}` 发起 RPA 门户自动注册（异步，受理即返回）后，RPA 侧完成注册时**回调 SaaS 平台统一结果通知接口**，将注册结果（文件 / 错误）通知 SaaS（示例地址 `http://192.168.1.211:8080/rpa/autoRegisterCallback`，以实际配置为准）。

### 14.1 接口信息

| 项目             | 值                                                         |
| ---------------- | ---------------------------------------------------------- |
| **接口地址**     | `POST https://test-cloud.usaeu.com/prod-api/delivery/rpa/autoRegisterCallback`（以实际配置为准） |
| **请求方式**     | POST                                                       |
| **Content-Type** | `application/json`                                         |
| **防重**         | 接口带防重提交，短时间内的重复回调会被拦截并返回提示；接收端仍须按 `bizParam` 幂等处理（以最后为准） |

### 14.2 请求体（回调数据）

**回调数据整体结构：**

| 字段          | 类型        | 说明                                                         |
| ------------- | ----------- | ------------------------------------------------------------ |
| `code`        | int         | 处理结果：`200`=成功，非 200=失败                            |
| `msg`         | string      | 处理消息（成功 `success`，失败为错误原因）                   |
| `ProcessMode` | string      | 处理模式：`async`                                            |
| `data`        | object/null | 成功：对象，含 `receiptType`（回执类型）及对应回执信息；失败：`null` |
| `bizParam`    | object      | 业务标识信息（SaaS 发起注册时原样回传），**必传**，字段见下表 |

**`data.receiptType` 回执类型（注册流程按阶段回调两次）：**

| 回执类型        | 触发时机   | 包含信息                                                     |
| --------------- | ---------- | ------------------------------------------------------------ |
| `REGISTER_INFO` | 注册完成后 | VRS 注册回执编码、MTD 账号/密码/秘钥、注册邮箱，及注册回执/确认文件 |
| `ISSUED_INFO`   | 税号下发后 | VAT 税号、申报截止时间、首次申报区间、税号生效日期、EORI 号，及证书/截图文件 |

**回执类型一：注册信息（`receiptType=REGISTER_INFO`）**

```json
{
    "code": 200,
    "msg": "success",
    "ProcessMode": "async",
    "data": {
        "receiptType": "REGISTER_INFO",
        "vrsReceiptCode": "",
        "mtdAccount": "",
        "mtdPassword": "",
        "mtdSecretKey": "",
        "mtdRegisterEmail": "",
        "files": [
            {
                "url": "common-test/rpa/2026/08/28/xxx.pdf",
                "name": "注册回执文件.pdf",
                "type": "REGISTRATION_RECEIPT_FILE"
            },
            {
                "url": "common-test/rpa/2026/08/28/xxx.pdf",
                "name": "注册确认文件.pdf",
                "type": "REGISTRATION_CONFIRMATION_FILE"
            }
        ]
    },
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": "123456",
        "deliveryId": 123456,
        "pushType": "DE_VAT_REGISTER",
        "operatorId": 1,
        "operatorTime": "2026-08-28 10:00:00"
    }
}
```

| 字段               | 类型   | 必填 | 说明                                                 |
| ------------------ | ------ | ---- | ---------------------------------------------------- |
| `receiptType`      | string | 是   | 回执类型，固定 `REGISTER_INFO`                       |
| `vrsReceiptCode`   | string | 否   | VRS 注册回执编码                                     |
| `mtdAccount`       | string | 否   | MTD 账号                                             |
| `mtdPassword`      | string | 否   | MTD 密码                                             |
| `mtdSecretKey`     | string | 否   | MTD 秘钥                                             |
| `mtdRegisterEmail` | string | 否   | MTD 注册邮箱                                         |
| `files`            | array  | 否   | 注册结果文件数组（无文件可为空数组），元素字段见下表 |

**回执类型二：下号信息（`receiptType=ISSUED_INFO`）**

```json
{
    "code": 200,
    "msg": "success",
    "ProcessMode": "async",
    "data": {
        "receiptType": "ISSUED_INFO",
        "vatNumber": "",
        "declarationDeadline": "",
        "firstDeclarationPeriodStart": "",
        "firstDeclarationPeriodEnd": "",
        "vatEffectiveDate": "",
        "eoriNumber": "",
        "files": [
            {
                "url": "common-test/rpa/2026/08/28/xxx.pdf",
                "name": "VAT税号证书.pdf",
                "type": "VAT_CERTIFICATE_FILE"
            },
            {
                "url": "common-test/rpa/2026/08/28/xxx.pdf",
                "name": "申请EORI结果截图.jpeg",
                "type": "EORI_APPLICATION_RESULT_SCREENSHOT"
            }
        ]
    },
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": "123456",
        "deliveryId": 123456,
        "pushType": "DE_VAT_REGISTER",
        "operatorId": 1,
        "operatorTime": "2026-08-28 10:00:00"
    }
}
```

| 字段                          | 类型   | 必填 | 说明                                                 |
| ----------------------------- | ------ | ---- | ---------------------------------------------------- |
| `receiptType`                 | string | 是   | 回执类型，固定 `ISSUED_INFO`                         |
| `vatNumber`                   | string | 是   | VAT 税号                                             |
| `declarationDeadline`         | string | 否   | 申报截止时间，格式 `yyyy-MM-dd`，如 `2026-12-07`     |
| `firstDeclarationPeriodStart` | string | 否   | 首次申报开始时间，格式 `yyyy-MM-dd`，如 `2026-08-20` |
| `firstDeclarationPeriodEnd`   | string | 否   | 首次申报结束时间，格式 `yyyy-MM-dd`，如 `2026-10-31` |
| `vatEffectiveDate`            | string | 否   | 税号生效日期，格式 `yyyy-MM-dd`，如 `2026-08-20`     |
| `eoriNumber`                  | string | 否   | EORI 号，固定为 `GB + VAT税号 + 000`                 |
| `files`                       | array  | 否   | 下号文件数组（无文件可为空数组），元素字段见下表     |

**`data.files[]` 元素字段：**

| 元素字段 | 类型   | 说明                                   |
| -------- | ------ | -------------------------------------- |
| `url`    | string | 文件访问地址（OSS 相对路径，不含域名） |
| `name`   | string | 文件名                                 |
| `type`   | string | 文件类型枚举，取值见下表               |

**回调文件类型枚举（`data.files[].type`，回调专用，勿自定义）：**

| 文件类型枚举                         | 说明               |
| ------------------------------------ | ------------------ |
| `REGISTRATION_RECEIPT_FILE`          | 注册回执文件       |
| `REGISTRATION_CONFIRMATION_FILE`     | 注册确认文件       |
| `VAT_CERTIFICATE_FILE`               | VAT 税号证书       |
| `EORI_APPLICATION_RESULT_SCREENSHOT` | 申请 EORI 结果截图 |

**`bizParam` 字段：**

| 字段                   | 类型   | 必填 | 说明                                                         |
| ---------------------- | ------ | ---- | ------------------------------------------------------------ |
| `deliveryId`           | long   | 是   | 交付信息 ID（回调定位业务单据）；**缺失或为 null 时回调直接丢弃，仅记录 error 日志** |
| `pushType`             | string | 是   | 推送类型（`{国家二字码}_{业务大类}_{REGISTER\|DECLARE}_...`，同 §3）；**缺失或为 null 时回调直接丢弃，仅记录 error 日志** |
| `BusinessSerialNumber` | string | 否   | 业务流水号（交付编号），原样回传                             |
| `BusinessId`           | string | 否   | 业务 ID，原样回传                                            |
| `operatorId`           | long   | 否   | 发起注册的操作人 ID（成功时作为文件记录 `createBy`）         |
| `operatorTime`         | string | 否   | 发起注册的操作时间，格式 `yyyy-MM-dd HH:mm:ss`（成功时作为文件记录 `createTime`） |
| `logId`                | long   | 否   | 推送请求日志 ID（发起侧回填，用于关联请求日志，回调接口不读取） |

**失败回调（`code` 非 200，`data` 为 `null`，错误原因放 `msg`）：**

```json
{
    "code": 500,
    "msg": "注册失败原因描述",
    "ProcessMode": "async",
    "data": null,
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": "123456",
        "deliveryId": 123456,
        "pushType": "DE_VAT_REGISTER"
    }
}
```

**SaaS 侧处理语义：**

| 回调结果                                          | SaaS 侧处理                                                  |
| ------------------------------------------------- | ------------------------------------------------------------ |
| `code=200` 且 `receiptType=REGISTER_INFO`         | 记录注册信息（VRS 注册回执编码、MTD 账号/密码/秘钥、注册邮箱），并将 `data.files` 逐项写入交付文件记录（`type=RPA`，**删旧插新**：先删除该 `deliveryId` + `pushType` 的旧 RPA 文件记录，再批量插入）；同时记录回调成功日志 |
| `code=200` 且 `receiptType=ISSUED_INFO`           | 记录下号信息（VAT 税号、申报截止时间、首次申报区间、税号生效日期、EORI 号），并将 `data.files` 逐项写入交付文件记录（`type=RPA`，**删旧插新**）；同时记录回调成功日志 |
| `code≠200`                                        | **不更新文件记录**，仅记录回调失败日志（错误信息入日志）     |
| `bizParam.deliveryId` 或 `bizParam.pushType` 为空 | 回调直接丢弃（仅记录 error 日志，不影响其他业务）            |

### 14.3 响应格式（SaaS 返回）

**成功响应：**

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": null
}
```

| 字段   | 类型   | 说明                               |
| ------ | ------ | ---------------------------------- |
| `code` | int    | `200`=成功；`500`=服务器内部错误   |
| `msg`  | string | 成功为「操作成功」；失败为错误原因 |
| `data` | null   | 恒为 `null`                        |

> SaaS 内部业务处理不影响接口返回：`bizParam` 缺失关键字段、注册失败等场景均仅记录日志，HTTP 层仍返回 `200`。回调方收到 `2xx` 即视为通知送达。

### 14.4 cURL 调用示例

```bash
curl --location --request POST 'http://192.168.1.211:8080/rpa/autoRegisterCallback' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "code": 200,
    "msg": "success",
    "ProcessMode": "async",
    "data": {
        "receiptType": "ISSUED_INFO",
        "vatNumber": "GB123456789",
        "declarationDeadline": "2026-12-07",
        "firstDeclarationPeriodStart": "2026-08-20",
        "firstDeclarationPeriodEnd": "2026-10-31",
        "vatEffectiveDate": "2026-08-20",
        "eoriNumber": "GB123456789000",
        "files": [
            {
                "url": "common-test/rpa/2026/08/28/xxx.pdf",
                "name": "VAT税号证书.pdf",
                "type": "VAT_CERTIFICATE_FILE"
            }
        ]
    },
    "bizParam": {
        "BusinessSerialNumber": "DVAT12312312312312313",
        "BusinessId": "123456",
        "deliveryId": 123456,
        "pushType": "DE_VAT_REGISTER",
        "operatorId": 1,
        "operatorTime": "2026-08-28 10:00:00"
    }
}'
```

---

## 附录 A：Country 枚举

| 代码 | 国家     | 文件            | 状态     |
| ---- | -------- | --------------- | -------- |
| DE   | 德国     | `countries/de.php` | 已实现 |
| FR   | 法国     | `countries/fr.php` | 已实现 |
| BE   | 比利时   | `countries/be.php` | 预留   |
| GB   | 英国     | `api.php` | 已实现 |
| IT   | 意大利   | `countries/it.php` | 已实现 |
| NL   | 荷兰     | 待创建          | 预留     |
| ES   | 西班牙   | `countries/es.php` | 已实现 |
| PL   | 波兰     | 待创建          | 预留     |
| AT   | 奥地利   | 待创建          | 预留     |
| SE   | 瑞典     | 待创建          | 预留     |
| CZ   | 捷克     | 待创建          | 预留     |