WxJava 服务商电子发票 API 接入指南公众号/card/invoice与支付 V3new-tax-control-fapiao双体系对比与选型【免费下载链接】WxJava微信开发 Java SDK 支持包括微信支付开放平台小程序企业微信视频号公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava本文基于 WxJava 仓库内调研文档 docs/ELECTRONIC_INVOICE_API_COMPARISON.md 展开核心回答一个高频问题当需求方提出微信电子发票接入时到底该用weixin-java-mp的公众号开票接口还是weixin-java-pay的支付 V3 服务商电子发票接口。读完本文你将掌握两套体系在 SDK 模块归属、API 形态、鉴权上下文、覆盖范围上的本质差异并能结合源码与测试用例准确选型、快速接入。背景与结论速览Gitee IssueIDMETW补充的官方链接获取开通服务商电子发票能力邀请链接与 GitHub Issue #4066 给出的开发接入准备是同一套微信支付 V3 服务商电子发票产品文档前者是 API 列表中的具体接口后者是该产品的接入总览。核心结论两个 Issue 实际指向的是同一个需求——微信支付 V3 服务商电子发票能力接入当前weixin-java-mp中的WxMpMerchantInvoiceService是另一套旧的公众号/card/invoice/*接口不能把它当作这两个 Issue 所要求的支付 V3 能力实现该能力在 WxJava 中由weixin-java-pay模块的PartnerInvoiceService提供对应/v3/new-tax-control-fapiao/*API 实现。调研说明调研时 Gitee 页面/API 的 TLS 连接失败未能独立读取 IDMETW 的评论但用户随后提供的4015941495链接已明确该 Issue 实际指向支付 V3 服务商电子发票。当前仓库既有的公众号体系WxMpMerchantInvoiceService模块归属与接口定位当前代码将旧版公众号开票能力归入公众号模块weixin-java-mp核心接口为 WxMpMerchantInvoiceService.java实现类为 WxMpMerchantInvoiceServiceImpl.java。该接口的 Javadoc 明确引用公众号官方文档商户开票模式说明流程文档商户开票接口列表接口文档后者当前重定向至新版服务号文档从代码结构看这套接口围绕授权页 → 获取用户授权数据 → 开票 → 冲红 → 查询发票信息的完整开票闭环设计同时包含商户侧配置能力。接口方法清单方法能力关键入参getAuthPageUrl(InvoiceAuthPageRequest)获取开票授权页链接授权页请求参数getAuthData(InvoiceAuthDataRequest)获得用户授权数据授权数据请求参数rejectInvoice(InvoiceRejectRequest)拒绝开票用户授权填写数据无效时用户会收到开票失败提示拒绝请求参数makeOutInvoice(MakeOutInvoiceRequest)开具电子发票开票请求参数clearOutInvoice(ClearOutInvoiceRequest)发票冲红冲红请求参数queryInvoiceInfo(fpqqlsh, nsrsbh)查询发票信息发票请求流水号、纳税人识别号setMerchantContactInfo / getMerchantContactInfo设置/获取商户联系方式商户联系信息setAuthPageSetting / getAuthPageSetting配置/获取授权页面字段授权页面配置setMerchantInvoicePlatform / getMerchantInvoicePlatform设置/获取商户开票平台信息开票平台信息底层 API 地址接口实际请求的公众号 API 定义在 WxMpApiUrl.java#L1098-L1157 的Invoice枚举中全部基于API_DEFAULT_HOST_URL公众号 API 域名下的/card/invoice/*路径枚举常量请求路径GET_AUTH_URL/card/invoice/getauthurlGET_AUTH_DATA/card/invoice/getauthdataREJECT_INSERT/card/invoice/rejectinsertMAKE_OUT_INVOICE/card/invoice/makeoutinvoiceCLEAR_OUT_INVOICE/card/invoice/clearoutinvoiceQUERY_INVOICE_INFO/card/invoice/queryinvoceinfoSET_CONTACT_SET_BIZ_ATTR/card/invoice/setbizattr?actionset_contactGET_CONTACT_SET_BIZ_ATTR/card/invoice/setbizattr?actionget_contactSET_AUTH_FIELD_SET_BIZ_ATTR/card/invoice/setbizattr?actionset_auth_fieldGET_AUTH_FIELD_SET_BIZ_ATTR/card/invoice/setbizattr?actionget_auth_fieldSET_PAY_MCH_SET_BIZ_ATTR/card/invoice/setbizattr?actionset_pay_mchGET_PAY_MCH_SET_BIZ_ATTR/card/invoice/setbizattr?actionget_pay_mch使用注意事项开票相关错误码WxMpMerchantInvoiceService的 Javadoc 明确提醒根据不同开票平台以下错误码可能开票成功开票、冲红内部暂时未处理73105开票平台开票中请使用相同的发票请求流水号重试开票73107发票请求流水正在被处理请通过查询接口获取结果73100开票平台错误这意味着在公众号体系下调用开票/冲红接口时遇到上述错误码不应简单视为失败而应结合查询接口确认最终状态。历史来源历史提交058ce62a2b932633931e30762f44c561481dde5f将该服务及其请求/响应 Bean 加入weixin-java-mp提交说明关联 #1305。相关请求/响应 Bean 位于 weixin-java-mp/src/main/java/me/chanjar/weixin/mp/bean/invoice/merchant/ 下。两个 Issue 共同指向的支付 V3 体系PartnerInvoiceService官方产品背景#4066 链接的开发接入准备属于微信电子发票产品要求在微信支付服务商号申请服务商电子发票权限并提到数电发票资源。IDMETW 链接的获取开通服务商电子发票能力邀请链接位于相同产品的API 列表下路径为GET /v3/new-tax-control-fapiao/fapiaomerchant/getspinviteurl。同一官方文档导航的 API 列表覆盖邀请子商户开通、检查子商户开票状态、创建电子发票卡券模板、配置开发选项、抬头填写链接/信息、各行业开票、冲红、查询、下载/上传发票文件、插入用户卡包以及多个异步通知。例如开具通用行业电子发票接口为POST /v3/new-tax-control-fapiao/fapiao-applications/issue-general请求域名为https://api.mch.weixin.qq.com并要求微信支付 API 证书签名、服务商模式的sub_mchid和唯一开票申请单号fapiao_apply_id官方文档为开具通用行业电子发票。该页还规定敏感字段使用微信支付公钥或平台证书加密。SDK 中的实现入口该体系在 SDK 中的核心接口为 PartnerInvoiceService.java实现类为 PartnerInvoiceServiceImpl.java请求/响应 Bean 位于 weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/invoice/ 下。接口能力全景分组方法对应路径见实现类子商户邀约getInviteUrl(subMchId)/getInviteUrl(request)GET /v3/new-tax-control-fapiao/fapiaomerchant/getspinviteurl子商户邀约列表listInviteMerchants(query)GET /v3/new-tax-control-fapiao/fapiaomerchant/listspinvitemchinfo子商户状态getSubMerchantInvoiceStatus(subMchId)GET /v3/new-tax-control-fapiao/merchant/{sub_mchid}/check-status通用行业开票issueGeneralInvoice(request)POST /v3/new-tax-control-fapiao/fapiao-applications/issue-general旅客运输行业开票issuePassengerTransportInvoice(request)POST /v3/new-tax-control-fapiao/fapiao-applications/issue-passenger-transport不动产租赁行业开票issueRealEstateLeasingInvoice(request)POST /v3/new-tax-control-fapiao/fapiao-applications/real-estate-leasing成品油行业开票issueRefinedOilInvoice(request)POST /v3/new-tax-control-fapiao/fapiao-applications/issue-refined-oil查询电子发票getInvoice(fapiaoApplyId, subMchId, fapiaoId)GET /v3/new-tax-control-fapiao/fapiao-applications/{fapiao_apply_id}冲红电子发票reverseInvoice(request)POST /v3/new-tax-control-fapiao/fapiao-applications/{fapiao_apply_id}/reverse发票文件下载信息getInvoiceFileDownloadInfo(fapiaoApplyId, subMchId, fapiaoId)GET /v3/new-tax-control-fapiao/fapiao-applications/{fapiao_apply_id}/fapiao-files上传发票文件uploadInvoiceFile(request)POST /v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file卡券模板createCardTemplate(request)POST /v3/new-tax-control-fapiao/card-template开发选项配置updateDevelopmentConfig(request)PATCH /v3/new-tax-control-fapiao/merchant/development-config抬头填写链接getUserTitleUrl(request)GET /v3/new-tax-control-fapiao/user-title/title-url抬头信息getUserTitle(subMchId, scene, fapiaoApplyId)GET /v3/new-tax-control-fapiao/user-title插入用户卡包insertCards(request)POST /v3/new-tax-control-fapiao/fapiao-applications/{fapiao_apply_id}/insert-cards接口 Javadoc 还提示两点实践要点issueGeneralInvoice接口受理成功后请通过查询电子发票接口获取处理结果issuePassengerTransportInvoice接口受理成功时返回 HTTP 202 Accepted无应答包体受理成功不代表开票完成需通过开票结果回调或查询接口获取处理结果。该方法的默认实现抛出UnsupportedOperationException用于保持源码兼容性对应测试见 PartnerInvoiceServiceImplTest.java#L23-L27。实现层细节与关键调用链在 PartnerInvoiceServiceImpl.java 中可以看到路径常量INVITE_URL_PATH、ISSUE_GENERAL_PATH、ISSUE_PASSENGER_TRANSPORT_PATH、FAPIAO_APPLICATIONS_PATH均基于/v3/new-tax-control-fapiao/前缀统一通过WxPayService发起请求getV3/postV3/patchV3走微信支付 V3 签名体系请求基址来自payService.getPayBaseUrl()默认即https://api.mch.weixin.qq.com参数 URL 编码所有查询参数经URLEncoder.encode(..., UTF_8)编码必填参数为空时抛出IllegalArgumentException(微信支付接口必填参数不能为空)路径式fapiao_apply_id查询、冲红、文件下载、插卡等接口把fapiao_apply_id拼入 URL 路径并在请求体中移除该字段见reverseInvoice、insertCards中对 JSON body 的remove(fapiao_apply_id)处理文件上传uploadInvoiceFile使用WechatPayUploadHttpPost.Builder(...).buildFapiaoFile()构造发票文件上传请求元数据包含sub_mchid、file_type、digest_alogrithm官方文档既定拼写、digest。请求参数示例通用行业电子发票GeneralInvoiceRequest.java 展示了核心请求结构字段通过SerializedName与官方 JSON 字段对齐顶层sub_mchid子商户号、fapiao_apply_id唯一开票申请单号、buyer_information购买方信息、fapiao_information发票信息FapiaoInformationfapiao_id、total_amount、items发票项目列表、export_business_policy_code、vat_refund_levy_code、billing_person_id、billing_person、fapiao_bill_type、transaction_information交易信息、remarkInvoiceItemtax_code税收分类编码、goods_name、specification、unit、quantity、total_amount、tax_rate、discount、preferential_policy_codeTransactionInformationpay_channel、transaction_id、out_trade_no、amount。官方要求敏感字段使用微信支付公钥或平台证书加密后再传输接入时需按微信支付文档对相应字段做加密处理。测试用例验证PartnerInvoiceServiceImplTest.java 通过动态代理WxPayService捕获实际请求 URL 与请求体验证了实现细节例如getInviteUrl(19998278783)生成https://api.mch.weixin.qq.com/v3/new-tax-control-fapiao/fapiaomerchant/getspinviteurl?sub_mchid19998278783issueGeneralInvoice请求体包含fapiao_apply_id:invoice-001URL 命中.../fapiao-applications/issue-general查询接口拼接?sub_mchid1900000109fapiao_idfapiao-001并可解析出fapiao_information[0].status冲红接口 URL 命中.../fapiao-applications/apply-001/reverse且请求体不包含fapiao_apply_id抬头链接 URL 中fapiao_apply_idapply%7C001、seller_name%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7验证了参数编码行为。两套体系的直接差异维度既有公众号能力两个 Issue 指向的微信支付能力SDK 模块weixin-java-mp应位于weixin-java-pay官方文档产品线developers.weixin.qq.com的公众号电子发票pay.weixin.qq.com/doc/v3/partner的微信支付合作伙伴电子发票API 形态/card/invoice/*/v3/new-tax-control-fapiao/*身份/鉴权上下文公众号 access token、用户授权页/授权数据微信支付服务商号、子商户号、V3 签名与敏感字段加密覆盖范围授权、开票、冲红、查询及公众号商户配置子商户邀约/状态、模板/开发配置、行业开票、文件和卡包、通知请求域名公众号 API 域名https://api.mch.weixin.qq.com选型建议判断需求归属可从三个问题入手产品线归属需求文档来自developers.weixin.qq.com公众号/服务号电子发票还是pay.weixin.qq.com/doc/v3/partner微信支付服务商电子发票前者选WxMpMerchantInvoiceService后者选PartnerInvoiceService身份上下文业务是围绕公众号 access token 用户授权页公众号模式还是围绕服务商号 子商户号 V3 证书签名服务商模式V3 模式下还需要服务商号具备服务商电子发票权限API 形态接口路径是/card/invoice/*还是/v3/new-tax-control-fapiao/*路径前缀可直接定位到对应 SDK 服务类。总结两个 IssueIDMETW与 #4066都是同一个微信支付 V3 服务商电子发票接入需求当前由weixin-java-pay的PartnerInvoiceService提供对应的new-tax-control-fapiaoAPI 实现而weixin-java-mp的WxMpMerchantInvoiceService承载的是另一套公众号/card/invoice/*旧能力。接入时务必先按产品线、鉴权上下文与 API 形态完成归属判断避免在错误的模块中寻找实现。原始调研全文见 docs/ELECTRONIC_INVOICE_API_COMPARISON.md。【免费下载链接】WxJava微信开发 Java SDK 支持包括微信支付开放平台小程序企业微信视频号公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
