Bitzsoft.Integrations.Express.ShowApi 1.0.0-alpha.10

Bitzsoft.Integrations.Express.ShowApi

万维易源快递物流查询服务实现 -- API 市场聚合，作为备用查询与时效预估渠道。

功能特性

• 基于万维易源统一 API 网关，支持快递物流查询、订阅推送、快递公司识别和物流时效查询
• 认证方式：随表单请求传递 showapi_appid 与 showapi_sign
• 定位为备用聚合平台，不提供寄件下单、订单取消和电子面单能力
• 双层错误码校验：同时检查网关层 showapi_res_code 和业务层 ret_code
• 实现 IExpressProvider 统一契约，可无缝替换其他供应商实现

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express.ShowApi

PackageReference

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

配置

appsettings.json

{
  "Express": {
    "ShowApi": {
      "AppId": "你的AppId",
      "AppSecret": "你的AppSecret",
      "BaseUrl": "https://route.showapi.com",
      "HttpClientName": "ShowApiExpress"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Express.ShowApi;

builder.Services.AddBitzsoftShowApiExpress(
    builder.Configuration.GetSection("Express:ShowApi"));

委托配置

builder.Services.AddBitzsoftShowApiExpress(options =>
{
    options.AppId = "your_app_id";
    options.AppSecret = "your_app_secret";
});

请求审计

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

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

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("AppSecret");
});
services.AddBitzsoftShowApiExpress(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)
    {
        // 查询单个运单轨迹（未传 carrierCode 时使用 auto 自动识别）
        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[] { "YT001", "ZTO002" });
    }
}

单号识别与时效查询

// 自动识别快递公司
ExpressCarrierInfo carrier = await _express.DetectCarrierAsync("SF1234567890");
Console.WriteLine($"{carrier.CarrierName}（统一编码 {carrier.UnifiedCode}）");

// 物流时效查询（仅返回预计用时，不返回真实运费）
IReadOnlyList<ExpressQuoteResult> quotes = await _express.GetQuoteAsync(request);

核心类型一览

实现状态

API 端点

依赖

注意事项

• 万维易源定位为 API 市场，接口返回体包含网关层 showapi_res_code 和业务层 ret_code，封装会同时检查两层错误码
• SubscribeAsync 会调用 /64-22 更新账号级回调地址；同一 App 多业务共用时需避免互相覆盖回调配置
• GetQuoteAsync 对应物流时效查询接口，无法返回真实运费，EstimatedCost 保持默认值
• 查询接口未传入快递公司编码时使用 auto 作为自动识别编码，具体可用性以万维易源套餐和接口返回为准
• 不同接口的可用额度和计费策略由万维易源控制，生产使用前应在控制台确认套餐权限
• IExpressProvider 使用 TryAddSingleton 注册，如需同时注册多个供应商请单独引用并自行解析

相关包

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