接入易错点

 商户API证书须在到期前完成更换

 说明：商户 API 证书有效期为5年，到期自动作废；过期后 APIv3 接口及部分需证书的 APIv2 账单接口无法调用。
正确应该怎么做：① 到期前申请新证书；② APIv3 更新私钥与证书序列号，APIv2 替换 apiclient_cert.p12；③ 发布后观察旧证书昨日调用量，连续为0后再完成切换确认。
典型反例：代码已发版但仍有旧证书调用路径，未核对调用量即认为迁移完成。
见 4013053057-如何更换商户API证书、4012072428-申请商户API证书 

 证书到期后账单下载及其他接口调用失败，对账链路中断。

 APIv3密钥变更须同步所有账单服务

 说明：APIv3 密钥用于解密相关报文；使用旧密钥会因认证失败抛出 AEADBadTagException: Tag mismatch，修改密钥后各服务不会自动同步。
正确应该怎么做：① 修改前确认影响范围并暂停相关服务；② 在商户平台【账户中心-账户设置-API安全】修改密钥；③ 更新所有账单下载、解密和回调服务并重启验证。
典型反例：只更新一台服务器，其他账单任务节点仍使用旧密钥。
见 4012072195-配置APIv3密钥、4013053274-AEADBadTagException Tag mismatch 

 账单下载或解密报 AEADBadTagException: Tag mismatch，部分节点账单任务失败。 

 交易账单与资金账单须按用途分别申请

 说明：交易账单记录支付成功订单和退款受理成功订单，用于订单、退款、手续费核对；资金账单记录基本账户、运营账户和手续费账户的收支，用于余额及资金流水核对。
正确应该怎么做：① 订单、退款和每笔手续费使用交易账单；② 提现、商家转账、充值、结算及账户余额变化使用资金账单；③ 申请资金账单时按实际账户传 account_type，两类账单再按业务单号或微信订单号关联。
典型反例：在交易账单中查提现或商家转账，或只用资金账单判断订单退款状态。
见 4013071215-产品介绍、4013071227-申请交易账单、4013071235-申请资金账单、4013071249-资金账单详细说明 

 交易数据与资金数据口径混用，订单、提现或手续费无法核对，账户余额和结算差异无法定位。

 对账单须按商户号维度分别下载

 说明：微信支付对账单以商户号维度生成；多个商户号即使共用同一结算银行卡，也须分别下载和核对。
正确应该怎么做：① 对账任务按商户号分别调度；② 每个商户号使用对应商户凭证申请账单；③ 先按商户号核对，再在结算层汇总银行卡到账。
典型反例：按结算银行卡归集后只下载一份账单，把多个商户号混在同一对账文件中。
见 4013071254-常见问题、4013071227-申请交易账单 

 多个商户号漏账或混账，无法按商户号逐笔核对和定位差异。

 当日账单须次日上午10点后再申请

 说明：交易账单和资金账单按自然日生成，当日账单不可下载，前一日账单应在次日上午10点后申请；资金账单通常从上午9点开始生成。
正确应该怎么做：① 对账任务按 T+1 调度，最早在次日上午10点后申请；② bill_date 填需要下载的历史自然日，不得填请求当天；③ 返回 STATEMENT_CREATING 时间隔约30分钟重试，直到成功或明确返回 NO_STATEMENT_EXIST。
典型反例：日切后立即高频申请当日或前一日账单，并把生成中直接判为漏单。
见 4013071215-产品介绍、4013071218-开发指引、4013071227-申请交易账单、4013071254-常见问题 

 返回 STATEMENT_CREATING“账单生成中”或 NO_STATEMENT_EXIST“请求的账单文件不存在”，当日无法取得目标账单，自动对账被阻塞。 

 无对应流水时不生成账单

 说明：交易账单在指定日期无支付成功或退款受理成功记录时不生成；资金账单在指定账户无资金变动时不生成。NO_STATEMENT_EXIST 表示无对应账单，STATEMENT_CREATING 表示仍在生成。
正确应该怎么做：① 先核对商户号、账单类型、bill_date 和 account_type；② 确认当日无交易或无资金变动后，将 NO_STATEMENT_EXIST 按空账单处理并停止重试；③ 见 STATEMENT_CREATING 才继续等待后重试。
典型反例：把 NO_STATEMENT_EXIST 当作签名错误或系统故障无限重试。
见 4013071218-开发指引、4013071227-申请交易账单、4013071235-申请资金账单、4013071254-常见问题 

 无流水日持续返回 NO_STATEMENT_EXIST 并触发无效告警；把生成中误判为空账单则会漏下载应得文件。

 账单日期须使用YYYY-MM-DD且限近三个月

 说明：境内交易账单和资金账单的 bill_date 使用 yyyy-MM-dd 格式，接口仅支持申请近三个月内的账单，且不能申请请求当天。
正确应该怎么做：① 按业务发生日期生成 bill_date；② 仅选择近三个月内的历史日期；③ 更早账单改用商户平台预约下载能力，不向按日接口传超出范围的日期。
典型反例：直接传时间戳、把请求当天作为账单日期，或用单日接口循环拉取数年前账单。
见 4013071215-产品介绍、4013071218-开发指引、4013071227-申请交易账单、4013071235-申请资金账单 

 请求返回日期格式错误、账单不存在或超出可下载范围，无法取得目标日期的账单文件。

 账单下载链接须5分钟内签名下载

 说明：申请账单接口只返回文件下载地址，不直接返回账单数据；download_url 有效期为5分钟，获取文件时须按 APIv3 规则生成签名并通过 GET 请求下载。
正确应该怎么做：① 申请交易账单或资金账单获取 download_url 和 hash_value；② 在5分钟内按 APIv3 规则签名并发起 GET 请求；③ 下载后计算 SHA1 摘要，并与接口返回的 hash_value 比对。
典型反例：把 download_url 当普通网页保存后延迟访问，或跳过哈希校验直接把文件入库。
见 4013071218-开发指引、4013071238-下载账单、4013071227-申请交易账单、4013071254-常见问题 

 下载链接失效或请求被拒，且无法识别文件在传输过程中是否损坏，账单获取链路中断。

 交易账单按支付成功时间归属日期

 说明：交易账单以支付成功时间或商户退款受理成功时间判断数据时间，日切点为每日 00:00:00；下单时间不作为账单归属依据。
；带券订单的账单归属以券完成时间为准，可能晚于订单支付时间，对账时须同时核对订单支付时间与券完成时间。
正确应该怎么做：① 用实际支付成功时间或退款受理成功时间选择 bill_date；② 对跨零点支付、延迟支付及带券订单同时核对相邻日期账单；③ 按商户订单号和微信订单号与本地单据逐笔关联。
典型反例：按订单创建日归档，或把使用优惠券、临近零点支付成功的订单固定归到前一日账单。
见 4013071215-产品介绍、4013071246-交易账单详细说明 

 对账批次与账单日期错位，出现查无订单、单边账或漏账，日终无法对平。