Bitzsoft.Integrations.Express.Cainiao 1.0.1

Bitzsoft.Integrations.Express.Cainiao

菜鸟速递 EDI 服务实现 -- 对接菜鸟速递开放平台 B2C 订单管理接口。

功能特性

• 基于菜鸟速递 EDI form-urlencoded 公共信封，业务报文使用 JSON
• 认证方式：logistic_provider_id + data_digest = Base64(MD5(logistics_interface + secretKey))
• 支持轨迹查询、轨迹订阅、三合一下单、运单取消、时效表达、电子面单取号与预分拣
• 统一异常处理，供应商错误码自动映射为 ExpressException
• 实现 IExpressProvider 统一契约，可无缝替换其他供应商实现

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express.Cainiao

PackageReference

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

配置

appsettings.json

{
  "Express": {
    "Cainiao": {
      "AppKey": "菜鸟提供的对接码",
      "AppSecret": "双方约定的secretKey",
      "BaseUrl": "https://edi-daily.xpm.cainiao.com",
      "HttpClientName": "CainiaoExpress"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Express.Cainiao;

builder.Services.AddBitzsoftCainiaoExpress(
    builder.Configuration.GetSection("Express:Cainiao"));

委托配置

builder.Services.AddBitzsoftCainiaoExpress(options =>
{
    options.AppKey = "your_provider_id";
    options.AppSecret = "your_secret_key";
});

请求审计

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

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

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("AppSecret");
});
services.AddBitzsoftCainiaoExpress(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[] { "CN001", "CN002" });
    }
}

订阅轨迹推送

ExpressSubscriptionResult sub = await _express.SubscribeAsync(
    trackingNumber: "CN001",
    callbackUrl: "https://yourapp.com/express/callback");
// 回调接收需按菜鸟推送接口另行暴露服务

核心类型一览

实现状态

API 端点

依赖

注意事项

• 公开文档中的 edi-daily.xpm.cainiao.com 为测试网关域名，生产地址、对接码和密钥需由菜鸟侧提供
• SubscribeAsync 只提交订阅运单号，回调 URL 不属于该接口入参；回调服务需按菜鸟"物流轨迹推送接口"另行实现
• GenerateWaybillAsync 只能返回取号结果，HTML/PDF 打印内容需结合菜鸟打印组件或淘系专用能力补充
• GetQuoteAsync 对应下单前预计揽收信息，不是按单运费报价
• IExpressProvider 使用 TryAddSingleton 注册，如需同时注册多个供应商请单独引用并自行解析

相关包

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