Skip to main content

開發者 · 郵政 API

郵政 API 規格 v1

採用 HTTPS 及 JSON。欄位名稱使用 snake_case，日期格式為 YYYY-MM-DD，金額以十進位字串表示。我們在同一個請求中驗證每件郵件，因此回應即為結果。

規格 v1規劃中這些端點尚在規劃中。正式上線前，我們會為每位客戶開通沙箱環境。

基本資訊

基本資訊
項目內容
正式環境https://api.alliedchb.com/v1
沙箱環境https://api-test.alliedchb.com/v1
身分驗證標頭 X-Client-Id 及 X-Client-Secret，每個環境一組。我們以安全管道傳送用戶端密碼。
請求追蹤選用標頭 X-Request-Id 。
冪等性依 item_id 判定：同一 S10 號碼第二次 POST 時，回傳 DUPLICATE 。
批次大小每個請求 1 至 5,000 件郵件。
結構描述postal-items.v1.json（JSON Schema 2020-12）。

端點

  • POST/v1/items傳送一批郵件。每件郵件各有自己的結果。
  • GET/v1/items/{item_id}單件郵件的狀態歷程：報關單號、CBP 及 FDA 事件，以及關稅。
  • GET/v1/health服務檢查。無需身分驗證。

傳送批次

以三種語言撰寫的同一個請求。本文是一個 postal-items.v1 批次。
curl -X POST https://api-test.alliedchb.com/v1/items \  -H "X-Client-Id: $ALLIED_CLIENT_ID" \  -H "X-Client-Secret: $ALLIED_CLIENT_SECRET" \  -H "Content-Type: application/json" \  --data @postal-items.v1.example.json

回應：每件郵件一項結果

200 OK · application/json
{  "batch_ref": "POST-DISPATCH-2026-10-01-A",  "results": [    {      "item_id": "CP123456785CA",      "result": "ACCEPTED",      "route": "ET13",      "ace_bill": { "mode": "AIR", "bill_type": "R", "issuer": "", "number": "SFPCP123456785CA" },      "warnings": [],      "field_errors": []    }  ]}

錯誤

整個請求失敗時，會收到此封套。單件郵件的問題則在該郵件的結果中回傳。
錯誤
HTTP錯誤發生情況
400INVALID_JSON本文不是有效的 JSON。
401UNAUTHORIZED未提供用戶端 ID 或用戶端密碼，或其內容不正確。
422VALIDATION_ERROR批次不符合結構描述。field_errors 列出每個問題。
429RATE_LIMITED請求過多。請等候後再重新傳送。
500SERVER_ERROR我方錯誤。請再次傳送同一批次：重複的郵件會回傳 DUPLICATE 。
422 · VALIDATION_ERROR
{  "error": "VALIDATION_ERROR",  "message": "The batch does not match postal-items.v1.json",  "field_errors": [    { "field": "items[3].contents[0].hs_code", "code": "SCHEMA", "message": "required" }  ]}

驗證代碼

我們依下列規則檢查每件郵件。
驗證代碼
代碼規則結果
SCHEMA郵件符合 postal-items.v1.json 。拒絕
S10_FORMAT2 個字母、8 位數字、1 位檢查碼及 2 個字母的國家代碼。拒絕
S10_CHECK_DIGIT權重為 8 6 4 2 3 5 9 7。結果為 10 時改為 0，結果為 11 時改為 5。拒絕
ZIP_UNKNOWN收件人郵遞區號是有效的美國郵遞區號。拒絕
S10_US_ISSUED號碼以 US 結尾，因此由 USPS 核發。報關類型 13 需要外國郵政業者核發的號碼。警告
OVER_2500依 CBP 匯率換算，郵件價值超過 $2,500。正式報關
DUPLICATE我們已有此 S10 號碼。重複

狀態清單

GET /v1/items/{item_id} 中的郵件狀態。
狀態清單
狀態含義
RECEIVED我們已收到郵件資料。
VALIDATED郵件已通過檢查。
FILED我們已將報關傳送至 CBP。報關單號在回應中。
CBP_RELEASEDCBP 已放行郵件。
CBP_HOLDCBP 扣留郵件。
FDA_HOLDFDA 扣留郵件以進行審查。
FDA_MAY_PROCEEDFDA 已放行郵件。
REJECTED郵件未通過檢查。回應列出每個問題。

從資料測試開始

請以 JSON、CSV 或 Excel 寄給我們一批發運樣本。我們在第一筆報關前，回報資料中的每項缺漏。報價請來信洽詢。

請致電 (908) 291-8001 或發送電子郵件至 mail@alliedchb.com

寫信給郵件業務組報關類型 13 說明

本頁為翻譯版本。本網站以英文版為正式版本。我們的線上表單及文件均為英文。 English