NFC-e 离线开票
生成设备配对码
生成收银机配对所用的一次性配对码;首次调用即为该主体开通离线开票。
/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacaotoken、timestamp、sign 三个签名头,参见认证与签名。每台收银机一个配对码。配对码自带平台地址、主体与环境,门店侧只需输入配对码并选择 A1 证书。主体须为启用状态,并已在该环境开通 NFC-e(注册开票主体时的 emissaoNFeConsumidor 段);Producao 还要求主体有有效的 A1 证书。每个主体的设备数不设上限,只要还有可用系列就能继续添加设备。每台设备独占一个 NFC-e 系列,在线与离线开票都用它、号码连续;serie 与 numeroInicial 指定这个系列与第一张票的号码,不传时平台自动分配系列、从 1 开始。云端开票接口开的 NFC-e 仍用主体档案里的系列。
路径参数
empresaId* | string | 开票主体标识 |
* 必填字段
请求体
nomeDispositivo | string | 设备名称 |
ambiente | string | 开票环境 |
formaPermitida | string | 允许形态 |
serie | int | 设备系列 |
numeroInicial | int | 起始号码 |
* 必填字段
codigoAtivacao 交给门店。success | bool | 调用结果 |
message | string | 结果说明 |
| object | 新生成的配对码 |
业务错误返回 HTTP 200,success 为 false;资源不存在返回 HTTP 404,字段校验失败返回 HTTP 400。请一律按 code 判断。
配对码以文本或 .tfa 文件交给门店:.tfa 文件就是配对码全文,UTF-8 编码、单行。配对码一次性、72 小时有效,遗失请重新生成。一个主体同时最多 20 个待使用(未使用且未过期)的配对码。
首次生成:不带请求体
请求体为空对象 {}(或不带请求体):缺省名称、主体当前环境、不限形态。首次调用即为该主体开通离线开票,没有单独的开通步骤。nomeDispositivo、ambiente、formaPermitida 都不填。
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Dispositivo 1","ambiente": "Homologacao","formaPermitida": "Qualquer","serie": null,"numeroInicial": null}}
SDK 用:带设备名称
只给内置 SDK 的收银软件用,见内置 SDK 教程。nomeDispositivo 与 formaPermitida = Sdk 为可选并填写;ambiente 不填,取主体当前环境。请求即本页顶部示例。
nomeDispositivo | string | 设备名称 |
formaPermitida | string | 允许形态 |
* 必填字段
响应:SDK 配对码
立即保存或交付 codigoAtivacao,之后任何接口都查不到全文。
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Caixa 01","ambiente": "Homologacao","formaPermitida": "Sdk","serie": null,"numeroInicial": null}}
指定设备系列与起始号码
让收银机使用与门店约定好的系列。serie 与 numeroInicial 为可选并填写;该设备第一张票不论在线还是离线,都是系列 21 的 1 号,之后顺序递增。配对时会再核对一次系列,期间若已被占用,配对返回同一错误码,须重新生成配对码。
{"nomeDispositivo": "Caixa 03","serie": 21,"numeroInicial": 1}
serie | int | 设备系列 |
numeroInicial | int | 起始号码 |
* 必填字段
换电脑沿用原系列
旧收银机已停用,且离线票已全部补传(pendentesTransmissao 为 0)。传同一个 serie、不传 numeroInicial:平台接着该系列已知的最大号往后,并在 numeroInicial 返回实际起始号码。旧收银机还有票未补传时返回 10029225。
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Caixa 01","ambiente": "Homologacao","formaPermitida": "Qualquer","serie": 2,"numeroInicial": 422}}
ambiente开票环境
| 取值 | 含义 |
|---|---|
| Homologacao | 测试环境:票据无税务效力,用于联调 |
| Producao | 生产环境:票据有税务效力;要求主体已上传有效的 A1 证书 |
formaPermitida允许形态
不传即 Qualquer。
| 取值 | 含义 |
|---|---|
| Qualquer | 发票助手或内置 SDK 的收银软件都可配对 |
| Assistente | 只有发票助手能配对,内置 SDK 的收银软件配对时得到 10029209 |
| Sdk | 只有内置 SDK 的收银软件能配对,发票助手会拒绝 |
| 错误码 | HTTP | |
|---|---|---|
| 10029100 | 404 | 主体不存在,或不属于当前集成商。 |
| 10029101 | 200 | 主体不能开 NFC-e:未启用、该环境未开通 NFC-e,或 Producao 缺少有效的 A1 证书;message 说明原因。 |
| 10029219 | 200 | ambiente 与主体当前环境不一致。 |
| 10029104 | 200 | 该主体的离线开票被平台停用,请联系平台。 |
| 10029201 | 200 | 本主体已有 20 个待使用的配对码;先用掉或等其过期。 |
| 10029221 | 200 | serie 在 890 到 999 之间;CNPJ 开票方的 NFC-e 只能用 0 到 889 号系列。 |
| 10029222 | 200 | serie 是主体档案里任一环境的 NFC-e 系列;换一个系列。 |
| 10029223 | 200 | serie 已被本主体其他在用设备或待使用的配对码占用;message 说明占用者。 |
| 10029224 | 200 | numeroInicial 不大于该系列平台已知的最大号;message 给出这个号码。 |
| 10029225 | 200 | serie 属于已停用或被吊销、但还有离线票没补传完的设备;等补传完成后再生成。 |
| 10029001 | 200 | ambiente 或 formaPermitida 不在取值内;message 说明是哪一项。 |
| 10001001 | 400 | 字段校验失败,含 serie 不在 0 到 999、numeroInicial 不在 1 到 999999999;message 点名字段。 |
