> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 報關 API 指南

> 提交跨境電商交易資訊至支付寶或微信的報關系統。

透過報關 API，商戶可將**跨境支付交易資訊**提交至支付寶或微信對應的海關系統，以符合跨境電商監管要求。正確提交報關資料可：

* 提升清關效率
* 降低交易被海關攔截風險
* 符合支付平台合規要求

***

## 使用前提

* 僅適用於**跨境交易**
* 僅可對**已成功支付的交易**（`respcd` = `0000`）進行報關
* 商戶須已完成支付寶或微信的跨境商戶報備

***

# 1. 發起報關申請

此接口用於**支付成功後提交報關資訊**。

## HTTP 請求

`POST ../custom/v1/declare`

***

## 請求參數

| 參數名稱               | 必填 | 類型          | 說明                            |
| ------------------ | -- | ----------- | ----------------------------- |
| `trade_type`       | 是  | String(8)   | 支付平台類型：`weixin` 或 `alipay`    |
| `syssn`            | 是  | String(32)  | QFPay 交易流水號                   |
| `customs`          | 是  | String(20)  | 海關代碼，例如：`SHANGHAI_ZS`         |
| `mch_customs_no`   | 是  | String(20)  | 商戶海關登記編號                      |
| `action_type`      | 否  | String(10)  | 僅微信適用：`ADD`（新增）或 `MODIFY`（修改） |
| `mch_customs_name` | 否  | String(256) | 僅支付寶適用：報關商戶名稱                 |
| `out_request_no`   | 否  | String(32)  | 僅支付寶適用：商戶報關請求流水號              |
| `amount`           | 否  | String(20)  | 僅支付寶適用：報關金額（例如 `2.00`）        |

***

## 子訂單參數（拆單或修改報關時使用）

如為拆單交易或進行修改報關，需提供以下欄位：

| 參數名稱            | 條件必填 | 類型         | 說明                                        |
| --------------- | ---- | ---------- | ----------------------------------------- |
| `sub_order_no`  | 條件   | String(64) | 子訂單編號                                     |
| `fee_type`      | 條件   | String(8)  | 幣別（微信僅支援 `CNY`）                           |
| `order_fee`     | 條件   | String(8)  | 子訂單總金額（分）=`product_fee` + `transport_fee` |
| `product_fee`   | 條件   | String(8)  | 商品金額（分）                                   |
| `transport_fee` | 條件   | String(8)  | 運費金額（分）                                   |

***

## 回應參數

| 參數名稱                         | 類型          | 說明                                    |
| ---------------------------- | ----------- | ------------------------------------- |
| `syssn`                      | String(40)  | QFPay 交易流水號                           |
| `respcd`                     | String(4)   | `0000` 成功；`1143/1145` 表示處理中需重查；其他表示失敗 |
| `resperr`                    | String(128) | 錯誤描述                                  |
| `respmsg`                    | String(128) | 附加訊息                                  |
| `verify_department`          | String      | 海關受理部門                                |
| `verify_department_trade_id` | String      | 海關返回的交易編號                             |

***

# 2. 查詢報關結果

可查詢報關是否成功處理，或是否被海關受理。

## HTTP 請求

`POST ../custom/v1/query`\
或\
`GET ../custom/v1/query`

***

## 請求參數

| 參數名稱           | 必填 | 類型         | 說明                    |
| -------------- | -- | ---------- | --------------------- |
| `trade_type`   | 是  | String(8)  | `weixin` 或 `alipay`   |
| `customs`      | 是  | String(20) | 海關代碼，例如 `SHANGHAI_ZS` |
| `syssn`        | 是  | String(32) | QFPay 交易流水號           |
| `sub_order_no` | 否  | String(40) | 子訂單編號                 |

***

## 回應參數

| 參數名稱      | 類型          | 說明                                                                                     |
| --------- | ----------- | -------------------------------------------------------------------------------------- |
| `syssn`   | String(40)  | QFPay 交易流水號                                                                            |
| `respcd`  | String(4)   | 回應碼                                                                                    |
| `resperr` | String(128) | 錯誤訊息                                                                                   |
| `respmsg` | String(128) | 附加訊息                                                                                   |
| `data`    | Array       | 報關資料陣列，包含 `sub_order_no`、`verify_department`、`verify_department_trade_id`、`errmsg` 等欄位 |

***

# 3. 重新發送報關資料

若海關端未成功接收報關資料，可使用此接口重新推送。

## HTTP 請求

`POST ../custom/v1/redeclare`

***

## 請求參數

| 參數名稱             | 必填 | 類型         | 說明                  |
| ---------------- | -- | ---------- | ------------------- |
| `trade_type`     | 是  | String(8)  | `weixin` 或 `alipay` |
| `customs`        | 是  | String(20) | 海關代碼                |
| `syssn`          | 是  | String(32) | QFPay 交易流水號         |
| `mch_customs_no` | 是  | String(20) | 商戶海關登記編號            |
| `sub_order_no`   | 否  | String(40) | 子訂單編號（拆單時需提供）       |

***

## 注意事項

<Tip>
  * 僅可對成功交易（`respcd` = `0000`）進行報關。
  * 支付寶報關需確認「報關商戶名稱」與「海關登記編號」正確一致。
  * 微信拆單報關時，需確保 `product_fee` 與 `transport_fee` 金額準確。
  * 各地區海關合規要求不同，請依所在地法規準備資料。
</Tip>

完整回應碼請參考：\
[交易狀態碼](/zh-hant/integration/api-reference/status-codes)