Credenciales de Hacienda

Credenciales de Hacienda

Cada cliente emisor necesita credenciales de Hacienda para que Asientra pueda firmar XMLs con XAdES-EPES y autenticarse contra los endpoints de recepción. Esta página explica qué credenciales se necesitan, cómo se almacenan de forma segura, y cómo subirlas y validarlas.

Video próximamente · 90s

Antes de empezar

Cuidado

Las credenciales de Hacienda son datos sensibles. Asientra las almacena encriptadas con Rails 7 encrypted attributes — nunca aparecen en logs, correos, ni exportaciones. El acceso queda registrado en el audit trail del cliente. No compartas estos datos por WhatsApp, email, ni ningún canal no encriptado.

Nota

Necesitás tener a mano cuatro elementos: la llave criptográfica en formato .p12, el PIN de la llave, el usuario de la API de Hacienda, y la contraseña de ese usuario. Tu cliente debe obtenerlos desde el portal ATV o mediante su certificado emitido por Ministerio de Hacienda. Asientra valida todo contra sandbox antes de guardar.

Por qué se necesitan estas credenciales

El sistema de facturación electrónica de Costa Rica requiere dos tipos de autenticación:

• Firma XAdES-EPES: cada XML de factura debe ir firmado con la llave privada del cliente (archivo .p12 + PIN). Sin firma válida, Hacienda rechaza el comprobante.
• Autenticación API: el envío a los endpoints de recepción de Hacienda requiere credenciales OAuth (usuario + contraseña) del emisor.

Asientra maneja ambos pasos internamente — vos solo subís las credenciales una vez y el sistema las usa cada vez que se firma o envía un comprobante.

Subir las credenciales

1

Abrí la pestaña de credenciales

Desde el perfil del cliente, hacé click en la pestaña Credenciales de Hacienda. Si el cliente está en estado onboarding, verás un banner que guía directamente a esta sección.

Pestaña de credenciales con sección vacía y botón 'Configurar credenciales'

2

Subí el archivo .p12

Arrastrá el archivo .p12 al área de carga o hacé click para seleccionarlo. El archivo debe ser el certificado del emisor emitido por el Ministerio de Hacienda. Asientra verifica que el archivo sea un PKCS#12 válido antes de intentar desencriptarlo.

Área de drag-and-drop para el archivo .p12 con indicador de validación

3

Ingresá el PIN

El PIN es la contraseña de la llave privada dentro del .p12. Asientra lo verifica inmediatamente intentando extraer la clave privada — si el PIN es incorrecto, el error aparece en el momento y el archivo no se guarda.

El campo está enmascarado y nunca se muestra en texto plano después de guardado.

4

Ingresá usuario y contraseña de la API

Estos son las credenciales de autenticación para los endpoints de recepción de Hacienda:

• Usuario API: el identificador asignado por Hacienda para el emisor.
• Contraseña API: la contraseña correspondiente.

Si tu cliente opera en sandbox, usá las credenciales de sandbox. Si ya tiene producción, elegí el ambiente apropiado en el siguiente paso.

Formulario de usuario y contraseña API con selector de ambiente

5

Seleccioná el ambiente

Elegí entre Sandbox y Producción:

• Sandbox: para pruebas. Hacienda acepta comprobantes pero no los registra como válidos para fines fiscales.
• Producción: comprobantes con validez fiscal plena.

Cuidado

El switch de sandbox a producción requiere aprobación explícita de un owner o admin del despacho. No es posible cambiarlo desde un rol contador_junior. Esta separación es intencional — una factura enviada a producción por error tiene implicaciones fiscales reales.

6

Validá contra sandbox

Hacé click en Validar credenciales. Asientra envía un XML de prueba a Hacienda sandbox con las credenciales proporcionadas. Si la validación pasa:

1. Las credenciales quedan guardadas en forma encriptada.
2. El cliente pasa automáticamente a estado activo.
3. Se registra un evento cliente.credenciales_actualizadas en el audit trail.

Panel post-validación con checkmarks verdes y fecha de vencimiento del certificado

Vencimiento del certificado

El certificado .p12 tiene fecha de expiración. Asientra detecta el campo certificado_vence_at al parsear el archivo y muestra la fecha en la pestaña de credenciales.

30 días antes del vencimiento, el sistema emite automáticamente una alerta de severidad critical (ver Severidades y reglas) y notifica al contador asignado al cliente. No esperés a que la alerta aparezca — consultá con tu cliente la renovación del certificado con al menos un mes de anticipación.

Cuidado

Si el certificado vence y no lo renovás, todos los intentos de firma fallan y las facturas quedan en estado error_envio. Las facturas no enviadas dentro del plazo reglamentario pueden requerir una nota de corrección.

Actualizar credenciales existentes

Para reemplazar credenciales (ej. renovación anual), repetí el mismo flujo. El sistema sobrescribe las credenciales encriptadas y registra el cambio con timestamp en el audit trail. El cliente no pierde el estado activo ni los datos históricos.

Errores comunes

| Mensaje | Causa probable | Cómo resolverlo | |---|---|---| | “Archivo .p12 no válido o corrupto” | El archivo no es un PKCS#12 o está dañado | Solicitá el archivo original al cliente o descargalo nuevamente desde ATV | | “PIN incorrecto” | El PIN no desencripta la llave privada del archivo | Verificá el PIN con el cliente; no hay forma de recuperarlo si se perdió | | “Certificado vencido” | La fecha notAfter del certificado ya pasó | El cliente debe renovar el certificado en Hacienda antes de poder emitir | | “Error de autenticación API (401)” | Usuario o contraseña API incorrectos, o ambiente equivocado | Verificá que el usuario y contraseña correspondan al ambiente seleccionado (sandbox vs. producción) |

Relacionado

• Onboarding de un cliente
• Credenciales TRIBU-CR
• Emitir una factura electrónica