参考
错误码
TF Fiscal Open API 错误码合并参考,按层与领域分组,附 HTTP 状态、场景与处置建议。
错误格式
错误按产出层分三种格式,见通用约定:
| 层 | HTTP | 格式 | 码字段 |
|---|---|---|---|
| 平台网关(鉴权、订阅、限流、请求体大小、文件下载链接) | 401 / 403 / 404 / 413 / 429 / 503 | 平台统一响应体 {success, errorType, code, message} | code(整数) |
| 开票主体、NF-e、NFC-e、CT-e、DC-e、NFS-e、发票邮件、Webhook 注册 | 400 / 404 / 409 / 500 | 数组 [{codigo, mensagem}],每个问题一条 | codigo(字符串) |
| NF-e 验证与身份核验 | 400 / 404 / 409 / 422 / 428 / 451 / 500 / 503 | 无包装对象 {code, message} | code(整数) |
| NFC-e 离线开票开放接口 | 200 / 400 / 404 | 平台统一响应体,业务错误也是 HTTP 200 | code(整数) |
| 发票助手本机接口 | 400 / 404 / 409 / 429 / 500 / 503;鉴权 401 / 403 | 业务错误为数组 [{codigo, mensagem}];鉴权错误为平台统一响应体 | codigo / code |
| 内置 SDK | 无 | 异常对象的 Codigo 与 Tipo | Codigo(整数) |
message 随 Language / Accept-Language 请求头本地化(默认葡语)。请按码分支,不要按文案分支。数组格式里的 codigo 一律是平台错误码的数字串。
各领域码段:
| 码段 | 领域 |
|---|---|
| 10001xxx | 请求校验与平台异常 |
| 10003xxx | 开票主体与证书 |
| 10004xxx | NF-e 开票、取消与更正函 |
| 10005xxx | 税务引擎 |
| 10009xxx | 开放平台(鉴权、订阅、限流、webhook、下载链接) |
| 10013xxx | 文件下载 |
| 10015xxx | NF-e 验证 |
| 10016xxx | 身份核验(CNPJ / CPF) |
| 10017xxx | CT-e |
| 10018xxx | NFS-e |
| 10019xxx | DC-e |
| 10021xxx | 发票邮件 |
| 10022xxx | NFC-e |
| 10029xxx | NFC-e 离线开票(开放接口、设备配对、离线开票内核、SDK、发票助手) |
网关:鉴权与授权
平台统一响应体格式,在请求到达接口前产出。401 与 403 属配置错误,不修复就重试没有意义,还可能触发限流。签名方案见认证与签名。
| HTTP | 错误码 | 含义 | 处置 |
|---|---|---|---|
| 401 | 10009000 | 缺少签名请求头(token / sign / timestamp) | 每次请求带全三个头 |
| 401 | 10009001 | 时间戳非法或时钟偏差超 ±300 秒 | 校准时钟(NTP);每次请求重新生成时间戳,勿复用 |
| 401 | 10009002 | token 无效 | 核对 app_secret;如已轮换请更新配置 |
| 401 | 10009003 | 签名不匹配 | 重新推导签名;见认证与签名的核对清单 |
| 403 | 10009004 | 应用已停用 | 联系平台 |
| 403 | 10009015 | 应用未生效(待审批或已驳回) | 等待审批 / 联系平台 |
| 403 | 10009014 | 集成商账户已停用 | 联系平台 |
| 403 | 10009005 | 接口未订阅 | 为所调端点申请订阅 |
| 429 | 10009006 | 超出限流额度,或应用处于冷却期 | 按 Retry-After 等待后重试,仍被拒再指数退避(初始 1 秒,倍增至 30 秒上限,加抖动);限流按应用与接口组两级实施,规则与响应头见限流与退避 |
| 413 | 10009027 | 请求体超过网关大小上限 | 减小请求体;NF-e 验证每次只发送一张不超过 1 MB 的 NF-e |
下载链接(linkDanfe、linkDownloadXml、linkDacce、nfeLinkXml、cteLinkDacte、dceLinkDace 等)是不带签名头的 GET 请求;失败以 HTTP 状态 + 平台统一响应体返回,见文件下载:
| HTTP | 错误码 | 含义 | 处置 |
|---|---|---|---|
| 401 | 10009035 | 下载链接无效(路径被改、令牌挪用或签名不符) | 使用查询接口原样返回的链接 |
| 401 | 10009036 | 下载链接已过期 | 重新调用查询接口获取新链接 |
| 503 | 10009037 | 文件尚未生成 | 按 Retry-After 稍后重试同一链接 |
| 404 | 10013011 | 下载的文件不存在 | 核对链接来源 |
| 429 | 10013016 | 回调链接的单 IP 下载过于频繁 | 按 Retry-After 重试 |
请求校验与平台异常
| 错误码 | HTTP | 格式 | 场景 | 处置 |
|---|---|---|---|---|
| 10001001 | 400 | 数组 | 请求字段校验失败,每字段一条;亦包括 emissaoDCe 段的注册 / 更新契约错误(两个配置块都缺、更新改 cnpj / 换市政、号段降号、换系列) | 按 mensagem 修正 |
| 10001000 | 500 | 数组或无包装对象 | 平台侧异常;数组格式端点与验证、身份核验都可能返回 | 退避重试;持续出现请携带失败请求的 timestamp 与路径联系平台 |
开票主体与证书
数组格式。见开票主体。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10003004 | 400 | 注册:城市 / 州解析不到 IBGE 码;开票:收件人 IBGE 市政码不存在或与 uf 不一致 | 核对 UF 与城市名 / IBGE 码 |
| 10003008 | 400 | 证书密码不符 | 核对密码 |
| 10003000 | 404 | empresaId 不存在或非本应用名下 | 核对 empresaId |
| 10003002 | 400 | CNPJ 已注册 | 该主体已存在,直接使用原 empresaId |
| 10003006 | 400 | 注册资料缺 IE | 补 inscricaoEstadual |
| 10003010 | 400 | 证书 CNPJ 与主体不一致 | 换正确证书 |
| 10003011 | 400 | 证书已过期 | 换有效证书 |
| 10003012 | 400 | 证书与现有证书重复 | 无需上传 |
| 10003050 | 400 | 自动注册:公开登记数据中查不到该 CNPJ | 核对 CNPJ |
| 10003051 | 503 | 自动注册:公开登记数据暂不可用 | 稍后原样重试 |
| 10003052 | 400 | 主体税制待确认(自动注册推不出税制),不能开新票 | 带 id 调注册主体传 optanteSimplesNacional 与 mei |
| 10003053 | 400 | 自动注册:登记地址的州或城市无法识别 | 改用注册主体接口 |
| 10009033 | 400 | Webhook 注册参数不合法(id 不匹配 / contentType 非 JSON / eventos 含未知编码) | 按说明修正,见 Webhook 注册 |
| 10009010 | 400 | Webhook 回调地址不合法,只接受 http / https 地址 | 改用公网 https 地址 |
| 10009013 | 400 | Webhook 回调地址指向内网或保留网段 | 改用公网地址 |
| 10009019 | 400 | Webhook 回调地址过长 | 缩短地址 |
税种
数组格式。税种不存在为 HTTP 404,并发修改为 HTTP 409,其余 HTTP 400。全部错误码见税种。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10005200 | 404 | 编号不存在或已删除 | 核对编号与 empresaId |
| 10005203 | 400 | 税码不受支持 | 按 NF-e 开票的税码表修正 |
| 10005204 | 400 | 分类码不属于所填 CST | 分类码前三位须等于 CST |
| 10005206 | 409 | 税种被并发修改 | 重新查询后再提交 |
| 10005208 | 400 | 创建或整份替换的请求体带了 codigo | 删掉 codigo:编号由平台生成,创建响应返回,之后按路径传 |
| 10005210 | 400 | 请求体含不存在的字段,mensagem 点名路径 | 删掉该字段,字段名以端点页为准 |
| 10005211 | 400 | 同一组两行的 cenario、tipoPessoa、naoContribuinte 组合重复 | 合并或删掉其中一行 |
| 10005212 | 400 | 行的 cfop 首位与场景不符 | 按场景改 CFOP:州内出库 5、跨州 6、出口 7,入库 1 / 2 / 3 |
| 10005213 | 400 | 数值或布尔传成了字符串,mensagem 点名路径 | 数值传 JSON 数字,布尔传 true / false |
| 10005214 | 400 | CFOP 与组不符:ISSQN 行只能用 5933,ICMS 行不能用 5933 | 按组改 CFOP |
| 10005216 | 400 | 更新时 tipo 与现值不同 | 税种类型不能改,另建一个税种 |
| 10005217 | 400 | NFCe 税种带了 NFC-e 开票没有的字段,mensagem 点名路径 | 删掉该字段,或改建 NFe 税种 |
| 10005218 | 400 | 该类型不能有的组:NFe 带 issqn,NFCe 带 ipi | 删掉该组 |
| 10005219 | 400 | NFCe 税种的行场景不是 SaidaDentroEstado / Padrao | 改场景 |
| 10004047 | 400 | 非纳税人或个人买方的 ICMS 行用了纳税人专用税码(10、30、70、101、201、202、203)或带 percentualCreditoSimples | 改用 102 / 500 等税码,或去掉该维度 |
| 10005008 | 400 | PIS / COFINS 01 行的 aliquota 与主体已配置计税制度的法定税率不符 | 改成法定税率或不填,见开票主体的「税收制度」 |
| 10004046 | 400 | 税码与主体税制不符(CRT 1/4 须三位 CSOSN,CRT 2/3 须两位 CST) | 按主体税制改税码 |
NF-e
数组格式。业务错误为 HTTP 400;单据不存在为 HTTP 404,codigo 为 10004000 或 10004001。发行阶段的 SEFAZ 驳回不走 HTTP 错误,而是查询结果 Negada + webhook invoice.rejected。见 NF-e。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10004000 / 10004001 | 404 | 查询 / 取消 / 更正函的 nfeId 不存在 | 核对开票时传入的 id 与 empresaId |
| 10004002 | 400 | 该 CNPJ 待处理开票任务超限 | 稍后重试 |
| 10004004 | 400 | 主体不可开票(未审批通过或证书未就绪) | 等待审批 / 关联证书 |
| 10004012 | 400 | 取消 / 更正函:票不在已授权状态 | 查询确认状态 |
| 10004013 | 400 | 取消:超出 24 小时窗口 | 改开退货票 |
| 10004014 | 400 | 取消:SEFAZ 拒绝(附返回码与原因) | 按 SEFAZ 原因处理 |
| 10004015 | 400 | 更正函:同票已达 20 封 | 不能再登记,需取消重开或退货票 |
| 10004016 | 400 | 更正函:SEFAZ 拒绝(附返回码与原因) | 按 SEFAZ 原因处理 |
| 10004017 | 400 | 更正函:内容净化后不足 15 字符 | 用葡语 / ASCII 文本重写 |
| 10004019 | 400 | 更正函:超出授权后 720 小时窗口 | 只能取消重开或退货票 |
| 10004021 至 10004026 | 400 | 退货票引用校验:缺引用 / 非退货票带引用 / 原票不存在或不属本主体 / 原票未授权 / 原票行不存在 / 数量超原票行 | 见 NF-e 开票的退货票规则 |
| 10004030 | 400 | ambienteEmissao 与主体当前环境不一致 | 按主体环境提交或联系运营切换,见环境 |
| 10004031 | 400 | 不支持的取值(presencaConsumidor / 多条支付 / 未知支付类型 / tipoPessoa 与证件不符 / CPF 买方携带 inscricaoEstadual) | 按 NF-e 开票的支持范围调整 |
| 10004034 | 400 | CNPJ 买方未传 cliente.inscricaoEstadual | 补买方 IE(ICMS 纳税人) |
| 10004043 | 400 | 契约字段缺失(税码所需的减基比例 / ST MVA 与税率 / 递延比例 / 按量单位税额 / IPI 税码 / pCredSN 请求与档案皆无),mensagem 点名字段路径 | 按 NF-e 开票的税码矩阵补字段 |
| 10004044 | 400 | 字段不适用于该税码(非 ST 税码带 substituicaoTributaria、非抵免税码带 percentualCreditoSimples) | 去掉该组 |
| 10004045 | 400 | CNPJ 买方的 cliente.inscricaoEstadual 不符合买方所在州的校验位规则(否则取号后被 SEFAZ 209 拒绝并烧号) | 核对买方 IE 与州 |
| 10004046 | 400 | 税码与主体税制不匹配(CRT 1/4 须三位 CSOSN,CRT 2/3 须两位 CST) | 按主体税制改税码 |
| 10004047 | 400 | 非纳税人买方使用了只对纳税人合法的税码(10/30/70、101/201/202/203)或携带 pCredSN | 改用 102 / 500 或不带抵免的 900 |
| 10004051 | 400 | 未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州 | 传 IBGE 码,或核对 cep / uf |
| 10005000 | 400 | 税务引擎校验拒绝(税制错配、ST 用于非纳税人、税率越界等) | 见 NF-e 开票的税参规则 |
| 10005007 | 400 | CRT 3 主体的 PIS / COFINS CST 01 没传税率,主体又未配置计税制度,平台无法补率 | 传 aliquota,或在控制台「税务补录」里配置计税制度,见开票主体 |
| 10005008 | 400 | CRT 3 主体的 PIS / COFINS CST 01 税率与主体计税制度的法定税率不符 | 改成法定税率或不传,见开票主体 |
| 10005202 | 400 | 商品行引用的税种不存在、已删除或属于别的主体 | 核对 classeImposto 与 empresaId,见税种 |
| 10005215 | 400 | 引用的税种类型与单据不符:NF-e 只能引用 NFe 税种,NFC-e 只能引用 NFCe 税种 | 改引用对应类型的税种 |
| 10005220 | 400 | 引用的税种与主体当前税制不符(IncompativelComRegime) | 按新税制整份替换税种,见税种 |
| 10001002 | 400 | 引用税种的商品行直传了 icms 或 issqn 却没传 cfop | 在该商品行补 cfop |
| 10005209 | 400 | 引用的税种在本行需要的组(ICMS 或服务行 ISSQN、PIS、COFINS)里没有适用于本票的行,mensagem 写明组、场景、客户类型与是否非纳税人 | 给税种补一行,或在请求里直传该组,见税种的选行顺序 |
NFC-e
数组格式。业务错误为 HTTP 400;单据或主体不存在为 HTTP 404。SEFAZ 驳回不走 HTTP 错误,而是查询结果 Negada + webhook nfce.rejected。见 NFC-e。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10022006 | 404 | nfceId 不存在 | 核对 id 与 empresaId |
| 10003000 | 404 | empresaId 不存在 | 核对 empresaId |
| 10022001 | 400 | 主体当前环境未开通 NFC-e | 注册或更新时传 emissaoNFeConsumidor 的对应环境 |
| 10022002 | 400 | 主体不可开票(未审批通过或证书不可用) | 等待审批或关联证书 |
| 10022003 | 400 | ambienteEmissao 与主体当前环境不一致 | 按主体环境提交 |
| 10022004 | 400 | 不符合 NFC-e 规则,mensagem 点名原因 | 按原因修正,或改开 NF-e |
| 10022007 | 400 | 超出取消期限(取消 30 分钟、替代取消 168 小时) | 按州规定另开 NF-e 冲销 |
| 10022008 | 400 | 当前状态不允许此操作(不是已授权、取消处理中) | 查询确认状态 |
| 10022009 | 400 | 州要求二维码 v2,但主体没有可用的安全码 | 二维码 v2 由平台为主体切换,安全码只在生产环境生效,请联系平台 |
| 10022024 | 400 | 未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州 | 传 IBGE 码,或核对 cep / uf |
| 10001001 | 400 | 请求字段校验失败 | 按 mensagem 修正 |
| 10005000 | 400 | 税务引擎校验拒绝 | 按 mensagem 修正 |
| 10005007 | 400 | CRT 3 主体的 PIS / COFINS CST 01 没传税率,主体又未配置计税制度,平台无法补率 | 传 aliquota,或在控制台「税务补录」里配置计税制度,见开票主体 |
| 10005008 | 400 | CRT 3 主体的 PIS / COFINS CST 01 税率与主体计税制度的法定税率不符 | 改成法定税率或不传,见开票主体 |
| 10005202 | 400 | 商品行引用的税种不存在、已删除或属于别的主体 | 核对 classeImposto 与 empresaId,见税种 |
| 10005215 | 400 | 引用的税种类型与单据不符:NF-e 只能引用 NFe 税种,NFC-e 只能引用 NFCe 税种 | 改引用对应类型的税种 |
| 10005220 | 400 | 引用的税种与主体当前税制不符(IncompativelComRegime) | 按新税制整份替换税种,见税种 |
| 10001002 | 400 | 引用税种的商品行直传了 icms 或 issqn 却没传 cfop | 在该商品行补 cfop |
| 10005209 | 400 | 引用的税种在本行需要的组(ICMS 或服务行 ISSQN、PIS、COFINS)里没有适用于本票的行,mensagem 写明组、场景、客户类型与是否非纳税人 | 给税种补一行,或在请求里直传该组,见税种的选行顺序 |
| 10005205 | 400 | 税种选中的行含 NFC-e 不接受的组或字段,mensagem 点名字段 | 为 NFC-e 另建一个税种,或在请求里传该组覆盖 |
10022004 常见原因:在场方式不允许;送货、取货地址跨州或买方是纳税人;金额超上限;未达识别要求;配送缺承运方或地址,或非配送填了承运方、运费方式;本州不允许配送;CFOP 或税码不在 NFC-e 允许范围;支付不足、找零不符或用了 SemPagamento,或刷卡组、支付说明用在不允许的支付方式上;携带 NFC-e 不允许的字段(一次列出全部);取值名未知。
SEFAZ 常见驳回(motivoStatus 原样回显):704 开票时刻早于 SEFAZ 收到时刻 5 分钟以上;717 在场方式不允许;725 CFOP 不允许;750 达到识别门槛但未识别消费者;780 超过州金额上限;785 / 786 / 787 / 788 本州不允许配送、配送缺承运方、缺消费者、缺地址;462 / 463 / 464 安全码未登记、已停用、二维码校验不符;865 支付合计小于票面总额。
NFC-e 离线开票
见 NFC-e 离线开票。
开放接口
平台统一响应体。业务错误为 HTTP 200、success 为 false;主体、设备不存在为 HTTP 404;字段校验失败为 HTTP 400。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10029100 | 404 | 主体不存在或不属于当前集成商 | 核对 empresaId |
| 10029202 | 404 | 设备不存在或不属于该主体 | 核对 dispositivoId |
| 10029101 | 200 | 主体不能开 NFC-e:尚未通过运营审核、审核被驳回或已停用,所选环境未开通 NFC-e,或生产环境缺少有效 A1 证书;message 说明原因 | 新注册的主体需等待运营审核通过后再开通离线开票、生成配对码;驳回的按原因修改后重新提交;注册时传 emissaoNFeConsumidor;关联有效证书 |
| 10029104 | 200 | 该主体的离线开票被平台停用 | 联系平台 |
| 10029201 | 200 | 主体待使用的配对码已有 20 个 | 先使用或等待过期 |
| 10029219 | 200 | ambiente 与主体当前环境不一致 | 按主体当前环境生成配对码 |
| 10029221 | 200 | serie 在 890 到 999 之间;CNPJ 开票方的 NFC-e 只能用 0 到 889 号系列 | 换 0 到 889 内的系列 |
| 10029222 | 200 | serie 是主体档案里任一环境的 NFC-e 系列 | 换一个系列 |
| 10029223 | 200 | serie 已被本主体其他在用设备或待使用的配对码占用;message 说明占用者 | 换一个系列 |
| 10029224 | 200 | numeroInicial 不大于该系列平台已知的最大号;message 给出这个号码 | 传更大的起始号码,或不传由平台接着往后 |
| 10029225 | 200 | serie 属于已停用或被吊销、但还有离线票没补传完的设备 | 等原设备补传完成后再生成 |
| 10029001 | 200 | 参数取值超出范围,message 点名字段 | 按允许取值修正 |
| 10001001 | 400 | 请求字段校验失败 | 按 message 修正 |
设备配对
发票助手或 SDK 配对时由平台返回,发票助手的安装向导与 SDK 异常原样展示。
| 错误码 | 场景 | 处置 |
|---|---|---|
| 10029203 / 10029204 | 设备已停用 / 已被平台吊销 | 重新生成配对码 |
| 10029205 | 配对码无效 | 核对是否完整复制;必要时重新生成 |
| 10029206 / 10029207 / 10029208 | 配对码已过期 / 已使用 / 已作废 | 重新生成配对码 |
| 10029209 | 配对码不允许该形态(例如 Assistente 码用于 SDK) | 按接入形态重新生成 |
| 10029210 | SDK 配对未提供收银软件名称 | 初始化时传收银软件名称 |
| 10029501 | 收银软件被平台封禁 | 联系平台 |
| 10029211 | 收银程序版本被封禁或低于最低版本 | 升级收银程序 |
| 10029212 | 内核版本过旧 | 升级发票助手或 SDK |
| 10029213 | 证书 CNPJ 与主体不符 | 选用该主体的 A1 证书 |
| 10029214 | 证书已过期 | 更换有效证书 |
| 10029219 | 配对码环境与主体当前环境不一致(配对时再核对一次) | 在主体当前环境重新生成配对码 |
| 10029221 到 10029225 | 配对码指定的设备系列在配对时再核对一次,已不可用;含义同生成配对码时的同号错误 | 重新生成配对码,换一个系列或起始号码 |
| 10029307 | 设备环境与主体当前环境不一致:主体切换环境后,旧环境设备在线开票与补传都被拒绝 | 在主体当前环境重新生成配对码、配对新设备,停用旧设备 |
| 10029424 | 设备在线开票的号码已被占用;内核弃号重试一次仍冲突时返回 | 本机库与平台记录不一致,导出日志联系平台 |
| 10029426 | 设备在线开票时,同一 id 在平台已有未被拒绝的票 | 核对原票;新的销售用新 id |
离线开票内核与 SDK
发票助手与内置 SDK 共用离线开票内核。内核错误在 SDK 中以异常抛出(Codigo 为错误码、Tipo 为常量),在发票助手本机接口中以 codigo 返回。10029800 段与 10029780 段来自内核,10029870 段来自 SDK 与运行时通信;只因 SDK 自身缺陷才会出现的码不在此列,见 SDK 参考。平台返回的错误码原样透传。
| 错误码 | 常量 | 场景 | 处理 |
|---|---|---|---|
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | 商品行引用了税种,但连不上平台展开;未占用票号,发票助手返回 HTTP 400 | 恢复网络后用同一 id 重发;断网时商品行改传 impostos,见税种与联网 |
| 10029801 | ENGINE_NOT_ACTIVATED | 该主体未在本机配对,或本机尚未配对任何主体 | 引导配对;多主体时检查 empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | 配对了多个主体但未指定 empresaId | 传 empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | 没有可用于离线开票的许可证 | 联网同步一次(SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | 许可证已过期;离线开票被拒,在线开票照常 | 恢复网络,自动续签 |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | 许可证签名无效 | 人工处理:联系平台,本地库可能被篡改 |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | 许可证不属于本设备 | 人工处理:重新配对 |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | 已过离线开票截止时间 | 恢复网络后在线开票 |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | 本设备系列号码已用到 999999999 | 停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列 |
| 10029809 | ENGINE_CLOCK_ROLLBACK | 系统时钟被往回调 | 人工处理:校正系统时间 |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | 最早待补传票已超补传时限 | 人工处理:尽快恢复网络补传 |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | 主体或州不允许离线开票;或刚从备份恢复、尚未拿到新许可证 | 只能在线开票;刚恢复的联网同步一轮后自动恢复离线开票 |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | 含燃料的票不能离线开 | 网络恢复后开票 |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | 证书找不到、无私钥或 CNPJ 不符 | 人工处理:检查证书存储,必要时 TrocarCertificado |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | 证书已过期 | 人工处理:续期后 TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | 本机配置或计税数据缺失或校验失败 | 联网同步;持续出现联系平台 |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | 设备已被停用 | 人工处理:联系集成商;已开离线票照常补传 |
| 10029817 | ENGINE_REQUEST_INVALID | 请求校验失败,Detalhes 逐字段列出原因 | 修正请求;可先用 Previsualizar 预校验 |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | 同一 id 已用于内容不同的票 | 新单用新 id;重试用原请求取回原票 |
| 10029819 | ENGINE_NOTE_NOT_FOUND | 本机没有这张票 | 核对 id 与 empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | 当前状态不可修正 | 只有 Rejeitada 可以 Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | 修正改变了金额或税额 | 只改非金额内容 |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | 当前状态不可取消;替代取消时原票不是在线开出的正常票(离线票、已取消或已有挂起取消) | 不要重试 |
| 10029823 | ENGINE_SERIE_EXHAUSTED | 设备系列号码已用尽 | 停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列 |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | 需要联网的操作(配对)连不上平台 | 检查网络后重试 |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | 配对码格式、签名或有效期不对 | 人工处理:重新生成配对码 |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | 配对码指向的平台地址不受信 | 人工处理:确认配对码来源与安装包环境(测试 / 生产) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | 数据目录来自别的电脑或别的 Windows 用户 | 人工处理:用原电脑、原用户运行,或重新配对 |
| 10029828 | ENGINE_DATA_DIR_LOCKED | 数据目录被其他进程占用,包括恢复备份时本程序还没 Encerrar 的实例 | 关闭另一个实例;恢复备份前先 Encerrar |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | 本地库不一致 | 人工处理:不要删除数据目录,联系平台 |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | SDK 与运行时版本不兼容 | SDK 与运行时配套升级 |
| 10029831 | ENGINE_RUNTIME_START_FAILED | 运行时启动失败 | 检查运行时目录是否完整、是否被杀毒软件拦截 |
| 10029832 | ENGINE_RUNTIME_CRASHED | 运行时意外退出 | 可重试;开启自动重启时 SDK 自行恢复,开票用同一 id 重发 |
| 10029833 | ENGINE_TIMEOUT | 等待超时 | 开票用同一 id 重发,或先 Consultar |
| 10029834 | ENGINE_SHUTTING_DOWN | 正在关闭或已关闭 | 重新 Iniciar |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | Java 进程内模式需要 Java 21 及以上 | 改用子进程模式 |
| 10029836 | ENGINE_INTERNAL_ERROR | 内核内部错误,说明里带定位号 | 联系平台并提供定位号与日志 |
| 10029837 | ENGINE_ALREADY_ACTIVATED | 该主体已在本数据目录配对 | 无需再配对;换设备须先停用旧设备 |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | 平台响应校验失败,已保留原数据 | 稍后自动重试;持续出现检查网络代理是否改写了响应 |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | 平台已配对但本机保存失败 | 用同一配对码再次配对 |
| 10029840 | ENGINE_CONFIG_INVALID | 初始化配置非法 | 修正配置 |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | 授权 XML 不可用:尚未授权,或本机没有且向平台回取不到 | 等授权事件后再取;回取不到时稍后重试 |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | 数据目录被更新版本用过,内核拒绝启动;发票助手本机接口返回 HTTP 503 | 安装或升级到不低于上次使用的版本;不要删除数据目录 |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | 取消 XML 不可用:尚未取消,或本机没有且向平台回取不到 | 等取消成功事件后再取;回取不到时稍后重试 |
| 10029844 | ENGINE_EXPORT_FAILED | 导出或备份写文件失败:目标不可写,或备份文件已存在 | 换目录或文件名;检查磁盘空间与权限 |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | 替代取消的替代票密钥不合法,或不是本设备本主体未被拒收的离线票 | 传本设备为同一笔销售开出的离线票 44 位密钥 |
| 10029846 | ENGINE_BACKUP_INVALID | 备份无法恢复:口令错误,或备份文件被改动、损坏、不是离线开票的备份;发票助手返回 HTTP 400 | 核对备份口令;换一份完好的备份。原库保持不变 |
| 10029874 | ENGINE_PARAMS_INVALID | 参数缺失或类型错误,Detalhes.campo 点名参数 | 修正参数,例如请求不是 JSON 对象、证书指纹格式、日期格式 |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | 找不到运行时 | 检查安装包与运行时目录 |
| 10029878 | ENGINE_TOO_MANY_PENDING | 同时等待中的调用超过 64 个 | 降低并发 |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | 主从模式的从机连不上主机,请求没有送到 | 稍后重试,或把收银切到备用机 |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | 请求已发到主机但没收到响应,结果未知 | 主机恢复后用同一个 id 查询;同一 id 同样内容重开不会重复开票 |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | 从机的终端令牌无效或已吊销 | 在主机重新签发终端令牌,更新从机配置 |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | 主机地址格式不对,或不是局域网私有地址 | 修正从机配置的主机地址 |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | 当前模式不提供该方法 | 配对、换证书、备份与导出在主机做;终端管理只在主机调用 |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | 主机拒绝了请求来源,例如从机不在允许网段内 | 检查主机的允许网段与网络 |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | 鉴权失败过多,被主机限频 | 核对令牌,1 分钟后再试 |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | 主机的局域网端口无法监听 | 换主机端口,或释放被占用的端口 |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | 要吊销的终端不存在 | 核对终端标识 |
发票助手
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10029900 | 401 | 缺少收银令牌 | 带 Authorization: Bearer tfl_… |
| 10029901 | 401 | 收银令牌无效或已吊销 | 店长重新生成令牌 |
| 10029902 | 403 | 令牌无权访问该主体 | 生成包含该主体的令牌 |
| 10029903 | 403 | 来源地址不在局域网允许网段 | 检查局域网模式设置 |
| 10029904 | 400 | 回调地址不合法 | 只允许 http / https;局域网模式关闭时只允许本机回环地址 |
| 10029905 | 401 | 桌面程序操作需要店长会话 | 输入店长 PIN 登录 |
| 10029906 | 401 | 店长 PIN 错误 | 重新输入;累计输错 5 次会锁定 |
| 10029907 | 409 | 打印机不可用 | 检查打印机连接与「设置」里选的打印机 |
| 10029908 | 409 | 尚未完成安装向导 | 先完成安装向导 |
| 10029909 | 400 | 请求不合法 | 按 mensagem 修正 |
| 10029910 | 404 | 资源不存在 | 核对路径 |
| 10029911 | 400 | PIN 格式不对,须为 6 到 8 位数字 | 按格式重新设置 |
| 10029912 | 500 | 助手内部错误 | 导出诊断包联系平台 |
| 10029913 | 403 | 桌面程序请求的 Host 头不被允许,只接受 127.0.0.1、localhost 或 [::1] 加助手端口 | 用 http://127.0.0.1:端口 打开桌面程序,不要经代理或其他主机名访问 |
| 10029914 | 429 | PIN 错误次数过多,锁定中 | 等锁定结束,见发票助手常见问题 |
| 10029916 | 409 | 所选端口被占用或无法监听,设置未修改 | 换一个端口 |
| 10029917 | 403 | 收银员会话无权访问该主体 | 由店长 PIN 登录后操作 |
| 10029918 | 429 | 助手忙:XML 回取已有 3 个在进行,或已有一项导出、备份在进行 | 稍后重试,不要连续重复调用 |
| 10029919 | 400 | 出站代理设置不合法 | 在桌面程序「设置」按提示修正出站代理的「联网方式」与「代理地址」,设置未保存 |
| 10029920 | 409 | 保存出站代理或从备份恢复时要重启开票内核,但有导出、备份或 XML 下载在进行,15 秒内没有结束 | 等这些操作结束后再保存或再恢复;设置与本地库都没有改动 |
| 10029922 | 409 | 助手数据目录所在磁盘剩余空间不足 256 MB,导出、备份或上传备份文件被拒 | 清理该磁盘后重试 |
| 10029923 | 403 | 桌面程序的请求缺少或带错防跨站令牌,常见于会话过期或页面停留过久 | 刷新页面;仍出现时重新输入店长 PIN 登录 |
| 10029924 | 429 | 收银员会话开设过于频繁,同一来源每分钟最多 20 次 | 等一分钟后再进入开票页 |
发票助手错误只出现在助手的本机接口与桌面程序中,内置 SDK 不会返回;10029905 到 10029908、10029911、10029913 到 10029917、10029919 到 10029924 只在桌面程序中出现。
CT-e
数组格式。业务错误为 HTTP 400;单据 / 任务不存在为 HTTP 404,codigo 为 10017002 或 10017003。发行阶段的 SEFAZ 驳回体现为查询结果 Negada + webhook cte.rejected。见 CT-e。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10017002 / 10017003 | 404 | cteId 不存在或非本主体 | 核对 id 与 empresaId |
| 10003000 | 404 | empresaId 不存在 | 核对 empresaId |
| 10017004 | 400 | 主体不可发行(未审批 / 证书未就绪) | 等待审批 / 关联证书 |
| 10017005 / 10017006 | 400 | 同请求并发重复 / 该 CNPJ 待处理任务超限 | 稍后重试 |
| 10017007 | 400 | 号段无法确定(未配置或多个启用号段未指定) | 配置模型 57 号段 |
| 10017010 | 400 | ambienteEmissao 与主体环境不一致 | 按主体环境提交 |
| 10017011 | 400 | 市政 IBGE 码不存在 | 核对 codigoIbge |
| 10017050 | 400 | 未传 codigoIbge,且无法按邮编补齐:缺 cep、邮编不在基础数据中或对应多个市政 | 传 codigoIbge,或核对 cep |
| 10017012 / 10017013 | 400 | 参与方缺失 / 承担方与 IE 指示不符 | 补参与方或改 indicadorIeTomador |
| 10017014 | 400 | 单据引用不合法(缺失、chave 校验位错、三种类型混用、前序单据与服务类型不符) | 调整单据引用 |
| 10017015 | 400 | 单据类型与引用不符(补充 / 替代) | 按 tipo 补 ctesComplementados / cteSubstituido |
| 10017016 | 400 | 运费组成合计不等于总额,或 aReceber 大于总额 | 修正金额 |
| 10017017 / 10017018 / 10017019 | 400 | RNTRC 非法 / 模态不支持 / 枚举或格式非法(mensagem 点名字段) | 按 mensagem 修正 |
| 10017020 至 10017025 | 400 | 税参缺失 / 禁传 / 与税制不符 / 跨州非纳税人缺 icmsUfFim / 税率表缺项 / CST 不支持 | 见 CT-e 的税参说明 |
| 10017030 | 400 | 同 id 报文不同 | 换 id 或沿用原报文 |
| 10017031 | 400 | 生产环境同 id 已有在途 / 已授权单据 | 查询原单 |
| 10017040 至 10017045 | 400 | 状态不允许事件 / 超取消窗口 / 事件文本非法 / SEFAZ 拒绝事件 / 更正序号超限 / 被撤销事件不存在 | 见 CT-e 的取消与事件规则 |
| 10017048 / 10017049 | 400 | 已登记信函更正不可取消 / 信函更正超 720 小时窗口 | 见 CT-e 的取消与事件规则 |
| 10001001 | 400 | 请求字段校验失败(每字段一条) | 按 mensagem 修正 |
DC-e
数组格式。业务错误为 HTTP 400;单据 / 任务不存在为 HTTP 404,codigo 为 10019002 或 10019003。发行阶段的 SEFAZ 驳回体现为查询结果 Negada + webhook dce.rejected;取消阶段的 SEFAZ 拒绝走 dce.cancel_rejected。见 DC-e。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10019002 / 10019003 | 404 | dceId 不存在、非本主体,或取消时单据尚未物化 | 核对 id 与 empresaId;Pendente 单据待授权后再取消 |
| 10003000 | 404 | empresaId 不存在 | 核对 empresaId |
| 10019012 / 10019010 | 400 | 主体未配置 DC-e 发行(缺 tipoEmitente / 模型 99 号段 / Marketplace 站点),或 ambiente 与主体当前环境不一致 | 注册时传 emissaoDCe 或带 id 更新补配;按主体当前环境提交,切生产联系运营 |
| 10019014 | 400 | Marketplace / Carrier 主体未传 remetente | 补发件方 |
| 10019015 | 400 | remetente.endereco 缺失 | 补发件方地址 |
| 10019016 | 400 | 巴西发件方缺 cpfCnpj | 补发件方证件 |
| 10019004 | 400 | 主体不可发行(未审批 / 证书未就绪) | 等待审批 / 关联证书 |
| 10019017 | 400 | 巴西收件方缺 cpfCnpj | 补收件方证件 |
| 10019011 | 400 | 市政 IBGE 码不存在或与 uf 不一致 | 核对 cidade / uf |
| 10019049 | 400 | 未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州 | 传 IBGE 码,或核对 cep / uf |
| 10019005 / 10019006 | 400 | 同请求并发重复 / 该 CNPJ 待处理任务超限 | 稍后重试 |
| 10019007 | 400 | 号段无法确定(多个启用号段) | 联系运营收敛号段 |
| 10019013 | 400 | 主体类型 Carrier 当前不支持发行 | 改用 Marketplace / OwnIssuer 主体 |
| 10019018 | 400 | 明细不合法(NCM 位数、数量 ≤ 0、单价为负) | 按 mensagem 修正 |
| 10019019 | 400 | 枚举或格式非法(mensagem 点名字段:tipoPessoa、modalidade、dataEmissao、证件、电话、邮箱、自发主体 remetente 与主体不符等) | 按 mensagem 修正 |
| 10019020 | 400 | 承运商 CNPJ 不合法 | 修正 cnpjTransportadora |
| 10019021 | 400 | 附加信息超长 | 缩短文本 |
| 10019022 | 400 | autorizacaoDownloadXml 条数或证件不合法;含发行方自身 CNPJ;同一证件重复 | 修正该列表 |
| 10019030 | 400 | 同 id 报文不同 | 换 id 或沿用原报文 |
| 10019031 | 400 | 生产环境同 id 已有在途 / 已授权单据 | 查询原单 |
| 10019040 至 10019043 | 400 | 状态不允许取消 / 超 24 小时窗口 / 取消已受理 / 理由不合法 | 见 DC-e 的取消规则 |
| 10019048 | 400 | dataEmissao 超出允许窗口(超前大于 5 分钟或回溯大于 30 天,mensagem 带当前允许范围) | 改用当前时刻或省略 dataEmissao |
| 10001001 | 400 | 请求字段校验失败(每字段一条);emissaoDCe 的注册 / 更新契约错误 | 按 mensagem 修正 |
NFS-e
数组格式 [{codigo, mensagem}];业务错误为 HTTP 400;单据不存在为 HTTP 404,codigo 为 10018002 或 10018003。发行是异步的:受理期的拒绝是同步 HTTP 错误,发行方的驳回体现为查询结果 Negada + webhook nfse.rejected。见 NFS-e。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10018001 | 400 | 受理期参数校验拒绝,mensagem 说明具体原因(含 IBS/CBS 门控未生效、圣保罗主体携带 ibsCbs、码值或结构约束不满足) | 按 mensagem 修正 |
| 10018002 / 10018003 | 404 | 单据不存在:nfseId 不属于本主体,或进项密钥不在本主体的进项里 | 核对 nfseId / chaveAcesso 与 empresaId |
| 10018004 | 400 | 主体不可开票(停用 / 证书不可用) | 检查主体状态与证书 |
| 10018005 | 400 | 主体缺 NFS-e 档案,mensagem 点名缺哪一项 | 注册时传 emissaoNFSe 或带 id 更新补配 |
| 10018010 | 400 | 该市镇的 NFS-e 标准尚未支持 | 该市镇暂不可开,联系平台 |
| 10018012 | 400 | 服务码不在 LC 116 官方清单内 | 核对 codigoTributacaoNacional |
| 10018013 | 400 | 接收方证件不合法 | 核对 CPF / CNPJ / NIF |
| 10018014 | 400 | 服务出口缺出境国 | 补 servico.paisPrestacao |
| 10018015 | 400 | 被替代票不可替代 | 核对被替代票状态 |
| 10018020 | 400 | 无法确定 ISS 税率(直传与市政参数均无) | 传 servico.iss.aliquota 或正确的 servico.codigoTributacaoMunicipal |
| 10018022 | 400 | Simples 主体不得直传 ISS 税率 | 去掉 aliquota |
| 10018023 | 400 | 判定联邦源泉扣缴还缺以下信息,请补充或直接传扣缴额:%s。%s 一次列出全部缺的字段路径:servico.retencoes.categoriaFederal、cliente.orgaoPublico、cliente.optanteSimplesNacional、servico.retencoes.modoContratacao、servico.retencoes.anexoSimples、servico.retencoes.inss/irrf/csll/pis/cofins | 补齐所列字段后重发,或在 servico.retencoes 直传扣缴额,无扣缴传 0;清单含 servico.retencoes.inss/irrf/csll/pis/cofins 时只能直传,见于服务分类要求人工判定、或本主体以接收方或中介方身份开票 |
| 10018030 / 10018031 | 400 | 同一请求正在处理中 / 该单号已开票或同 id 不同内容 | 稍后重试;换单号或核对内容 |
| 10018040 | 400 | 取消分析申请已在处理中 | 等市镇裁决 |
| 10018041 | 400 | 该票已被替代 | 不可再操作 |
| 10018042 | 400 | 当前状态不允许该事件(取消;进项票表态:已取消 / 已被替代 / 已有表态 / 本主体非接收方或中介方) | 核对票状态,一张票每方只能表态一次 |
| 10018063 | 400 | DPS 报文不符合官方 XSD,明细含行号、列号、错误键与元素名 | 常见原因是文本含 Latin-1 以外字符、地址不完整、码值不在官方码表 |
| 10018064 | 400 | NFS-e 事件报文不符合官方 XSD | 核对 motivo 长度(15-255)、codigoMotivo 取值与字符集 |
| 10018065 | 400 | 本票需要的 NFS-e 计税基础数据未导入,请在请求中直接传入箭头后的字段,或先导入基础数据:%s。%s 按「业务项 -> 可改传的请求字段」列出:retencao-federal -> servico.retencoes.inss/irrf/csll/pis/cofins、pis-cofins -> servico.pisCofins.aliquotaPis/aliquotaCofins、iss-local-incidencia -> servico.iss.municipioIncidencia.codigoIbge;只在请求没给、须由平台查的那一项用到未就绪的数据时出现,一律在受理时返回 | 在请求里直接传箭头后的字段,或联系平台确认基础数据已导入;iss-local-incidencia 出现于服务发生地与开票方不同城时,传 servico.iss.municipioIncidencia 即可 |
| 10018066 | 400 | 未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州 | 传 IBGE 码,或核对 cep / uf |
发票邮件
数组格式。业务错误为 HTTP 400;查无为 HTTP 404;同一张票上一封邮件未到终态为 HTTP 409。投递失败不走 HTTP 错误,而是查询结果 Falha + webhook email.failed。见发票邮件。
| 错误码 | HTTP | 场景 | 处置 |
|---|---|---|---|
| 10003000 | 404 | empresaId 不存在 | 核对 empresaId |
| 10021001 | 404 | 邮件模板不存在或不属于本集成商 | 核对 templateId |
| 10021002 | 400 | 模板已停用,或模板的发票类型与单据不符 | 换模板或启用 |
| 10021003 | 400 | 模板引用了白名单之外的变量 | 按变量枚举修正 |
| 10021004 | 400 | 模板 HTML 含禁止的内容或正文超过 64 KB | 按消息点名的位置修正 |
| 10021005 | 400 | 模板列表的 tipoDocumento 不支持 | 只传 NFe / NFSe / CTe / DCe |
| 10021010 | 404 | 发票不存在或不属于本主体 | 核对 documentoId、tipoDocumento 与 empresaId |
| 10021011 | 400 | 发票尚未授权,或已取消、已被替代 | 授权后再发 |
| 10021012 | 400 | 该发票类型没有默认模板 | 传 templateId 或设默认模板 |
| 10021013 | 400 | 没有收件人 | 传 destinatarios |
| 10021015 | 409 | 同一张票上一封邮件尚未到终态 | 等 Enviado 或 Falha 后用新 id 重发 |
| 10021020 | 404 | 邮件不存在或不属于本主体 | 核对 emailId 与 empresaId |
| 10001001 | 400 | 请求字段校验失败(每字段一条) | 按 mensagem 修正 |
NF-e 验证
无包装的 {code, message} 对象,见 NF-e 验证。XML 验证与 chave 查询的请求级错误为 HTTP 400,请求未进入校验流程:
| 错误码 | 接口 | 含义 | 处置 |
|---|---|---|---|
| 10015000 | XML 验证 | 请求体为空 | 在 body 中发送 XML |
| 10015001 | XML 验证 | 超过 1 MB | 真实单张 NF-e 不会超过此限制;检查是否包了一层或二次编码 |
| 10015002 | XML 验证 | 检测到 DTD(<!DOCTYPE) | 去除 DTD |
| 10015003 | XML 验证 | 编码非 UTF-8 | 提交前转为 UTF-8 |
| 10015005 | XML 验证 | 已停用,不再返回(原含义:该 chave 已由其他集成商提交验证) | 无需处理:不同集成商可各自验证同一张票 |
| 10015104 | chave 查询 | chave 非法(长度 / 字符 / 校验位) | 先本地校验:44 位数字;末位为 mod-11 校验位 |
| 10015004 | chave 查询 | 各数据源均查无此票 | 平台与官方数据源均无该 chave;与开票方核实 |
DANFE 获取
DANFE 获取失败时按下表返回 HTTP 状态与无包装的 {code, message} 对象;即使请求头带 Accept: application/pdf,错误也以 JSON 返回。
| 错误码 | HTTP | 含义 | 处置 |
|---|---|---|---|
| 10015104 | 400 | chave 非法(长度 / 字符 / 校验位) | 先本地校验:44 位数字;末位为 mod-11 校验位 |
| 10015300 | 404 | 本账户没有这张票的验证记录(其他集成商验证过也一样) | 先用 XML 验证 提交这张票;不要重试 |
| 10015301 | 409 | 验证还没完成(PENDING_SEFAZ / VALIDATING) | 收到 invoice.verify.completed 后再取 |
| 10015302 | 409 | 当前结论不出 PDF(只有 VALIDATED 与 status 为 Cancelada 的票出 PDF) | 不要重试 |
| 10015303 | 409 | 平台缺这张票的 XML 原文 | 用 XML 验证原样重新提交这份 XML、不带 forceRevalidate,再取 |
| 10015304 | 503 | XML 原文还在归档 | 按 Retry-After(5 秒)后重试 |
| 10015305 | 503 | 生成繁忙或暂时不可用 | 按 Retry-After 后重试 |
| 10001000 | 500 | 平台内部错误 | 退避重试;持续失败请携带请求的 timestamp 与路径联系平台 |
一级校验错误
以 HTTP 200 返回,位于 XML 验证响应的 validation.errors[]。这些不是传输错误:请求成功、单据不合格。除 PROTOCOL_MISSING(warning)外均为阻断项(终态 REJECTED)。
errors[].code | 数字码 | 含义 |
|---|---|---|
XML_MALFORMED | 10015100 | XML 语法非法 |
XSD_INVALID | 10015101 | 不符合 NF-e 4.00 XSD 版式 |
SIGNATURE_INVALID | 10015102 | 数字签名验证失败(内容被篡改,或签名时证书已过期) |
SIGNATURE_CERT_MISMATCH | 10015103 | 签名证书 CNPJ 与开票方不符 |
ACCESS_KEY_INVALID | 10015104 | chave 结构 / 校验位非法 |
ACCESS_KEY_MISMATCH | 10015105 | chave 分段与票面字段不一致 |
PROTOCOL_MISMATCH | 10015106 | 协议块与票内容不自洽 |
PROTOCOL_MISSING | 10015107 | 无协议节点(warning,不阻断) |
XML_VERSION_UNSUPPORTED | 10015108 | 版式版本非 4.00 |
二级结论
非 HTTP 错误:经 webhook invoice.verify.completed 送达。
validationStatus | 终态 | 处置 |
|---|---|---|
VALIDATED | 是 | 可放行(发货、结算) |
REJECTED | 是 | 不可放行;reason 说明 SEFAZ 判定(已取消 / 否决 / 作废 / 查无 / 协议不符) |
VALIDATION_ERROR(status 为 null) | 是,可重试 | 平台侧核验失败,非发票判定;与其他结论一样 24 小时内复用,请稍后带请求头 forceRevalidate: true 重新提交 |
VALIDATION_ERROR(status 为 Desconhecida) | 是,重试不会改变 | SEFAZ 不受理这张票的查询(如 cStat 526,开具时间过久),非发票判定,不代表发票是假的;结论一直复用,无需重试,需要时用其他方式确认 |
身份核验
无包装的 {code, message} 对象。格式与校验位错误由平台本地拦截,不会发往上游数据源,因此不消耗调用额度也不计费。见身份核验。
| 错误码 | HTTP | 责任方 | 含义 | 处置 |
|---|---|---|---|---|
| 10016000 | 400 | 调用方 | CPF 格式不合法(须 11 位数字) | 检查是否误传格式符或位数不足 |
| 10016001 | 400 | 调用方 | CPF 校验位不合法 | 本地先用 mod-11 算法校验 |
| 10016002 | 400 | 调用方 | 出生日期格式不合法(须 DDMMYYYY 有效日期) | 注意是日月年顺序,且须为真实存在的日期 |
| 10016003 | 400 | 调用方 | 未找到该 CPF 的信息 | 该 CPF 不存在,或 CPF 与出生日期不匹配(二者不作区分) |
| 10016004 | 451 | 第三方(上游依法拦截) | LGPD: menor de 16 anos (Lei Felca),持有人小于 16 岁 | 依法不提供数据,勿重试 |
| 10016005 | 422 | 第三方(上游依法拦截) | LGPD: menor de idade,持有人 16 到 17 岁 | 依法不提供数据,勿重试 |
| 10016006 | 428 | 第三方(上游依法拦截) | LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao,年龄无法核实 | 平台已带出生日期补核验一次仍未通过,勿重试 |
| 10016010 | 400 | 调用方 | CNPJ 格式不合法(须 14 位数字) | 检查是否误传格式符 |
| 10016011 | 400 | 调用方 | CNPJ 校验位不合法 | 本地先用 mod-11 算法校验 |
| 10016012 | 400 | 调用方 | 未找到该 CNPJ 的信息 | 该 CNPJ 在官方登记中不存在 |
| 10016020 | 503 | 第三方(上游不可用) | 上游数据源暂不可用 | 指数退避重试(初始 1 秒,倍增至 30 秒上限,加抖动);持续出现请联系平台 |
处理指引
- 401 / 403:配置错误;修正凭证、订阅或时钟。不要原样重试。
- 400 / 404:请求或业务规则问题;按码修正。少数码为暂时性,可稍后重试:10004002、10017005 / 10017006、10019005 / 10019006。
- 422 / 428 / 451:身份核验的法定拦截;重试无意义。
- 429:先按
Retry-After等待再重试,仍被拒再指数退避加抖动(初始 1 秒,倍增至 30 秒上限);不理会 429 持续重发会进入冷却,见限流与退避。 - 503:按
Retry-After重试同一请求或链接(10009037、10015304 / 10015305、10016020)。 - 5xx:退避重试;持续失败请携带失败请求的
timestamp与路径联系平台。 - 统一响应体
errorType:1API 错误、2SEFAZ 驳回、3系统异常(可重试)、4字段校验失败(修正请求)。 - 不要盲目重发被驳回的单据:
Negada与REJECTED是终态结论,先按 SEFAZ 原因处理。
