Ambiente de Pruebas Hacienda Costa Rica: Guía de Staging

El ambiente de staging del Ministerio de Hacienda es donde su sistema debe validarse antes de pasar a producción. A diferencia del sandbox de otras administraciones tributarias, el staging de Hacienda Costa Rica tiene particularidades que conviene conocer para no perder días por configuraciones que en producción funcionan distinto y que el equipo de operaciones solo descubre cuando el primer documento real es rechazado.

Esta guía explica qué es el ambiente de staging de Hacienda Costa Rica para factura electrónica v4.4, cómo se accede, qué diferencias tiene respecto a producción, qué set mínimo de pruebas conviene cubrir antes de migrar, y los errores frecuentes que aparecen tras la migración por configuraciones inconsistentes entre ambientes.

Qué es el staging de Hacienda y cómo se accede

URL del endpoint y autenticación

El endpoint de staging tiene una URL base distinta a producción. La autenticación usa el mismo mecanismo OAuth contra el servidor de identidad de Hacienda, pero con credenciales específicas del ambiente de pruebas que no son las mismas que las de producción. Conviene almacenar los endpoints y credenciales en variables de entorno separadas por ambiente para que el cambio entre staging y producción sea configuración, no código.

Habilitación previa al uso del staging

Antes de poder transmitir al staging, el contribuyente debe estar registrado en el sistema de Hacienda con su certificado digital BNCR vinculado a su cédula jurídica o física. El proceso de habilitación es el mismo para staging y producción: una vez habilitado, ambos ambientes quedan disponibles. La habilitación se hace en el portal ATV con los datos del contribuyente y del software que va a usarse.

Diferencias clave con producción

Receptores y emisores sintéticos

En staging, los receptores son ficticios y pueden usar identificaciones de prueba que Hacienda mantiene reservadas para ese ambiente. Usar identificaciones reales en staging no necesariamente genera rechazo, pero las operaciones no tienen efecto fiscal: son pruebas. En producción ocurre lo opuesto: usar identificaciones sintéticas genera rechazo porque el receptor no existe en los registros fiscales reales. Mantener separados los datos de prueba y de producción en el código del sistema es condición para que la migración no se confunda.

Plazos de respuesta y rate limit

El staging suele tener rate limits más estrictos que producción porque está dimensionado para tráfico de pruebas, no para volúmenes reales. Una prueba de carga que satura el staging no necesariamente saturaría producción. Los plazos de respuesta de Hacienda al validar documentos en staging son similares a producción, pero pueden ser menos consistentes por la propia naturaleza del ambiente de pruebas.

Set de pruebas recomendado

Set mínimo de validación previa

Antes de cualquier paso a producción, el sistema emisor debe poder cubrir los escenarios básicos en staging: emisión de factura electrónica simple, emisión de tiquete electrónico, nota crédito asociada a una factura previa, nota débito, y consulta de estado del documento por su clave. Cada uno debe completar el ciclo asincrónico hasta recibir la respuesta de Hacienda con el estado final.

Set extendido para robustez en producción

Adicional al set mínimo, conviene cubrir escenarios edge case en staging: factura con muchas líneas (50 o más), factura con varios impuestos discriminados, factura con exoneración parcial, receptor del exterior con pasaporte como identificación, rechazo simulado por error de cálculo, manejo de timeout del endpoint de Hacienda. Cubrir estos casos en staging revela fallos del lado del sistema emisor antes de que aparezcan en producción bajo presión.

Migración correcta de staging a producción

Checklist de cambios al migrar

El checklist mínimo de migración incluye cuatro cambios: URL base del endpoint (de staging a producción), credenciales OAuth (las de producción son distintas a las de staging), URL del servidor de identidad (también cambia), y atributo de ambiente en el XML cuando aplique. Cualquiera de los cuatro olvidado genera rechazo del primer envío en producción por incoherencia entre el ambiente declarado y el endpoint usado.

Estrategia de paso gradual

Conviene transmitir el primer documento de producción a un receptor conocido (la propia empresa o un proveedor cercano) por bajo monto. Una vez verificado el flujo completo — emisión, recepción por Hacienda, consulta de estado, ApplicationResponse positiva — escalar al volumen normal. Saltarse el paso gradual es la causa más común de incidentes en las primeras horas de producción.

Errores frecuentes post-migración

Credenciales de staging que sobreviven a la migración

El error más frecuente al migrar es no rotar las credenciales OAuth: el sistema sigue intentando autenticarse contra el servidor de identidad de producción con credenciales de staging. Hacienda devuelve 401 a todos los envíos. Diagnóstico: comparar el token usado contra las credenciales configuradas en variables de entorno y confirmar que el ambiente del token coincide con el endpoint.

Identificaciones sintéticas en producción

Casos donde el sistema de pruebas quedó mezclado con el de producción y un par de facturas reales se emitieron al receptor sintético usado en staging. Hacienda rechaza con error de receptor no encontrado o con error de identificación inválida. Prevención: separar completamente los datos de prueba de los de producción, validar el formato de la identificación del receptor antes de transmitir.

Preguntas frecuentes

¿Cuál es la diferencia entre el staging de Hacienda y el sandbox del proveedor tecnológico? Son dos ambientes distintos. El staging de Hacienda es el ambiente oficial de pruebas donde el Ministerio valida documentos sintéticos antes de aprobar el paso a producción. El sandbox del proveedor tecnológico es un entorno propio que puede o no estar conectado al staging de Hacienda. En PTs maduros, el sandbox propio se conecta efectivamente al staging — lo cual significa que las pruebas viajan al validador real y se reciben las respuestas reales. En PTs menos maduros, el sandbox del PT puede ser un mock local sin conexión al validador real, lo cual hace que las pruebas no detecten errores que aparecerían en producción.

¿Cómo puedo verificar que mi sistema está listo para producción sin riesgo de rechazo en el primer envío? Tres validaciones mínimas. Primera: completar el set mínimo de pruebas en staging y confirmar que todos los escenarios reciben aprobación de Hacienda. Segunda: emitir una factura de prueba a un receptor real conocido (su propia empresa) por bajo monto en producción y verificar aprobación antes de habilitar tráfico. Tercera: configurar alertas automáticas sobre el primer día de producción (cualquier rechazo dispara notificación inmediata) en lugar de esperar al monitoreo regular.

¿Qué diferencia hay entre el rate limit del staging y el de producción de Hacienda? El rate limit del staging suele ser más estricto que el de producción porque el ambiente está dimensionado para pruebas, no para volúmenes reales. Para pruebas de carga realistas, conviene coordinar con Hacienda o con el proveedor tecnológico una ventana específica, o realizar las pruebas en producción con volumen creciente bajo monitoreo cercano, lo cual es habitual en migraciones de empresas con volumen alto. El rate limit de producción no se documenta públicamente con precisión: conviene preguntar al PT por los límites efectivos del plan contratado.

¿Es posible mantener staging y producción operando en paralelo después de la migración? Sí, y es recomendable. Mantener un environment de staging activo después del paso a producción permite probar cambios de código (refactors, optimizaciones, nuevos casos de uso) sin riesgo en producción. La práctica estándar es mantener tres ambientes en paralelo: desarrollo local con mocks, staging conectado al ambiente de pruebas de Hacienda, y producción. Cada release nuevo cruza primero por staging antes de habilitarse en producción, lo cual cubre los casos en que un cambio aparentemente trivial rompe alguna parte del cálculo de la clave o de la firma.

Ambiente de Pruebas (Staging) Hacienda Costa Rica para Factura Electrónica v4.4