使用说明

Hacienda CR

Facturación electrónica para Costa Rica, desde tu código, tu terminal o tu asistente de IA.

Toolkit open-source en TypeScript para trabajar con comprobantes electrónicos v4.4 del Ministerio de Hacienda: autenticación OAuth2, generación de XML, firma XAdES-EPES, cálculo de IVA y consulta de estados.

Casos de uso · Empezar · Documentación · Contribuir · Reportar un problema

Consultá las versiones publicadas y sus archivos verificados en GitHub Releases.

La visión: facturación dentro de tu producto

Que cada venta pueda convertirse en un comprobante electrónico desde el mismo lugar donde ocurre. Un checkout, una caja, un sistema de gestión o una conversación con un asistente pueden ser el punto de partida.

Hacienda CR aporta una base común para construir esos flujos: tu aplicación define la experiencia, conecta sus datos y usa el toolkit para generar, firmar, enviar y consultar comprobantes. La integración con Hacienda pasa a formar parte de tu producto, con código abierto que podés inspeccionar y adaptar.

La visión es una infraestructura abierta de facturación electrónica para Costa Rica: que más equipos puedan lanzar productos con facturación integrada y dedicar su esfuerzo a las necesidades de sus clientes.

Qué podés construir

1. Un SaaS que factura desde su propio panel

Para equipos que desarrollan software de gestión o servicios por suscripción. Al cerrar una orden o registrar un cobro, tu backend toma los datos del cliente, calcula los impuestos y genera el comprobante. Tu panel muestra si Hacienda lo aceptó o rechazó, junto con el motivo.

Valor para tu cliente: gestionar su operación y su facturación en una misma experiencia. Usá el SDK; tu aplicación administra las empresas, sus credenciales, los cobros y la programación de renovaciones.

2. Una tienda que conecta pedidos con comprobantes

Para ecommerce y plataformas de ventas. Cuando tu sistema confirma el pago de un pedido, podés iniciar el flujo de factura electrónica con el SDK y asociar la clave y el estado al pedido. Ante una devolución, podés construir una nota de crédito referenciada al comprobante original.

Valor para tu negocio: evitar volver a digitar una venta para facturarla. Tu tienda conecta su proveedor de pagos y decide cuándo emitir y cómo entregar el comprobante al comprador.

3. Un punto de venta con facturación integrada

Para productos de caja, restaurantes y comercios. Al cerrar una venta, tu aplicación puede generar una factura o un tiquete, calcular el IVA y enviar el XML firmado mediante el SDK. Para un ajuste posterior, puede generar la nota de crédito o débito correspondiente.

Valor para el comercio: convertir la facturación en un paso del flujo de caja, usando los datos que ya capturó el negocio.

4. Un ERP que incorpora el ciclo de comprobantes

Para equipos que integran ventas, compras y contabilidad. Podés conectar una orden con su factura, consultar el estado en Hacienda y construir mensajes de receptor para aceptar o rechazar comprobantes recibidos. Tu sistema conserva la relación entre la operación y sus documentos.

Valor para el equipo administrativo: seguir cada comprobante desde su sistema de gestión. Usá el SDK para la integración y la CLI para consultas y validaciones operativas.

5. Automatización para un despacho contable

Para desarrolladores que apoyan a contadores o administran varias empresas. Un script puede usar perfiles de la CLI para validar archivos, consultar comprobantes y devolver resultados con --json. Antes de enviar una factura, --dry-run permite revisar el XML generado.

Valor para el despacho: transformar tareas repetidas en flujos reproducibles y detectar errores antes del envío. El equipo define los datos de entrada y revisa los resultados.

6. Un asistente que prepara la factura por vos

Para productos con asistentes de IA y equipos que usan clientes MCP. Una persona describe el servicio, el cliente y el monto; el asistente usa el servidor MCP para preparar el borrador, consultar al contribuyente y generar XML sin firmar. Después, tu flujo permite revisar los datos y completar la firma y el envío con el SDK o la CLI.

Valor para quien factura: pasar de una conversación a un documento estructurado, con una etapa de revisión antes de emitirlo.

Elegí un flujo y probalo en sandbox: empezá con una operación de tu producto, generá su comprobante y consultá la respuesta de Hacienda. Los ejemplos de abajo te dan el punto de entrada para cada herramienta.

Elegí tu herramienta

Paquete	Para qué usarlo	Documentación
`@dojocoding/hacienda-sdk`	Integrar autenticación, XML, firma y API en tu aplicación.	SDK
`@dojocoding/hacienda-cli`	Crear borradores, validar, firmar, enviar y consultar desde la terminal.	CLI
`@dojocoding/hacienda-mcp`	Generar borradores y XML con asistentes que soportan MCP.	MCP

El SDK y la CLI permiten trabajar en sandbox y producción. El servidor MCP genera XML sin firmar; completá la firma y el envío con el SDK o la CLI.

Empezá acá

Necesitás Node.js 22+. Para autenticarte, usá tus credenciales del IDP de Hacienda del ambiente elegido. Para firmar y enviar comprobantes, necesitás además un certificado .p12 y su PIN.

SDK: desde tu aplicación

npm install @dojocoding/hacienda-sdk

Definí HACIENDA_USERNAME y HACIENDA_PASSWORD en tu entorno y ejecutá este ejemplo en un módulo TypeScript:

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

const client = new HaciendaClient({
  environment: Environment.Sandbox,
  credentials: {
    idType: IdType.PersonaJuridica,
    idNumber: "3101234567", // Reemplazá por tu cédula jurídica.
    username: process.env.HACIENDA_USERNAME!, // Full issued IDP username.
    password: process.env.HACIENDA_PASSWORD!,
  },
});

await client.authenticate();

const clave = client.buildClave({
  date: new Date(),
  taxpayerId: "3101234567",
  documentType: DocumentType.FACTURA_ELECTRONICA,
  sequence: 1, // Asigná un consecutivo único para cada comprobante.
  situation: Situation.NORMAL,
});

console.log(clave); // Clave numérica de 50 dígitos.

Continuá con creación de documentos, firma digital y envío y consulta. HaciendaClient gestiona autenticación y claves; las operaciones de XML, firma y envío se usan como funciones del SDK.

CLI: desde tu terminal

npm install -g @dojocoding/hacienda-cli

# Definí HACIENDA_USERNAME y HACIENDA_PASSWORD antes de autenticarte.
hacienda auth login --cedula-type 02 --cedula 3101234567 --environment sandbox

# Creá y validá un borrador.
hacienda draft --interactive --output factura.json
hacienda validate factura.json

# Revisá el XML antes de enviarlo.
hacienda submit factura.json --dry-run

# Consulta pública, sin autenticación.
hacienda lookup 3101234567

Para enviar, configurá el certificado y el PIN según la referencia de la CLI. Los comandos admiten --json para automatización.

MCP: desde tu asistente de IA

Agregá este servidor a la configuración MCP de tu cliente (por ejemplo, Claude Desktop):

{
  "mcpServers": {
    "hacienda-cr": {
      "command": "npx",
      "args": ["-y", "@dojocoding/hacienda-mcp"]
    }
  }
}

Probá: “Generá un borrador de factura por dos horas de consultoría a ₡50.000 cada una con IVA del 13%.”

Herramientas: draft_invoice, create_invoice, lookup_taxpayer, check_status, list_documents y get_document. Consultá configuración, parámetros y recursos MCP.

Comprobantes soportados

Comprobante	Builder del SDK
Factura Electrónica	`buildFacturaXml()`
Nota de Débito Electrónica	`buildNotaDebitoXml()`
Nota de Crédito Electrónica	`buildNotaCreditoXml()`
Tiquete Electrónico	`buildTiqueteXml()`
Factura Electrónica de Compra	`buildFacturaCompraXml()`
Factura Electrónica de Exportación	`buildFacturaExportacionXml()`
Recibo Electrónico de Pago	`buildReciboPagoXml()`
Mensaje Receptor (aceptación o rechazo)	`buildMensajeReceptorXml()`

Documentación

Tu primera factura en sandbox: ejemplo ejecutable desde los datos de una venta hasta la respuesta de Hacienda, con recuperación de estado.
Integrar facturación en tu producto: pedidos, workers, persistencia, empresas, consecutivos y reintentos en producción.
Migración de entradas a v4.4: campos requeridos, pagos, descuentos y validación XSD.
Investigación del REP exacto: fuentes oficiales, límites del oráculo monetario y contrato propuesto; no implica un productor exacto disponible.
Referencia completa del SDK: autenticación, XML, impuestos, claves, firma, API, configuración, logging y errores.
Referencia de comandos: opciones y ejemplos de la CLI.
Integración MCP: configuración del cliente y recursos.
Tipos y constantes compartidos.
Informe de conformidad de catálogos: cada tabla de códigos del SDK contra las fuentes primarias de Hacienda, con veredicto y cita por fila. Es evidencia histórica (la lectura del 2026-10-14) más una reconciliación con el main vigente: el apéndice es una foto de aquel momento, no el estado actual.

Verificación de firma

verifySignedDocumentXml (SDK) verifica el comprobante que el propio SDK firma: los digests de cada referencia, la firma RSA sobre el ds:SignedInfo canónico, la canonicalización declarada, la vigencia del certificado, la política de firma (identificador, método de digest y hash contra la política publicada) y la identidad de las partes contra la clave. El tipo de comprobante sale de la raíz del documento, nunca del contenido.

La confianza la establece el pin de hoja que provee el consumidor: el certificado embebido en el documento no establece confianza, no se valida cadena de CA ni revocación, y nada sale a la red. Sin pin, el resultado declara la confianza como no establecida y no es válido.

Verificar una firma no es aceptación fiscal. El verificador no consulta a Hacienda, no habilita regímenes y no sustituye la respuesta del API: un documento puede verificar criptográficamente y ser rechazado. La aceptación real sólo la establece Hacienda sobre el documento enviado.

Credenciales y configuración

Variable	Uso
`HACIENDA_USERNAME`	Usuario IDP completo emitido por Hacienda; conserva guiones y dominio.
`HACIENDA_PASSWORD`	Contraseña del IDP de Hacienda.
`HACIENDA_P12_PATH`	Ruta al certificado `.p12` para los comandos que la admiten.
`HACIENDA_P12_PIN`	PIN del certificado `.p12`.

Los perfiles se guardan en ~/.hacienda-cr/config.toml. Las contraseñas y PINs se suministran por variables de entorno y no se guardan en los perfiles. Empezá con sandbox antes de usar credenciales de producción.

Descargas históricas de npm

El contador suma las descargas de SDK, CLI, MCP y shared, desde la creación de cada paquete hasta el último día disponible en npm. Son descargas del registro, incluyendo CI y dependencias transitivas; no representan instalaciones únicas ni personas.

Ver totales por paquete y fecha de corte. El workflow de actualización actualiza el contador diariamente y también puede ejecutarse manualmente.

Desarrollo y contribuciones

Para desarrollar en este repositorio, usá Node.js 22.13+ y la versión de pnpm declarada en package.json. Los paquetes publicados conservan su requisito Node.js 22+.

git clone https://github.com/DojoCodingLabs/hacienda-cr.git
cd hacienda-cr
pnpm install
pnpm verify

packages/sdk/   Autenticación, XML, firma digital, impuestos y API
packages/cli/   Binario hacienda
packages/mcp/   Servidor MCP con transporte stdio
shared/         Tipos, esquemas y constantes compartidos
docs/           Referencia, banner y métricas de npm

Para trabajar en un paquete: pnpm --filter @dojocoding/hacienda-sdk test.

Catálogos de códigos y sus alias

Los catálogos de códigos se generan desde packages/sdk/schemas/codes.json con pnpm spec:generate y viven en shared/src/generated/ (nunca se editan a mano: cada archivo empieza con NO EDITAR). El registro de parejas tabla→export vive en scripts/codes-generate/table-map.mjs; cuando Hacienda publica un código nuevo, se amplía ahí con la clave revisada y se regenera.

Ese mismo registro declara los alias deprecados que la API publicada expone y que el generador no emite (no son códigos del XSD, son nombres heredados de un código canónico):

Alias	Código canónico	Motivo
`DocumentTypeCode.COMPRA_PAGO`	`DocumentTypeCode.FACTURA_ELECTRONICA_COMPRA` (`08`)	nombre heredado de la factura electrónica de compra
`DocumentTypeCode.GASTO_VIAJE`	`DocumentTypeCode.FACTURA_ELECTRONICA_EXPORTACION` (`09`)	nombre heredado de la factura electrónica de exportación

La paridad de valor no los cuenta (no hay tabla que los pardee); una prueba verifica que cada alias declarado siga publicado y apunte a su código canónico.

Encontrá trabajo en Issues, abrí un issue con pasos para reproducir un error o proponé una mejora. Para contribuir código, hacé un fork, creá una rama, agregá los tests correspondientes y ejecutá los checks anteriores antes de abrir un pull request. Usamos Changesets para versionar los paquetes.

Agradecimientos

Gracias a CRLibre/API_Hacienda y CRLibre/fe-hacienda-cr-misc por sus referencias y recursos para la comunidad de facturación electrónica costarricense.

Licencia

MIT. Construido por Dojo Coding para la comunidad de desarrolladores de Costa Rica 🇨🇷.

Guías para contribuidores: desarrollo y pruebas y versionado y publicación.

The additive exact decimal ordinary FE API preserves supported financial strings through BigInt calculation, JSON and XML; legacy numeric APIs are unchanged. Its explicit IVA13/full-payment scope does not imply all domestic fiscal cases or external acceptance.

El simulador de transporte es una herramienta interna en packages/mock; no está publicado en npm ni establece aceptación fiscal.