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 件邮件。
Schemapostal-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批次不符合 Schema。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收件人的 ZIP 邮编是有效的美国 ZIP 邮编。拒绝
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