Hacienda CR

What is Hacienda CR about?

Hacienda CR provides an open‑source toolkit written in TypeScript to work with the Costa Rican Ministry of Finance (Hacienda) electronic‑invoice specifications (v4.4). It includes a programmatic SDK, a command‑line interface, and an MCP server so developers can create, sign (XAdES‑EPES), submit, and monitor electronic invoices, credit/debit notes, tickets, receipts and receiver messages.

How to use Hacienda CR?

1. Install the desired package
   • SDK: npm install @dojocoding/hacienda-sdk
   • CLI (global): npm install -g @dojocoding/hacienda-cli
   • MCP server (via MCP client): npx -y @dojocoding/hacienda-mcp
2. Configure credentials – set HACIENDA_USERNAME, HACIENDA_PASSWORD, and optionally HACIENDA_P12_PATH / HACIENDA_P12_PIN in the environment or via the CLI profile stored in ~/.hacienda-cr/config.toml.
3. Authenticate (SDK: client.authenticate(), CLI: hacienda auth login).
4. Create a draft, sign it, and submit:
   • SDK: use HaciendaClient methods such as buildClave, buildFacturaXml, and the signing helpers.
   • CLI: hacienda draft, hacienda validate, hacienda submit.
   • MCP: send prompts to the server (e.g., draft_invoice) and receive JSON drafts that can later be signed with the SDK or CLI.
5. Query status with hacienda lookup (CLI) or SDK’s client.getDocumentStatus.

Key features of Hacienda CR

• Full fiscal workflow: authentication (OAuth2), XML generation for all supported document types, XAdES‑EPES digital signing, submission, and status lookup.
• Multiple entry points: programmatic SDK, interactive CLI, and MCP server for AI‑driven assistants.
• Sandbox & production environments – switch with a single flag.
• Type‑safe TypeScript definitions for all request/response objects.
• Built‑in validation against Hacienda XSD schemas.
• Convenient helpers for IVA (13 %) calculations, key (clave) generation, and document sequencing.
• Extensible – can be wrapped in SaaS, ERP, POS, or accounting automation tools.

Use cases of Hacienda CR

1. SaaS billing platforms – automatically issue electronic invoices when a subscription renews.
2. E‑commerce stores – tie order completion to invoice generation and attach the Hacienda key to the order record.
3. Point‑of‑sale systems – generate tickets, invoices, and credit notes on the fly from the cash register.
4. Enterprise ERP integration – synchronize sales, purchases, and accounting with Hacienda's APIs.
5. Accounting firm automation – batch‑process drafts, validate them with --json, and generate reports.
6. AI assistants – use the MCP server so a conversational agent can draft invoices from natural‑language instructions, then hand off to the SDK/CLI for signing and submission.

FAQ from the Hacienda CR

• Do I need a digital certificate? Yes, a .p12 certificate and its PIN are required for signing and submitting documents.
• Can I test without real credentials? Absolutely – the sandbox environment works with test credentials provided by Hacienda.
• Which Node version is required? Node.js 22 or newer.
• How are packages versioned? Each of the three packages (sdk, cli, mcp) is versioned independently using Changesets.
• Is the MCP server mandatory? No, it is an optional integration point for AI assistants; the SDK and CLI cover all core functionalities.
• Where can I find documentation? Detailed guides are under the docs/ folder, including sandbox‑guide, production‑integration, and full reference markdown files.

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.7.0 está publicada y verificada en los cuatro paquetes. El registro del release conserva versiones, integridades, procedencia y recuperación de la publicación, junto con los avisos de seguridad pendientes. Publicar el SDK no activa una integración fiscal ni adopta la versión en una aplicación. La preparación 0.8.0 es un PR de versiones para corregir el contrato de historial; todavía no representa publicación ni adopción.

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.
• 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

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 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

Usá Node.js 22+ y la versión de pnpm declarada en package.json.

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.