物流接口Shipping API

EasyShippingX 物流接口总览EasyShippingX shipping API overview

该页面用于技术评估阶段,帮助团队在查看完整受限文档前,先判断接口覆盖范围、接入复杂度和上线路径。接口能力覆盖询价、创建、追踪、退款及对账字段映射,支持门户与 API 的渐进式上线。This page is designed for technical evaluation before full credentialed documentation review. It helps teams understand API scope, integration complexity, and rollout options across quotation, shipment creation, tracking, refunds, and reconciliation field mapping.

公开评估层:你可以先确认什么Public evaluation layer: what teams can verify first

通过3PL API 采购清单将技术评估转为多客户运营要求,再用EDI 与 Shipping API 边界指南判断各类消息与执行步骤应由哪个系统负责。Use the 3PL API procurement checklist to translate this technical evaluation into multi-client operating requirements. The EDI and Shipping API boundary guide helps decide which system should own each message and execution step.

  • 接口是否覆盖核心履约流程(询价、下单、追踪、退款)。Whether core fulfillment flows are covered: quotation, order creation, tracking, and refunds.
  • 字段是否可映射到 OMS/WMS/ERP 的订单与账单模型。Whether fields can map cleanly into OMS, WMS, and ERP shipment models.
  • 是否支持低风险上线:先用门户、后续扩展 API。Whether low-risk rollout is possible with portal-first and API expansion later.

核心接口链路Core API workflow

需要承运商专项评估示例时,可参考SpeedX 接入流程指南,并对照账户文档核验相同的报价、面单、轨迹与恢复边界。For a carrier-specific example of the evaluation sequence, use the SpeedX integration workflow guide and check the same quotation, label, tracking, and recovery boundaries against the account documentation.

阶段Step目标Purpose关键字段Key fields
询价Quotation评估订单预估费用与可用服务Estimate service fit and projected charges重量、区域、服务类型Weight, region, service type
创建运单Create shipment生成运单并返回唯一标识Create shipment and return unique identifiersorder_id、shipment_codeorder_id, shipment_code
轨迹Tracking同步轨迹事件和异常状态Sync tracking events and exception states状态、时间戳、异常标识Status, timestamp, exception type
退款冲销Refund/reversal发起退款并回写账单链路Trigger refund and map to billing recordsrefund_id、原 shipment_coderefund_id, source shipment_code

把物流接口当成完整生命周期,而不是单个下单端点Treat a shipping API as a lifecycle, not one purchase endpoint

可靠的接入从订单输入开始,贯穿地址与包裹校验、可用服务询价、承运选择、创建标签、轨迹回传、取消退款和账单核对。技术评估时应逐段确认输入、输出、唯一标识和失败状态,而不是只验证能否返回一张面单。A reliable integration starts with order input and continues through address and parcel validation, service quotation, carrier selection, label creation, tracking updates, voids or refunds, and invoice review. Technical evaluation should confirm the input, output, unique identifiers, and failure states for every stage rather than stopping after one label is returned.

能力Capability接入时要确认What to verify运营结果Operational outcome
询价与服务筛选Rates and service filtering地址、尺寸重量、服务约束和报价有效期Address, dimensions, weight, service constraints, and quote validity只展示符合订单承诺的可用路径Show only options that fit the order promise
创建与标签Creation and labels幂等键、标签格式、外部订单号和重试结果Idempotency key, label format, external order ID, and retry outcome避免重复运单并保留审计链路Avoid duplicate shipments and preserve an audit trail
轨迹与异常Tracking and exceptions事件映射、时间戳、重复事件和告警规则Event mapping, timestamps, duplicates, and alert rules让客服与仓库使用同一状态口径Give support and warehouse teams one status model
冲销与对账Voids and reconciliation退款状态、原运单关联和最终账单字段Refund state, original-shipment linkage, and final invoice fields解释询价、购标与最终费用之间的差异Explain differences between quote, label purchase, and final charge

财务评审时,可进一步查看询价与最终承运账单差异指南,把预估字段和实际费用调整映射到同一运单记录。For finance review, use the rate quote versus final carrier charge guide to map projected fields and final adjustments to the same shipment record.

上线前的可靠性与治理检查Reliability and governance checks before launch

认证、密钥与环境隔离Authentication, credentials, and environment separation

测试和生产凭证应分开保存,并明确密钥轮换、最小权限和日志脱敏责任。测试数据也应使用可识别的环境标记,避免团队把测试标签或事件带入真实履约流程。Test and production credentials should be stored separately, with clear ownership for rotation, least privilege, and log redaction. Test records also need visible environment markers so test labels or events cannot enter live fulfillment by mistake.

幂等、超时与安全重试Idempotency, timeouts, and safe retries

创建类请求需要稳定的业务唯一键。客户端超时时,不应立即假设请求失败并重新购标;应先通过唯一键查询结果,再决定重试。这样才能把网络故障与真实业务失败区分开。Creation requests need a stable business key. When the client times out, it should not assume failure and purchase again immediately; it should look up the result by that key before retrying. This separates a network failure from a genuine business failure.

事件消费、监控与人工兜底Event consumption, monitoring, and manual fallback

轨迹事件应允许重复和乱序到达,并保留原始事件用于排查。上线看板至少要覆盖请求成功率、延迟、重试量、未匹配事件和人工处理队列;同时保留门户兜底,让仓库在局部接口故障时仍可完成关键出单。Tracking consumers should tolerate duplicate and out-of-order events while retaining raw events for investigation. Launch monitoring should cover request success, latency, retries, unmatched events, and the manual-work queue. A portal fallback also lets the warehouse complete critical shipments during a localized integration failure.

接口专题页API topic pages

轨迹接口Tracking API

轨迹事件、异常状态与工单升级路径。Shipment events, exception states, and escalation workflows.

常见问题FAQ

不需要。公开评估层可先判断接口覆盖、字段模型和接入路径是否匹配。No. The public layer already helps teams assess flow coverage, field model fit, and onboarding path.
可以。许多团队通过门户先跑通流程,再分阶段接入 API。Yes. Many teams validate operations in the portal first, then expand through phased API rollout.
不是。运营和财务也可用它确认轨迹与对账的数据协同方式。No. Operations and finance teams can use it to confirm how tracking and reconciliation data will align.

准备进入 API 接入评估?Ready to evaluate API onboarding?

先提交运单画像获取承运组合建议,再安排技术评审与测试凭证流程。Share shipment profile first, then move into technical review and test credential planning.