Emissão de NF-e - Treeunfe API NF-e B2C

POST /nfe emite uma NF-e modelo 55 para a empresa dona da x-api-key.

Com ou sem cálculo de tributos

Com cálculo (padrão)
Sem cálculo (calculateTaxes: false)

A Treeunfe calcula os tributos de cada item e os totalizadores — ICMS, ST, DIFAL, FCP, IPI, PIS, COFINS, IBS e CBS — pelas regras de emissão configuradas no emissor.

Use quando o seu sistema não tem motor fiscal próprio.

Estrutura do body

{
  "calculateTaxes": true,
  "NFe": {
    "infNFe": {
      "ide": { },
      "emit": { },
      "dest": { },
      "autXML": [ ],
      "det": [ ],
      "total": { },
      "transp": { },
      "pag": { },
      "infRespTec": { }
    }
  }
}

Campo	Descrição
`calculateTaxes`	`true` (padrão) para a Treeunfe calcular os tributos; `false` para enviar os tributos prontos.
`externalId`	Opcional. Identificador da nota no seu sistema.
`NFe.infNFe`	Os grupos da nota, com as mesmas tags do leiaute oficial da NF-e (MOC).

Os nomes das tags seguem o leiaute da SEFAZ. A única diferença é CNPJCPF: informe CNPJ ou CPF no mesmo campo, só com números.

Grupos principais

Grupo	Conteúdo
`ide`	Identificação: UF, série, número, datas, tipo de operação, finalidade.
`emit`	Emitente: CNPJ, razão social, endereço (`enderEmit`), IE e `CRT`.
`dest`	Destinatário: CNPJ/CPF, nome, endereço (`enderDest`), `indIEDest`, e-mail.
`autXML`	CNPJs/CPFs autorizados a baixar o XML.
`det`	Itens: `prod` (produto) e `imposto` (tributos).
`total`	Totais: `ICMSTot` e `IBSCBSTot`.
`transp`	Transporte. `modFrete: 9` = sem frete.
`pag`	Pagamento (`detPag`).
`infRespTec`	Responsável técnico.

O ambiente da nota (homologação ou produção) vem da API Key. Não informe o ambiente no payload.

ide.serie e ide.nNF são opcionais. Sem eles, a Treeunfe usa a série e a numeração das configurações de NF-e da empresa no emissor.

Payload enxuto (com cálculo)

Com calculateTaxes: true, envie só os dados comerciais. Cada item leva apenas prod (NCM, CFOP, quantidade e valor), sem o grupo imposto. Também não é preciso enviar IBSCBSTot, autXML nem infRespTec.

A Treeunfe aplica a regra fiscal que cobre o NCM do item e preenche os tributos e os totais.

{
  "calculateTaxes": true,
  "externalId": "pedido-1234",
  "NFe": {
    "infNFe": {
      "ide": {
        "cUF": 41,
        "natOp": "Venda",
        "dhEmi": "2026-11-10T10:00:00-03:00",
        "dhSaiEnt": "2026-11-10T10:00:00-03:00",
        "tpNF": 1,
        "idDest": 2,
        "cMunFG": 4115200,
        "tpImp": 1,
        "tpEmis": 1,
        "finNFe": 1,
        "indFinal": 0,
        "indPres": 1,
        "indIntermed": 0
      },
      "emit": {
        "CNPJCPF": "12345678000195",
        "xNome": "EMPRESA EXEMPLO LTDA",
        "xFant": "EMPRESA EXEMPLO",
        "enderEmit": {
          "xLgr": "Avenida Exemplo", "nro": "5145", "xBairro": "Zona 07",
          "cMun": 4115200, "xMun": "MARINGA", "UF": "PR", "CEP": "87020035",
          "cPais": 1058, "xPais": "Brasil", "fone": "44999990000"
        },
        "IE": "9071311225",
        "CRT": 3
      },
      "dest": {
        "CNPJCPF": "11222333000181",
        "xNome": "CLIENTE EXEMPLO LTDA",
        "enderDest": {
          "xLgr": "Rua 115", "nro": "942", "xBairro": "Setor Sul",
          "cMun": 5208707, "xMun": "Goiania", "UF": "GO", "CEP": "74085325",
          "cPais": 1058, "xPais": "BRASIL"
        },
        "indIEDest": 1,
        "IE": "107753936"
      },
      "det": [
        {
          "prod": {
            "cProd": "PROD-001",
            "cEAN": "SEM GTIN",
            "xProd": "PRODUTO EXEMPLO",
            "NCM": "85176241",
            "CFOP": 6102,
            "uCom": "UNID",
            "qCom": 1,
            "vUnCom": "1000.00",
            "vProd": "1000.00",
            "cEANTrib": "SEM GTIN",
            "uTrib": "UNID",
            "qTrib": 1,
            "vUnTrib": "1000.00",
            "indTot": 1
          }
        }
      ],
      "total": {
        "ICMSTot": {
          "vBC": "0.00", "vICMS": "0.00", "vICMSDeson": "0.00", "vFCP": "0.00",
          "vBCST": "0.00", "vST": "0.00", "vFCPST": "0.00", "vFCPSTRet": "0.00",
          "vProd": "1000.00", "vFrete": "0.00", "vSeg": "0.00", "vDesc": "0.00",
          "vII": "0.00", "vIPI": "0.00", "vIPIDevol": "0.00", "vPIS": "0.00",
          "vCOFINS": "0.00", "vOutro": "0.00", "vNF": "1000.00"
        }
      },
      "transp": { "modFrete": 9 },
      "pag": { "detPag": { "indPag": "0", "tPag": "90", "vPag": "0.00" } }
    }
  }
}

Antes da primeira emissão, consulte o checklist de NF-e para confirmar que a empresa tem certificado, configurações e regras fiscais prontas.

Payload com os tributos preenchidos

Se o seu sistema já calcula os tributos, envie o grupo imposto em cada item e os totais completos.

Regime tributário

O exemplo abaixo é de regime normal (emit.CRT: 3, ICMS CST 00). Para Simples Nacional, use emit.CRT: 1 e os grupos ICMSSN com CSOSN (por exemplo, ICMSSN102).

{
  "calculateTaxes": true,
  "NFe": {
    "infNFe": {
      "ide": {
        "cUF": 41, "natOp": "Venda",
        "serie": "1", "nNF": 10,
        "dhEmi": "2026-10-20T15:24:48-03:00",
        "dhSaiEnt": "2026-10-20T15:24:48-03:00",
        "tpNF": 1, "idDest": 1, "cMunFG": 4115200, "tpImp": 1,
        "tpEmis": 1, "finNFe": 1,
        "indFinal": 1, "indPres": 1, "indIntermed": 0
      },
      "emit": {
        "CNPJCPF": "12345678000195",
        "xNome": "EMPRESA EXEMPLO LTDA",
        "xFant": "EMPRESA EXEMPLO",
        "enderEmit": {
          "xLgr": "Avenida Exemplo", "nro": "5145", "xBairro": "Zona 07",
          "cMun": 4115200, "xMun": "MARINGA", "UF": "PR", "CEP": "87020035",
          "cPais": 1058, "xPais": "Brasil", "fone": "44999990000"
        },
        "IE": "9071311225",
        "CRT": 3
      },
      "dest": {
        "CNPJCPF": "12345678909",
        "xNome": "Consumidor Exemplo",
        "enderDest": {
          "xLgr": "Rua das Flores", "nro": "652", "xBairro": "Centro",
          "cMun": 4115200, "xMun": "MARINGA", "UF": "PR", "CEP": "87025500",
          "cPais": 1058, "xPais": "BRASIL", "fone": "44999991111"
        },
        "indIEDest": 9,
        "email": "consumidor@exemplo.com.br"
      },
      "autXML": [{ "CNPJ": "12345678000195" }],
      "det": [
        {
          "prod": {
            "cProd": "30880297", "cEAN": "SEM GTIN",
            "xProd": "BARRA CHATA AC 2 X 1/4 A-36",
            "NCM": "72149100", "CFOP": 5102, "uCom": "M", "qCom": 1,
            "vUnCom": "16.3100000000", "vProd": "16.31",
            "cEANTrib": "SEM GTIN", "uTrib": "M", "qTrib": 1,
            "vUnTrib": "16.3100000000", "indTot": 1
          },
          "imposto": {
            "vTotTrib": "3.23",
            "ICMS": {
              "ICMS00": {
                "orig": 5, "CST": "00", "modBC": 0, "vBC": "16.31",
                "pICMS": "19.00", "vICMS": "3.10",
                "pFCP": "2.00", "vFCP": "0.33"
              }
            },
            "IPI": { "cEnq": "999", "IPINT": { "CST": "53" } },
            "PIS": { "PISNT": { "CST": "07" } },
            "COFINS": { "COFINSNT": { "CST": "07" } },
            "IBSCBS": {
              "CST": "000",
              "cClassTrib": "000001",
              "gIBSCBS": {
                "vBC": "13.21",
                "gIBSUF": { "pIBSUF": "0.10", "vIBSUF": "0.01" },
                "gIBSMun": { "pIBSMun": "0.00", "vIBSMun": "0.00" },
                "vIBS": "0.01",
                "gCBS": { "pCBS": "0.90", "vCBS": "0.12" }
              }
            }
          }
        }
      ],
      "total": {
        "ICMSTot": {
          "vBC": "16.31", "vICMS": "3.10", "vICMSDeson": "0.00",
          "vFCP": "0.33", "vBCST": "0.00", "vST": "0.00",
          "vFCPST": "0.00", "vFCPSTRet": "0.00", "vProd": "16.31",
          "vFrete": "0.00", "vSeg": "0.00", "vDesc": "0.00",
          "vII": "0.00", "vIPI": "0.00", "vIPIDevol": "0.00",
          "vPIS": "0.00", "vCOFINS": "0.00", "vOutro": "0.00",
          "vNF": "16.31", "vTotTrib": "3.23"
        },
        "IBSCBSTot": {
          "vBCIBSCBS": "13.21",
          "gIBS": {
            "gIBSUF": { "vDif": "0.00", "vDevTrib": "0.00", "vIBSUF": "0.01" },
            "gIBSMun": { "vDif": "0.00", "vDevTrib": "0.00", "vIBSMun": "0.00" },
            "vIBS": "0.01", "vCredPres": "0.00", "vCredPresCondSus": "0.00"
          },
          "gCBS": {
            "vDif": "0.00", "vDevTrib": "0.00", "vCBS": "0.12",
            "vCredPres": "0.00", "vCredPresCondSus": "0.00"
          }
        }
      },
      "transp": { "modFrete": 9 },
      "pag": { "detPag": { "indPag": "0", "tPag": "90", "vPag": "0.00" } },
      "infRespTec": {
        "CNPJ": "12345678000195",
        "xContato": "Responsavel Tecnico",
        "email": "suporte@sua-software-house.com.br",
        "fone": "4430000000"
      }
    }
  }
}

Resposta

Quando a SEFAZ autoriza a nota:

{
  "outcome": "SUCCESS",
  "chaveAcesso": "41261012345678000195554650000000101585524161",
  "protocolo": "141260000000000"
}

Status de resposta

Status	Significado
`200`	Nota processada. Confira `outcome`.
`400`	Body inválido.
`401`	`x-api-key` ausente ou inválida.
`402`	Emissão bloqueada por plano ou saldo da conta.
`403`	Empresa inativa (`Organization is inactive`).
`422`	Nota rejeitada na validação ou pela SEFAZ.
`503`	SEFAZ indisponível. Tente de novo mais tarde.

Veja também Erros.

​Com ou sem cálculo de tributos

Com cálculo (padrão)

Sem cálculo (calculateTaxes: false)

​Estrutura do body

​Grupos principais

​Payload enxuto (com cálculo)

​Payload com os tributos preenchidos

​Regime tributário

​Resposta

​Status de resposta

On this page