发票核验API对接实战：验真、状态复检与幂等限流

发票核验这件事，我前后做过三轮：最早是给一家做企业报销的团队写对接层，后来是给一个电商结算系统补验票环节，最近一次是把验票能力抽成独立服务给多条业务线复用。三轮下来最大的感受是——发票核验API看着只是一个"传发票号、返回真假"的接口，真接进业务里才知道，坑全在参数的组装方式、状态的时效性、以及"查到了但不等于能用"这三件事上。它本质上是把一张纸质或电子的交易凭证，转成结构化的、可被程序判断的凭证数据，再叠加真伪、状态、一致性、重复性四层校验，最终回答一个业务问题：这笔钱该不该付、这笔费用该不该报。适合谁来读？如果你是后端开发、结算/财务系统的技术负责人、做SaaS报销或供应链对账的产品同学，这篇基本可以直接拿去当对接手册；如果你只是想了解这套东西怎么运转，前面几节也能看懂。

1. 为什么发票核验值得单独抽一层API

1.1 从人工验票到接口验票，中间隔着的不是技术而是流程

很多人以为验票上接口就是把人工操作换成代码调用，实际不是。人工验票的时候，财务同事拿到一张票，看一眼抬头对不对、金额对不对、章清不清楚，凭经验就能下判断，模糊地带靠"我觉得没问题"兜底。一旦交给程序，所有模糊地带都必须变成明确的判定条件和阈值，这是最大的工作量来源。我在第一个项目里踩的坑就是：业务方只提了"验真伪"，上线两周后财务跑来问"为什么作废的票也过了"，因为验真接口返回的是"该票存在且要素一致"，但票面状态是作废——真伪和可用性是两件事，前者是数据层面的比对，后者是业务层面的判断。

所以抽一层独立API的价值，不在于少写几个HTTP请求，而在于把散落在各业务线里的判断逻辑收拢成一套统一口径。电商结算线关心的是"这张票能不能作为付款前置条件"，报销线关心的是"这张票有没有被别的同事报过"，供应链线关心的是"票面销售方和合同签约主体是不是同一家"。三种诉求共用同一个查验底层，但上层的判定规则完全不同。把底层查验做成独立服务、上层规则做成可配置的策略，是我目前认为最省事的架构——后面再加业务线，只需要加一套策略，不用再碰接口对接。

还有一层现实原因：查验这件事天生依赖外部服务方，接口会限流、会超时、会有维护窗口，业务线各自直连的话，故障面会被放大好几倍。统一收口之后，限流、缓存、降级、重试都在一个地方做，业务侧只需要处理"成功/失败/待定"三种结果。

1.2 三类典型场景，需求差异比想象中大

同样是调发票核验API，不同场景对"准"和"快"的要求完全不一样，用同一套参数去打，一定会有一边不满意。

电商结算那条线的教训特别深。我们一开始把报销场景的参数直接搬过去，只校验了发票代码和号码，结果出现"票是真的，但抬头写的是另一家公司"的情况，钱已经付出去了才发现票不能入账。后来补了购买方名称和纳税人识别号的强一致性校验，并且加了金额容差判断（价税合计与订单金额差异超过0.01元就挂起）。这个0.01元不是拍脑袋定的，是因为平台补贴、优惠券分摊之后，开票金额和订单实付金额经常有分位差，容差太小会疯狂误拦，太大又失去意义，实测下来一分钱是平衡点。

对公付款那条线则完全相反，它不怕慢，怕的是"事后才发现票被红冲了"。所以那条线上我们做的是异步查验加周期性复检，付款前查一次，付款后第7天、第30天各复检一次状态。这个设计在后面第5节会详细讲。

1.3 直连、聚合、还是自建识别加查验的组合

选型这块我试过三种路子，各有各的适用边界。

直连单一服务方：对接成本最低，文档清晰，问题是单点依赖。有一回服务方做例行维护，我们整条结算链路卡了四十分钟，虽然最后靠人工放行兜住了，但那次之后我就坚持至少准备一路备用通道。直连适合业务量不大、对可用性要求不极端的团队。

聚合服务商：一次对接拿到多家通道，失败自动切换，省心。代价是返回字段会被做一层归一化，某些细节字段（比如特定票种的附加要素）可能拿不到，而且出问题时排查链路变长，你不知道是源通道的问题还是聚合层的问题。我做报销SaaS那次用的就是聚合，整体体验还行，但对返回值的字段含义必须逐个和文档核对，不能想当然。

自建OCR加查验：只在一种情况下值得做——你的票据形态特别杂，比如大量扫描件、拍照件、甚至是PDF里嵌的图。这时候先做本地图像处理和要素抽取，把关键字段提出来，再拿字段去调查验接口，能显著减少无效调用。我们做过一个内部统计，脏图直接送查验的失败率接近三成，先过一遍质量检测（清晰度、倾斜角、是否截断）再送，失败率能压到一成以下。这套组合的成本是要维护识别模型，小团队慎入。

我的建议是：主链路走直连或聚合，同时在本地做一层轻量的前置校验——字段完整性检查、格式校验、必填项兜底，能挡掉相当一部分注定失败的请求，省配额也省时间。

2. 一张发票到底要核验哪些东西

2.1 五个维度拆开看，缺一个都会出问题

把"核验"当成一个动作是外行视角，实际至少要拆成五层，每一层的失败表现和处置方式都不同。

第一层，要素完整性。发票代码、发票号码、开票日期、金额、校验码（部分票种有）、购买方和销售方信息，这些字段缺一个，后面的查验根本没法发起。这一层在本地就能做，不需要调接口。我见过最离谱的情况是前端把开票日期传成了"2024/03/01"这种带斜杠的格式，服务方直接返回参数错误，日志里一堆400，排查了半天以为是接口挂了。

第二层，真伪。拿要素去和票据数据源比对，返回一致或不一致。这一层解决的是"这张票存不存在、要素对不对得上"。

第三层，状态。票是真的，但它可能是作废状态，也可能是被红冲过的。绝大多数事故都出在这里——只查真伪不查状态，等于只做了一半。

第四层，一致性。票面信息和你的业务单据是否匹配：抬头是不是本公司、金额和订单差多少、开票日期是否在合理窗口内、销售方是否和合同主体一致。这一层完全是业务规则，接口不会替你做。

第五层，重复性。同一张票有没有被用过。这一层必须在自己这边做，因为外部接口不知道你的业务数据。做法是建唯一索引，键用发票代码加发票号码的组合，同时记录使用场景和使用单号，重复提交时直接拦。

这五层是串联关系，任何一层不通过都应该阻断流程，但阻断后的处置不一样：第一层和第二层失败通常直接拒绝，第三层失败要转人工复核（因为存在数据同步延迟的可能），第四层失败看差异大小决定是挂起还是放行，第五层失败一律拒绝并留痕。

2.2 字段解析里那些文档不会写的事

发票要素字段看着简单，实际有几个地方特别容易出岔子。

发票代码和号码的长度不固定。不同票种、不同时期的编码规则不一样，有的十位有的十二位，号码有的八位有的二十位。写校验规则时千万别写死长度，用"数字串、长度在合理区间内"这种宽松规则。我在第二个项目里写了固定长度校验，结果新版电子发票的号码长度变了，整批票被拦在门外，紧急发版才修好。后来改成只校验"纯数字且长度大于等于8"，再没出过问题。

金额字段一定要区分含税和不含税。接口返回通常有金额、税额、价税合计三个字段，业务侧做比对时用哪个取决于场景。报销场景一般用价税合计，因为员工填的是实际支付金额；采购入账场景要用不含税金额加税额分开核对，因为进项抵扣是按税额算的。混用会导致对不上账，而且这种错很难被发现，因为差额看起来"不大"。

校验码后六位是个可选要素。部分票种查验时需要它，部分不需要。对接时要做成条件必填，根据票种动态判断，而不是无脑必传或必不传。

购买方名称的写法差异极大。全角半角括号、空格、"(集团)"这类后缀的有无，都会造成字符串比对失败。我的做法是先做归一化：去空格、全角转半角、统一括号形态，再做精确比对；归一化后仍不一致的，走模糊匹配加人工确认，不要直接判死。

2.3 新版电子发票给接口层带来的变化

这几年票据形态在往全面数字化走，业内常说的数电票就是这一类。它对接口层的影响比想象中大，我总结了三处必须改的地方。

第一，票面要素的结构变了。传统票有发票代码、校验码这些字段，新版电子票的编码规则和字段集合不一样，有些字段直接没有了。如果你的数据表把发票代码设成非空唯一键的一部分，新版票进来会直接插不进去。正确做法是把唯一键设计成"票种 + 票据唯一标识"的组合，并且给缺失字段留空值空间。

第二，状态变更更频繁也更隐蔽。红冲在数字化形态下操作成本极低，一张票可能今天正常、下周就被冲了，而你的系统里还留着"验真通过"的记录。这就是为什么我一直强调状态要定期复检，不能只在入账那一刻查一次。

第三，文件形态从图片变成结构化数据加版式文件。这意味着你可以直接解析XML或JSON拿到要素，不必非得走OCR。我在最近一次改造里就把图片识别链路降级成了兜底方案，主链路走结构化解析，识别准确率和速度都上了一个台阶，同时也少了一堆图像预处理的维护成本。

2.4 查验请求的参数组装：五个要素怎么凑

绝大多数查验接口的核心入参就是五要素：发票代码、发票号码、开票日期、不含税金额（或价税合计，看接口定义）、校验码后六位。少一个或者错一个，返回的就是"不一致"或者"查无此票"，而这两种返回在业务上是完全不同的含义，不能混为一谈。

这里有个实操细节：金额参数的精度。有的接口要求传两位小数的字符串，有的要求传分为单位的整数，还有的接受浮点数但内部按分处理。传浮点数最容易出事，0.1加0.2那种经典问题会在比对时制造假不一致。我的做法是全程用整数分做内部计算，只在调用接口的最后一刻按对方要求转换，转换时显式做四舍五入并打印日志。

3. 接口层的工程细节，决定了这套东西稳不稳

3.1 幂等设计：别让一次重试变成两次入账

查验接口本身是只读的，理论上没有幂等风险。但整条链路不是——查验通过之后往往跟着入账、标记已使用、触发付款这些写操作，一旦重试没控制好，就会出现"查了两次、入账两次"。我在第一个项目里就遇到过网络抖动导致客户端重试，结果同一张票在系统里生成了两条报销记录，财务对账时发现金额翻倍，排查了一整天才定位到是重试没带幂等键。

做法很直接：客户端为每次业务请求生成一个全局唯一的请求ID，随查验请求一起传给下游，下游用它做去重。同时本地建一张请求记录表，记录请求ID、票据标识、请求时间、响应结果，重试前先查这张表，命中就直接返回缓存结果，不再真正发起调用。这个表还顺带解决了排查问题——出了问题直接按请求ID捞日志，比翻应用日志快得多。

幂等键的选择也有讲究。用时间戳或者随机数做主键，重试时生成新的就没意义了；正确做法是把业务单据号加票据标识拼起来做键，这样无论重试多少次，键都一样。

3.2 同步还是异步：按耗时分布来定，别拍脑袋

查验接口的响应时间分布很不均匀。正常情况几百毫秒返回，遇到源端响应慢的时候十几秒也有可能。如果你的业务是员工在页面上点提交、等着看结果，那必须走同步加超时控制，超时时间设在3到5秒，超时后转异步并给用户一个"核验中"的状态，不能让页面一直转圈。

如果是批量核验，比如月底一次性处理几千张票，那就该走异步。我们的做法是提交任务拿任务ID，后台按批次跑，前端轮询或者用回调通知。批量跑的时候有几个参数必须调：单批条数、并发数、批次间隔。单批太大容易触发对方限流，太小则吞吐上不去；并发数我一般设在对方配额上限的六到七成，留出余量给主链路的实时请求；批次间隔用来做平滑，避免瞬间打满。

这里有个经验值可以参考：如果对方给的QPS上限是20，批量任务我最多开到12到14并发，间隔100到200毫秒。实测下来既能跑满吞吐，又不会因为瞬时突刺被限流。当然这个数得根据对方实际的限流策略微调，有的服务方是按分钟算配额的，那就得把窗口拉长做匀速。

3.3 缓存怎么用才不给自己挖坑

缓存这块我吃过亏。一开始想着查验结果不会变，就设了七天缓存，结果一张票在缓存期内被作废了，系统还认为它有效，付款流程照常走完。后来改成两级策略：

第一级，短缓存。同一张票在短时间内被重复查询（比如用户连续点击提交、或者多个业务线同时查同一张票），缓存十分钟。这一级纯粹是为了削峰，不承担正确性责任。

第二级，状态复检。入账成功之后，把票据标识写入复检队列，在T+7、T+30、T+90三个时间点各查一次状态。发现作废或红冲就触发告警和后续处理流程（通知财务、标记异常、必要时发起追回）。这一级才是保证正确性的关键，缓存本身不该承担这个职责。

用一张表说清楚不同数据的缓存策略：

3.4 错误码体系：把对方的码翻译成自己的语言

服务方的错误码是按他们的系统逻辑设计的，直接透传给业务侧，业务侧根本不知道该怎么处理。中间必须做一层翻译，把错误归成几类：可重试、不可重试、需人工、需用户修改。

我的做法是定义一套内部错误码，格式是业务域加序号，然后在适配层做映射表。比如对方返回"请求频率超限"，映射成内部的可重试类错误，触发退避重试；对方返回"要素不一致"，映射成不可重试类，直接把差异字段回给用户让他核对；对方返回"系统繁忙"，映射成需人工类，进队列等待。这套映射表要跟着服务方文档更新，我在代码里把它做成了配置文件而不是硬编码，改起来不用发版。

重试策略也要区分。网络类错误用指数退避，间隔按1秒、2秒、4秒递增，最多三次；限流类错误要读对方返回的重试等待时间，没有的话按固定间隔退；参数类错误一律不重试，重试一万次结果都一样，只会浪费配额。这条规则写进代码容易，写进团队规范难，我在代码评审清单里专门加了一条"新增外部调用必须显式声明重试策略"。

4. 从零接通的完整实现路径

4.1 密钥管理与环境隔离

密钥绝对不能硬编码进代码，也不能写进配置文件提交到代码仓库。我的标准做法是：密钥存在配置中心或密钥管理服务里，应用启动时拉取，内存中只保留密文引用，日志里永远不打印明文。本地开发环境用一套独立的测试密钥，和生产的完全隔离，避免开发调试时把生产配额跑光。

还有一点容易忽略：回调地址的白名单。如果用了异步回调，接收端必须校验来源，不能谁发过来都信。做法是校验签名，签名密钥同样走密钥管理。我见过一个项目回调接口完全裸奔，任何人构造一个请求就能把票据状态改成"已核验"，虽然最后没造成实际损失，但评审的时候被列为高危问题。

下面是一段密钥加载和客户端初始化的示例，语言用 Python，实际项目里换成什么语言都行，逻辑是一样的：

import os import hmac import hashlib import time import uuid import requests from typing import Optional class InvoiceClient: def __init__(self, app_id: str, app_secret: str, base_url: str, timeout: int = 5): self.app_id = app_id self.app_secret = app_secret self.base_url = base_url self.timeout = timeout self.session = requests.Session() def _sign(self, timestamp: str, nonce: str, body: str) -> str: raw = f"{self.app_id}{timestamp}{nonce}{body}" return hmac.new( self.app_secret.encode("utf-8"), raw.encode("utf-8"), hashlib.sha256 ).hexdigest() def _headers(self, body: str) -> dict: ts = str(int(time.time() * 1000)) nonce = uuid.uuid4().hex return { "X-App-Id": self.app_id, "X-Timestamp": ts, "X-Nonce": nonce, "X-Signature": self._sign(ts, nonce, body), "Content-Type": "application/json", "X-Request-Id": uuid.uuid4().hex, } # 密钥从环境变量或密钥管理服务注入，严禁写在源码里 client = InvoiceClient( app_id=os.environ["INVOICE_APP_ID"], app_secret=os.environ["INVOICE_APP_SECRET"], base_url=os.environ.get("INVOICE_BASE_URL", "https://api.example-invoice.com"), )

签名算法里带上时间戳和随机串，是为了防重放。服务端一般会校验时间戳在五分钟内，超出直接拒绝，所以客户端和服务器的时钟必须同步，容器环境里记得配NTP。

4.2 单张核验：一次完整调用的现场记录

单张核验是最常用的路径，也是排查问题的基准。我把整个调用拆成四步：本地预检、组装参数、发起请求、结果归一化。

本地预检负责挡住明显错误的请求，比如票据标识为空、日期格式不对、金额为负。这一步不调外部接口，纯本地逻辑，但能省掉大量无效调用。组装参数时要注意精度转换和字段映射，把业务侧的字段名翻译成接口要求的字段名，这个映射关系做成配置表维护，别写死在代码里。

发起请求和结果归一化是重点。归一化指的是把服务方返回的原始结构，转成内部统一的判定结果：通过、不通过、待定三种。为什么要"待定"？因为有些返回既不能判定通过，也不能判定不通过，比如"系统繁忙""数据同步中"，硬归到前两类都会出错。

import json from dataclasses import dataclass @dataclass class VerifyResult: status: str # pass / reject / pending reason_code: str detail: dict raw: dict def verify_invoice(client: InvoiceClient, invoice: dict) -> VerifyResult: # 第一步：本地预检 if not invoice.get("invoice_no"): return VerifyResult("reject", "MISSING_INVOICE_NO", {}, {}) amount_cent = int(round(float(invoice["amount"]) * 100)) payload = { "invoiceCode": invoice.get("invoice_code", ""), "invoiceNo": invoice["invoice_no"], "billingDate": invoice["billing_date"], # 统一 YYYY-MM-DD "amount": f"{amount_cent / 100:.2f}", # 精度归一 "checkCode": invoice.get("check_code", ""), "invoiceType": invoice.get("invoice_type", ""), } body = json.dumps(payload, ensure_ascii=False, sort_keys=True) # 第二步：发起请求，带幂等与超时 try: resp = client.session.post( f"{client.base_url}/v2/invoice/verify", data=body.encode("utf-8"), headers=client._headers(body), timeout=client.timeout, ) data = resp.json() except requests.Timeout: return VerifyResult("pending", "UPSTREAM_TIMEOUT", {}, {}) except requests.RequestException as e: return VerifyResult("pending", "UPSTREAM_ERROR", {"msg": str(e)}, {}) # 第三步：结果归一化 code = data.get("code") if code == "0000": state = data.get("data", {}).get("state") if state == "VALID": return VerifyResult("pass", "OK", data.get("data", {}), data) if state in ("INVALID", "VOID", "RED_FLUSHED"): return VerifyResult("reject", f"STATE_{state}", data.get("data", {}), data) return VerifyResult("pending", "STATE_UNKNOWN", data.get("data", {}), data) mapping = { "1001": ("reject", "ELEMENT_MISMATCH"), "1002": ("reject", "NOT_FOUND"), "2001": ("pending", "RATE_LIMITED"), "2002": ("pending", "UPSTREAM_BUSY"), "3001": ("reject", "PARAM_ERROR"), } status, reason = mapping.get(code, ("pending", "UNKNOWN")) return VerifyResult(status, reason, data.get("data", {}), data)

这段代码里有几个刻意的设计。金额统一转成整数分之后再做字符串格式化，避免浮点误差；请求体用sort_keys=True序列化，因为签名要和请求体严格对应，键序不一致会导致验签失败；异常一律归到"待定"而不是"不通过"，因为网络问题不代表票有问题，这个区分在线上非常关键。

4.3 批量核验：并发控制与限流的具体参数

批量场景的难点不在调用本身，而在怎么在不被限流的前提下跑满吞吐。我的实现是一个生产者消费者模型：生产者从数据库拉待核验的票，塞进有界队列；消费者用固定大小的线程池从队列取，每个消费者独立限流。

线程池大小和限流参数需要一起调。我的经验是先确定对方给出的配额上限，然后按七成分配，再根据线上监控的实际限流率回调。比如配额是每分钟600次，那就做到每分钟420次左右，换算下来每100毫秒放1个请求，配合8到10个线程就够。如果限流率持续高于1%，说明分配比例还是偏大，往下调到六成。

import time import threading from concurrent.futures import ThreadPoolExecutor from queue import Queue, Empty class RateLimiter: def __init__(self, permits_per_second: float): self.interval = 1.0 / permits_per_second self.lock = threading.Lock() self.next_time = time.monotonic() def acquire(self): with self.lock: now = time.monotonic() wait = max(0.0, self.next_time - now) self.next_time = max(now, self.next_time) + self.interval if wait > 0: time.sleep(wait) def run_batch(items: list, client: InvoiceClient, qps: float = 7.0, workers: int = 8, on_result=None): limiter = RateLimiter(qps) queue = Queue(maxsize=workers * 4) stop = threading.Event() def worker(): while not stop.is_set(): try: item = queue.get(timeout=0.5) except Empty: continue try: limiter.acquire() result = verify_invoice(client, item) if on_result: on_result(item, result) finally: queue.task_done() threads = [threading.Thread(target=worker, daemon=True) for _ in range(workers)] for t in threads: t.start() for item in items: queue.put(item) queue.join() stop.set() for t in threads: t.join(timeout=2)

队列容量设成线程数的四倍，是为了让线程不至于频繁空转，同时也不会因为积压太多导致内存问题。消费者用timeout而不是阻塞等待，是为了在任务结束时能正常退出，不被卡死在get上。

4.4 验重与三单匹配：把规则写成可配置的策略

验重相对简单，建唯一索引就够了。建表时把"票种 + 票据唯一标识"做成联合唯一键，插入冲突就说明这张票已经被用过，直接返回重复。注意不要用自增ID加票据号做键，那样重复插入不会冲突，等于没约束。

三单匹配复杂一些，它要回答的是"订单、发票、支付流水三者能不能对上"。我的做法是把它做成策略配置，每条规则独立开关，独立配置阈值。

这里的90天不是我拍的，是结合常见业务周期和票据开具习惯定的经验值，实际项目中要根据自身业务调整。阈值配置一定要放到配置中心，因为业务规则会变，改一个数字不该走发版流程。

5. 常见问题与排查实录

5.1 高频错误对照表

线上跑了这么久，大部分问题都能归到有限的几类里，整理成表方便快速定位。

我印象最深的一次是深夜告警，批量任务成功率掉到四成。一开始怀疑是对方限流，查了响应码发现全是超时，再查网络监控没异常，最后翻到对方状态页才知道是例行维护。这件事之后我加了两个措施：一是把批量任务调度从固定时间改成带随机抖动的时间窗，避免所有任务挤在同一时刻；二是在客户端维护一个"最近错误码分布"的滑动窗口指标，错误率超过阈值自动降低并发，把资源让给实时链路。

5.2 数据质量类问题，比接口问题更难查

接口问题一般有明确报错，数据问题往往是"没报错但结果不对"，排查成本高得多。我遇到过三种典型情况。

金额单位混乱。有的业务线传元，有的传分，混在一起就出现"金额差一百倍"的不一致。解决办法是在入口强制统一单位，命名上直接体现，比如字段就叫amount_cent，看到名字就知道单位，从根上避免误解。

票种缺失。不传票种，服务方按默认票种解析，遇到其他票种就判定要素不一致。这个问题的隐蔽之处在于，大部分票是默认票种，所以错误率看起来不高，容易被认为是偶发。

日期时区问题。开票日期是日期不是时间戳，但有些系统会做时区转换，跨零点的时候可能差一天。做法是全程用字符串YYYY-MM-DD传递，不做任何时区转换，从源头消灭这类问题。

5.3 留痕与对账，别等出事才想起补

每一次查验请求和响应，都应该完整留存：请求ID、票据标识、入参、响应原文、耗时、调用时间。留存不是为了让日志好看，是为了出事时能自证。

我们做过一次内部审计演练，随机抽了一百笔已入账的票据，要求在两小时内还原"这张票什么时候验的、返回了什么、谁批准的、依据哪条规则"。因为留痕完整，实际用了不到半小时。如果当时只有应用日志，这个任务基本不可能完成——日志会滚动、会被清理，而且散落在多个实例上。

留痕数据建议单独存一张表，字段设计上把"业务单据号"作为主要查询维度，而不是票据号。因为出问题时通常是从业务侧发起排查，先有单号才去找票。

6. 安全与合规的工程化落地

6.1 数据最小化：能不传的坚决不传

发票数据里包含购买方和销售方的名称、纳税人识别号、金额，这些都属于敏感商业信息。对接外部服务时，只传查验必需的字段，不要图省事把整个业务对象序列化过去。多传的字段既增加泄露面，也可能因为字段校验规则不同导致请求失败。

本地存储同样要克制。票面文件、结构化数据、查验结果分开存，访问权限分开控制。票面文件建议加密存储，访问走临时凭证，不要给长期可用的下载链接。日志里票据号码要做打码处理，只保留前后各四位，中间用星号替代，这样排查问题时还能定位，又不至于明文外泄。

6.2 证据链留存：把"我查过"变成"我能证明我查过"

合规检查关心的不是你有没有查，而是你能不能拿出证据证明你查了、查的结果是什么、基于这个结果做了什么决策。所以留痕要形成闭环：请求记录、响应记录、判定结果、业务动作，四者用同一个请求ID串起来。

留存期限按内部合规要求定，行业里常见的做法是三到十年，具体看业务性质。技术上要注意的是冷热分离，近期数据放热存储供查询，超过一定时间的转冷存储归档，别让一张表撑到几十亿行还在上面建索引。

6.3 服务方评估：别只看价格和文档

选服务方的时候我一般看四件事。第一是字段覆盖度，返回的字段能不能支撑你的判定规则，缺字段就得自己补，补起来很麻烦。第二是状态更新的时效，票据作废或红冲之后，多久能在查验结果里体现出来，这个指标直接影响你的复检策略。第三是配额和限流的透明度，是否明确给出配额、是否返回剩余额度、超限后的行为是否可预期。第四是故障沟通机制，出问题时有没有状态页、有没有通知渠道，这决定了你半夜被告警叫醒后能不能快速判断是自己的问题还是对方的问题。

价格当然重要，但排在后面。我见过为了省成本选了便宜通道，结果状态更新延迟两天，导致一批已付款的票被红冲，损失远超省下的费用。查验这件事，准确性和时效性的权重应该远高于单价。

7. 我在这套系统上攒下的几条实操心得

第一条，先做数据模型再做接口对接。很多人上来就写HTTP调用，写到一半发现字段存不下、状态表达不了，回头改表结构，返工量巨大。正确顺序是先想清楚要存哪些字段、状态机有几种流转、哪些字段参与判定，把表设计定了再接接口。

第二条，把"待定"当成一等公民。绝大多数线上事故不是判定错了，而是把不确定的情况硬塞进了通过或不通过。网络超时、状态同步中、系统繁忙，这些都该是独立的中间态，有独立的处置流程和超时兜底。我现在的习惯是每个外部依赖的返回都必须能映射到至少三种状态，少于三种就说明设计不完整。

第三条，复检机制比首次查验更重要。首次查验只能证明"那一刻票是有效的"，证明不了"现在还有效"。定期复检的成本很低，收益是把事后追责变成事中拦截。我现在做的项目里，复检队列是标配，T+7、T+30、T+90三个节点，作废和红冲自动告警。

第四条，别把业务规则写进代码。抬头比对要不要模糊匹配、金额容差多少、日期窗口多长，这些都是业务决策，会变。写成配置，让业务方自己能调，比每次改代码发版强得多。我现在的做法是把这些规则抽成一个规则引擎的最小实现，配置项加表达式，覆盖八成场景足够用了。

第五条，限流参数要留余量，但别留太多。留太少会被限流，留太多吞吐上不去。我一般按配额的七成做初始值，然后根据线上限流率微调，稳定在1%以下就算合理。这个数字不是理论最优，是从几次事故里试出来的经验值。

最后再补一个小技巧：给查验链路加一个"影子模式"。新接入一个服务方或者改动判定规则时，先让新逻辑在影子模式下跑一段时间，只记录结果不影响业务，拿实际数据比对新旧逻辑的差异。我们最近一次换通道就是这么做的，跑了两周发现新通道在某些票种上的状态返回比老通道慢一天，提前发现了这个问题，避免了上线后的事故。这个模式几乎零成本，但能挡掉大部分"上线才发现"的问题。