TF Fiscal
开发文档

NFC-e 离线开票

生成设备配对码

生成收银机配对所用的一次性配对码;首次调用即为该主体开通离线开票。

POST/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao
需要 token、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起始号码

* 必填字段

200
生成成功。把 codigoAtivacao 交给门店。
success
bool调用结果
message
string结果说明
object新生成的配对码

业务错误返回 HTTP 200,success 为 false;资源不存在返回 HTTP 404,字段校验失败返回 HTTP 400。请一律按 code 判断。

配对码以文本或 .tfa 文件交给门店:.tfa 文件就是配对码全文,UTF-8 编码、单行。配对码一次性、72 小时有效,遗失请重新生成。一个主体同时最多 20 个待使用(未使用且未过期)的配对码。

首次生成:不带请求体

请求体为空对象 {}(或不带请求体):缺省名称、主体当前环境、不限形态。首次调用即为该主体开通离线开票,没有单独的开通步骤。nomeDispositivo、ambiente、formaPermitida 都不填。

json
{
"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,之后任何接口都查不到全文。

json
{
"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 号,之后顺序递增。配对时会再核对一次系列,期间若已被占用,配对返回同一错误码,须重新生成配对码。

json
{
"nomeDispositivo": "Caixa 03",
"serie": 21,
"numeroInicial": 1
}
serie
int设备系列
numeroInicial
int起始号码

* 必填字段

换电脑沿用原系列

旧收银机已停用,且离线票已全部补传(pendentesTransmissao 为 0)。传同一个 serie、不传 numeroInicial:平台接着该系列已知的最大号往后,并在 numeroInicial 返回实际起始号码。旧收银机还有票未补传时返回 10029225。

json
{
"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
}
}