# @dojocoding/hacienda-sdk 中文文档

规范地址：https://npmcn.com/package/%40dojocoding/hacienda-sdk/

版本：0\.13\.0
npm 元数据更新时间：2026-11-01T02:10:46.532Z
中文译文更新时间：2026-11-12T15:15:38.929Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.2 MB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：10 个
- 首次发布：2026-02-22T18:35:13.061Z
- 最新版本发布：2026-11-01T02:10:46.122Z
- 近 30 天下载量：6022（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

哥斯达黎加电子发票的核心SDK(Hacienda API v4.4)

## 安装

```sh
npm install @dojocoding/hacienda-sdk
```

也可以使用：`pnpm add @dojocoding/hacienda-sdk`、`yarn add @dojocoding/hacienda-sdk`、`bun add @dojocoding/hacienda-sdk`

## README

# @dojocoding/hacienda-sdk (英语)

哥斯达黎加电子发票的核心SDK(Hacienda API v4.4).

为Ministerio de Hacienda API提供认证,XML生成,XAdES-ESPES数字签名,税收计算,以及一个被打入的HTTP客户端.

## 安装

```bash
npm install @dojocoding/hacienda-sdk
```

要求数 **节点.js 22+** (使用当地语言) `fetch` 财务报告和审定财务报表 `crypto.subtle`) (中文(简体) ).

## 快速启动

```ts
import { HaciendaClient, Environment, IdType } from "@dojocoding/hacienda-sdk";

const client = new HaciendaClient({
  environment: Environment.Sandbox,
  credentials: {
    idType: IdType.PersonaJuridica,
    idNumber: "3101234567",
    username: process.env.HACIENDA_USERNAME!, // Full issued IDP username.
    password: process.env.HACIENDA_PASSWORD!,
  },
});

await client.authenticate();
const token = await client.getAccessToken();
```

设定 `HACIENDA_USERNAME` 到完整的用户名 从Tico Factura复制, 包括每个连字符和域名(例如, `cpf-01-1234-5678@stag.comprobanteselectronicos.go.cr`) (中文(简体) ). `credentials.username` 发送时未改变,可使用 just `password`; 标识字段 在此模式中是可选的。 如果提供这些证件,则仍然是经验证的纳税人身份证. 无 `username`SDK保留了遗产 `buildUsername(idType, idNumber)` 倒计时。 无法推断纳税人身份证上的用户名.

关于可开具的发票 验证 签署 提交 情况工作流程, 跟着 [沙盒走过](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/sandbox-guide.md) 使用 [`examples/sandbox.mjs`](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/packages/sdk/examples/sandbox.mjs) 财务报告和审定财务报表 [`examples/order.json`](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/packages/sdk/examples/order.json)。 。 。 . 关于应用程序架构,见 [生产一体化指南](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/production-integration.md)。 。 。 . 评议 [v4.4 移徙说明](https://npmcn.com/package/%40dojocoding/hacienda-sdk/MIGRATION-v4.4.md) 在调整现有投入之前.

## 支持输入

法律实体 身份识别 在整个身份识别过程中接受十个字母数字字符 和相接相接相接相接相接相接 三位数的专用手机,例如: `911` 为: 已支持。 仅提供税收支持的ISC和 `datosImpuestoEspecifico`,包括: 五进制酒精比例。 混合税计算包括适用的 iVA基数中的具体税和所有净税合计. 见 [移徙说明](https://npmcn.com/package/%40dojocoding/hacienda-sdk/MIGRATION-v4.4.md) 用于投入 示例和相容性细节.

## API 参考

### 客户端

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `HaciendaClient` | 类 | 主要切入点 -- -- 管弦乐团、圆盘生成 |
| `HaciendaClientOptionsSchema` | Zod 计划 | 验证客户端构建器选项 |

### 认证

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `TokenManager` | 类 | OAuth2 ROPC 符号生命周期管理 |
| `loadCredentials()` | 函数 | 建立和验证认证证书 |
| `buildUsername()` | 函数 | 从 cedula 类型和编号中构建境内流离失所者用户名 |
| `getEnvironmentConfig()` | 函数 | 返回环境的 API/ IDP URL |
| `Environment` | 数字 | `Sandbox`, (中文(简体) ), `Production` |
| `IdType` | 数字 | `PersonaFisica`, (中文(简体) ), `PersonaJuridica`, (中文(简体) ), `DIMEX`, (中文(简体) ), `NITE` |

### 奴隶数量

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `buildClave()` | 函数 | 从组件中构建一个 50 个字符片格 |
| `parseClave()` | 函数 | 将一个 50 个字符拼接为组件 |
| `DocumentType` | 数字 | 文档类型代码( E)`01`\- 说吧`09`(中文(简体) ) |
| `Situation` | 数字 | 情况代码( E)`1`\- 说吧`3`(中文(简体) ) |

### XML 数据

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `buildXml()` | 函数 | 有命名空间支持的低级 XML 构建器 |
| `buildFacturaXml()` | 函数 | 构建 Factura 电子化a XML 文档 |
| `buildTiqueteXml()` | 函数 | 构建 Tiquete 电子 XML 文档 |
| `buildNotaCreditoXml()` | 函数 | 构建一个 Nota de Credito 电子化 XML 文档 |
| `buildNotaDebitoXml()` | 函数 | 构建一个 Nota de Debito 电子化的 XML 文档 |
| `buildFacturaCompraXml()` | 函数 | 构建 Factura 电子化 de Compra XML 文档 |
| `buildFacturaExportacionXml()` | 函数 | 构建 Factura 电子 XML 文档 |
| `buildReciboPagoXml()` | 函数 | 构建 Recibo 电子化 de Pago XML 文档 |
| `buildMensajeReceptorXml()` | 函数 | 构建 Mensaje 受体 XML 文档 |
| `validateFacturaInput()` | 函数 | 根据业务规则验证事实数据 |
| `validateDocumentXml()` | 函数 | 以捆绑的 v4. 4 XSD 验证; 可选需要签名结构 |

### 税务计算

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `calculateLineItemTotals()` | 函数 | 计算单行项目的全部总数 |
| `calculateInvoiceSummary()` | 函数 | 将所有行项目合并成一个 ResumenFactura |
| `round5()` | 函数 | 回合至小数点后5位(Hacienda要求) |

### 签名

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `loadP12()` | 函数 | 装入 .p12 证书并提取密钥 |
| `signXml()` | 函数 | 以 XAdES- ESPES 标记 XML( 已签名的 XML 字符串返回) |
| `signAndEncode()` | 函数 | 为 API 提交签名 XML 和 Base64- encode |

### API 客户端

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `HttpClient` | 类 | 用认证头注入的 HTTP 客户端 |
| `bootstrapClient()` | 函数 | 从保存的配置创建认证的 HTTP 客户端 |
| `RateLimiter` | 类 | 请求费率限制符 |
| `submitDocument()` | 函数 | 提交文件(POST/recepcion) |
| `getStatus()` | 函数 | 获取文档状态 (GET /recepcion/{clave}) |
| `submitAndWait()` | 函数 | 提交和投票直至结束 |
| `withRetry()` | 函数 | 以重试逻辑环绕一个同步操作 |
| `listComprobantes()` | 函数 | 列出一个已观测到的元数据页, 并附有组合方过滤器 |
| `getComprobante()` | 函数 | 按 clave (不是 XML/ status) 获取观测到的元数据/ 引用 |
| `lookupTaxpayer()` | 函数 | 由 Cedula( 公共 API) 查找纳税人 |
| `isTerminalStatus()` | 函数 | 检查状态是否为最终 |
| `extractRejectionReason()` | 函数 | 从响应 XML 提取拒绝理由 |

### 配置

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `loadConfig()` | 函数 | 装入配置文件 `~/.hacienda-cr/config.toml` |
| `saveConfig()` | 函数 | 保存配置文件到配置 |
| `listProfiles()` | 函数 | 列出所有配置配置 |
| `deleteProfile()` | 函数 | 删除配置文件 |
| `getNextSequence()` | 函数 | 获取并递增下一个文档序列 |
| `getCurrentSequence()` | 函数 | 获取当前序列而不增加 |
| `resetSequence()` | 函数 | 将文档序列重排为 0 |

顺序帮助者 `(documentType, branch, pos, options)`· ; `resetSequence` 带 `(documentType, branch, pos, value, options)`。本地计数键确实 不包括发行者、简介或环境。 使用 `options.configDir` 要隔离 本地计数器,或在应用程序的数据库中以交易方式分配 多个主机. 见 [序列分配](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/production-integration.md#consecutivos-y-aislamiento-por-empresa)。 。 。 .

### 日志

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `Logger` | 类 | 有层次和格式的结构记录器 |
| `LogLevel` | 数字 | `DEBUG`, (中文(简体) ), `INFO`, (中文(简体) ), `WARN`, (中文(简体) ), `ERROR`, (中文(简体) ), `SILENT` |
| `noopLogger` | 实例 | 压制所有输出的 Logger |

### 错误

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `HaciendaError` | 类 | 所有 SDK 错误的基准错误分类 |
| `ValidationError` | 类 | 输入验证失败 |
| `ApiError` | 类 | HTTP/网络出错(包括 `statusCode`, (中文(简体) ), `responseBody`(中文(简体) ) |
| `AuthenticationError` | 类 | 认证/保存的生命周期失败 |
| `SigningError` | 类 | XAdES- EPES 签名失败 |
| `HaciendaErrorCode` | 数字 | 错误类别代码 |

### 出错代码( API)

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `HaciendaRejectionCode` | 数字 | Hacienda 拒绝理由代码 |
| `REJECTION_CODE_DESCRIPTIONS` | 对象 | 人可读的拒绝说明 |
| `getRejectionDescription()` | 函数 | 地图拒绝代码到描述 |
| `getHttpStatusDescription()` | 函数 | 将 HTTP 状态映射到描述 |
| `isRetryableStatus()` | 函数 | 检查 HTTP 状态是否可以重试 |

## 完整文档

见 [SDK 参考](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/reference.md#sdk--documentaci%C3%B3n-completa), (中文(简体) ), [沙盒走过](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/sandbox-guide.md),以及 [生产一体化指南](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/production-integration.md)。 。 。 .

## 迁移到0.4.0

见 [移徙指导](https://npmcn.com/package/%40dojocoding/hacienda-sdk/MIGRATION-v4.4.md) 对于所需的提供者ID,严格的XSD验证,请求最后期限,取消,以及提交重试行为.

## 精确的十进制普通 FE( 添加)

`calculateExactFe` 财务报告和审定财务报表 `buildExactFacturaXml` 接受严格 `ExactFeInput` 明确命名的小数弦事实 `FE-domestic-ordinary-iva13-v1` 案例。 他们使用缩放的 BigInt 和精确的小数 XML 不进行数字转换. 遗产数字API保持不变. 这是普通的IVA13,完全 而不是每个财政制度。 见 [合同、精确度、限度 独立核查](https://npmcn.com/package/docs/specs/exact-ordinary-fe.md)。 。 。 .

历史的包装现在遵循了记录的元数据合同,并暴露了原始观测到的射程头. 见 [明确移徙和限制](https://npmcn.com/package/docs/history-contract.md) 在更换回填消费者之前.

目前准确的FE信贷条件需要正数 1-5 位数 `plazoCredito` 关于02/10, 而不修改有效的正本词典。 历史的只读相容性使用 明确分开 `calculateRetainedExactFe`编号 :`RetainedExactFeInputSchema` 合同,从不保留XML/签名构建器。 见 [信贷期中规则和 消费者移徙](https://npmcn.com/package/docs/exact-fe-credit-terms.md)。 。 。 .

### 准确的普通 TE 源候选人

添加剂 `calculateExactTe` 编号 : `buildExactTiqueteXml` 共享 `ExactTeInputSchema` 保留十进制文本和实际可选的接收数据. 它们不制造FE接收器或允许现场发放TE。 见 [合同、范围和核查限制](https://npmcn.com/package/docs/exact-te.md)。该来源 切片不是新公布的版本,也不是精确的CLI/MCP活化.

### 准确的普通 ND 源候选人

`calculateExactNd` 编号 : `buildExactNotaDebitoXml` 独立计算 带有明确正线和正线的正FE参考递增 装订。 它们保留了原始事实,并不确立原始接受, 法定年龄资格或账户效应。 见 [范围和主要规则](https://npmcn.com/package/docs/exact-nd.md)。 。 。 . 这种添加剂SDK/共享源片不是版本起伏或活活活活化.

## 国内普通FEC来源

添加 `ExactFecInputSchema` 编号 : `calculateExactFec` 编号 : `buildExactFacturaCompraXml` 保存实际供应商Emisor和买方的受体, 要求买方拥有的08个身份/活动和明确的证明证据 不进行数字转换,计算出普通的IVA13小数字符串。 这是第一个 案件为国内01-04,条件为01/02;外国05,废品06/条件为13 特别税案仍须另行处理。 现有家庭/遗产 不变。 见 [准确的 FEC 边界](https://npmcn.com/package/docs/exact-fec.md) 独立资格/年龄/反应-征兆和释放门.

## 未发放准确的信贷延期

`calculateExactNcPartial` 编号 : `buildExactNotaCreditoPartialXml` 计算清晰 与精确小数字符串相关的信用额度。 累计剩余贷项 是外部不可改变的并行分类账权限,而不是原封顶. `calculateExactFeReplacement` 编号 : `buildExactFacturaReplacementXml` 新建一个 FE \* 保留机构拒绝的参考资料、新的身份和明确 第16条理由 现有API不变. 见 [来源合同和独立合同 授权/释放限制](https://npmcn.com/package/docs/exact-credit-extensions.md)。 。 。 .

## 未释放的当前 FE 校正

目前精确的FE使用本地的Unicode发行商/收发商/商业名称边界和 提供正向付款分配;新准确的TE分摊正向付款 合同。 历史 0.6-0.9 源/矿和计算产出代码仍然存在 单独可读,无保留建造者或签发权。 见 [现行规则、真正的登记证据和按版本迁移](https://npmcn.com/package/docs/current-fe-native-boundaries.md)。 。 。 .

## 未放行的明确外事服务IVA13采购来源

`calculateExactFecForeignServiceIva13` 编号 : `buildExactFacturaCompraForeignServiceIva13Xml` 保存实际供应商05, 外国地址/参考资料 16/理由 11和买方拥有的 08 个身份 选择了普通的IVA13服务箱。 供应商身份从未决定赔偿责任 或可信用性。 废品06/条件13和其他制度仍未完成. 见 [来源、主要规则和独立大门](https://npmcn.com/package/docs/exact-foreign-service-fec.md)。 。 。 .

准确接收方合同和剩余运输/结果门: [收件人确认](https://npmcn.com/package/docs/exact-recipient-message.md)。 。 。 .

-   仅显示来源 [非主题个人用货](https://npmcn.com/package/docs/exact-used-personal-goods-fec.md):实际供应商06/买方08,普通折扣,准确的非主体金额;资质,转售和验收保持独立.

## 常见问题

### @dojocoding/hacienda-sdk 是什么？

哥斯达黎加电子发票的核心SDK\(Hacienda API v4\.4\)

### 如何安装 @dojocoding/hacienda-sdk？

在项目目录运行 npm install @dojocoding/hacienda-sdk，或使用 pnpm add / yarn add / bun add。

### @dojocoding/hacienda-sdk 支持 TypeScript 吗？

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

### @dojocoding/hacienda-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dojocoding/hacienda-sdk 需要什么版本的 Node\.js？

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

### @dojocoding/hacienda-sdk 可以商用吗？

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

### @dojocoding/hacienda-sdk 的下载量有多少？

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

### @dojocoding/hacienda-sdk 还在维护吗？

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