> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 建立國際出貨
> 建立跨境配送標籤的端對端指南
# 建立國際出貨
本指南將引導您使用 YunExpress 建立一筆從日本到美國的跨境出貨。相同的流程適用於所有支援的物流業者和配送路線。
## 開始之前
* 您已在入門流程中取得 API 權杖（請參閱[認證](/zh-Hant/authentication#存取方式)）
* 您已知道物流業者的 slug 和產品代碼（請參閱[物流業者與產品代碼](/zh-Hant/core-concepts#物流業者與產品代碼)）
## 1. 準備出貨資料
國際出貨需要以下資訊：
* **寄件地址** — 您的倉庫或物流中心
* **收件地址** — 客戶的配送地址
* **包裹詳細資訊** — 重量和品項層級的海關申報（英文描述、數量、單價、單位重量）
海關申報（`descriptionEn`、`unitPrice`、`unitWeight`）是跨境出貨的必填欄位。遺漏或不準確的海關資料可能導致清關延誤。
## 2. 建立標籤
請將 `unique-key-per-request` 替換為每次呼叫時的唯一值。重複使用相同的 `idempotencyKey` 將觸發冪等重放，而非建立新標籤。
```bash cURL theme={null}
curl -X POST https://api.flexforward.com/labels \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "unique-key-per-request",
"courier": "yunexpress",
"service": {
"productCode": "HKMUZXR"
},
"shipment": {
"shipFrom": {
"contact": {
"firstName": "Warehouse",
"lastName": "Staff",
"phone": "+81-90-1234-5678"
},
"address": {
"countryCode": "JP",
"city": "Tokyo",
"postalCode": "100-0001",
"streetLines": ["1-1 Marunouchi"]
}
},
"shipTo": {
"contact": {
"firstName": "Jane",
"lastName": "Smith",
"phone": "+1-555-0100",
"email": "jane.smith@example.com"
},
"address": {
"countryCode": "US",
"city": "Los Angeles",
"state": "CA",
"postalCode": "90001",
"streetLines": ["456 Oak Avenue", "Apt 12"]
}
},
"parcels": [
{
"weight": 0.8,
"items": [
{
"descriptionEn": "Cotton T-Shirt",
"descriptionLocal": "コットンTシャツ",
"quantity": 2,
"unitPrice": { "amount": 29.99, "currency": "USD" },
"unitWeight": 0.3,
"hsCode": "6109.10"
},
{
"descriptionEn": "Phone Case",
"descriptionLocal": "スマホケース",
"quantity": 1,
"unitPrice": { "amount": 12.00, "currency": "USD" },
"unitWeight": 0.2,
"hsCode": "3926.90"
}
]
}
]
}
}'
```
```javascript Node.js theme={null}
const response = await fetch('https://api.flexforward.com/labels', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
idempotencyKey: 'unique-key-per-request',
courier: 'yunexpress',
service: {
productCode: 'HKMUZXR'
},
shipment: {
shipFrom: {
contact: { firstName: 'Warehouse', lastName: 'Staff', phone: '+81-90-1234-5678' },
address: { countryCode: 'JP', city: 'Tokyo', postalCode: '100-0001', streetLines: ['1-1 Marunouchi'] }
},
shipTo: {
contact: { firstName: 'Jane', lastName: 'Smith', phone: '+1-555-0100', email: 'jane.smith@example.com' },
address: { countryCode: 'US', city: 'Los Angeles', state: 'CA', postalCode: '90001', streetLines: ['456 Oak Avenue', 'Apt 12'] }
},
parcels: [{
weight: 0.8,
items: [
{ descriptionEn: 'Cotton T-Shirt', descriptionLocal: 'コットンTシャツ', quantity: 2, unitPrice: { amount: 29.99, currency: 'USD' }, unitWeight: 0.3, hsCode: '6109.10' },
{ descriptionEn: 'Phone Case', descriptionLocal: 'スマホケース', quantity: 1, unitPrice: { amount: 12.00, currency: 'USD' }, unitWeight: 0.2, hsCode: '3926.90' }
]
}]
}
})
});
const label = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.flexforward.com/labels',
headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
json={
'idempotencyKey': 'unique-key-per-request',
'courier': 'yunexpress',
'service': {
'productCode': 'HKMUZXR'
},
'shipment': {
'shipFrom': {
'contact': {'firstName': 'Warehouse', 'lastName': 'Staff', 'phone': '+81-90-1234-5678'},
'address': {'countryCode': 'JP', 'city': 'Tokyo', 'postalCode': '100-0001', 'streetLines': ['1-1 Marunouchi']}
},
'shipTo': {
'contact': {'firstName': 'Jane', 'lastName': 'Smith', 'phone': '+1-555-0100', 'email': 'jane.smith@example.com'},
'address': {'countryCode': 'US', 'city': 'Los Angeles', 'state': 'CA', 'postalCode': '90001', 'streetLines': ['456 Oak Avenue', 'Apt 12']}
},
'parcels': [{
'weight': 0.8,
'items': [
{'descriptionEn': 'Cotton T-Shirt', 'descriptionLocal': 'コットンTシャツ', 'quantity': 2, 'unitPrice': {'amount': 29.99, 'currency': 'USD'}, 'unitWeight': 0.3, 'hsCode': '6109.10'},
{'descriptionEn': 'Phone Case', 'descriptionLocal': 'スマホケース', 'quantity': 1, 'unitPrice': {'amount': 12.00, 'currency': 'USD'}, 'unitWeight': 0.2, 'hsCode': '3926.90'}
]
}]
}
}
)
label = response.json()
```
## 3. 確認回應
```json 201 Created theme={null}
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "created",
"courier": "yunexpress",
"courierOrderNumber": "YT2503010001",
"courierTrackingNumber": "YT2503010001CN",
"error": null
}
```
如果 `status` 為 `created`，表示標籤已準備就緒。請儲存 `id`，後續將用於取得標籤文件和追蹤出貨。
如果 `status` 為 `failed`，請檢查 `error` 物件以了解物流業者的拒絕原因。詳情請參閱[錯誤處理](/zh-Hant/error-handling#下游物流業者錯誤502)。
## 4. 後續步驟
下載航空提單 PDF 以貼附於包裹上。
使用正規化的追蹤資料監控出貨進度。
## 國際出貨提示
* **HS 編碼** — 附上國際商品統一分類代碼（`hsCode`）可加速清關流程。請至您所在國家的海關機構網站查詢編碼。
* **當地語言描述** — `descriptionLocal` 欄位提供目的地國家語言的品項描述，有助於海關處理。
* **冪等性** — 請務必使用有意義的 `idempotencyKey`（例如：您的訂單 ID），以確保重試是安全的。請參閱[冪等性與重試](/zh-Hant/idempotency-and-retries)。