如何使用SDK对接QuickBooks POS与ASP.NET/.NET Web应用

前置准备 #

• 确认QuickBooks POS版本为v12及以上桌面版，POS端进入设置-集成设置页，开启第三方应用接入权限，记录配置的接入端口、本机计算机名，默认端口为8080。
• 安装对应版本的QuickBooks POS SDK，SDK位数必须和已安装的POS程序位数一致：32位POS安装32位SDK，64位POS安装64位SDK，安装完成后系统会自动注册对应COM互操作程序集，无需额外引入第三方依赖包。

项目配置 #

• 若使用ASP.NET Framework项目，直接在项目引用中添加Interop.QBPOSFC的COM引用，选择和SDK版本匹配的主版本号即可，目前最新SDK对应的程序集版本为14.0。
• 若使用ASP.NET Core/.NET 5+项目，SDK原生提供的COM组件无法直接引用，需要先通过Windows SDK自带的tlbimp工具将COM类型库导出为标准.NET互操作程序集，执行命令：tlbimp QBPOSFC14.dll /out:QBPOSFC.Interop.dll，将生成的dll放入项目目录添加本地引用即可。注意项目平台目标必须设置为和POS、SDK一致的x86/x64架构，不能使用Any CPU，否则运行时会抛出COM调用格式异常。

核心连接与调用逻辑 #

注意：QuickBooks POS SDK为本地COM组件，不支持直接跨公网远程调用。ASP.NET应用必须和POS程序部署在同一台机器，或同一局域网内可直连POS的接入端口，公网场景需要自行在POS所在机器部署代理服务做请求转发，禁止直接将POS接入端口暴露到公网。

基础连接与API调用示例代码如下：

using System;
using System.Runtime.InteropServices;
using QBPOSFC14;

public class QbPosClient : IDisposable
{
    private QBPOSSessionManager _sessionManager;
    // 局域网部署时改为POS所在机器的内网IP/计算机名
    private const string TargetPosHost = "localhost";
    private const string TargetPosPort = "8080";
    // 自定义你的应用名称，POS端授权记录会显示该名称
    private const string IntegratorAppName = "自定义ASP.NET业务应用";
    // 本地开发可留空，上架官方应用市场需要申请专属AppId
    private const string IntegratorAppId = "";

    public void Connect()
    {
        _sessionManager = new QBPOSSessionManager();
        try
        {
            // 建立基础连接，最后一个参数为连接模式：0为多用户共享模式，2为单用户独占模式
            _sessionManager.OpenConnection(IntegratorAppId, IntegratorAppName, TargetPosHost, TargetPosPort, 0);
            // 开启会话，第一个参数为公司文件路径，留空默认使用POS当前打开的公司文件
            _sessionManager.BeginSession("", QBPOSOpenMode.omDontCare);
        }
        catch (Exception ex)
        {
            // 常见报错原因：POS未启动、端口不通、未授权、平台位数不匹配、IIS权限不足
            throw new InvalidOperationException($"QuickBooks POS连接失败：{ex.Message}", ex);
        }
    }

    // 示例：查询在售库存商品列表
    public IItemInventoryRetList GetActiveInventoryItems()
    {
        var msgSet = _sessionManager.CreateMsgSetRequest();
        var queryReq = msgSet.AppendItemInventoryQueryRq();
        // 设置查询过滤条件：仅返回在售商品
        queryReq.ORListQueryWithOwnerIDAndMaxReturned.ListFilter.ActiveStatus.SetValue(QBENActiveStatus.asActiveOnly);

        var responseSet = _sessionManager.DoRequests(msgSet);
        var firstResp = responseSet.ResponseList.GetAt(0);
        if (firstResp.StatusCode != 0)
        {
            throw new InvalidOperationException($"库存查询失败，错误码{firstResp.StatusCode}：{firstResp.StatusMessage}");
        }
        return firstResp.Detail as IItemInventoryRetList;
    }

    public void Dispose()
    {
        if (_sessionManager != null)
        {
            try
            {
                _sessionManager.EndSession();
                _sessionManager.CloseConnection();
            }
            finally
            {
                Marshal.ReleaseComObject(_sessionManager);
                _sessionManager = null;
            }
        }
    }
}

部署与使用注意事项 #

• 首次连接时必须保持QuickBooks POS处于前台运行状态，POS端会弹出第三方应用授权提示，选择「始终允许该应用访问」后后续连接不会重复弹窗。
• 若ASP.NET部署在IIS上，需要将对应应用程序池的运行标识修改为拥有本地COM组件访问权限的本地账户，不要使用默认的ApplicationPoolIdentity，否则会抛出80040154 检索COM类工厂失败的权限错误，测试阶段可临时设置为本地管理员账户验证连通性，验证通过后再按需收缩权限。
• 所有SDK生成的COM对象必须手动释放，不要依赖.NET GC自动回收，否则会出现内存泄漏、POS端会话占满无法新建连接的问题。
• 不要在静态类中缓存长连接会话，QuickBooks POS默认会话超时时间为2分钟，建议每次业务请求新建客户端实例、用完即释放，有性能需求的场景可自行实现短连接池做心跳保活。
• 所有增删改查API的请求结构可以参考SDK安装目录下附带的官方开发文档，不同版本POS支持的API字段有细微差异，不要跨版本复制请求结构。

内容的提问来源于stack exchange，提问作者VIKAS SURANI