公开技术评估层：先判断能不能接、怎么接、复杂度多大Public technical evaluation layer for fast integration assessment

API 接口清单Endpoint list

以下接口与当前公开文档保持一致，覆盖下单、查询、计价、打印、退款与轨迹链路。Aligned with current ShowDoc public docs, covering order creation, query, quotation, print, refund, and tracking workflows.

• POST /v1/order 创建订单并返回运单编码等核心履约字段。Create shipment and return shipment_code with core fields.
• POST /v1/order/quotation 下单前估算费用与计费重量。Estimate price and billable weight before order creation.
• GET /v1/order/{shipment_code} 查询订单和面单状态（部分渠道需异步拉取面单）。Query order and label status (some channels require asynchronous label retrieval).
• POST /v1/shipment/{shipment_code}/refund 提交取消/退款申请（下单 30 天内；退款审核由服务商流程驱动）。Submit cancellation/refund requests (within 30 days; final approval follows carrier workflow).
• GET /v1/order/{shipment_code}/track 获取轨迹节点，用于异常跟进。Retrieve tracking events for monitoring and exception handling.

退款提醒：取消分两阶段处理，整体周期通常不超过 30 天；公开文档说明 USPS 取消会收取约 10% 运费。已取消运单不可继续发货。Refund note: cancellation follows a two-phase process and is generally completed within 30 days; public docs indicate USPS cancellations may incur about 10% freight. Do not ship with cancelled labels.

请求/响应示例Sample request / response

POST /v1/order/quotation
{
  "order_id": "SO-10001",
  "ship_from_zip": "91761",
  "ship_to_zip": "33101",
  "weight_lb": 1.2,
  "service": "ground"
}

200 OK
{
  "shipment_code": "QTE-6G72A",
  "carrier": "USPS",
  "estimated_total": 5.92,
  "currency": "USD"
}

示例用于评估字段结构，不代表完整业务字段与生产凭证。Example payloads are for evaluation only and do not include full production fields.

错误处理原则Error handling principles

• 2xx 代表请求受理成功，4xx 处理参数/业务错误，5xx 处理系统级问题。Use 2xx for accepted requests, 4xx for validation/business errors, and 5xx for system-side failures.
• 不要将所有异常统一归类为“接口调用失败”，请保留原始错误码与错误信息以便修正后重试。Do not collapse all errors into a generic “API call failed”; preserve raw error codes/messages for corrective retry.
• 建议结合告警和重试上限，避免无限重试导致流量放大。Set retry caps and alerts to avoid runaway retry loops.

幂等与重试摘要Idempotency / retry summary

• 关键写接口建议使用唯一业务单号 + 幂等键，避免重复出单。Use unique order references and idempotency keys on write endpoints.
• 超时重试采用指数退避，并保留请求日志用于追踪。Apply exponential backoff retries with request logs for traceability.
• 失败补偿优先走查询接口确认状态，再决定是否重放请求。Use status query before replaying failed writes.