Hacienda Cr

hacienda-cr — Facturación Electrónica Costa Rica

El toolkit open-source más completo para facturación electrónica en Costa Rica.\ SDK + CLI + Servidor MCP para emitir comprobantes electrónicos contra la API v4.4 del Ministerio de Hacienda.

](https://www.npmjs.com/package/@dojocoding/hacienda-sdk)   ](https://nodejs.org) 

¿Por qué hacienda-cr?

Emitir facturas electrónicas en Costa Rica no debería ser un dolor de cabeza. Entre la autenticación OAuth2, la generación de XML con namespaces específicos, la firma digital XAdES-EPES, la clave numérica de 50 dígitos y el polling del estado... hay demasiada complejidad accidental.

hacienda-cr resuelve todo eso en un solo toolkit:

• SDK — Librería TypeScript con tipado estricto: auth, XML, firma digital, cálculo de IVA, envío y consulta.
• CLI — Herramienta de línea de comandos hacienda para emitir, firmar, validar y consultar desde la terminal.
• MCP Server — Servidor de Model Context Protocol para que asistentes de IA (Claude, etc.) emitan facturas por vos.

Funciona con los 7 tipos de comprobante + Mensaje Receptor. Compatible con sandbox y producción.

Empezá en 2 minutos

Opción 1: SDK (para desarrolladores)

npm install @dojocoding/hacienda-sdk

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

// 1. Crear el cliente
const client = new HaciendaClient({
  environment: "sandbox",
  credentials: {
    idType: "02", // Cédula Jurídica
    idNumber: "3101234567",
    password: process.env.HACIENDA_PASSWORD!,
  },
});

// 2. Autenticarse
await client.authenticate();

// 3. Generar la clave numérica
const clave = client.buildClave({
  date: new Date(),
  taxpayerId: "3101234567",
  documentType: DocumentType.FACTURA_ELECTRONICA,
  sequence: 1,
  situation: Situation.NORMAL,
});

// 4. Construir XML, firmar y enviar (ver ejemplo completo abajo)

Opción 2: CLI (para facturar desde la terminal)

npm install -g @dojocoding/hacienda-cli

# Autenticarse
hacienda auth login --cedula-type 02 --cedula 3101234567

# Crear borrador interactivo
hacienda draft --interactive

# Validar antes de enviar
hacienda validate factura.json

# Enviar (vista previa primero)
hacienda submit factura.json --dry-run

# Consultar contribuyente
hacienda lookup 3101234567

Opción 3: MCP Server (para asistentes de IA)

npm install -g @dojocoding/hacienda-mcp
hacienda-mcp

Le podés decir a Claude: _"Creá una factura de Mi Empresa S.A. (cédula 3101234567) a Cliente S.R.L. (cédula 3109876543) por 2 horas de consultoría a ₡50.000 cada una con IVA del 13%."_

Tipos de comprobante soportados

Tabla de contenidos

• SDK — Documentación completa

- HaciendaClient - Autenticación OAuth2 - Creación de documentos - Cálculo de IVA - Clave numérica - Firma digital XAdES-EPES - Envío y consulta de estado - Consulta de contribuyentes - Gestión de configuración - Logging estructurado - Manejo de errores

• CLI — Referencia de comandos
• MCP Server — Integración con IA
• Desarrollo
• Licencia

SDK — Documentación completa

HaciendaClient

El punto de entrada principal. Orquesta autenticación, generación de claves y operaciones con la API.

import { HaciendaClient } from "@dojocoding/hacienda-sdk";

const client = new HaciendaClient({
  // Requerido
  environment: "sandbox", // "sandbox" | "production"
  credentials: {
    idType: "02", // "01"=Física, "02"=Jurídica, "03"=DIMEX, "04"=NITE
    idNumber: "3101234567", // Cédula de 9-12 dígitos
    password: process.env.HACIENDA_PASSWORD!,
  },

  // Opcional
  p12Path: "/ruta/al/certificado.p12", // Para firma digital
  p12Pin: process.env.HACIENDA_P12_PIN, // PIN del .p12
  fetchFn: customFetch, // Implementación fetch personalizada
});

Las opciones se validan al instanciar con Zod. Si algo está mal, lanza ValidationError con detalles claros.

Autenticación OAuth2

Hacienda usa OAuth2 ROPC (Resource Owner Password Credentials). El SDK maneja todo el ciclo de vida del token automáticamente.

// Autenticarse (obtiene access + refresh token)
await client.authenticate();

// Verificar estado
console.log(client.isAuthenticated); // true

// Obtener token válido (refresca automáticamente si expiró)
const token = await client.getAccessToken();

// Forzar re-autenticación
client.invalidate();
await client.authenticate();

Ciclo de vida del token:

• Access token expira en ~5 minutos (se cachea en memoria, se refresca 30s antes)
• Refresh token dura ~10 horas
• getAccessToken() maneja el refresh de forma transparente

Ambientes de Hacienda:

Creación de documentos

Ejemplo completo de una Factura Electrónica — el flujo es igual para los demás tipos:

import {
  buildFacturaXml,
  calculateLineItemTotals,
  calculateInvoiceSummary,
  buildClave,
  DocumentType,
  Situation,
} from "@dojocoding/hacienda-sdk";
import type { LineItemInput } from "@dojocoding/hacienda-sdk";

// 1. Definir las líneas de detalle
const lineas: LineItemInput[] = [
  {
    numeroLinea: 1,
    codigoCabys: "8310100000000", // Código CABYS (13 dígitos)
    cantidad: 2,
    unidadMedida: "Unid",
    detalle: "Servicios de desarrollo web",
    precioUnitario: 50000,
    esServicio: true,
    impuesto: [
      {
        codigo: "01", // IVA
        codigoTarifa: "08", // Tarifa general 13%
        tarifa: 13,
      },
    ],
  },
  {
    numeroLinea: 2,
    codigoCabys: "4321000000000",
    cantidad: 1,
    unidadMedida: "Unid",
    detalle: "Laptop",
    precioUnitario: 500000,
    esServicio: false,
    impuesto: [
      {
        codigo: "01",
        codigoTarifa: "08",
        tarifa: 13,
      },
    ],
    descuento: [
      {
        montoDescuento: 25000,
        naturalezaDescuento: "Descuento por volumen",
      },
    ],
  },
];

// 2. Calcular totales por línea (agrega montoTotal, subTotal, impuestoNeto, etc.)
const lineasCalculadas = lineas.map(calculateLineItemTotals);

// 3. Calcular resumen de factura (ResumenFactura)
const resumen = calculateInvoiceSummary(lineasCalculadas);

// 4. Generar la clave numérica
const clave = buildClave({
  date: new Date(),
  taxpayerId: "3101234567",
  documentType: DocumentType.FACTURA_ELECTRONICA,
  sequence: 1,
  situation: Situation.NORMAL,
});

// 5. Consecutivo
const numeroConsecutivo = "00100001010000000001";

// 6. Armar la factura y generar XML
const factura = {
  clave,
  codigoActividad: "620100",
  numeroConsecutivo,
  fechaEmision: new Date().toISOString(),
  emisor: {
    nombre: "Mi Empresa S.A.",
    identificacion: { tipo: "02", numero: "3101234567" },
    correoElectronico: "facturacion@miempresa.co.cr",
  },
  receptor: {
    nombre: "Cliente S.R.L.",
    identificacion: { tipo: "02", numero: "3109876543" },
    correoElectronico: "pagos@cliente.co.cr",
  },
  condicionVenta: "01", // Contado
  medioPago: ["01"], // Efectivo
  detalleServicio: lineasCalculadas,
  resumenFactura: resumen,
};

const xml = buildFacturaXml(factura);

Validación de XML:

import { validateFacturaInput } from "@dojocoding/hacienda-sdk";

const resultado = validateFacturaInput(datosFactura);
if (!resultado.valid) {
  for (const err of resultado.errors) {
    console.error(`${err.path}: ${err.message}`);
  }
}

Cálculo de IVA

Utilidades para calcular impuestos, totales por línea y resúmenes según la normativa de Hacienda. Todos los montos se redondean a 5 decimales.

import { round5, calculateLineItemTotals, calculateInvoiceSummary } from "@dojocoding/hacienda-sdk";
import type { LineItemInput, CalculatedLineItem, InvoiceSummary } from "@dojocoding/hacienda-sdk";

const item: LineItemInput = {
  numeroLinea: 1,
  codigoCabys: "8310100000000",
  cantidad: 3,
  unidadMedida: "Sp",
  detalle: "Horas de consultoría",
  precioUnitario: 75000,
  esServicio: true,
  impuesto: [{ codigo: "01", codigoTarifa: "08", tarifa: 13 }],
};

const calculado: CalculatedLineItem = calculateLineItemTotals(item);
// calculado.montoTotal      = 225000       (3 × ₡75.000)
// calculado.subTotal        = 225000       (sin descuentos)
// calculado.impuestoNeto    = 29250        (₡225.000 × 13%)
// calculado.montoTotalLinea = 254250       (₡225.000 + ₡29.250)

const resumen: InvoiceSummary = calculateInvoiceSummary([calculado]);
// resumen.totalServGravados  = 225000
// resumen.totalImpuesto      = 29250
// resumen.totalComprobante   = 254250

Exoneraciones de IVA:

const itemExonerado: LineItemInput = {
  // ...campos base
  impuesto: [
    {
      codigo: "01",
      codigoTarifa: "08",
      tarifa: 13,
      exoneracion: {
        tipoDocumento: "01",
        numeroDocumento: "AL-001-2025",
        nombreInstitucion: "MEIC",
        fechaEmision: "2025-01-01T00:00:00",
        porcentajeExoneracion: 100,
      },
    },
  ],
};

Tarifas de IVA soportadas: 0%, 1%, 2%, 4%, 8%, 13%

Clave numérica

Cada comprobante electrónico requiere una clave numérica única de 50 dígitos. El SDK la genera y parsea automáticamente.

Estructura: [506][DDMMYY][cédula 12 dígitos][sucursal 3][terminal 5][tipo doc 2][consecutivo 10][situación 1][código seguridad 8]

import { buildClave, parseClave, DocumentType, Situation } from "@dojocoding/hacienda-sdk";

// Generar clave
const clave = buildClave({
  date: new Date("2025-07-15"),
  taxpayerId: "3101234567",
  documentType: DocumentType.FACTURA_ELECTRONICA,
  sequence: 42,
  situation: Situation.NORMAL,
  branch: "001", // Opcional, default "001"
  pos: "00001", // Opcional, default "00001"
});
// => "50615072500310123456700100001010000000042112345678"

// Parsear clave existente
const parsed = parseClave(clave);
// parsed.countryCode   => "506"
// parsed.date          => Date(2025-07-15)
// parsed.taxpayerId    => "003101234567"
// parsed.documentType  => "01"
// parsed.sequence      => 42
// parsed.situation     => "1"
// parsed.securityCode  => "12345678"

Códigos de situación:

• 1 Normal (envío estándar en línea)
• 2 Contingencia (fallo del sistema de Hacienda)
• 3 Sin Internet (fuera de línea)

Firma digital XAdES-EPES

Todo XML enviado a Hacienda debe estar firmado con XAdES-EPES usando el certificado .p12 del contribuyente (RSA 2048 + SHA-256). El SDK maneja todo el proceso de firma.

import { readFileSync } from "node:fs";
import { signXml, signAndEncode, loadP12 } from "@dojocoding/hacienda-sdk";

const p12Buffer = readFileSync("/ruta/al/certificado.p12");
const pin = process.env.HACIENDA_P12_PIN!;

// Firmar XML (retorna XML firmado como string)
const xmlFirmado = await signXml(xml, p12Buffer, pin);

// Firmar y codificar en Base64 (listo para enviar a la API)
const xmlBase64 = await signAndEncode(xml, p12Buffer, pin);

// Cargar .p12 para inspeccionar el certificado
const credenciales = await loadP12(p12Buffer, pin);
// credenciales.privateKey      — CryptoKey para firma
// credenciales.certificateDer  — Certificado codificado en DER

Envío y consulta de estado

Opción simplificada — submitAndWait (recomendada):

Envía el documento y espera a que Hacienda lo procese. Maneja el polling automáticamente.

import { submitAndWait, HttpClient } from "@dojocoding/hacienda-sdk";

const httpClient = new HttpClient({
  baseUrl: "https://api.comprobanteselectronicos.go.cr/recepcion-sandbox/v1",
  getToken: () => client.getAccessToken(),
});

const resultado = await submitAndWait(
  httpClient,
  {
    clave: "50601...",
    fecha: new Date().toISOString(),
    emisor: {
      tipoIdentificacion: "02",
      numeroIdentificacion: "3101234567",
    },
    comprobanteXml: xmlBase64Firmado,
  },
  {
    pollIntervalMs: 3000, // Consultar cada 3 segundos (default)
    timeoutMs: 60000, // Timeout a 60 segundos (default)
    onPoll: (status, intento) => {
      console.log(`Intento ${intento}: ${status.status}`);
    },
  },
);

if (resultado.accepted) {
  console.log("¡Comprobante aceptado por Hacienda!");
} else {
  console.log("Rechazado:", resultado.rejectionReason);
}

Opción granular — control total:

import { submitDocument, getStatus, isTerminalStatus } from "@dojocoding/hacienda-sdk";

// Enviar
const response = await submitDocument(httpClient, solicitud);

// Consultar estado
const status = await getStatus(httpClient, "50601...");
if (isTerminalStatus(status.status)) {
  console.log("Estado final:", status.status);
}

Listar y consultar comprobantes:

import { listComprobantes, getComprobante } from "@dojocoding/hacienda-sdk";

const lista = await listComprobantes(httpClient, {
  offset: 0,
  limit: 10,
  fechaEmisionDesde: "2025-01-01",
  fechaEmisionHasta: "2025-12-31",
});

const detalle = await getComprobante(httpClient, "50601...");

Reintentos con backoff exponencial:

import { withRetry } from "@dojocoding/hacienda-sdk";

const resultado = await withRetry(() => submitDocument(httpClient, solicitud), {
  maxAttempts: 3,
  delayMs: 1000,
  backoff: "exponential",
});

Consulta de contribuyentes

Buscá información de cualquier contribuyente usando la API pública de actividades económicas de Hacienda (no requiere autenticación):

import { lookupTaxpayer } from "@dojocoding/hacienda-sdk";

const info = await lookupTaxpayer("3101234567");
console.log(info.nombre); // "MI EMPRESA S.A."
console.log(info.tipoIdentificacion); // "02"
for (const actividad of info.actividades) {
  console.log(`${actividad.codigo}: ${actividad.descripcion} (${actividad.estado})`);
}

Gestión de configuración

La configuración se almacena en ~/.hacienda-cr/config.toml con soporte para múltiples perfiles (ej: sandbox, producción, distintas empresas).

import {
  loadConfig,
  saveConfig,
  listProfiles,
  deleteProfile,
  getNextSequence,
  resetSequence,
} from "@dojocoding/hacienda-sdk";

// Guardar un perfil
await saveConfig(
  {
    environment: "sandbox",
    cedula_type: "02",
    cedula: "3101234567",
    p12_path: "/ruta/al/certificado.p12",
  },
  "miempresa",
);

// Cargar un perfil
const config = await loadConfig("miempresa");

// Listar perfiles
const perfiles = await listProfiles();

// Eliminar un perfil
await deleteProfile("perfil-viejo");

// Gestión de consecutivos (numeración automática)
const consecutivo = await getNextSequence("02", "3101234567", "01", "001", "00001");
await resetSequence("02", "3101234567", "01", "001", "00001");

Seguridad: Las contraseñas y PINs nunca se almacenan en archivos de configuración. Siempre van por variables de entorno:

• HACIENDA_PASSWORD — Contraseña del IDP
• HACIENDA_P12_PIN — PIN del certificado .p12

Logging estructurado

Logger integrado con niveles configurables y soporte para JSON (ideal para producción).

import { Logger, LogLevel, noopLogger } from "@dojocoding/hacienda-sdk";

const logger = new Logger({
  level: LogLevel.DEBUG, // DEBUG, INFO, WARN, ERROR, SILENT
  format: "text", // "text" | "json"
  context: "mi-app",
});

logger.debug("Token refrescado", { expiresIn: 300 });
logger.info("Comprobante enviado", { clave: "50601..." });
logger.warn("Rate limit acercándose");
logger.error("Envío falló", { statusCode: 500 });

// Logger silencioso (suprime toda salida)
const silencioso = noopLogger;

Manejo de errores

Todos los errores del SDK extienden HaciendaError para un manejo uniforme:

import {
  HaciendaError,
  ValidationError,
  ApiError,
  AuthenticationError,
  SigningError,
} from "@dojocoding/hacienda-sdk";

try {
  await client.authenticate();
  const xml = buildFacturaXml(factura);
  const firmado = await signAndEncode(xml, p12, pin);
  const resultado = await submitAndWait(httpClient, solicitud);
} catch (err) {
  if (err instanceof ValidationError) {
    // Fallo de validación (esquema Zod o reglas de negocio)
    console.error("Validación:", err.message, err.details);
  } else if (err instanceof AuthenticationError) {
    // Fallo de autenticación o ciclo de vida del token
    console.error("Auth:", err.message);
  } else if (err instanceof SigningError) {
    // Fallo de firma XAdES-EPES (certificado malo, PIN incorrecto, etc.)
    console.error("Firma:", err.message);
  } else if (err instanceof ApiError) {
    // Error HTTP/red de la API de Hacienda
    console.error("API:", err.message, err.statusCode, err.responseBody);
  } else if (err instanceof HaciendaError) {
    // Cualquier otro error del SDK
    console.error(`[${err.code}]`, err.message);
  }
}

Códigos de error (HaciendaErrorCode):

CLI — Referencia de comandos

npm install -g @dojocoding/hacienda-cli

Todos los comandos soportan --json para salida legible por máquinas.

hacienda auth login

Autenticarse con el IDP de Hacienda y guardar el perfil.

hacienda auth login \
  --cedula-type 02 \
  --cedula 3101234567 \
  --environment sandbox \
  --profile default

# Contraseña por variable de entorno (recomendado)
export HACIENDA_PASSWORD="tu-contraseña"
hacienda auth login --cedula-type 02 --cedula 3101234567

hacienda auth status

Mostrar estado actual de autenticación.

hacienda auth status
hacienda auth status --profile produccion
hacienda auth status --json

hacienda auth switch

Cambiar entre perfiles de autenticación.

hacienda auth switch            # Listar perfiles disponibles
hacienda auth switch produccion # Cambiar a un perfil específico

hacienda submit

Enviar un comprobante electrónico a Hacienda.

hacienda submit factura.json --dry-run   # Vista previa del XML
hacienda submit factura.json             # Enviar de verdad
hacienda submit factura.json --json      # Salida JSON

hacienda status

Consultar el estado de procesamiento de un comprobante por su clave.

hacienda status 50601012400310123456700100001010000000001199999999

hacienda list

Listar comprobantes recientes desde Hacienda.

hacienda list
hacienda list --limit 50 --offset 0
hacienda list --json

hacienda get

Obtener detalle completo de un comprobante por su clave.

hacienda get 50601012400310123456700100001010000000001199999999

hacienda sign

Firmar un documento XML con certificado .p12 (XAdES-EPES).

hacienda sign factura.xml --p12 cert.p12 --pin 1234 --output firmado.xml
hacienda sign factura.xml --p12 cert.p12 --pin 1234  # stdout

# Con variables de entorno
export HACIENDA_P12_PATH=/ruta/al/cert.p12
export HACIENDA_P12_PIN=1234
hacienda sign factura.xml --output firmado.xml

hacienda validate

Validar un archivo de factura (JSON o XML) contra esquemas y reglas de negocio.

hacienda validate factura.json
hacienda validate documento.xml
hacienda validate factura.json --json

hacienda lookup

Consultar actividades económicas de un contribuyente por cédula (sin autenticación).

hacienda lookup 3101234567
hacienda lookup 3101234567 --json

hacienda draft

Crear interactivamente un borrador de factura JSON para envío.

hacienda draft                                       # Modo interactivo
hacienda draft --no-interactive                      # Plantilla en blanco
hacienda draft --template nota-credito --output nc.json

Plantillas: factura (default), nota-credito, nota-debito, tiquete

Variables de entorno

MCP Server — Integración con IA

El paquete @dojocoding/hacienda-mcp expone el SDK como servidor MCP (Model Context Protocol), permitiendo que asistentes de IA emitan facturas electrónicas de forma conversacional.

Configuración con Claude Desktop

Agregá esto al claude_desktop_config.json:

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

Herramientas disponibles

Recursos disponibles

Desarrollo

Requisitos previos

• Node.js 22+ (usa fetch y crypto.subtle nativos)
• pnpm 9+

Comenzar

git clone https://github.com/DojoCodingLabs/hacienda-cr.git
cd hacienda-cr
pnpm install
pnpm build
pnpm test
pnpm lint
pnpm typecheck

Estructura del proyecto

hacienda-cr/
├── packages/
│   ├── sdk/       # @dojocoding/hacienda-sdk — Core: auth, XML, firma, API
│   ├── cli/       # @dojocoding/hacienda-cli — Binario `hacienda` (citty)
│   └── mcp/       # @dojocoding/hacienda-mcp — Servidor MCP
├── shared/        # @dojocoding/hacienda-shared — Tipos, constantes, enums compartidos
├── turbo.json     # Configuración de Turborepo
├── vitest.workspace.ts
└── pnpm-workspace.yaml

Construir paquetes individuales

pnpm --filter @dojocoding/hacienda-sdk build
pnpm --filter @dojocoding/hacienda-sdk test
pnpm --filter @dojocoding/hacienda-sdk test clave.spec.ts

Stack tecnológico

Contribuir

1. Hacé fork del repositorio
2. Creá un branch (git checkout -b feature/mi-feature)
3. Hacé tus cambios con tests
4. Ejecutá pnpm test && pnpm lint && pnpm typecheck
5. Abrí un pull request

Convenciones:

• Archivos: kebab-case.ts
• Tipos/Clases: PascalCase
• Funciones/Variables: camelCase
• Constantes: UPPER_SNAKE_CASE

Agradecimientos

Este proyecto se construye sobre el trabajo pionero de la comunidad open-source costarricense:

• CRLibre/API_Hacienda — La API open-source original para facturación electrónica en Costa Rica (PHP). Su documentación, diagramas de flujo y recursos comunitarios fueron referencias invaluables para entender la API de Hacienda. Gracias a toda la comunidad CRLibre por hacer la facturación electrónica accesible para los desarrolladores ticos.
• CRLibre/fe-hacienda-cr-misc — Recursos compartidos y documentación para facturación electrónica en Costa Rica.

Licencia

MIT

Construido por Dojo Coding

Herramientas open-source para desarrolladores costarricenses 🇨🇷