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.
/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacaotoken, 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* | string | Identificador da empresa |
* Campo obrigatório
Corpo da requisição
nomeDispositivo | string | Nome do dispositivo |
ambiente | string | Ambiente de emissão |
formaPermitida | string | Forma permitida |
serie | int | Série do dispositivo |
numeroInicial | int | Número inicial |
* Campo obrigatório
codigoAtivacao à loja.success | bool | Resultado da chamada |
message | string | Texto do resultado |
| object | Có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.
{"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 | string | Nome do dispositivo |
formaPermitida | string | Forma permitida |
* Campo obrigatório
Resposta: código para o SDK
Guarde ou entregue codigoAtivacao agora; ele não volta em nenhuma outra consulta.
{"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.
{"nomeDispositivo": "Caixa 03","serie": 21,"numeroInicial": 1}
serie | int | Série do dispositivo |
numeroInicial | int | Nú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.
{"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}}
ambienteAmbiente
| Valores | Significado |
|---|---|
| Homologacao | Homologação: notas sem valor fiscal, para testes de integração |
| Producao | Produção: notas com valor fiscal; exige certificado A1 válido da empresa |
formaPermitidaForma permitida
Omitido vale Qualquer.
| Valores | Significado |
|---|---|
| Qualquer | Pode ser pareado pelo Assistente Fiscal ou por um PDV com SDK |
| Assistente | Só o Assistente Fiscal pareia; o PDV com SDK recebe 10029209 |
| Sdk | Só um PDV com SDK pareia; o Assistente recusa o código |
| Código | HTTP | |
|---|---|---|
| 10029100 | 404 | Empresa inexistente ou de outro integrador. |
| 10029101 | 200 | A empresa não pode emitir NFC-e: inativa, sem NFC-e no ambiente ou, em Producao, sem certificado A1 válido; message diz o motivo. |
| 10029219 | 200 | ambiente diferente do ambiente atual da empresa. |
| 10029104 | 200 | Emissão offline da empresa desativada pela plataforma; fale com a plataforma. |
| 10029201 | 200 | Já há 20 códigos pendentes nesta empresa; use-os ou espere vencerem. |
| 10029221 | 200 | serie entre 890 e 999; a NFC-e de emitente CNPJ só usa as séries 0 a 889. |
| 10029222 | 200 | serie é a série NFC-e do perfil da empresa em algum dos ambientes; escolha outra. |
| 10029223 | 200 | serie já está com outro dispositivo ativo ou com um código pendente da empresa; message diz qual. |
| 10029224 | 200 | numeroInicial não é maior que o maior número já conhecido na série; message traz esse número. |
| 10029225 | 200 | serie pertence a um dispositivo desativado ou revogado que ainda tem notas offline a transmitir; aguarde a transmissão terminar. |
| 10029001 | 200 | ambiente ou formaPermitida fora dos valores; message diz qual. |
| 10001001 | 400 | Validação de campo, inclusive serie fora de 0 a 999 ou numeroInicial fora de 1 a 999999999; message aponta o campo. |
