Emitindo uma NFe

Este guia vai te ajudar a emitir a sua primeira Nota Fiscal (NF-e, modelo 55) usando a nossa API.

1. Obtendo suas credenciais

Para se comunicar com a API, você precisa de duas credenciais — veja os detalhes em Autenticação:

1. Faça login no Painel do Desenvolvedor e copie sua Chave de Acesso (nfe_access_...), em “Suas Chaves de Acesso” — ela identifica a sua conta e vai em todo request, no header X-Access-Key.
2. Cadastre uma empresa — é lá que fica o certificado digital e a configuração fiscal (UF, ambiente).
3. Gere uma chave de API para essa empresa. Ela começa com nfe_test_... (homologação) ou nfe_live_... (produção), e vai no header Authorization: Bearer.

2. Instalando o SDK

Node.js

npm install @tenzanlabs/nfe-node-sdk

Python

pip install tenzan-nfe-python-sdk

Java

<dependency>
    <groupId>io.github.tenzan-labs</groupId>
    <artifactId>nfe-java-sdk</artifactId>
    <version>2.0.0</version>
</dependency>

3. Disparando a Nota

O corpo de emit é o documento fiscal em si — os nomes de campo são os mesmos em todas as linguagens e na REST API (nada de camelCase traduzido pelo SDK). O campo mod ("55") indica que é uma NF-e.

Campos obrigatórios pouco óbvios

Além dos campos de identificação do documento, o schema hoje também exige modalidade_frete, veiculo_placa e agropecuario_tipo_guia mesmo quando a operação não envolve transporte de carga própria ou produto agropecuário — nesses casos, envie modalidade_frete: "9" (sem frete) e os outros dois como string vazia.

Node.js

import { NFeClient } from '@tenzanlabs/nfe-node-sdk';

const client = new NFeClient('nfe_access_SUA_CHAVE_DE_ACESSO_AQUI', 'nfe_test_SUA_CHAVE_AQUI');

async function run() {
  try {
    const resposta = await client.emit({
      mod: '55',
      natureza_operacao: 'Venda de Mercadoria',
      data_emissao: new Date().toISOString(),
      tipo_documento: '1',
      local_destino: '1',
      finalidade_emissao: '1',
      consumidor_final: '1',
      presenca_comprador: '1',
      modalidade_frete: '9',
      veiculo_placa: '',
      agropecuario_tipo_guia: '',
      cnpj_emitente: '12345678000199',
      inscricao_estadual_emitente: '123456789',
      nome_destinatario: 'João da Silva',
      cpf_destinatario: '11122233344',
      itens: [
        {
          codigo_produto: '123',
          descricao: 'Caneta Azul',
          codigo_ncm: '96081000',
          cfop: '5102',
          unidade_comercial: 'UN',
          quantidade_comercial: 10,
          valor_unitario_comercial: 2.5,
          icms_origem: '0',
          icms_situacao_tributaria: '102',
          pis_situacao_tributaria: '07',
          cofins_situacao_tributaria: '07',
        },
      ],
    });
    console.log('Sucesso! invoiceId:', resposta.invoiceId);
  } catch (error) {
    console.error('Erro:', error.message);
  }
}
run();

Python

from datetime import datetime, timezone
from nfe_sdk import NFeClient

client = NFeClient(access_key='nfe_access_SUA_CHAVE_DE_ACESSO_AQUI', api_key='nfe_test_SUA_CHAVE_AQUI')

try:
    resposta = client.emit({
        "mod": "55",
        "natureza_operacao": "Venda de Mercadoria",
        "data_emissao": datetime.now(timezone.utc).isoformat(),
        "tipo_documento": "1",
        "local_destino": "1",
        "finalidade_emissao": "1",
        "consumidor_final": "1",
        "presenca_comprador": "1",
        "modalidade_frete": "9",
        "veiculo_placa": "",
        "agropecuario_tipo_guia": "",
        "cnpj_emitente": "12345678000199",
        "inscricao_estadual_emitente": "123456789",
        "nome_destinatario": "João da Silva",
        "cpf_destinatario": "11122233344",
        "itens": [
            {
                "codigo_produto": "123",
                "descricao": "Caneta Azul",
                "codigo_ncm": "96081000",
                "cfop": "5102",
                "unidade_comercial": "UN",
                "quantidade_comercial": 10,
                "valor_unitario_comercial": 2.50,
                "icms_origem": "0",
                "icms_situacao_tributaria": "102",
                "pis_situacao_tributaria": "07",
                "cofins_situacao_tributaria": "07",
            }
        ],
    })
    print("Sucesso! invoiceId:", resposta["invoiceId"])
except Exception as e:
    print("Erro:", e)

Java

import br.com.saascore.nfe.NFeClient;
import br.com.saascore.nfe.model.NfeData;
import java.util.*;

public class Main {
    public static void main(String[] args) {
        NFeClient client = new NFeClient("nfe_access_SUA_CHAVE_DE_ACESSO_AQUI", "nfe_test_SUA_CHAVE_AQUI");

        NfeData nota = new NfeData();
        nota.mod = "55";
        nota.natureza_operacao = "Venda de Mercadoria";
        nota.data_emissao = java.time.Instant.now().toString();
        nota.tipo_documento = "1";
        nota.local_destino = "1";
        nota.finalidade_emissao = "1";
        nota.consumidor_final = "1";
        nota.presenca_comprador = "1";
        nota.modalidade_frete = "9";
        nota.veiculo_placa = "";
        nota.agropecuario_tipo_guia = "";
        nota.cnpj_emitente = "12345678000199";
        nota.inscricao_estadual_emitente = "123456789";
        nota.nome_destinatario = "João da Silva";
        nota.cpf_destinatario = "11122233344";

        NfeData.NfeDataItens item = new NfeData.NfeDataItens();
        item.codigo_produto = "123";
        item.descricao = "Caneta Azul";
        item.codigo_ncm = "96081000";
        item.cfop = "5102";
        item.unidade_comercial = "UN";
        item.quantidade_comercial = 10;
        item.valor_unitario_comercial = 2.50;
        item.icms_origem = "0";
        item.icms_situacao_tributaria = "102";
        item.pis_situacao_tributaria = "07";
        item.cofins_situacao_tributaria = "07";
        nota.itens = List.of(item);

        try {
            var resposta = client.emit(nota);
            System.out.println("Sucesso! invoiceId: " + resposta.invoiceId);
        } catch (Exception e) {
            System.out.println("Erro: " + e.getMessage());
        }
    }
}

cURL (REST)

curl -X POST https://app.nfe.tenzanlabs.com/v1/nfe/emit \
  -H "X-Access-Key: nfe_access_SUA_CHAVE_DE_ACESSO_AQUI" \
  -H "Authorization: Bearer nfe_test_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "mod": "55",
    "natureza_operacao": "Venda de Mercadoria",
    "data_emissao": "2026-08-19T12:00:00-03:00",
    "tipo_documento": "1",
    "local_destino": "1",
    "finalidade_emissao": "1",
    "consumidor_final": "1",
    "presenca_comprador": "1",
    "modalidade_frete": "9",
    "veiculo_placa": "",
    "agropecuario_tipo_guia": "",
    "cnpj_emitente": "12345678000199",
    "inscricao_estadual_emitente": "123456789",
    "nome_destinatario": "João da Silva",
    "cpf_destinatario": "11122233344",
    "itens": [
      {
        "codigo_produto": "123",
        "descricao": "Caneta Azul",
        "codigo_ncm": "96081000",
        "cfop": "5102",
        "unidade_comercial": "UN",
        "quantidade_comercial": 10,
        "valor_unitario_comercial": 2.50,
        "icms_origem": "0",
        "icms_situacao_tributaria": "102",
        "pis_situacao_tributaria": "07",
        "cofins_situacao_tributaria": "07"
      }
    ]
  }'

4. Acompanhando o resultado

emit é assíncrono — a resposta acima (202) só confirma que o documento entrou na fila, com { message, invoiceId, accessKey }. Para saber se ele foi autorizado, consulte o invoiceId (veja Consultar documento) até o status deixar de ser PENDENTE.

Próximo passo: cancelamento, correção e demais operações.