Bitzsoft.Integrations.Express.ChinaPost 1.0.1

Bitzsoft.Integrations.Express.ChinaPost

中国邮政/EMS 物流服务实现 -- 基于《中小电商企业接口规范 V2.7》公共请求信封对接。

功能特性

• EMS 三要素认证：senderNo + authorization + 公共请求信封（apiCode）
• 支持运单轨迹查询、白名单订阅、订单接入、订单取消、预估邮费、面单查询
• 支持按 EMS 常见单号规则的本地承运商识别
• 统一异常处理，供应商错误码自动映射为 ExpressException
• 实现 IExpressProvider 统一契约，可无缝替换其他供应商实现

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express.ChinaPost

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Express.ChinaPost" Version="1.0.0" />

配置

appsettings.json

{
  "Express": {
    "ChinaPost": {
      "SenderNo": "协议客户号",
      "Authorization": "测试或生产授权码",
      "BaseUrl": "https://api.ems.com.cn",
      "UserCode": "可选用户编码",
      "Version": "V1.0.0",
      "HttpClientName": "ChinaPostExpress"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Express.ChinaPost;

builder.Services.AddBitzsoftChinaPostExpress(
    builder.Configuration.GetSection("Express:ChinaPost"));

委托配置

builder.Services.AddBitzsoftChinaPostExpress(options =>
{
    options.SenderNo = "your_sender_no";
    options.Authorization = "your_authorization";
});

请求审计

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftChinaPostExpress(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("Authorization");
});
services.AddBitzsoftChinaPostExpress(options => { /* ... */ });

使用示例

物流轨迹查询

using Bitzsoft.Integrations.Express.Interfaces;
using Bitzsoft.Integrations.Express.Models;

public class TrackingService
{
    private readonly IExpressProvider _express;

    public TrackingService(IExpressProvider express) => _express = express;

    public async Task TrackAsync(string trackingNumber)
    {
        ExpressTrackingInfo info = await _express.TrackAsync(trackingNumber);
        Console.WriteLine($"状态: {info.State}, 轨迹数: {info.Traces.Count}");

        foreach (var step in info.Traces)
            Console.WriteLine($"[{step.Time:yyyy-MM-dd HH:mm}] {step.Description}");

        // 批量查询
        IReadOnlyList<ExpressTrackingInfo> batch =
            await _express.BatchTrackAsync(new[] { "EA001", "EA002" });
    }
}

订阅轨迹推送

ExpressSubscriptionResult sub = await _express.SubscribeAsync(
    trackingNumber: "EA001",
    callbackUrl: "https://yourapp.com/express/callback");

核心类型一览

实现状态

EMS 扩展参数

ExpressShipmentOrder.Extra 可传 EMS 特有字段：

取消订单时 EMS 需同时传 logisticsOrderNo 和 waybillNo。统一接口只有 orderId 参数，因此可传：

logisticsOrderNo|waybillNo|cancelReason

或 JSON：

{"logisticsOrderNo":"O202203281508328002352578560","waybillNo":"1295838760599","cancelReason":"客户取消"}

依赖

注意事项

• EMS 要求地址使用国标全称，例如 浙江省、杭州市
• 统一模型中的重量单位为千克，Provider 会转换为 EMS 的克
• GetQuoteAsync 使用 EMS 国内特快物品默认产品代码 112104302300991
• GenerateWaybillAsync 若未在 Extra["waybillNo"] 中传单号，会先调用订单接入接口创建订单，再查询面单
• IExpressProvider 使用 TryAddSingleton 注册，如需同时注册多个供应商请单独引用并自行解析

相关包

• Bitzsoft.Integrations.Express -- 抽象层
• Bitzsoft.Integrations.Express.All -- 聚合包
• Bitzsoft.Integrations.Express.Kdniao -- 快递鸟
• Bitzsoft.Integrations.Compatibility -- 基础工具库