# @brasil-fiscal/core 中文文档

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

版本：1\.6\.0
npm 元数据更新时间：2026-05-02T05:23:23.802Z
中文译文更新时间：2026-11-08T14:11:24.992Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：84.7 kB，99 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-05-01T01:33:13.817Z
- 最新版本发布：2026-05-02T05:23:23.659Z
- 近 30 天下载量：6295（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Fraestrutura Compartilhada para documentos fiscais eletronicos brasileiros (NFe, CTe, MDFe). Certificado Digital, Assinatura XML, transporte mTLS, 帮助器.

## 安装

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

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

## README

# @ brasil-财政/核心

(原始内容存档于2018-03-26) (英语). Infraestrutura compatrilhada para documentos fiscais eletronicos brasileiros. Certificado Digital, Assinatura XML, transporte mTLS, helpers e 常数——tudo que NFe, CTe e MDFe tem em comum. 中国植物物种信息数据库.

## 派克服务?

Este Pacote eh 一个基地做projetos `@brasil-fiscal/*`来点逻辑的 **身份证** (原始内容存档于2018-03-26) (英语). Enter NFe, CTe e MDFe:

-   Carregar 认证数字 A1 (.pfx/.p12)
-   Assinar XML com XMLDSig (RSA-SHA1) (英语)
-   通过 HTTPS com mTLS 的 Comunicar com a SEFAZ
-   C14N de XML 数据
-   Gerar chave de acesso (44个数字)
-   CNPJ e 森林合作伙伴关系
-   Codigos IBGE 数字化UFs
-   错误基础类

**(原始内容存档于2018-10-29) (英语). Voce provavelmente nao pricisa instalar este pacote pretamente.** Ele eh uma dependencia dos pacotes de documento pacio financial: 国家财政局 国家财政局

| 帕科特语Name | 文档 |
| --- | --- |
| [`@brasil-fiscal/nfe`](https://github.com/brasil-fiscal/nfe) | NFE / NFC-e(诺塔财政公司) |
| [`@brasil-fiscal/cte`](https://github.com/brasil-fiscal/cte) | CTe(运输协会) |
| [`@brasil-fiscal/mdfe`](https://github.com/brasil-fiscal/mdfe) | MDFe (菲斯凯斯文件公司) |

## 印斯达拉考

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}嘿 哥们儿 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}嘿 哥们儿

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

## API 密码

### 数字证书

```typescript
import { A1CertificateProvider } from '@brasil-fiscal/core';

const provider = new A1CertificateProvider(pfxBuffer, 'senha');
const cert = await provider.load();
// cert.privateKey, cert.certPem, cert.pfx, cert.password, cert.notAfter
```

### Asinatura XML 图像

```typescript
import { DefaultXmlSigner } from '@brasil-fiscal/core';

const signer = new DefaultXmlSigner();
const xmlAssinado = signer.sign(xml, certificateData);
```

O 签名人探测器`infNFe`, (中文(简体) ), `infCte`, (中文(简体) ), `infMDFe`, (中文(简体) ), `infEvento`, (中文(简体) ), `infInut`(原始内容存档于2018-10-26). e assina corretamente.

### 运输 mTLS

```typescript
import { NodeHttpSefazTransport } from '@brasil-fiscal/core';

const transport = new NodeHttpSefazTransport({ timeout: 30000 });
const response = await transport.send({
  url: 'https://nfe.sefaz.mt.gov.br/...',
  soapAction: '...',
  xml: envelopeXml,
  pfx: cert.pfx,
  password: cert.password
});
```

### 帮助 XML

```typescript
import { tag, tagGroup, formatDate, escapeXml, padLeft } from '@brasil-fiscal/core';

tag('CNPJ', '12345678000195');           // <CNPJ>12345678000195</CNPJ>
tag('xNome', undefined);                  // '' (omite tags vazias)
tagGroup('emit', tag('CNPJ', '123'));     // <emit><CNPJ>123</CNPJ></emit>
formatDate(new Date(), '-03:00');         // '2024-04-28T10:00:00-03:00'
```

### SOPAP 软件

```typescript
import { extractSoapBody, extractTag } from '@brasil-fiscal/core';

const body = extractSoapBody(soapResponseXml);  // conteudo dentro de <soap:Body>
const cStat = extractTag(body, 'cStat');         // conteudo de <cStat>
```

### 阿克塞多骑士团

```typescript
import { generateAccessKey, generateNumericCode } from '@brasil-fiscal/core';

const chave = generateAccessKey({
  uf: '51',
  dataEmissao: new Date(),
  cnpj: '12345678000195',
  modelo: '55',     // 55=NFe, 57=CTe, 58=MDFe, 65=NFCe
  serie: 1,
  numero: 1,
  tipoEmissao: 1,
  codigoNumerico: generateNumericCode()
});
// 44 digitos com digito verificador
```

### 维拉多克·德·多克托斯

```typescript
import { isValidCnpj, isValidCpf, formatCnpj, formatCpf } from '@brasil-fiscal/core';

isValidCnpj('11222333000181');  // true
isValidCpf('52998224725');      // true
formatCnpj('11222333000181');   // '11.222.333/0001-81'
formatCpf('52998224725');       // '529.982.247-25'
```

### 常数

```typescript
import { UF_CODES } from '@brasil-fiscal/core';

UF_CODES['MT'];  // '51'
UF_CODES['SP'];  // '35'
```

### 埃尔罗斯

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

// DFeError — erro base de todos os documentos fiscais
// CertificateError — falha no certificado digital
// SefazRejectError — SEFAZ rejeitou o documento (cStat + xMotivo)
// SchemaValidationError — XML invalido contra XSD
```

## 对比( 界面)

O 核心定义相悖 que podem ser expertados por qualquer pacote :

| 相对 | 责任 | 执行 |
| --- | --- | --- |
| `CertificateProvider` | 卡尔加证书 | `A1CertificateProvider` |
| `SefazTransport` | Comunicacao HTTP 相机 SEFAZ | `NodeHttpSefazTransport` |
| `XmlSigner` | Assinar XML com 证书 | `DefaultXmlSigner` |
| `SchemaValidator` | 验证 XML 反 XSD | (执行em cada pacote) |

### Criando 提供商自定义

```typescript
import type { CertificateProvider, CertificateData } from '@brasil-fiscal/core';

export class MyCertificateProvider implements CertificateProvider {
  async load(): Promise<CertificateData> {
    // Sua logica (vault, HSM, banco de dados, etc.)
    return { pfx, password, notAfter, privateKey, certPem };
  }
}
```

## 阿基特图拉

```
src/
  contracts/        Interfaces (CertificateProvider, SefazTransport, XmlSigner, SchemaValidator)
  infra/
    certificate/    A1CertificateProvider (carrega .pfx/.p12 via openssl)
    xml/            DefaultXmlSigner, canonicalize (C14N), xml-helper (tag, escapeXml)
    transport/      NodeHttpSefazTransport (mTLS), soap-helper (extractSoapBody)
  shared/
    errors/         DFeError, CertificateError, SefazRejectError, SchemaValidationError
    helpers/        CNPJ, CPF, mod11, access-key
    constants/      UF_CODES (codigos IBGE)
```

### 小学

-   **零依赖性运行时间** - 阿佩纳斯 `node:crypto`, (中文(简体) ), `node:https`, (中文(简体) ), `node:child_process`
-   **相对的初等动物** - 托达integracao externa eh uma 接口
-   **法尔哈尔快活** - 错误的claros com 班级
-   **编辑手册** - 散货箱,通过构件提供喷气管

## 请求

-   节点.js 18
-   OpenSSL Instalado (para carregar certificados A1) (英语)

## 德森沃尔维门托

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

## 孔布里布伊多语Name

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

### 代码样式

-   TypeScript 严格模式, 返回类型
-   单引号,分号,sem后接逗号,100 Chars por linha
-   路径别名 : `@core/*` 马佩亚 第9段 `src/*`
-   接口 sem 前缀 `I` (单位:千美元)`CertificateProvider`,纳奥 `ICertificateProvider`(中文(简体) )

## @brasil-财政

| 帕科特语Name | 状态 | 德克里亚 |
| --- | --- | --- |
| **@ brasil-财政/核心** | 静态 | (原始内容存档于2013-10-12) (英语). Infraestrutura compatilhada (este pacote) |
| [@brasil-fiscal/ nfe (英语)](https://github.com/brasil-fiscal/nfe) | 静态 | NFC-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) | 脱口而出 | 新加坡 |

## 利琴卡语Name

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

## 常见问题

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

Fraestrutura Compartilhada para documentos fiscais eletronicos brasileiros \(NFe, CTe, MDFe\)\. Certificado Digital, Assinatura XML, transporte mTLS, 帮助器\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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