En Costa Rica todo restaurante o comercio que emita factura está obligado a usar facturación electrónica con Hacienda. La pregunta no es si integrar, es cómo hacerlo sin que tu POS rechace comprobantes y sin descubrir a los seis meses que tu cola de envío genera duplicados.
Esta guía es la versión técnica + pricing realista de cómo cotizamos en Sirius la integración con Hacienda para restaurantes, sodas y cualquier punto de venta que emita comprobantes. Si necesitas el rango exacto ya, pasa al cotizador — 4 preguntas, 30 segundos.
💡 TL;DR: USD 2 500 (básico: emitir + firmar + enviar) a USD 4 500 (con notas de crédito, exoneraciones, cola asíncrona, retries). 2–3 semanas. Las cuatro decisiones que importan: tipo de comprobante, certificado propio vs BSP, cola sincrónica vs asíncrona, manejo de rechazos 4xx.
Por qué importa y cuándo es obligatoria
Desde que Hacienda completó la migración al régimen de comprobantes electrónicos, cualquier contribuyente que emita un comprobante debe hacerlo electrónicamente: restaurantes, comercios, servicios profesionales y ecommerce.
Las multas por no emitir o emitir mal van desde 1 salario base por comprobante con error hasta cierres temporales en casos de reincidencia. Más allá de la multa, un cliente corporativo no te paga sin factura electrónica — hoteles, hospitales y empresas grandes te exigen comprobante completo con cédula jurídica.
La integración no es opcional, pero cómo la integras sí: puedes pagar un proveedor USD 100/mes, usar un POS comercial que lo trae incluido por USD 30–80/mes, o integrarlo en tu sistema custom. Cada opción tiene tradeoffs.
Cómo funciona el sistema de Hacienda
Cuatro componentes que necesitas entender antes de codificar.
1. ATV (Administración Tributaria Virtual)
Es el portal web de Hacienda en atv.hacienda.go.cr. Ahí registras el emisor, generas las claves criptográficas (.p12 + clave), consultas comprobantes y declaras IVA mensual. Cada emisor tiene un .p12 que firma criptográficamente cada XML, rota cada 4 años. Sin ese .p12 y su clave, tu sistema no puede emitir nada.
2. Estructura del XML
El comprobante electrónico v4.4 sigue un esquema XSD publicado por Hacienda. Cada comprobante tiene:
- Clave numérica de 50 dígitos: país (506) + fecha (DDMMAA) + cédula del emisor (12 dígitos) + sucursal + terminal + tipo + consecutivo + situación + código de seguridad.
- Encabezado: emisor, receptor (si aplica), fecha y hora.
- Detalle de línea: código, descripción, cantidad, precio unitario, IVA (1 %, 2 %, 4 %, 8 % o 13 %), total.
- Resumen: totales gravados, exentos, exonerados, impuestos, total comprobante.
- Información de referencia (necesaria para notas de crédito/débito).
- Bloque de firma XAdES-BES.
Un dígito mal = rechazo y el comprobante no es válido.
3. Firma digital XAdES-BES
El XML se firma en modo enveloped — la firma queda dentro como nodo <ds:Signature> con hash SHA-256, certificado X.509, RSA-SHA256, política de firma y timestamp.
Implementaciones probadas: la oficial en Java de Hacienda, xml-crypto + node-forge en Node.js, librerías nativas de .NET. La firma falla silenciosamente si la cadena de certificados está mal armada — siempre prueba contra staging antes.
4. API REST de envío y consulta
Tres endpoints relevantes:
POST /recepcion— envías el XML firmado en base64. Responde 202 o error.GET /recepcion/{clave}— consultas estado: "aceptado", "rechazado" o "procesando".GET /recepcion/{clave}/recibo— descargas el mensaje de confirmación.
Autenticación OAuth 2.0: con usuario + password generas access_token vigente 5 minutos.
Pricing realista: USD 2 500 – 4 500
El precio depende de qué tan completo necesitas el módulo. Acá el desglose por feature concreto:
| Feature | Costo USD | Tiempo |
|---|---|---|
| Setup base (ATV, .p12, OAuth, conectividad staging/prod) | 400 – 600 | 3 días |
| Generación de XML v4.4 (encabezado, líneas, totales) | 600 – 900 | 4 días |
| Firma XAdES-BES con node-forge / Java / .NET | 400 – 700 | 3 días |
Cola asíncrona + worker (BullMQ, SQS, o tabla pending) |
400 – 600 | 3 días |
| Retries con backoff + manejo de timeouts | 200 – 400 | 2 días |
| Notas de crédito y débito (referencias) | 300 – 500 | 2 días |
| Exoneraciones (RUT y vigencia) | 300 – 500 | 2 días |
| Manejo de códigos de error 4xx con notificaciones | 200 – 400 | 2 días |
| Generación de PDF + QR + envío por correo | 300 – 500 | 2 días |
| Tests automatizados + monitoreo de cola | 200 – 400 | 2 días |
| Total integración básica | 2 500 | 2 sem |
| Total integración completa | 4 500 | 3 sem |
Qué incluye USD 2 500 (básica)
Emisión de tiquete y factura, firma XAdES-BES contra producción, cola sincrónica con retry simple (3 intentos), generación de PDF con QR, envío automático por correo y 30 días de soporte.
Qué agrega llegar a USD 4 500
- Notas de crédito y débito con referencias al comprobante original.
- Exoneraciones — consulta del padrón, autoridad reguladora, vigencia.
- Cola asíncrona robusta — BullMQ o SQS, dashboard, reprocesar manualmente.
- Manejo granular de errores 4xx — diccionario completo de códigos + acción (corregir, anular, escalar).
- Reprocesamiento masivo después de downtime de Hacienda.
- Reportería tributaria — exporte mensual para el contador.
- Multi-sucursal — consecutivos independientes por terminal.
Si tu restaurante tiene una sola sucursal, < 50 tiquetes diarios y no manejas exoneraciones, la básica te alcanza. Si eres una cadena, atiendes empresas con exoneración o manejas devoluciones frecuentes, necesitas la completa.
Para ver cómo este módulo encaja en el costo total, el pillar de pricing tiene el desglose: USD 2 500–4 500 para el POS base + USD 2 500–4 500 de facturación = USD 5 000–9 000 para un restaurante completo. Casos y stack en /servicios/restaurants.
Las 4 decisiones técnicas que importan
Decisión 1: comprobante completo vs tiquete electrónico
La factura electrónica lleva datos del receptor (nombre, cédula, correo) y se usa cuando el cliente la pide para deducir impuestos o es B2B. El tiquete es la versión simplificada para consumidor final.
Tu sistema debe permitir ambos. El flujo típico es 90 % tiquete, 10 % factura. Diseña el UI para que el mesero cambie de tiquete a factura con un solo tap y capture cédula/correo en el momento. Forzar siempre factura completa con cédula del cliente final genera errores de tipeo masivos.
Decisión 2: certificado propio (.p12) vs proveedor BSP
Con certificado propio gestionas el .p12 directamente; costo marginal por comprobante = cero. Con un BSP (Business Service Provider) pagan USD 0.05–0.15 por comprobante o suscripción de USD 30–80/mes.
- < 500 comprobantes/día + equipo técnico: certificado propio sale más barato a 12 meses.
- 2 000+ comprobantes/día o sin equipo técnico: BSP simplifica.
- Restaurante chico (< 100/día) que quiere máxima simplicidad: BSP por USD 30/mes es razonable.
En Sirius cotizamos por defecto certificado propio porque el cliente tiene control y elimina dependencia mensual.
Decisión 3: cola sincrónica vs asíncrona
Sincrónica: en el momento del cobro, el sistema firma y envía a Hacienda. Más simple, pero si Hacienda tarda 8 segundos el cliente espera 8 segundos, y si está caída no se puede cobrar.
Asíncrona (recomendada): el sistema imprime el tiquete inmediatamente con estado "pendiente". Un worker en background firma, envía y actualiza. Cliente no espera, soporta caídas de Hacienda. Requiere cola (BullMQ, SQS, o tabla pending_invoices) y dashboard.
Para un POS de restaurante en producción, siempre asíncrono.
Decisión 4: manejo de errores 4xx
Hacienda devuelve códigos específicos:
- Clave duplicada → no reintentes; genera nueva clave.
- RUT inexistente del receptor → notifica al usuario; permite corregir.
- IVA mal calculado → bug en tu sistema; alerta crítica al admin.
- Comprobante ya anulado → ignora silenciosamente.
- Timeout / 503 → reintenta con backoff exponencial.
Reintentos ciegos sin diagnóstico generan duplicados y multas. Tu sistema debe tener un diccionario código → acción, y cualquier código desconocido se escala al admin, no se reintenta automáticamente.
HowTo paso a paso
Registrar emisor en ATV. Entra a
atv.hacienda.go.cr, registra el emisor, define actividades económicas (5610 para restaurantes) y descarga el .p12. Anota la clave.Generar token OAuth y validar conectividad. Genera el access_token (vigente 5 min) y hace un
curlmanual contra staging para confirmar 200 antes de codificar nada.Construir el XML v4.4. Descarga el XSD oficial. Genera clave de 50 dígitos, encabezado completo, líneas con IVA bien calculado, totales que cuadren bit a bit, e información de referencia para notas de crédito/débito.
Firmar con XAdES-BES. Usa el .p12 para firmar el XML como nodo
<ds:Signature>embedded. Siempre prueba contra staging antes de producción.Encolar el envío. No envíes inline en la transacción del POS. Encolalo en
pending_invoiceso job queue. Worker dedicado con backoff exponencial (5s, 30s, 2min, 10min, 1h).Manejar aceptación o rechazo. Hacienda devuelve 202 en el POST; en 5–60 segundos consultas estado vía GET. Solo con "aceptado" generas el PDF.
Generar PDF y enviarlo. Genera el PDF con datos del XML, QR de validación pública y respuesta del Ministerio. Envías por correo o imprimes en térmica 80mm.
Errores comunes que vemos en producción
Clave numérica mal armada. El consecutivo debe ser único por tipo de comprobante y por terminal. Equipos que comparten consecutivo generan duplicados. Solución: contador secuencial por terminal con bloqueo transaccional.
Reintentos infinitos en error 4xx. 503 es retry, 4xx es diagnosticar y corregir. Sistemas que reintentan 4xx mandan 50 veces el mismo XML rechazado. Solución: diccionario código → acción explícita; código desconocido = alerta al admin.
Redondeos de IVA. El IVA se calcula por línea, no sobre el total. Si redondeas al final, no cuadra. Solución: IVA por línea con 5 decimales, redondea a 2, suma redondeados.
Certificado vencido. El .p12 vence cada 4 años; si está hardcoded en disco, vence sin aviso. Solución: monitorea expiración en observabilidad, alerta 30 días antes, carga desde secret manager.
No manejar el modo offline. Si tu POS no puede emitir cuando cae internet, el negocio para. Solución: imprime el tiquete con estado "pendiente"; el worker lo sincroniza cuando vuelve conexión.
PDF mal generado. Hacienda no genera el PDF — lo genera tu sistema con datos del XML. Solución: genera el PDF al recibir aceptación; inspecciona uno por sucursal la primera semana.
No manejar contribuyente extranjero. Un cliente extranjero usa pasaporte, no cédula. Solución: soporta los tres tipos (cédula nacional, jurídica, pasaporte) desde el día 1.
Cómo encaja esto en el costo total de tu sistema
Si estás cotizando un sistema de restaurante completo, la facturación electrónica es un módulo del proyecto. Para entender el desglose total:
- POS web básico (menú, comandas, reportes diarios): USD 2 500–4 500. Detalle en el pillar de pricing.
- Reservas online + WhatsApp: + USD 800–1 500.
- Facturación electrónica con Hacienda (este módulo): + USD 2 500–4 500.
- Inventario de cocina: + USD 2 000–4 000.
Para un restaurante mediano que necesita POS + facturación electrónica + reservas, el rango total es USD 5 800–10 500. Ver casos reales y stack en /servicios/restaurants.
💡 Si necesitas el rango exacto para tu caso, pasa por el cotizador. 4 preguntas, 30 segundos, te da el rango USD con mensaje de WhatsApp pre-cargado.
En resumen
| Componente | Costo USD | Tiempo |
|---|---|---|
| Setup ATV + .p12 + OAuth | 400 – 600 | 3 días |
| Generación XML v4.4 | 600 – 900 | 4 días |
| Firma XAdES-BES | 400 – 700 | 3 días |
| Cola + worker + retries | 600 – 1 000 | 5 días |
| Notas crédito/débito + exoneraciones | 600 – 1 000 | 4 días |
| PDF + QR + envío por correo | 300 – 500 | 2 días |
| Total módulo facturación electrónica | 2 500 – 4 500 | 2 – 3 semanas |
Si tu proyecto cae fuera de estos rangos, conversémoslo. La cotización inicial es gratis, escrita, y no compromete a nada.
💡 Para una cotización aproximada en 30 segundos, usa el cotizador interactivo. 4 preguntas → rango USD + mensaje de WhatsApp con tu scope pre-cargado.
📞 Para hablar directo: WhatsApp +506 8433 7752 o admin@siriusx.net. Lunes a viernes 8 am–5 pm, sábados 8 am–12 md, hora CR.
Posts relacionados
- Cuánto cuesta desarrollar software en Costa Rica en 2026 — pillar completo de pricing por tipo y vertical.
- Cronograma de un MVP en 6 semanas — cómo se planifica un proyecto con facturación electrónica desde la semana 1.
- Servicios para restaurantes — casos reales, stack y cómo lo armamos.
