NFC-e 离线开票
发票助手教程
发票助手教程:在门店 Windows 电脑安装并配对发票助手,收银软件调用与云端 NFC-e 接口同路径的本机接口联网或断网开票,经本地回调或轮询收结果,以及部署运维、简易开票与常见问题。
TF Fiscal 发票助手(下称发票助手)是安装在门店 Windows 电脑上的程序,由后台服务和桌面界面组成。后台服务内置离线开票内核,在本机提供与云端 NFC-e 开票接口同路径、同请求体结构的接口(引用税种须联网);收银软件只要把调用地址换成本机,就同时具备在线开票与断网离线开票,读完本页即可完成安装、对接与收结果。开始前,集成商先为这台收银电脑调用生成设备配对码(formaPermitida 为 Assistente 或 Qualquer),把配对码交给门店。
1 安装助手并配对 ──► 2 收银软件调本机接口开票 ──► 3 收结果(本地回调或轮询)
1 安装与配对
准备
| 项 | 说明 |
|---|---|
| 电脑 | Windows,与收银软件同机;一台助手服务多台收银机时见局域网模式 |
| 权限 | 安装需要管理员权限 |
| 安装包 | TfFiscalAssistente-{versao}-Setup.exe({versao} 为版本号),在控制台左侧菜单「离线开票 → 离线开票」页的「下载」标签获取(登录即可,表中附文件大小与 SHA-256 校验值);电脑缺少 WebView2 运行时会自动安装,此时需要联网 |
| 配对码 | 集成商用生成设备配对码生成,formaPermitida 为 Assistente 或 Qualquer;文本或 .tfa 文件均可 |
| 证书 | 主体的 A1 证书:已在 Windows 证书存储中,或 PFX 文件加密码 |
安装后开始菜单「TF Fiscal」与桌面会出现「Assistente Fiscal」快捷方式,后台服务随 Windows 自动启动。桌面界面供店长和收银员使用,包括总览、开票、当日票据、票据详情、常用商品、收银接入、设置、关于与诊断;界面关闭或崩溃不影响后台服务开票。
多台电脑统一安装时改用 MSI 静默安装,见批量部署。
安装向导
首次打开桌面界面进入安装向导,全程只问配对码和证书,平台地址、环境、主体、设备系列都来自配对码与配对结果。
| 步骤 | 内容 |
|---|---|
| 1 欢迎 | 选择界面语言,缺省葡萄牙语;平台返回的错误说明也用这个语言,之后在设置里改语言立即生效 |
| 2 配对码 | 粘贴配对码、导入 .tfa 文件或用摄像头扫码。助手先在本机核验,显示环境(生产 / 测试)、到期时间,以及集成商指定的设备系列与起始号码,未指定时显示由平台分配、从 1 开始;配对码限定为 SDK 形态时在这一步拦下 |
| 3 证书 | 列出证书存储中带 CNPJ、未过期、有私钥的证书供选择;或导入 PFX。导入的私钥设为不可导出,PFX 密码不保存 |
| 4 店长 PIN | 设置 6 到 8 位数字的店长 PIN,用于取消、修正、令牌管理、导出与备份等操作 |
| 5 配对 | 联网配对,成功后显示主体名称、CNPJ、设备名、设备系列与本设备第一张票的号码;失败显示错误码与处理建议 |
| 6 完成 | 显示本机接口地址,引导到「收银接入」生成收银令牌,或直接进入「开票」 |
配对
- 配对因连不上平台而失败时,用同一个配对码再点一次配对即可,不要重新生成配对码:新码会多占一个设备名额。
- 证书列表里提示「服务账户无权使用该私钥」的,是存放在本机证书存储、后台服务账户还不能使用的证书:以管理员身份运行安装目录下的
scripts\conceder-acesso-chave.ps1 -Thumbprint {thumbprint}({thumbprint}为证书指纹),再点「刷新」。 - 同一台电脑服务多个主体(多个 CNPJ)时,再次进入安装向导即「添加公司」,需店长 PIN,流程相同。
2 收银软件对接
生成收银令牌
店长在桌面程序「收银接入」页生成收银令牌:
- 填写名称(如
PDV 01)、可访问的主体(多个 CNPJ 时勾选)、可选的回调地址。 - 令牌形如
tfl_加 43 个字符,只在生成时显示一次;填了回调地址时同时显示回调密钥whsec_…,同样只显示一次。 - 令牌可在同一页一键吊销,立即生效。
收银令牌只能调本机助手,泄露的影响限于这一台助手,可单独吊销;集成商的云端应用密钥不需要放到门店。
收银软件只用下面的本机接口。桌面程序自己用的管理接口(路径以 /assistente/api/ 开头)不对收银软件开放:只接受本机来源,需要店长或收银员会话,带会话的请求还要附上登录时下发的防跨站令牌,其他网页或程序伪造不了这类请求。
地址与鉴权
| 项 | 值 |
|---|---|
| 地址 | http://127.0.0.1:8765;局域网模式下为助手电脑的局域网地址 |
| 鉴权 | 请求头 Authorization: Bearer tfl_…;不带云端的 token / timestamp / sign |
| 正文类型 | Content-Type: application/json |
接口清单
| 方法 | 路径 | 用途 | 云端对应 |
|---|---|---|---|
| POST | /openapi/v2/empresas/{empresaId}/nfce | 开票 | 开具 NFC-e |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId} | 查询 | 查询 NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar | 取消 | 取消 NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar-substituicao | 替代取消 | 替代取消 |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cupom?formato=ESCPOS_80 | 小票,含 PDF 格式 | 本机独有 |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml | 授权 XML 下载 | 本机独有 |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml-cancelamento | 取消 XML 下载 | 本机独有 |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/correcao | 补传被拒后同号修正 | 本机独有 |
| GET | /openapi/local/v1/situacao | 助手状态 | 本机独有 |
与云端接口的差异
- 鉴权:用收银令牌,见地址与鉴权。
modoResposta不起作用:本机始终等待结果。在线结果不明时,内核放弃原号码,用下一个号码转为离线签发,原号码由平台核对后收口;当时不能离线签发才返回 HTTP 202 与AguardandoAutorizacao。其余成功返回 200。- 税种须联网:商品行可以用
classeImposto引用税种,由平台展开后开票;断网或连不上平台时返回 400 与10029780,提示改传impostos,不占用票号。助手不缓存税种,断网兜底须由收银程序自存展开后的impostos,见税种与联网。 empresaId:必须是本助手已配对、且令牌有权访问的主体;未配对返回 404 与10029801,令牌无权返回 403 与10029902。- 小票与 XML 链接:
linkDanfe指向本机小票(HTML 格式);linkDownloadXml在授权 XML 已下载到本机时指向本机 XML 接口,否则为null。 - 本机附加字段:响应在云端字段之外另带下表字段。
| 字段 | 说明 |
|---|---|
situacaoLocal | 本机状态。比 status 多两个取值:Rejeitada(离线票补传被 SEFAZ 拒绝,可同号修正)与 Recusada(平台拒收);这两种情况 status 显示为 Negada。situacaoLocal 本身为 Negada 表示在线被拒,不可同号修正。全部取值见单据状态取值 |
cStat / xMotivo | SEFAZ 结果码与结果说明。成对出现,离线待补传与平台拒收时为 null |
tentativaOnline | 在线尝试标志。true 表示先尝试过在线、结果不明后转为离线签发;在线授权的票,以及刚断网直接离线签发的票为 false |
transmitida | 已补传标志。仅查询返回 |
cancelamentoPendente | 取消待执行标志。仅查询返回;离线票授权前申请的取消为 true |
correcoes | 修正次数。仅查询返回 |
xmlAutorizadoDisponivel | 授权 XML 就绪标志。仅查询返回;true 表示已下载到本机 |
terminal | 收银台标识。开出这张票的收银令牌名称;桌面程序简易开票开出的票为 null。随提交上报平台,云端查询与 Webhook 的 terminal 同值 |
响应格式
| 情形 | HTTP | 响应体 |
|---|---|---|
| 开票、查询、修正成功 | 200;在线未决 202 | 与云端查询结构相同的无包装对象,加本机附加字段 |
| 取消、替代取消受理 | 200 | 无响应体;结果见响应头 X-Tffiscal-Cancelamento |
| 小票、XML 下载成功 | 200 | 文件原文,类型见小票与 XML 下载 |
| 业务错误 | 400;单据或主体不存在 404;XML 不可用 409;助手忙 429;内部错误 500;降级保护 503 | 数组 [{codigo, mensagem}],codigo 为错误码数字串;请求字段校验失败时每个字段一条 |
| 令牌或来源鉴权失败 | 401 / 403 | 平台统一响应体 {success, errorType, code, message} |
错误示例与各错误码的处理见错误处理。
3 开票、查询与补传
联网开票
请求体与云端开票相同;商品行引用税种(classeImposto)时须联网,见与云端接口的差异。联网时,助手在本设备系列上取号、签名,把签好的票交平台转发 SEFAZ,结果与云端同步开票相同;断网后接着同一顺序开离线票,在线票与离线票号码连续,见号码与系列。
下例是门店现场销售、消费者不识别:
POST /openapi/v2/empresas/1934811222334455/nfce HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{"id": "PDV01-000130","ambienteEmissao": "Homologacao","pedido": {"presencaConsumidor": "OperacaoPresencial","pagamento": { "formas": [ { "tipo": "Dinheiro", "valor": 50.00 } ], "troco": 7.50 }},"itens": [{"cfop": "5102", "codigo": "PF-FRANGO", "descricao": "PRATO FEITO FRANGO", "ncm": "21069090","quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 32.50,"impostos": { "icms": { "situacaoTributaria": "102" }, "pis": { "situacaoTributaria": "49" }, "cofins": { "situacaoTributaria": "49" } }},{"cfop": "5405", "codigo": "7894900011517", "descricao": "REFRIGERANTE LATA 350ML", "ncm": "22021000", "cest": "0300700","quantidade": 2, "unidadeMedida": "UN", "valorUnitario": 5.00,"impostos": { "icms": { "situacaoTributaria": "500" }, "pis": { "situacaoTributaria": "49" }, "cofins": { "situacaoTributaria": "49" } }}]}
| 字段 | 填写 |
|---|---|
id | 收银单据号。必填,即幂等键;重试同一单必须用同一个 id,助手返回原票,不会重复开票 |
ambienteEmissao | 开票环境。必填,与设备配对时的环境一致 |
pedido、itens | 订单与商品。必填,规则与开具 NFC-e相同 |
cliente | 消费者。可选,消费者不识别时不填 |
modoResposta | 响应模式。不填,本机忽略 |
SEFAZ 授权后返回 HTTP 200。前面是云端查询的全部字段(此处省略回显的 pedido 与 itens),后面是本机附加字段:
{"id": "PDV01-000130","tipo": "NFC-e","status": "Autorizada","motivoStatus": null,"ambienteEmissao": "Homologacao","dataCriacao": "2026-11-11T14:02:10Z","dataUltimaAlteracao": "2026-11-11T14:02:11Z","numero": "419","serie": "2","dataEmissao": "2026-11-11T14:02:10Z","chaveAcesso": "35261111222333000181650020000004191123456780","dataAutorizacao": "2026-11-11T14:02:11Z","protocolo": { "numero": "135261234567990" },"qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004191123456780|3|2","urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta","linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cupom?formato=HTML","linkDownloadXml": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/xml","emitidaEmContingencia": false,"alertas": [],"valorTotal": 42.50,"situacaoLocal": "Autorizada","cStat": 100,"xMotivo": "Autorizado o uso da NF-e","tentativaOnline": false}
断网开票
请求与联网开票相同。连不上平台时助手在本机签发离线应急票,返回 HTTP 200 与 ContingenciaPendente:
{"id": "PDV01-000131","tipo": "NFC-e","ambienteEmissao": "Homologacao","situacaoLocal": "ContingenciaPendente","status": "ContingenciaPendente","chaveAcesso": "35261111222333000181650020000004219123456783","serie": "2","numero": "421","dataEmissao": "2026-11-11T15:00:00Z","qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...","urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta","emitidaEmContingencia": true,"cStat": null,"xMotivo": null,"tentativaOnline": true,"linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=HTML"}
serie是本设备的设备系列,与在线票共用、号码连续,不同于云端开票接口用的主体档案系列;访问密钥第 35 位为 9。- 没有
protocolo,直接打印小票交给消费者:用小票接口取 ESC/POS 字节送打印机,小票自动带离线应急标识,份数由平台配置。 tentativaOnline为true表示先尝试过在线、结果不明,这张票用的是在线尝试那个号码的下一个号,原号码由平台核对后收口;最近一次联网刚失败过、直接离线签发时为false。- 联网后自动补传,补传规则见离线票与补传。集成商服务端先后收到
nfce.contingency_issued与nfce.authorized,见结果怎么收到;收银软件可经本地回调或查询得知结果。
查询与补传结果
用开票时的 id 查询这张票:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
补传授权后:
{"id": "PDV01-000131","tipo": "NFC-e","ambienteEmissao": "Homologacao","situacaoLocal": "Autorizada","status": "Autorizada","chaveAcesso": "35261111222333000181650020000004219123456783","serie": "2","numero": "421","dataEmissao": "2026-11-11T15:00:00Z","qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...","urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta","emitidaEmContingencia": true,"protocolo": { "numero": "135261234568001" },"cStat": 100,"xMotivo": "Autorizado o uso da NF-e","tentativaOnline": true,"transmitida": true,"cancelamentoPendente": false,"correcoes": 0,"dataUltimaAlteracao": "2026-11-11T16:20:31Z","linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=HTML","xmlAutorizadoDisponivel": true,"linkDownloadXml": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml"}
emitidaEmContingencia授权后仍为true。- 授权 XML 在补传授权后由助手自动下载;
xmlAutorizadoDisponivel为false时也可以直接调 XML 接口,助手会向平台回取,见小票与 XML 下载。
4 收结果
收银软件有两种方式拿到补传、取消等后续结果:配置本地回调由助手主动推送,或定时轮询查询。两种可以同时用。
轮询查询
不想接回调时,收银软件对状态未定的票(ContingenciaPendente、AguardandoAutorizacao、situacaoLocal 为 Rejeitada)定时调用查询,例如每分钟一次,直到状态确定;GET /openapi/local/v1/situacao 的 pendentesTransmissao 为 0 时说明离线票已全部补传。
本地回调
生成收银令牌时填了回调地址,助手就把这台助手上的票据结果推给收银软件。请求头、签名算法与载荷结构和云端 Webhook 相同,可以复用云端的验签代码,区别只在密钥:用生成令牌时显示的回调密钥 whsec_… 整串,而不是集成商的 app_secret。
事件
请求头 X-Tffiscal-Event | 触发 | nfeStatus |
|---|---|---|
nfce.contingency_issued | 本机离线签发成功 | ContingenciaPendente |
nfce.authorized | 补传授权、修正后授权,或在线未决后授权 | Autorizada |
nfce.rejected | 离线票补传被 SEFAZ 拒绝,或在线未决的票后来被 SEFAZ 拒绝 | Negada,nfeMotivoStatus 为返回码加原因 |
nfce.canceled | 取消成功,含替代取消 | Cancelada |
nfce.cancel_rejected | 取消被拒 | CancelamentoNegado |
nfce.intake_rejected | 本机独有:平台拒收这张离线票 | Recusada,nfeMotivoStatus 为平台错误码加原因;请联系平台排查 |
nfce.device.deactivated | 本机独有:设备被停用或吊销 | 载荷见载荷 |
nfce.rejected 的载荷不区分两种被拒:收到后查询这张票,按 situacaoLocal 处理。Rejeitada 为补传被拒,走同号修正;Negada 为在线被拒,不可同号修正,改正后换新 id 重开。
许可证、证书、连接状态、未用号申报等运维提醒不推送给收银软件,由桌面程序总览页展示。
请求头与验签
POST {callbackUrl}Content-Type: application/json; charset=utf-8X-Tffiscal-Event: nfce.contingency_issuedX-Tffiscal-Event-Id: 7b0c1d9e-2a52-4e0f-9a3e-5d2f1c0b8a77X-Tffiscal-Delivery-Id: 0f5f8d0c-9a4b-4b3d-8c0e-61f2b7d4a913X-Tffiscal-Timestamp: 1762786800X-Tffiscal-Signature: 9c1e…
{callbackUrl}是生成令牌时填写的回调地址。- 签名为
hex(HMAC-SHA256(回调密钥, timestamp + "." + 原始请求体)),64 位小写十六进制,对收到的原始字节计算。 - 按
X-Tffiscal-Event-Id去重:重试与重投时不变。
可用下面的固定向量自测验签:
| 输入 | 值 |
|---|---|
| 回调密钥 | whsec_testsecret |
X-Tffiscal-Timestamp | 1762790400 |
| 请求体 | {"tipo":"NFC-e","nfeId":"PDV-1"} |
| 期望签名 | 415bce74a6740037c540f3839e69a08bd3026c8337dd49c73e8a4877889de0a4 |
载荷
票据类事件与云端 NFC-e 回调字段相同、顺序相同,末尾带 dispositivoId。本机没有云端文件链接,nfeLinkDanfe 与 nfeLinkXml 恒为 null,小票用本机小票接口取:
{"tipo": "NFC-e","empresaId": "1934811222334455","nfeId": "PDV01-000131","nfeStatus": "Autorizada","nfeMotivoStatus": null,"nfeLinkDanfe": null,"nfeLinkXml": null,"nfeNumero": "421","nfeSerie": "2","nfeChaveAcesso": "35261111222333000181650020000004219123456783","nfeDataEmissao": "2026-11-11T15:00:00Z","nfeDataAutorizacao": "2026-11-11T16:20:30Z","nfeNumeroProtocolo": "135261234568001","nfeQrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...","dispositivoId": "1900000000000000001"}
设备停用事件 nfce.device.deactivated 的载荷:
{"tipo": "NFC-e","empresaId": "1934811222334455","dispositivoId": "1900000000000000001","situacao": "Desativado","motivo": "Caixa substituido","ocorridoEm": "2026-11-20T18:00:00Z"}
situacao 为 Desativado(集成商停用)、Revogado(平台吊销)、EmpresaDesativada(主体离线开票被平台停用)、AplicativoBloqueado(收银软件被平台封禁)或 VersaoBloqueada(收银程序版本被封禁或低于最低版本),见设备状态取值。
重试
- 返回任意 2xx 即送达;非 2xx、连接失败或 5 秒内未响应计为失败。
- 失败后按 10 秒、30 秒、2 分钟、10 分钟、30 分钟重试,之后每小时一次;自入队起 24 小时仍未送达即停止。
- 「收银接入」页可查看投递记录(保留 7 天)并手动重推。
- 回调失败不影响开票与补传。
5 常见操作
| 操作 | 怎么做 | 详见 |
|---|---|---|
| 处理被拒的票 | 按 situacaoLocal 区分:Rejeitada 同号修正,Negada / Recusada 换新 id 重开 | 被拒后的处理 |
| 打印小票、下载 XML | GET …/cupom?formato=…、GET …/xml、GET …/xml-cancelamento | 小票与 XML 下载 |
| 取消一张票 | POST …/cancelar,看响应头 X-Tffiscal-Cancelamento | 取消 |
| 同一笔销售开了两张票 | POST …/cancelar-substituicao,取消在线原票并指向离线替代票 | 替代取消 |
| 在收银界面显示离线、待补传 | GET /openapi/local/v1/situacao | 助手状态 |
| 处理错误 | 按 HTTP 状态与错误码处理 | 错误处理 |
被拒后的处理
被拒的票 status 都是 Negada,处理方式按 situacaoLocal 区分:
situacaoLocal | 含义 | 处理 |
|---|---|---|
Rejeitada | 离线票补传被 SEFAZ 拒绝。票已交给消费者,号码已占用 | 用同一号码修正后重传,不能另开一张,见下 |
Negada | 在线被 SEFAZ 拒绝,含在线未决后被拒。号码由平台申报作废、不再使用 | 改正请求后用新的 id 重新开票 |
Recusada | 平台拒收这张离线票。号码未生效 | 联系平台排查原因;改正后用新的 id 重新开票 |
用原 id 提交改过内容的开票请求返回 400 与 10029818。
补传被拒的查询结果示例(省略了与查询与补传结果相同的字段):
{"id": "PDV01-000131","tipo": "NFC-e","ambienteEmissao": "Homologacao","situacaoLocal": "Rejeitada","status": "Negada","chaveAcesso": "35261111222333000181650020000004219123456783","serie": "2","numero": "421","emitidaEmContingencia": true,"motivoStatus": "778 - Rejeicao: Informado NCM inexistente","cStat": 778,"xMotivo": "Rejeicao: Informado NCM inexistente","transmitida": true,"correcoes": 0}
同号修正时把完整的开票请求改好后提交,id 与原请求相同。下例中 ... 表示与原请求相同的内容,只改了商品行的 ncm:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/correcao HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{ "id": "PDV01-000131", "ambienteEmissao": "Homologacao", "pedido": { "...": "..." }, "itens": [ { "ncm": "22021000", "...": "..." } ] }
- 只能改不影响金额与税额的内容,例如商品 NCM、CFOP、消费者证件;号码、系列、访问密钥与开票时间保持不变。
- 合计或任一行税额变化返回 400 与
10029821;当前状态不是Rejeitada返回10029820。 - 成功返回 HTTP 200,结构与断网开票的响应相同,
situacaoLocal回到ContingenciaPendente,等待再次补传。
小票与 XML 下载
取小票时用 formato 选格式:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=ESCPOS_80 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
formato | 响应类型 | 用途 |
|---|---|---|
ESCPOS_80(缺省) | application/octet-stream | 80mm 热敏打印机,字节直接送打印机 |
ESCPOS_58 | application/octet-stream | 58mm 热敏打印机 |
TEXTO | text/plain; charset=utf-8 | 纯文本 |
HTML | text/html; charset=utf-8 | 屏幕预览或浏览器打印 |
PDF_80 | application/pdf | 80mm 连续纸 PDF,每联一页;存档或发给消费者 |
离线票小票的份数由平台配置,内容里已排好,原样打印即可。本机接口按缺省打印参数输出,不受桌面程序小票参数(见桌面程序的设置与维护)影响,收银软件按自己的打印机适配。
下载授权 XML:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
| 接口 | 返回 | 不可用时 |
|---|---|---|
GET …/xml | 授权 XML 原文,application/xml; charset=utf-8 | 尚未授权,或本机没有且向平台回取不到:409 与 10029841 |
GET …/xml-cancelamento | 取消 XML 原文,application/xml; charset=utf-8 | 尚未取消,或本机没有且向平台回取不到:409 与 10029843 |
- 票已授权(或已取消)但本机没有对应 XML 时,助手当场向平台回取后再返回,最长约 30 秒,调用方不要设过短的超时。
- 同时进行的回取最多 3 个,再多返回 429 与
10029918,稍后重试。
取消
提交取消理由即可:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cancelar HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{ "justificativa": "Cliente desistiu da compra no caixa" }
justificativa 必填,15 到 255 个字符。受理后返回 HTTP 200、无响应体,响应头 X-Tffiscal-Cancelamento 说明去向:
| 取值 | 含义 |
|---|---|
Solicitado | 已提交平台;结果经回调或查询获知 |
Agendado | 离线票已补传、尚未授权,取消已在平台挂起,授权那一刻由平台自动发起 |
EnfileiradoLocal | 本机排队:断网,或离线票 / 替代票尚未补传;补传后同一轮立即提交 |
取消时限与云端相同,见取消 NFC-e;当前状态不可取消返回 400 与 10029822。
替代取消
同一笔销售被开了两张票时使用:例如 PDV01-000130 在线开出,收银软件没等到结果、当成失败,断网后又为同一笔销售在本设备开出离线票 PDV01-000131,结果两张都有效。替代取消把在线开出的原票取消,并指向替代它的离线票:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cancelar-substituicao HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{"chaveAcessoSubstituta": "35261111222333000181650020000004219123456783","justificativa": "Venda registrada em contingencia off-line"}
| 字段 | 填写 |
|---|---|
nfceId(路径) | 原票单据号。要取消的那张在线开出的票 |
chaveAcessoSubstituta | 替代票访问密钥。必填,44 位,替代原票的离线票 |
justificativa | 取消理由。必填,规则与云端替代取消相同 |
前提:
- 原票是在线开出、已授权的正常票;离线票、已取消或已有挂起取消的票返回 400 与
10029822。 - 替代票是本设备、本主体开出、未被平台拒收的离线票;密钥不是 44 位、模型不是 65、校验位错误、CNPJ 与原票不同或等于原票密钥,都返回 400 与
10029845。 - 缺少
chaveAcessoSubstituta返回 400 与10029909。
受理后返回 HTTP 200、无响应体:
HTTP/1.1 200 OKX-Tffiscal-Cancelamento: EnfileiradoLocal
- 响应头取值与取消相同。替代票尚未补传或当前断网时为
EnfileiradoLocal:取消在本机排队,替代票补传成功后才提交。 - 结果经
nfce.canceled或nfce.cancel_rejected回调,或查询原票获知。时限与云端相同。
助手状态
GET /openapi/local/v1/situacao 返回令牌可访问的主体状态,可用于收银界面显示「离线中」「待补传 N 张」等提示:
{"versaoNucleo": "1.0.0","empresas": [{"empresaId": "1934811222334455","dispositivoId": "1900000000000000001","situacao": "Ativo","conectado": false,"ultimoContato": "2026-11-11T14:55:00Z","licencaExpiraEm": "2026-11-14T13:10:00Z","offlineAte": "2026-11-14T13:10:00Z","pendentesTransmissao": 3,"pendenteMaisAntigaEm": "2026-11-11T13:02:00Z","prazoTransmissaoAte": "2026-11-12T13:02:00Z","certificadoValidoAte": "2027-03-01T00:00:00Z","ultimoErro": null,"numerosNaoUtilizadosPendentes": 0,"restauradoPendenteSincronizacao": false}],"avisos": []}
| 字段 | 说明 |
|---|---|
versaoNucleo | 内核版本 |
empresaId / dispositivoId | 主体标识与设备标识 |
situacao | 设备状态。取值见设备状态取值 |
conectado | 平台连接标志。true 表示当前能连上平台 |
ultimoContato | 最近联系时间。最近一次成功连上平台的时间 |
licencaExpiraEm | 许可证到期时间 |
offlineAte | 离线截止时间。过了这个时间不能再离线开票 |
pendentesTransmissao | 待补传张数 |
pendenteMaisAntigaEm | 最早待补传时间。最早一张待补传票的开票时间 |
prazoTransmissaoAte | 补传截止时间。最早一张待补传票的补传期限;过了这个时间该设备不能继续离线开票 |
certificadoValidoAte | 证书到期时间 |
ultimoErro | 最近错误。最近一次错误说明,无错误为 null |
numerosNaoUtilizadosPendentes | 待申报未用号区间数。待向平台申报作废的未用号码区间数;大于 0 且长时间不降时联系平台核对 |
restauradoPendenteSincronizacao | 恢复待对齐标志。从备份恢复后、拿到新许可证前为 true,期间不能离线开票,联网开票先与平台同步一轮;对齐后为 false |
avisos | 运行告警。需要技术人员处理的运行环境问题,文案为葡萄牙语,没有时为空数组;桌面程序总览页顶部同样显示。例如配置了代理认证、但助手服务的启动参数不对导致代理认证可能无效,此时重新安装助手即可恢复 |
错误处理
业务错误为数组:
[{ "codigo": "10029817", "mensagem": "itens: obrigatório" },{ "codigo": "10029817", "mensagem": "pedido.pagamento: obrigatório" }]
令牌缺失(HTTP 401)时为统一响应体:
{ "success": false, "errorType": 1, "code": 10029900, "message": "Token de caixa ausente (Authorization: Bearer tfl_...)" }
| HTTP | 错误码 | 情形 | 处理 |
|---|---|---|---|
| 401 | 10029900 / 10029901 | 缺少令牌 / 令牌无效或已吊销 | 检查 Authorization 头;令牌被吊销时让店长重新生成 |
| 403 | 10029902 | 令牌无权访问该主体 | 店长在「收银接入」重新生成包含该主体的令牌 |
| 403 | 10029903 | 来源地址不在局域网允许网段 | 检查局域网模式设置 |
| 404 | 10029801 | 该主体未在本助手配对 | 核对 empresaId,或在安装向导添加主体 |
| 404 | 10029819 | 本机没有这张票 | 核对 nfceId |
| 400 | 10029817 | 请求校验失败,每个字段一条,含缺必填字段与契约里没有的字段(不会静默忽略) | 按 mensagem 修正 |
| 400 | 10029780 | 商品行引用了税种,但连不上平台展开;未占用票号 | 恢复网络后重发;断网时商品行改传 impostos |
| 400 | 10029909 | 请求不合法,例如替代取消缺少替代票密钥 | 按 mensagem 修正 |
| 400 | 10029818 | 同一 id 已用于内容不同的票 | 新单用新 id;重试用原请求;被拒后的处理见被拒后的处理 |
| 400 | 10029820 / 10029821 | 当前状态不可修正 / 修正改变了金额或税额 | 只有 Rejeitada 可修正,且只改非金额内容 |
| 400 | 10029822 | 当前状态不可取消(含本机尚未同步、平台判定不可取消的情形);替代取消时原票不是在线开出的正常票 | 不要重试 |
| 400 | 10029845 | 替代票密钥不合法,或不是本设备本主体未被拒收的离线票 | 核对替代票密钥 |
| 400 | 10029804 / 10029807 | 断网且许可证过期 / 离线截止已过 | 恢复网络,续签后自动恢复 |
| 400 | 10029808 | 本设备系列号码已用到 999999999 | 停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列 |
| 400 | 10029810 | 最早待补传票已超补传时限 | 恢复网络补传 |
| 400 | 10029811 | 主体或州不允许离线 | 只能联网开票 |
| 400 | 10029816 | 设备已被停用 | 联系集成商 |
| 400 | 10029424 | 平台返回号码已被占用,内核弃号重试一次仍冲突 | 导出诊断包联系平台排查 |
| 400 | 10029426 | 同一 id 在平台已有未被拒绝的票,例如已由云端接口开出 | 核对原票;新的销售用新 id |
| 409 | 10029841 | 授权 XML 不可用 | 等授权后再取;回取不到时稍后重试 |
| 409 | 10029843 | 取消 XML 不可用 | 等取消成功后再取;回取不到时稍后重试 |
| 429 | 10029918 | XML 回取并发已满 | 稍后重试 |
| 500 | 10029912 / 10029836 | 助手或内核内部错误 | 在「关于与诊断」导出诊断包,联系技术支持 |
| 503 | 10029842 | 降级保护:数据目录被更新版本用过 | 安装不低于提示版本的安装包,不要删除数据目录,见降级保护 |
完整错误码见错误码。平台与 SEFAZ 侧的错误码原样透传。
6 上线检查
安装与配对:
- 配对码的
formaPermitida为Assistente或Qualquer;配对码 72 小时有效且只能用一次。 - 所选证书的 CNPJ 与主体一致;证书存储里的证书已授权后台服务账户使用私钥。
- 店长 PIN 已设置并由店长保管;多人共用的电脑建议在「设置」打开「开票需要 PIN」。
收银软件对接:
- 每台收银台各有一个收银令牌,令牌与回调密钥在生成时已妥善保存(只显示一次)。
- 接口地址为
http://127.0.0.1:8765,局域网模式下为助手电脑的局域网地址;每个请求带Authorization: Bearer tfl_…。 - 每一单用唯一的
id,重试同一单用同一个id;ambienteEmissao与设备配对时的环境一致。 - 能处理 HTTP 202 与
AguardandoAutorizacao、ContingenciaPendente,以及按situacaoLocal区分的三种被拒,见被拒后的处理。 - 离线票返回后直接打印小票交给消费者,小票原样打印。
- XML 下载的超时不短于约 30 秒;收到 429 与
10029918时稍后重试。
收结果:
- 用本地回调时:用回调密钥
whsec_…验签、按X-Tffiscal-Event-Id去重、5 秒内返回 2xx。 - 不用回调时:对状态未定的票定时查询,直到状态确定。
- 收银界面可调
GET /openapi/local/v1/situacao显示待补传张数,关注prazoTransmissaoAte与avisos。
运行环境:
- 门店经代理上网时已在「设置」配置出站代理。
- 局域网模式下已由管理员运行防火墙放行脚本。
- 店长知道数据目录
%ProgramData%\TFFiscal\Assistente\里有未补传离线票的法律原件,不得删除、不得拷到别的电脑;需要时用「导出待补传包」与「备份」。
7 部署与运维
批量部署
多台电脑可用 MSI 静默安装并同时配对,配对失败则安装回滚。PFX 密码与店长 PIN 不写在命令行里(同机任何用户都能从进程列表看到命令行),而是先放进一个秘密文件。
第一步,管理员在提升权限的 PowerShell 中生成秘密文件。脚本以安全输入方式询问 PIN 与 PFX 密码;证书改用证书存储中的已有证书时加 -SemPfx,只询问 PIN:
& "C:\Program Files\TFFiscal\Assistente\scripts\preparar-segredos.ps1"
- 秘密文件固定生成在受保护目录
%ProgramData%\TFFiscal\deploy下,缺省文件名segredos.json,即C:\ProgramData\TFFiscal\deploy\segredos.json;要换文件名用-Nome。 - 脚本先建立或收紧这个目录,只允许 SYSTEM 与 Administrators 访问,再直接以受限权限创建文件。文件内容是 UTF-8 的 JSON
{"pin":"…","pfxSenha":"…"}。 - 配对时校验秘密文件与所在目录的所有者和访问权限,不合格即失败:秘密文件必须留在这个目录里,拷到别的目录(例如
C:\deploy)会被拒绝。 - 秘密文件读完立即覆盖并删除,无论配对成败,所以每次重跑安装都要重新生成。
第二步,静默安装:
msiexec /i TfFiscalAssistente-{versao}-x64.msi /qn /l*v instalar.log ^TFA_FILE="C:\deploy\loja.tfa" PFX_FILE="C:\deploy\certificado.pfx" SECRETS_FILE="C:\ProgramData\TFFiscal\deploy\segredos.json"
| 属性 | 必填 | 说明 |
|---|---|---|
TFA_FILE | 配对时必填 | 配对码文件路径。不传即普通安装,店长之后走安装向导 |
PFX_FILE | 与下一行二选一 | PFX 证书文件路径。密码取自秘密文件的 pfxSenha |
CERT_THUMBPRINT | 与上一行二选一 | 已有证书的指纹。可再传 CERT_STORE,缺省 LOCAL_MACHINE;须先运行私钥授权脚本 |
SECRETS_FILE | 配对时必填 | 秘密文件路径。须在 %ProgramData%\TFFiscal\deploy 下;内含 pin(6 到 8 位数字),用 PFX 时另含 pfxSenha |
- 旧属性
PFX_PASSWORD与ADMIN_PIN已不再支持,传了即安装失败。 - 静默安装要求电脑已有 WebView2 运行时。
- 因连不上平台而配对失败时,用同一组参数(重新生成秘密文件)再执行一次安装即可,不要换配对码。
静默配对按这台电脑是否已完成安装分两种情形,MSI 静默安装与下面的配对命令都适用:
| 情形 | 何时出现 | 配对的做法 | 秘密文件里的 pin |
|---|---|---|---|
| 首次安装 | 这台电脑还没有完成过安装 | 直接配对,pin 即设为店长 PIN | 新的店长 PIN,6 到 8 位数字 |
| 已安装后添加公司 | 已完成安装后再执行:卸载后重装(数据目录保留)、新版本覆盖安装,或在已安装的电脑上执行配对命令 | 先用 pin 登录店长会话,再配对,即添加一家公司;已配对的公司不受影响 | 必须是现有店长 PIN;不对时退出码为 1,店长 PIN 不变 |
两种情形下,用 PFX 证书时秘密文件都要含 pfxSenha。同一版本 MSI 的「修复」或「更改」不会触发静默配对;要在已安装的电脑上添加公司,直接用下面的配对命令。
已装好助手的电脑也可以由管理员直接执行配对命令(服务须在运行):
"C:\Program Files\TFFiscal\Assistente\runtime\bin\java.exe" -cp "C:\Program Files\TFFiscal\Assistente\app\*" ^com.tffiscal.nfce.assistant.AssistantMain ativar --arquivo C:\deploy\loja.tfa --pfx C:\deploy\certificado.pfx --segredos C:\ProgramData\TFFiscal\deploy\segredos.json
- 用证书存储中的证书时把
--pfx换成--thumbprint {thumbprint},可加--store LOCAL_MACHINE或--store CURRENT_USER。 --segredos -表示从标准输入读取秘密 JSON,不落盘。- 在已完成安装的电脑上执行即添加公司,秘密文件里的
pin须是现有店长 PIN;也可以在桌面程序里走安装向导添加。
| 退出码 | 含义 | 部署脚本的处理 |
|---|---|---|
0 | 配对成功 | 无 |
1 | 配对被拒 | 按标准输出中的错误码处理 |
2 | 参数错误、秘密文件不合格或服务不可达 | 修正参数与秘密文件后重跑 |
3 | 可用同一配对码重试 | 原样重跑同一条命令,不要换配对码 |
升级、卸载与数据目录
- 升级:用新版安装包覆盖安装,本地数据自动保留。
- 数据目录:
%ProgramData%\TFFiscal\Assistente\。补传前,离线票的已签名文件只存在这里,是唯一的法律原件;卸载时数据目录保留,不要手工删除,也不要拷到别的电脑使用。 - 证书到期续期后,在「设置」用店长 PIN「更换证书」,设备身份不变。
- 平台要求的最低版本高于本机版本时,总览页提示升级;升级前设备状态为
VersaoBloqueada,不能开新票。
降级保护
数据目录被更新版本的助手用过之后,再装回旧版本,旧版本不会启动开票内核,以免损坏本地数据。此时助手进入启动失败模式:
- 后台服务不退出,只监听本机回环地址,重启电脑或服务都不会恢复。
- 桌面界面显示阻断页,写明需要安装的最低版本与当前版本。
- 本机接口全部返回 HTTP 503:
[ { "codigo": "10029842", "mensagem": "… Instale o Assistente Fiscal na versão 1.4.0 ou superior …" } ]
处理:安装不低于提示版本的安装包。绝不要删除数据目录,里面可能有尚未补传的离线票。
局域网模式
一台助手服务同店多台收银机时,店长在「设置」开启局域网模式:
- 开启后助手监听本机全部网卡,只接受「允许网段」内的来源(缺省为本机所在的 /24 网段),网段外返回 403 与
10029903。 - 安装程序不会自动放行防火墙:需由管理员运行安装目录下的
scripts\abrir-firewall-rede-local.ps1 -RedesPermitidas {redesPermitidas},{redesPermitidas}为允许网段,例如192.168.0.0/24。 - 无论是否开启,每个请求都要带收银令牌。
- 局域网模式关闭时,回调地址只能是本机回环地址;开启后才能填局域网地址。
一店多收银台部署
一个门店有多台收银台时,全店只装一个发票助手,装在后台电脑或其中一台收银台上,其他收银台通过局域网调它:
- 安装并配对一个助手:按安装与配对完成安装向导,整店只用一个配对码、占一个设备名额。
- 打开局域网模式:店长在助手电脑的「设置」里打开。缺省关闭,此时助手只监听本机,局域网里的其他电脑连不上;打开后监听全部网卡,只接受允许网段内的来源,缺省为助手电脑所在的 /24 网段。防火墙放行与网段设置见局域网模式。
- 每台收银台一个收银令牌:店长在「收银接入」为每台收银台各生成一个令牌(
tfl_开头),名称写收银台编号,例如PDV 01、PDV 02;这个名称就是该收银台开出的票上的收银台标识terminal,出现在本机接口响应、云端查询与 Webhook 里。要收回调的,回调地址填那台收银台自己的局域网地址。一台收银台丢失或停用时只吊销它的令牌,其他收银台不受影响。 - 收银软件改用助手的局域网地址:把接口地址从
http://127.0.0.1:8765改为助手电脑的局域网地址,例如http://192.168.0.10:8765,请求头带本机的收银令牌。接口与写法和单机部署完全相同,见接口清单。
部署后的效果:
- 全店共用这一台设备的设备系列,各收银台开出的票号码连续,由助手按顺序取号,不会撞号。
- 外网断了但局域网还通时,各收银台照常开票:助手离线签发,联网后自动补传。
- 桌面程序(店长 PIN、简易开票、导出与备份等)只能在助手电脑本机打开,其他收银台只用本机接口。
注意事项:
- 助手电脑是单点:它关机、断电或离开局域网时,全店都开不了票,已开的离线票也要等它恢复才能补传。助手电脑应稳定运行、不关机,建议接 UPS。
- 局域网必须通:收银台与助手电脑之间的网络或交换机故障时,收银台连不上助手,也就开不了票。
- 备用方案:另找一台电脑再装一个助手,用新的配对码配对。它是另一台设备,有自己的设备系列与号码,也要有自己的收银令牌。主机故障时,收银软件切到备机的地址与令牌继续开票;主机上已开出的票仍在主机上查询与补传,主机修不好时按桌面程序的设置与维护中的「导出与备份」导出待补传包交平台。
与内置 SDK 的区别:用内置 SDK 时缺省每台收银台各自配对为一台设备、各有一个设备系列,各系列内号码连续,彼此独立。法规只要求同一系列内的号码连续,所以一店多系列同样合规。SDK 方式没有单点,但每台收银台都要装证书、占一个设备名额。SDK 也可以用主从模式让全店共用一个系列,见多收银台(主从模式)。
桌面程序的设置与维护
以下功能都在助手电脑本机的桌面程序里操作。
票据详情
票据详情页显示票面、二维码与状态时间线(离线签发、补传、授权或被拒、修正),并提供:
- 「下载 XML」(授权 XML)与「取消 XML」。本机没有时助手向平台回取,最长约 30 秒,请等待加载完成,不要重复点击。
- 「PDF 小票」与二维码「下载图片」。
- 替代取消:原票为在线开出、已授权的正常票时显示,需店长 PIN;从当日离线票中选择替代票,规则同替代取消。
出站代理
门店网络必须经代理上网时,店长在「设置」的出站代理中配置,助手连接平台与 SEFAZ 都走这里:
| 项 | 说明 |
|---|---|
| 联网方式 | 直连(缺省)、手工代理、系统代理。系统代理沿用 Windows 的系统代理设置;不支持 PAC 自动配置脚本,遇到时直连 |
| 代理地址 | 代理服务器地址。格式 主机:端口,手工模式必填,缺端口时取 8080 |
| 认证用户 | 代理认证用户。留空即不认证,同时清除已保存的口令 |
| 认证口令 | 代理认证口令。只写不读:保存后不再显示,留空表示不修改;加密保存,不进日志与诊断包 |
| 不走代理的主机 | 绕过代理的主机。用 ; 分隔,支持 *.域名 与 <local> |
- 保存后助手按新代理重启开票内核才生效,约需数秒,期间到达的开票请求排队等待、不会丢失;新代理下内核起不来时自动退回原设置。
- 改了模式、地址或用户名时必须重新输入口令。
- 设置不合法时界面提示并显示错误码
10029919,设置不变。 - 有导出、备份或 XML 下载在进行、15 秒内等不到结束时提示错误码
10029920,设置不变,等这些操作结束后再保存。
小票参数
「设置」的小票参数只作用于助手自己打印的小票(简易开票、补打、详情页预览),不影响收银软件经本机接口取到的小票:
| 项 | 取值 |
|---|---|
| 每行列数 | 48、42、32,或按纸宽缺省 |
| 打印机代码页 | CP1252(缺省)、CP860、CP850、CP437;代码页里没有的字符先去掉重音再打印 |
| 二维码打印方式 | 打印机原生指令:用打印机自带的二维码指令(缺省);图片:以位图打印,老打印机不认二维码指令时选它 |
| 打印后切纸 | 打印后是否切纸 |
| 联数 | 每次打印的份数,或按州规则;离线票按平台配置的份数 |
导出与备份
「关于与诊断」页提供三项下载与从备份恢复,都需要店长 PIN,下载的文件保存到店长选择的本机位置。同时只能进行一项导出或备份,另一项进行中时界面提示稍后再试(错误码 10029918)。助手数据目录所在磁盘剩余空间不足 256 MB 时,导出、备份与上传备份文件都会被拒(错误码 10029922),先清理磁盘再操作。
| 功能 | 内容 | 用途 |
|---|---|---|
| 导出 XML | 选主体与开票日期区间(最长 31 天),得到 zip:授权 XML、取消 XML,以及列出取不到的票与原因的清单;可勾选「只导本机」,只导本机已有的 XML,不联网回取 | 每月交给会计 |
| 导出待补传包 | 全部主体已签名、尚未补传的离线票,zip 格式;包内按设备分目录、每包至多 500 张,平台可直接导入 | 电脑损坏、来不及补传时交平台代为补传 |
| 备份 | 开票内核本地库的加密完整副本,需店长设置至少 8 位的备份口令(输入两次) | 同一台电脑的数据恢复 |
| 从备份恢复 | 选备份文件上传(最大 4 GB),再输入备份口令,用备份替换当前本地库 | 本地库丢失或损坏后恢复 |
导出:
- 导出 XML 时本机没有的 XML 会逐张向平台回取,数量大时要几分钟,请等待完成;连不上平台时其余票不再等待,直接列入取不到的清单。
- 待补传包里是已签名的法律原件,请妥善保管;导出不影响本机继续补传。
备份:
- 备份口令不保存在任何地方,口令丢失后备份无法恢复,请与备份文件分开保管。备份期间可以照常开票。
- 备份只能在同一台电脑上恢复(设备密钥与本机绑定);换电脑必须重新配对,未补传的票用「导出待补传包」处理。
从备份恢复:
- 从备份恢复需店长 PIN。恢复会替换当前本地库,原库自动另存在数据目录里;口令错误或备份文件被改动、损坏时提示错误码
10029846,原库保持不变、助手照常运行。上传的备份文件无论恢复成败都会删除,再试一次要重新选择文件。 - 恢复期间助手重启开票内核,约需数秒,期间到达的开票请求排队等待。还有导出、备份或 XML 下载在进行时,助手最多等 15 秒,仍未结束则不恢复并提示错误码
10029920,等这些操作结束后再点恢复。 - 备份之后开出的离线票不在备份里:恢复前如果助手还能正常运行,先导出待补传包交平台。
- 恢复后各主体先与平台对齐:对齐前不能离线开票,联网开票会先同步一轮再取号;拿到新的许可证后,设备系列号码向后跳过 50 个号并自动申报作废,在线与离线开票随即照常,避免与备份之后已开出的票重号。对齐前连不上平台就开不了票。
8 没有收银系统:简易开票
没有收银系统的小店可以直接用桌面程序的「开票」页:
- 用扫码枪扫商品条码,或按编码、名称搜索「常用商品」;也可用「快速商品」只填描述和金额,税务信息取设置里的缺省税组。
- 购物清单可改数量、行折扣、删除,合计实时计算。
- 付款支持现金(自动算找零)、借记卡、信用卡、PIX 与其他方式;金额超过本州识别门槛时必须填写消费者 CPF 或 CNPJ。
- 确认开票后显示结果(已授权或离线待补传)并自动打印,离线票的打印份数由平台配置。
- 快捷键:
F2新单、F4进入收款、F8开票并打印、Esc返回 / 取消本单,整页可以只用键盘操作。
「常用商品」页维护商品编码、名称、条码、NCM、CFOP、单位、单价与税组,商品税务信息与开票请求的 itens[].impostos 结构相同。
开票页缺省为收银员模式,不要求 PIN;可在「设置」打开「开票需要 PIN」,改为必须输入店长 PIN。关闭时同一台电脑上的任何人都能开票、看当日票据,多人共用的电脑建议打开。
简易开票的单据号与收银软件开的票一起显示在「当日票据」里:
- 开票页为每一单生成
PDV-{yyyyMMdd}-{8 位字母数字}格式的单据号,重试同一单沿用原单据号,助手返回原票、不会重复开票。 - 请求不带单据号时,由助手按
PDV-{yyyyMMdd}-{序号}生成,并自动跳过已被占用的单据号。
开票被拒时点「返回改单」,按被拒类型分两条路:
- 补传被拒(
Rejeitada):号码已占用,走同号修正,需店长 PIN。 - 在线被拒或平台拒收(
Negada/Recusada):号码未生效,改好后作为新单重开,换新的单据号。
「当日票据」页可按日期与状态筛选,对每张票「查看」「打印」「作废」「修正」(修正仅限补传被拒时);点开进入票据详情,见桌面程序的设置与维护。
常见问题
安装向导提示配对码无效或已过期?
配对码 72 小时有效且只能用一次。已过期、已使用或已作废的配对码都不能再用,请集成商重新生成配对码。
配对时提示证书 CNPJ 与主体不符?
所选证书的 CNPJ 必须与主体一致。一台电脑服务多个 CNPJ 时,请为每个主体分别生成配对码,在安装向导里各选对应证书。
收银软件调本机接口返回 401?
请求头要写成 Authorization: Bearer tfl_…。令牌只显示一次,丢失或被吊销后由店长在「收银接入」重新生成。
断网时提示许可证过期?
离线开票有时长上限,联网后自动续签。断网时间过长会触发,恢复网络即可。
离线票一直没有补传?
补传需要助手服务在运行且能连上平台。在总览页看连接状态与「最早一张待补传」时间;门店经代理上网时检查出站代理设置(见桌面程序的设置与维护);也可以在收银软件里调一次查询,或在桌面程序点「立即同步」。
更换门店电脑怎么办?
先让旧电脑联网把离线票补传完(总览页待补传为 0),再由集成商停用旧设备,为新电脑生成新配对码。不要把数据目录拷到新电脑:设备密钥与本机绑定,拷过去无法使用。
旧电脑坏了、来不及补传时:只要助手还能打开,就在「关于与诊断」导出待补传包(见桌面程序的设置与维护),把得到的 zip 文件原样(无需解压)交给平台运营,由平台代为导入补传;包内已按设备分目录、每包至多 500 张,不用再拆分,旧设备停用后仍可导入。
PIN 输错被锁?
每累计输错 5 次锁定一次:第一次锁 5 分钟,之后每次锁定时长加倍,最长 24 小时。锁定期间正确的 PIN 也会被拒绝;锁定结束后错误次数不清零,只有输对一次才清零。
联系技术支持要提供什么?
在「关于与诊断」导出诊断包。诊断包含状态与日志,不含私钥、令牌、回调密钥与 PIN。
设备状态取值
situacao | 含义 | 处理 |
|---|---|---|
Ativo | 可以开票 | 无 |
Desativado | 集成商已停用设备 | 不可恢复;同一电脑要继续用须重新配对 |
Revogado | 平台已吊销设备 | 联系平台 |
EmpresaDesativada | 该主体的离线开票被停用 | 联系平台 |
AplicativoBloqueado | 收银软件被平台封禁 | 联系平台 |
VersaoBloqueada | 收银程序版本被封禁或低于最低版本 | 升级发票助手 |
除 Ativo 外都不能开新票,已开出的离线票照常补传。
单据状态取值
本机接口响应里的 situacaoLocal 与 status。status 与云端取值一致,situacaoLocal 保留本机的完整状态。
situacaoLocal | status | 含义 | 出现在 |
|---|---|---|---|
Autorizada | Autorizada | SEFAZ 已授权,在线授权或离线票补传后授权 | 开票、查询 |
ContingenciaPendente | ContingenciaPendente | 本机离线签发,待补传 | 开票、查询、修正 |
AguardandoAutorizacao | AguardandoAutorizacao | 在线已受理、SEFAZ 尚未返回,且当时不能离线签发;开票返回 HTTP 202 | 开票、查询 |
Negada | Negada | 在线开票被 SEFAZ 拒绝,含在线未决后被拒;不可同号修正 | 开票、查询 |
Rejeitada | Negada | 离线票补传被 SEFAZ 拒绝;用同一号码修正,见被拒后的处理 | 查询、修正 |
Recusada | Negada | 平台拒收这张离线票;需人工介入 | 查询 |
Cancelada | Cancelada | 已取消,含替代取消 | 查询 |
