Sandbox de Hacienda: cómo probar la factura electrónica sin emitir de verdad

Respuesta corta: el sandbox es el ambiente de pruebas oficial de Hacienda: los comprobantes se firman, se envían y reciben un veredicto real (aceptado o rechazado), pero no tienen valor fiscal y llevan una numeración separada de la de producción. En Facturaencr lo usás gratis, con 100 comprobantes al mes, y podés empezar sin certificado propio con el emisor de pruebas EMISORPRUEBA.

Probar en sandbox es la diferencia entre descubrir un rechazo en tu escritorio o en la caja de un cliente. Esta guía explica qué es, cómo se usa y —lo menos conocido— qué cosas el sandbox no valida igual que producción.

Sandbox y producción, lado a lado

	Sandbox	Producción
Destino	Ambiente de pruebas oficial de Hacienda	Hacienda producción
Valor fiscal	Ninguno	Sí: es un comprobante real
Certificado	.p12 de pruebas	.p12 de producción
Numeración	Serie propia, separada	Tu serie fiscal real
Costo en Facturaencr	Gratis, 100 comprobantes al mes	Por documento emitido

Un certificado de pruebas no puede emitir en producción ni al revés: la combinación se valida antes de firmar.

Cómo se elige el ambiente

En la API de Facturaencr hay una sola URL base (https://api.facturaencr.com/v2/efactura). El ambiente no se elige por subdominio ni por parámetro: lo decide el campo environment de la llave de API que usás.

Eso tiene una consecuencia práctica: la misma petición, con otra llave, emite de verdad. Antes de mover algo a producción, confirmá qué llave tiene cargada tu aplicación:

curl -X POST https://api.facturaencr.com/v2/efactura/auth/verify \
  -H "X-API-Key: $EFACTURA_KEY" \
  -H "X-API-Secret: $EFACTURA_SECRET"
# → "apiKey": { "environment": "sandbox", ... }

Dos formas de probar

1. Con el emisor de pruebas (sin certificado)

Conseguir el .p12 de pruebas y las credenciales de Hacienda toma su tiempo. Para no frenar la integración, cada cuenta tiene habilitado un emisor de pruebas de la plataforma. Lo usás poniendo "emisorLegalId": "EMISORPRUEBA" y nada más:

curl -X POST https://api.facturaencr.com/v2/efactura/documents/tiquete \
  -H "X-API-Key: $EFACTURA_KEY" -H "X-API-Secret: $EFACTURA_SECRET" \
  -H "Idempotency-Key: prueba-0001" -H "Content-Type: application/json" \
  -d '{ "emisorLegalId": "EMISORPRUEBA", "condicionVenta": "01", "medioPago": ["01"],
        "detalle": [{ "codigoCabys": "2999999999007", "cantidad": 1, "unidadMedida": "Unid",
                      "detalle": "Producto de prueba", "precioUnitario": 1000,
                      "impuesto": [{ "codigo": "01", "codigoTarifa": "08", "tarifa": 13 }] }] }'

Es una emisión real contra el sandbox de Hacienda, no un simulador. Tiene tres límites: la numeración la asigna la plataforma (cada cuenta recibe su propia sucursal y terminal), el XML firmado no se descarga y en el PDF la identidad del emisor sale tapada. Cuando subís tu propio certificado para tu cédula, la API usa el tuyo sin que cambies una línea.

2. Con tu certificado de pruebas

Generás la llave criptográfica de pruebas en Hacienda, la subís con su PIN y tus credenciales de pruebas, y emitís con tu cédula. Así probás exactamente tu configuración: actividad económica, ubicación, sucursales y numeración. Cómo sacar esa llave está en la llave criptográfica de pruebas de Hacienda.

Las pruebas no tocan tu numeración real: cada ambiente lleva su propia serie por sucursal, terminal y tipo de comprobante.

Lo que el sandbox NO valida igual que producción

Esto lo aprendimos emitiendo, y vale la pena saberlo antes de perseguir un error que no existe:

Exoneraciones de Hacienda (tipos 04 y 11). El sandbox no tiene la base de exoneraciones autorizadas: rechaza con -125 toda exoneración de esos tipos, incluso autorizaciones reales y vigentes. Lo verificamos con números reales e inventados, y el resultado fue el mismo. Una exoneración de esos tipos no se puede probar en sandbox; sí otros tipos, como el 02 o el 03.

El aviso -37 de ubicación. Cuando provincia, cantón y distrito del emisor no coinciden con el padrón, Hacienda agrega el -37. Medido sobre 426 rechazos, apareció en 306, nunca como único motivo, y 301 de esos 306 eran de sandbox. Si lo ves, buscá el otro código del mensaje: ese es el que rechaza.

Un emisor «no inscrito» que sí lo está. Hay otro -37, con otro texto («condición diferente a Inscrito»), que sí rechaza solo. Lo vimos en sandbox con un contribuyente inscrito en producción: el padrón de pruebas iba desfasado. Leé el texto del mensaje, no solo el número.

El receptor sí se valida. Una factura a una cédula que no existe en el padrón sale rechazada con -38 también en sandbox. Para probar sin usar la cédula de un tercero, poné como receptor a tu propio emisor.

En sentido contrario, todo lo que es estructura y cálculo —esquema XSD, impuestos por línea, CABYS, referencias, pago mixto— se valida igual. Por eso un comprobante aceptado en sandbox es la mejor señal de que producción también lo va a aceptar.

Qué probar antes de pasar a producción

• Una factura y una nota de crédito que la referencia, las dos aceptadas.
• Todos los CABYS de tu catálogo existen (GET /catalogs/cabys).
• Ninguna línea sale con impuesto vacío.
• Idempotency-Key derivada de tu número de pedido.
• Webhook registrado y con la firma verificada.
• Sabés qué hace tu sistema ante un rejected.
• Guardás documentId, clave y consecutivo de cada emisión.

El paso a producción

Cuando la integración funciona en sandbox, subís el certificado de producción del comercio y cambiás la llave por una de producción: el código no cambia. Para integraciones por API, el paso a producción tiene un cobro único de ₡50.000 + IVA por integración, no por cliente: si tu sistema factura para veinte comercios, se paga una vez. Probar en sandbox es gratis siempre.

Preguntas frecuentes

¿Lo que emito en sandbox llega a Hacienda?

Sí, al ambiente de pruebas de Hacienda, que responde con un veredicto real. No tiene valor fiscal ni se declara.

¿El sandbox mueve mi consecutivo de producción?

No. Cada ambiente lleva su propia serie. La primera emisión de pruebas de un emisor arranca desde el número que ya tenía en producción, así que tampoco repite una clave.

¿Cuántos comprobantes de prueba puedo emitir?

En Facturaencr, 100 comprobantes al mes en el sandbox, gratis y sin tarjeta.

¿Puedo probar una exoneración en sandbox?

Las de tipo 02 o 03, sí. Las de tipo 04 y 11 las rechaza siempre el sandbox de Hacienda con -125, porque no tiene la base de autorizaciones.

Creá tu cuenta en la API de Facturaencr, generá una llave de sandbox y emití con EMISORPRUEBA en minutos. La documentación tiene ejemplos aceptados por Hacienda para cada comprobante, y tu primera factura por API te lleva paso a paso.