# @brasil-fiscal/nfe 中文文档

规范地址：https://npmcn.com/package/%40brasil-fiscal/nfe/

版本：2\.0\.7
npm 元数据更新时间：2026-07-29T19:16:53.267Z
中文译文更新时间：2026-11-08T14:12:26.089Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40brasil-fiscal/nfe
原文对照：https://npmcn.com/package/%40brasil-fiscal/nfe/?lang=original
项目主页：https://github.com/brasil-fiscal/nfe#readme
源码仓库：https://github.com/brasil-fiscal/nfe

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：874 kB，232 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- peer 依赖：pdfkit \>=0\.13\.0，qrcode \>=1\.5\.0
- 首次发布：2026-04-29T11:16:46.727Z
- 最新版本发布：2026-07-29T19:16:53.069Z
- 近 30 天下载量：6095（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

自由开放源代码:emissao de NFe (Nota Financial Eletronica) em TypeScript. 阿奎特图拉跛脚,零依赖,插座.

## 安装

```sh
npm install @brasil-fiscal/nfe
```

也可以使用：`pnpm add @brasil-fiscal/nfe`、`yarn add @brasil-fiscal/nfe`、`bun add @brasil-fiscal/nfe`

## README

# @brasil-fiscal/ nfe (英语)

启用源代码类型Script para emissao de **NFe(诺塔财政公司)** 电子 **NFC-e (诺塔财政公司)** 没有巴西语。 阿奎特图拉跛脚,全能插座。 生态主义 [`@brasil-fiscal`](https://github.com/brasil-fiscal)。 。 。 .

## 印斯达拉考

```bash
npm install @brasil-fiscal/nfe
```

Para gerar DANFE (PDF), instale tambem: 页面存档备份,存于互联网档案馆

```bash
npm install pdfkit
```

> 欧 [`@brasil-fiscal/core`](https://github.com/brasil-fiscal/core) (原始内容存档于2013-10-12). eh instalado自動相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接.

## 特征

### NFe(模式55)——汇编

-   Geracao de XML da NFe(排出SEFAZ 4.00)
-   Assinatura 数码相册证书 A1 (.pfx/.p12)
-   对抗 XSD 计划
-   通过 HTTPS com mTLS (modo sincrono) 传输系统
-   自治程序咨询
-   DFE(国家足球俱乐部顾问)
-   NFe 证书
-   科雷卡奥漫画(CC-e)
-   数字化
-   德德蒂纳塔里奥宣言(Conferenceao, Cciencia, desconhecimento, nao realationada)
-   Geracao de DANFE EM PDF (A4 retrato) (英语)
-   URLs de todos os 27 estados (14自译自审者)
-   提供商 spara certificado, transporte, XML e Assinatura

### NFC-e(模式65)——Em desenvolvimento

-   模型配置( M)`'55' | '65'`(中文(简体) )
-   QR 代码 da NFC-e(URL com hash SHA1)
-   坎波斯语Name `qrCode` 电子 `urlChave` 无集团 `infNFeSupl`
-   Destinatario opicional (consumidor nao identificado) (英语)
-   Cupom 术语 80mm com QR 码

## 快速启动

```typescript
import { NFeCore } from '@brasil-fiscal/nfe';
import { readFileSync } from 'node:fs';

const nfe = NFeCore.create({
  pfx: readFileSync('./certificado.pfx'),
  senha: 'senha-do-certificado',
  ambiente: 'homologacao',  // ou 'producao'
  uf: 'MT'
});
```

### 传送 NFe

```typescript
const result = await nfe.transmitir({
  identificacao: {
    naturezaOperacao: 'Venda de mercadoria',
    tipoOperacao: 1,
    destinoOperacao: 1,
    finalidade: 1,
    consumidorFinal: 1,
    presencaComprador: 1,
    uf: 'MT',
    municipio: '5103403',
    serie: 1,
    numero: 1
  },
  emitente: {
    cnpj: '12345678000195',
    razaoSocial: 'Empresa Teste Ltda',
    inscricaoEstadual: '131234567',
    regimeTributario: 1,
    endereco: {
      logradouro: 'Rua das Flores',
      numero: '100',
      bairro: 'Centro',
      codigoMunicipio: '5103403',
      municipio: 'Cuiaba',
      uf: 'MT',
      cep: '78005000'
    }
  },
  destinatario: {
    cpf: '52998224725',
    nome: 'Joao da Silva',
    indicadorIE: 9,
    endereco: {
      logradouro: 'Av Brasil',
      numero: '500',
      bairro: 'Centro',
      codigoMunicipio: '5103403',
      municipio: 'Cuiaba',
      uf: 'MT',
      cep: '78010100'
    }
  },
  produtos: [
    {
      numero: 1,
      codigo: '001',
      descricao: 'Produto Teste',
      ncm: '84714900',
      cfop: '5102',
      unidade: 'UN',
      quantidade: 2,
      valorUnitario: 49.90,
      valorTotal: 99.80,
      icms: { origem: 0, csosn: '102' },
      pis: { cst: '49' },
      cofins: { cst: '49' }
    }
  ],
  transporte: { modalidadeFrete: 9 },
  pagamento: {
    pagamentos: [{ formaPagamento: '01', valor: 99.80 }]
  }
});

console.log(result.autorizada);   // true
console.log(result.protocolo);    // '151240000012345'
console.log(result.chaveAcesso);  // 44 digitos
```

### 咨询程序o

```typescript
const result = await nfe.consultarProtocolo('51240412345678000195550010000000011234567890');
console.log(result.codigoStatus); // '100'
```

### 取消NFe

```typescript
await nfe.cancelar({
  chaveAcesso: '51240412345678000195550010000000011234567890',
  cnpj: '12345678000195',
  protocolo: '151240000012345',
  justificativa: 'Erro na emissao da nota fiscal eletronica'
});
```

### 科雷卡奥漫画(CC-e)

```typescript
await nfe.cartaCorrecao({
  chaveAcesso: '51240412345678000195550010000000011234567890',
  cnpj: '12345678000195',
  correcao: 'Correcao do endereco do destinatario para Rua ABC 123',
  sequencia: 1  // opcional, default 1
});
```

### Inutilizar 数字

```typescript
await nfe.inutilizar({
  cnpj: '12345678000195',
  ano: 2024,
  serie: 1,
  numeroInicial: 10,
  numeroFinal: 20,
  justificativa: 'Numeracao pulada por erro no sistema emissor'
});
```

### Consultar NFes recebidas (Distribuicao DFe) (英语)

```typescript
// Por ultimo NSU (paginacao manual)
const result = await nfe.distribuicaoPorNSU('12345678000195');
console.log(result.documentos);  // Array de { nsu, schema, xml }
console.log(result.ultNSU);      // Usar como input da proxima chamada

// Por chave de acesso
const result2 = await nfe.distribuicaoPorChave(
  '12345678000195',
  '51240412345678000195550010000000011234567890'
);
```

### 德蒂纳塔里奥宣言

```typescript
const input = {
  chaveAcesso: '51240412345678000195550010000000011234567890',
  cnpj: '12345678000195'
};

await nfe.manifestar.confirmar(input);
await nfe.manifestar.ciencia(input);
await nfe.manifestar.desconhecer({ ...input, justificativa: 'Nao reconheco esta operacao' });
await nfe.manifestar.naoRealizada({ ...input, justificativa: 'Mercadoria devolvida' });
```

### Gerar DANFE (PDF) (英语)

```typescript
import { writeFileSync } from 'node:fs';

const pdf = await nfe.danfe(xmlAutorizado);
writeFileSync('danfe.pdf', pdf);
```

> 重新定义 `pdfkit` 内斯塔拉多 : `npm install pdfkit`

### 错误的悲剧

```typescript
import { SefazRejectError, CertificateError, NFeError } from '@brasil-fiscal/nfe';

try {
  await nfe.transmitir(nfeData);
} catch (error) {
  if (error instanceof CertificateError) {
    console.error('Certificado:', error.message);
  } else if (error instanceof SefazRejectError) {
    console.error(`[${error.cStat}] ${error.xMotivo}`);
  } else if (error instanceof NFeError) {
    console.error('Erro:', error.message);
  }
}
```

## 乌索·阿凡卡多

Para quem pricisa de controle total, os supposers e 使用case individuais tambem estao disponiveis. 中国植物物种信息数据库. 韦雅 [文件/样本.md](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/EXAMPLES.md) a API de baixo nivel. \[永久失效連結\] 互联网档案馆的存檔,存档日期2011-12-02.

## 提供商插件

一个自以为是的人 Cada integracao externa eh uma 接口 que voce pode substituir : (原始内容存档于2019-09-31)

| 提供者 | 德克里亚 | 默认 | 折纸 |
| --- | --- | --- | --- |
| `CertificateProvider` | 卡雷加证书 | `A1CertificateProvider` (pfx/.p12) (中文(简体) ) | `@brasil-fiscal/core` |
| `SefazTransport` | Comunicacao HTTP 相机 SEFAZ | `NodeHttpSefazTransport` (毫升) | `@brasil-fiscal/core` |
| `XmlBuilder` | Gera XML 元素组件 | `DefaultXmlBuilder` | `@brasil-fiscal/nfe` |
| `XmlSigner` | Assina XML com 证书数字化 | `DefaultXmlSigner` | `@brasil-fiscal/core` |

Para criar seu professor, veja 互联网档案馆的存檔,存档日期2014-12-02 [文件/文件](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/PROVIDERS.md)。 。 。 .

## 阿基特图拉

Este Pacote 我们a [`@brasil-fiscal/core`](https://github.com/brasil-fiscal/core) (c) 证书、体位饱和、运输mTLS、助手。 O Core eh reutilizado entre NFe, CTe e MDFe. 互联网档案馆的存檔,存档日期2013-12-02.

```
@brasil-fiscal/core          Certificado A1, XMLDSig, mTLS, CNPJ/CPF, UF codes
      |
@brasil-fiscal/nfe           NFe + NFC-e (este pacote)
      |
      src/
        core/                 Fachada (NFeCore) e tipos
        domain/               Entidades puras e schemas Zod
        contracts/            Interface XmlBuilder (NFe-especifica)
        application/          Use cases (transmit, consult, cancel, etc.)
        infra/                DefaultXmlBuilder, SOAP, DANFE
        shared/               Constantes (CFOP, CST, URLs SEFAZ)
```

维哈, para detalhes Completos [文献/档案](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/ARCHITECTURE.md)。 。 。 .

## @brasil-财政

| 帕科特语Name | 状态 | 德克里亚 |
| --- | --- | --- |
| [@ brasil-财政/核心](https://github.com/brasil-fiscal/core) | 静态 | 国家林业局 |
| **@brasil-fiscal/ nfe (英语)** | 静态 | NFE-e(最高速率) |
| [@brasil-fiscal/ cte (英语)](https://github.com/brasil-fiscal/cte) | 脱口而出 | 中文本 |
| [@brasil-fiscal/ mdfe](https://github.com/brasil-fiscal/mdfe) | 脱口而出 | 货币基金 |
| [@brasil-fiscal/ sped-fiscal (英语)](https://github.com/brasil-fiscal/sped-fiscal) | 脱口而出 | EFD ICMS/IPI (SPED 财政) |
| [@brasil-fiscal/ sped-contribuicoes (英语)](https://github.com/brasil-fiscal/sped-contribuicoes) | 脱口而出 | EFD Contribuicoes (PIS/COFINS) (英语) |
| [@brasil-fiscal/ sintegra (英语)](https://github.com/brasil-fiscal/sintegra) | 脱口而出 | 新加坡 |

## 文档

| 文档 | 德克里亚 |
| --- | --- |
| [ROADMAP.md 地图](https://npmcn.com/package/%40brasil-fiscal/nfe/ROADMAP.md) | 脱口秀 |
| [文献/档案](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/ARCHITECTURE.md) | 阿基特图拉德塔尔哈达 |
| [文件/全球轨道](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/GLOSSARY.md) | Glossario de termos fiscais (法语) |
| [文件/文件](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/PROVIDERS.md) | Guia para criar 供应商 |
| [文件/样本.md](https://npmcn.com/package/%40brasil-fiscal/nfe/docs/EXAMPLES.md) | Exemplos 压缩件 |

## 实例

维雅一面 [`examples/`](https://npmcn.com/package/%40brasil-fiscal/nfe/examples/) 第4段:

-   `nfe-exemplo.xml` - XML de NFe gerado(法语)
-   `danfe-exemplo.pdf` ——DANFE EM PDF

Para regenerar : (原始内容存档于2018-09-29) `npx tsx scripts/generate-examples.ts`

## 请求

-   节点.js 18
-   认证数字 A1 (.pfx ou.p12)
-   OpenSSL Instalado( para carregar certificados e validar XSD) 主题 :
-   `pdfkit` (opional, apenas para gerar DANFE)

## 德森沃尔维门托

```bash
git clone https://github.com/brasil-fiscal/nfe.git
cd nfe
npm install
npm test
npm run lint
npm run build
```

## 孔布里布伊多语Name

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}康特利布科斯·绍·本·温达斯! 韦雅 [捐款额](https://npmcn.com/package/%40brasil-fiscal/nfe/CONTRIBUTING.md)。 。 。 .

## Inspiracao (英语)

-   [nfephp-org/ sped-nfe (英语)](https://github.com/nfephp-org/sped-nfe) - PHP咨询,NFe
-   [nfephp-org/ sped-common (英语)](https://github.com/nfephp-org/sped-common) - 基本连锁店

## 利琴卡语Name

[麻省理工学院](https://npmcn.com/package/%40brasil-fiscal/nfe/LICENSE)

## 常见问题

### @brasil-fiscal/nfe 是什么？

自由开放源代码:emissao de NFe \(Nota Financial Eletronica\) em TypeScript\. 阿奎特图拉跛脚,零依赖,插座\.

### 如何安装 @brasil-fiscal/nfe？

在项目目录运行 npm install @brasil-fiscal/nfe，或使用 pnpm add / yarn add / bun add。

### @brasil-fiscal/nfe 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @brasil-fiscal/nfe 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @brasil-fiscal/nfe 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @brasil-fiscal/nfe 可以商用吗？

@brasil-fiscal/nfe 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @brasil-fiscal/nfe 的下载量有多少？

根据 npm 官方下载统计，@brasil-fiscal/nfe 在 2026/10/09 – 2026/11/07 这 30 天内被下载 6,095 次，日均约 203 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @brasil-fiscal/nfe 还在维护吗？

最新版本 2\.0\.7 发布于 2026/07/30（3 个月前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/04/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。