TF Fiscal
Documentação

NFC-e offline

Gerar código de pareamento

Gera o código de uso único com que um caixa é pareado; a primeira chamada habilita a emissão offline da empresa.

POST/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao
Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Um código por caixa. O código já leva o endereço da plataforma, a empresa e o ambiente; na loja basta informá-lo junto com o certificado A1. A empresa precisa estar ativa e com NFC-e habilitada no ambiente (bloco emissaoNFeConsumidor do registro); em Producao precisa também de certificado A1 válido. Não há limite de dispositivos por empresa: enquanto houver série disponível, é possível adicionar mais caixas. Cada dispositivo tem uma série NFC-e só sua, usada online e offline com numeração contínua; serie e numeroInicial fixam essa série e o primeiro número, e omitidos a plataforma atribui a série e começa em 1. A NFC-e emitida pela API em nuvem continua usando a série do perfil da empresa.

Parâmetros de caminho

empresaId*
stringIdentificador da empresa

* Campo obrigatório

Corpo da requisição

nomeDispositivo
stringNome do dispositivo
ambiente
stringAmbiente de emissão
formaPermitida
stringForma permitida
serie
intSérie do dispositivo
numeroInicial
intNúmero inicial

* Campo obrigatório

200
Código gerado. Entregue codigoAtivacao à loja.
success
boolResultado da chamada
message
stringTexto do resultado
objectCódigo de pareamento gerado

Erros de negócio voltam com HTTP 200 e success = false; recurso inexistente volta com HTTP 404 e validação de campo com HTTP 400. Trate sempre pelo code.

Entregue o código à loja como texto ou como arquivo .tfa: o arquivo é o próprio texto do código, em UTF-8 e numa só linha. O código vale uma vez e expira em 72 horas; perdido, gere outro. Uma empresa aceita no máximo 20 códigos pendentes (não usados e não vencidos).

Primeiro código, sem corpo

Corpo vazio {} (ou sem corpo): nome padrão, ambiente atual da empresa e qualquer forma. A primeira chamada habilita a emissão offline da empresa; não há etapa separada. nomeDispositivo, ambiente e formaPermitida não enviados.

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
}
}

Caixa com SDK, com nome

Código só para o PDV com SDK embarcado. nomeDispositivo e formaPermitida = Sdk opcionais e enviados; ambiente não enviado, vale o ambiente atual da empresa. A requisição é o exemplo do topo da página.

nomeDispositivo
stringNome do dispositivo
formaPermitida
stringForma permitida

* Campo obrigatório

Resposta: código para o SDK

Guarde ou entregue codigoAtivacao agora; ele não volta em nenhuma outra consulta.

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
}
}

Série e número inicial definidos

Para o caixa usar uma série combinada com a loja. serie e numeroInicial opcionais e enviados; a primeira nota do dispositivo, online ou offline, sai com o número 1 da série 21, e as seguintes seguem em sequência. A série é conferida de novo no pareamento; se nesse meio-tempo deixou de estar livre, o pareamento devolve o mesmo código de erro e é preciso gerar outro código.

json
{
"nomeDispositivo": "Caixa 03",
"serie": 21,
"numeroInicial": 1
}
serie
intSérie do dispositivo
numeroInicial
intNúmero inicial

* Campo obrigatório

Trocar o computador mantendo a série

O caixa antigo foi desativado e já transmitiu todas as notas offline (pendentesTransmissao = 0). Envie a mesma serie sem numeroInicial: a plataforma continua depois do maior número já conhecido na série e devolve o número efetivo em numeroInicial. Se o caixa antigo ainda tem notas a transmitir, a resposta é 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
}
}