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

La versión 0.10.0 está publicada en los cuatro paquetes. El registro de publicación conserva los bytes verificados, procedencia y recuperación tras una demora de indexación de npm. La preparación revisada detalla sus APIs exactas y límites: REP exacto, transporte y correlación de mensajes del receptor, adopción en aplicaciones y aceptación fiscal siguen siendo trabajos separados. El registro histórico 0.7.0 conserva su verificación y recuperación de publicación.

El desarrollo nuevo está en pausa por solicitud del usuario al 18 de octubre de 2026. El contexto de continuación reúne el estado de los ocho issues, los límites pendientes y los criterios para retomar; la publicación 0.10.0 conserva su identidad y evidencia originales.

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.

Related MCP server: mcp-sii

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

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

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.

Credenciales y configuración

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 recalcula el total diariamente y también puede ejecutarse manualmente. Consulta el historial en bloques de hasta 365 días para respetar los límites de la API de npm. Si una consulta falla, conserva el último contador publicado.

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.

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.