TRIBU-CR Hacienda Costa Rica: qué es y cómo prepara su integración
El sistema tribu-cr hacienda costa rica factura electrónica es la nueva plataforma tributaria que reemplazará el ATV actual. Sin embargo, la migración afecta directamente los flujos de autenticación y envío de comprobantes que usted tiene hoy integrados. Por lo tanto, preparar su integración ahora le evitará interrupciones cuando el sistema entre en producción.
El Ministerio de Hacienda inició el despliegue de TRIBU-CR en etapas. En consecuencia, los developers que trabajan con la API actual deben entender qué cambia y qué permanece igual en el nuevo sistema. Asimismo, el período de transición permite probar la nueva integración antes de que el ATV quede inactivo.
Table of Contents
Qué es TRIBU-CR y por qué reemplaza el ATV de Hacienda
TRIBU-CR es el sistema integrado de gestión tributaria del Ministerio de Hacienda de Costa Rica. Sin embargo, no es solo una actualización visual del ATV. Por lo tanto, implica cambios técnicos en los endpoints, la autenticación y los esquemas de respuesta que usted recibe hoy.
- Unificación de sistemas: TRIBU-CR integra en una sola plataforma el ATV, el CRSF y los módulos de declaraciones. Por ejemplo, usted podrá consultar el estado del contribuyente y los comprobantes desde una sola API.
- Seguridad mejorada: El sistema adopta OAuth 2.0 para la autenticación. Sin embargo, el proceso de obtención de tokens cambia respecto al esquema actual del ATV.
- Trazabilidad completa: TRIBU-CR registra el historial completo de cada comprobante enviado. Adicionalmente, expone endpoints de consulta con mayor detalle de estados intermedios.
tribu-cr hacienda costa rica factura electrónica: qué cambia para su integración
Los cambios técnicos impactan tres capas de su integración actual. Sin embargo, el esquema XML de los comprobantes electrónicos permanece en la versión 4.4 sin modificaciones. Por lo tanto, el esfuerzo de adaptación se concentra en la capa de comunicación, no en la generación de documentos.
| Componente | ATV (actual) | TRIBU-CR (nuevo) |
|---|---|---|
| Autenticación | Usuario/contraseña en ATV | OAuth 2.0 con token JWT |
| Endpoint de envío | api.hacienda.go.cr/fe/ae | api.tribu-cr.hacienda.go.cr/fe/v1 |
| Esquema XML | Versión 4.4 | Versión 4.4 (sin cambios) |
| Consulta de estado | GET /fe/ae/{clave} | GET /fe/v1/comprobante/{clave} |
En consecuencia, si su sistema almacena los endpoints del ATV como constantes hardcodeadas, necesitará actualizarlos. Asimismo, el mecanismo de renovación automática de tokens requiere lógica adicional en su capa de comunicación.
Cómo preparar su integración para la migración a TRIBU-CR
La preparación tiene cuatro fases. Por lo tanto, no espere al período de transición para iniciar las primeras dos fases, ya que no dependen de que TRIBU-CR esté en producción.
- Abstraer los endpoints en variables de configuración. Sin embargo, no modifique los valores todavía. Asimismo, prepare la lógica para cambiarlos sin recompilar el sistema.
- Implementar autenticación OAuth 2.0. Por ejemplo, puede usar una biblioteca estándar de OAuth en su lenguaje de programación. Adicionalmente, el token de TRIBU-CR expira cada 30 minutos y debe renovarse automáticamente.
- Registrar su aplicación en el portal de TRIBU-CR. En consecuencia, obtendrá las credenciales client_id y client_secret necesarias para el flujo OAuth.
- Probar en el ambiente de desarrollo de TRIBU-CR. Por lo tanto, valide que el flujo completo —autenticación, envío, consulta de estado— funciona correctamente antes del go-live.
Para entender el contexto actual de la API de Hacienda antes de migrar, revise la guía de API de facturación electrónica de Hacienda Costa Rica. Sin embargo, esa guía cubre el sistema ATV actual, no TRIBU-CR directamente.
Cronograma oficial de migración de TRIBU-CR
Hacienda definió un cronograma por fases para la migración. Sin embargo, las fechas exactas pueden ajustarse según el avance del despliegue. Por lo tanto, monitoree las comunicaciones oficiales del Ministerio.
- Fase 1 — Piloto restringido: TRIBU-CR disponible para un grupo limitado de grandes contribuyentes. Por ejemplo, contribuyentes invitados por Hacienda pueden probar el sistema en producción.
- Fase 2 — Apertura progresiva: TRIBU-CR disponible para todos los contribuyentes en modo paralelo con el ATV. Adicionalmente, el ATV sigue aceptando comprobantes durante esta fase.
- Fase 3 — Migración completa: El ATV queda inactivo. En consecuencia, todos los sistemas deben estar integrados con TRIBU-CR antes de esta fecha.
Para entender el esquema técnico que utilizará en TRIBU-CR, consulte la guía de factura electrónica versión 4.4 en Costa Rica. Asimismo, ese artículo cubre los campos y validaciones que se mantienen sin cambios en la migración.
Errores frecuentes durante la migración a TRIBU-CR
Error: 401 Unauthorized — Token inválido o expirado
Causa: El token OAuth no fue renovado antes de su expiración a los 30 minutos.
Solución: Implementar renovación automática del token antes de cada solicitud o al recibir el error 401. Por ejemplo, use un interceptor HTTP que verifique la expiración del token antes de cada llamada a la API.
Error: 400 Bad Request — client_id no registrado
Causa: Las credenciales de la aplicación no fueron registradas en el portal de TRIBU-CR.
Solución: Completar el registro de la aplicación en el portal de desarrolladores de TRIBU-CR antes de intentar autenticarse. Sin embargo, el proceso de aprobación puede demorar hasta 5 días hábiles.
Error: 404 Not Found — Endpoint incorrecto
Causa: El sistema sigue apuntando a los endpoints del ATV en lugar de los de TRIBU-CR.
Solución: Actualizar todos los endpoints en la configuración del sistema. Adicionalmente, verifique que no existan endpoints hardcodeados en el código fuente o en archivos de configuración legacy.
Preguntas frecuentes sobre TRIBU-CR y factura electrónica
¿Cuál es la diferencia entre el ATV y TRIBU-CR para developers?
El ATV usa autenticación básica y endpoints REST propios de Hacienda. Sin embargo, TRIBU-CR adopta OAuth 2.0 estándar y nuevos endpoints con versionamiento. Por lo tanto, la mayor parte del cambio técnico está en la capa de autenticación y comunicación, no en los comprobantes.
¿Cómo puedo probar la integración con TRIBU-CR antes del go-live?
Hacienda pondrá a disposición un ambiente de desarrollo de TRIBU-CR para pruebas. Adicionalmente, el registro en ese ambiente es independiente del registro productivo. Por ejemplo, puede probar el flujo OAuth completo con credenciales de prueba antes de solicitar las credenciales de producción.
¿Qué pasa si no migro a TRIBU-CR antes del plazo final?
El ATV dejará de aceptar comprobantes en la Fase 3 de la migración. En consecuencia, su sistema no podrá enviar facturas electrónicas hasta completar la migración a TRIBU-CR. Como resultado, su empresa quedará fuera de cumplimiento fiscal durante el período de interrupción.
¿La API de Alanube soporta TRIBU-CR automáticamente?
Sí. La API de Alanube actualizará su integración con Hacienda Costa Rica cuando TRIBU-CR esté en producción. Adicionalmente, sus integradores no necesitarán modificar los payloads que envían a Alanube. Por lo tanto, el esfuerzo de migración a TRIBU-CR recae en Alanube, no en su equipo de desarrollo.
¿Quiere preparar su integración para TRIBU-CR antes del plazo? Pruebe la API de Alanube Costa Rica con acceso al sandbox: Pruebe la API de Alanube Costa Rica.
Fuentes
Ministerio de Hacienda de Costa Rica. (2025). Plan de migración al Sistema TRIBU-CR. Gobierno de Costa Rica. https://www.hacienda.go.cr/tribu-cr
