@dojocoding/hacienda-sdk (英语)
哥斯达黎加电子发票的核心SDK(Hacienda API v4.4).
为Ministerio de Hacienda API提供认证,XML生成,XAdES-ESPES数字签名,税收计算,以及一个被打入的HTTP客户端.
安装
npm install @dojocoding/hacienda-sdk
要求数 节点.js 22+ (使用当地语言) fetch 财务报告和审定财务报表 crypto.subtle) (中文(简体) ).
快速启动
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复制,
包括每个连字符和域名(例如,
[email protected]) (中文(简体) ). credentials.username
发送时未改变,可使用 just password; 标识字段
在此模式中是可选的。 如果提供这些证件,则仍然是经验证的纳税人身份证.
无 usernameSDK保留了遗产 buildUsername(idType, idNumber)
倒计时。 无法推断纳税人身份证上的用户名.
关于可开具的发票 验证 签署 提交 情况工作流程,
跟着 沙盒走过 使用
examples/sandbox.mjs 财务报告和审定财务报表 examples/order.json。 。 。 .
关于应用程序架构,见 生产一体化指南。 。 。 .
评议 v4.4 移徙说明 在调整现有投入之前.
支持输入
法律实体 身份识别 在整个身份识别过程中接受十个字母数字字符
和相接相接相接相接相接相接 三位数的专用手机,例如: 911 为:
已支持。 仅提供税收支持的ISC和 datosImpuestoEspecifico,包括:
五进制酒精比例。 混合税计算包括适用的
iVA基数中的具体税和所有净税合计. 见
移徙说明 用于投入
示例和相容性细节.
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 要隔离
本地计数器,或在应用程序的数据库中以交易方式分配
多个主机. 见 序列分配。 。 。 .
日志
| 导出 | 类型 | 说明 |
|---|---|---|
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 参考, (中文(简体) ), 沙盒走过,以及 生产一体化指南。 。 。 .
迁移到0.4.0
见 移徙指导 对于所需的提供者ID,严格的XSD验证,请求最后期限,取消,以及提交重试行为.
精确的十进制普通 FE( 添加)
calculateExactFe 财务报告和审定财务报表 buildExactFacturaXml 接受严格 ExactFeInput
明确命名的小数弦事实 FE-domestic-ordinary-iva13-v1
案例。 他们使用缩放的 BigInt 和精确的小数 XML 不进行数字转换.
遗产数字API保持不变. 这是普通的IVA13,完全
而不是每个财政制度。 见 合同、精确度、限度
独立核查。 。 。 .
历史的包装现在遵循了记录的元数据合同,并暴露了原始观测到的射程头. 见 明确移徙和限制 在更换回填消费者之前.
目前准确的FE信贷条件需要正数 1-5 位数 plazoCredito 关于02/10,
而不修改有效的正本词典。 历史的只读相容性使用
明确分开 calculateRetainedExactFe编号 :RetainedExactFeInputSchema
合同,从不保留XML/签名构建器。 见 信贷期中规则和
消费者移徙。 。 。 .
准确的普通 TE 源候选人
添加剂 calculateExactTe 编号 : buildExactTiqueteXml 共享
ExactTeInputSchema 保留十进制文本和实际可选的接收数据.
它们不制造FE接收器或允许现场发放TE。 见
合同、范围和核查限制。该来源
切片不是新公布的版本,也不是精确的CLI/MCP活化.
准确的普通 ND 源候选人
calculateExactNd 编号 : buildExactNotaDebitoXml 独立计算
带有明确正线和正线的正FE参考递增
装订。 它们保留了原始事实,并不确立原始接受,
法定年龄资格或账户效应。 见 范围和主要规则。 。 。 .
这种添加剂SDK/共享源片不是版本起伏或活活活活化.
国内普通FEC来源
添加 ExactFecInputSchema 编号 : calculateExactFec 编号 :
buildExactFacturaCompraXml 保存实际供应商Emisor和买方的受体,
要求买方拥有的08个身份/活动和明确的证明证据
不进行数字转换,计算出普通的IVA13小数字符串。 这是第一个
案件为国内01-04,条件为01/02;外国05,废品06/条件为13
特别税案仍须另行处理。 现有家庭/遗产
不变。 见 准确的 FEC 边界
独立资格/年龄/反应-征兆和释放门.
未发放准确的信贷延期
calculateExactNcPartial 编号 : buildExactNotaCreditoPartialXml 计算清晰
与精确小数字符串相关的信用额度。 累计剩余贷项
是外部不可改变的并行分类账权限,而不是原封顶.
calculateExactFeReplacement 编号 : buildExactFacturaReplacementXml 新建一个 FE
* 保留机构拒绝的参考资料、新的身份和明确
第16条理由 现有API不变. 见 来源合同和独立合同
授权/释放限制。 。 。 .
未释放的当前 FE 校正
目前精确的FE使用本地的Unicode发行商/收发商/商业名称边界和 提供正向付款分配;新准确的TE分摊正向付款 合同。 历史 0.6-0.9 源/矿和计算产出代码仍然存在 单独可读,无保留建造者或签发权。 见 现行规则、真正的登记证据和按版本迁移。 。 。 .
未放行的明确外事服务IVA13采购来源
calculateExactFecForeignServiceIva13 编号 :
buildExactFacturaCompraForeignServiceIva13Xml 保存实际供应商05,
外国地址/参考资料 16/理由 11和买方拥有的 08 个身份
选择了普通的IVA13服务箱。 供应商身份从未决定赔偿责任
或可信用性。 废品06/条件13和其他制度仍未完成.
见 来源、主要规则和独立大门。 。 。 .
准确接收方合同和剩余运输/结果门: 收件人确认。 。 。 .
- 仅显示来源 非主题个人用货:实际供应商06/买方08,普通折扣,准确的非主体金额;资质,转售和验收保持独立.