Receptor electrónico en Costa Rica: cómo recibir y confirmar comprobantes via API
Guía técnica para implementar el rol de receptor electrónico en Costa Rica: cómo recibir comprobantes de Hacienda, confirmar, aceptar o rechazar, y automatizar el flujo vía API.
Por Ing. Carlos Méndez | 4 de septiembre de 2026
Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.
La mayor parte de la documentación sobre facturación electrónica en Costa Rica cubre el rol del emisor: cómo construir el XML, firmarlo y enviarlo a ATV. Pero hay otra cara del sistema que los ISVs de software contable, ERP o sistemas de compras necesitan implementar: el rol del receptor electrónico. Cuando un proveedor envía una factura, Hacienda la deposita en el buzón electrónico del receptor. Si el receptor no confirma el comprobante en el plazo establecido, incumple su obligación fiscal.
Esta guía cubre la implementación técnica del receptor electrónico en Costa Rica: cómo recibir comprobantes desde ATV, cómo enviar la confirmación de aceptación o rechazo, los plazos máximos, la estructura del mensaje de respuesta, y cómo automatizar este flujo en un sistema de cuentas por pagar.
El rol del receptor electrónico en el sistema de Hacienda Costa Rica
Cuando un emisor envía un comprobante a ATV y Hacienda lo acepta, el sistema deposita el comprobante en el buzón electrónico del receptor. El receptor tiene la obligación de confirmar ese comprobante enviando un mensaje de aceptación total, aceptación parcial o rechazo. Este mensaje de confirmación es también un comprobante electrónico con su propia estructura XML, firmado con el certificado del receptor.
Tipos de mensaje de confirmación del receptor (códigos Hacienda): • Tipo 05 — Confirmación de Aceptación: acepta el comprobante íntegramente • Tipo 06 — Confirmación de Aceptación Parcial: acepta solo algunas líneas • Tipo 07 — Confirmación de Rechazo: rechaza el comprobante completo El plazo máximo para confirmar es de 8 días hábiles después de recibido el comprobante.
Cómo recibir comprobantes desde ATV: el buzón electrónico
ATV no push a los receptores los comprobantes recibidos. El receptor debe consultar activamente su buzón mediante polling al endpoint de consulta, o configurar un callbackUrl en el sistema de emisión de sus proveedores. La mayoría de implementaciones usan polling periódico (cada 5-15 minutos) para verificar si hay comprobantes nuevos pendientes de confirmación.
Endpoint de consulta del buzón de recepciones
# Consulta del buzón del receptor — ATV Costa Rica
# Autenticación OAuth (igual que para emisor)
POST https://idp.comprobanteselectronicos.go.cr/auth/realms/rut/protocol/openid-connect/token
Body: grant_type=client_credentials&client_id=xxx&client_secret=xxx
→ access_token
# Consultar comprobantes recibidos (pendientes de confirmación)
GET https://api.comprobanteselectronicos.go.cr/recepcion/v1/comprobante
Headers: Authorization: Bearer {access_token}
Params: receptor={cedula}&estado=procesando
# Respuesta: lista de comprobantes con campos:
# - clave: Clave del comprobante
# - fechaEmision: fecha del comprobante original
# - emisor: datos del emisor
# - xml: XML del comprobante en Base64
# - mensajeHacienda: estado de procesamiento de HaciendaEstructura del mensaje de confirmación: aceptación y rechazo
El mensaje de confirmación (tipo 05, 06 o 07) es un XML con su propio XSD definido por Hacienda. Debe ser firmado con el certificado XAdES-BES del receptor y enviado al endpoint de recepción de Hacienda, igual que se envía una factura. La diferencia es el tipo de documento y los campos específicos del mensaje de confirmación.
<!-- Estructura de Mensaje de Confirmación (tipo 05 — Aceptación) -->
<MensajeHacienda
xmlns="https://tribunet.hacienda.go.cr/docs/esquemas/2017/v4.3/mensajeHacienda">
<Clave>50600...clave del mensaje de confirmación</Clave>
<!-- La clave del mensaje tiene Situación=3 (normal) para confirmación -->
<NumeroCedulaEmisor>3101000001</NumeroCedulaEmisor>
<FechaEmisionDoc>2026-09-04T10:00:00-06:00</FechaEmisionDoc>
<Mensaje>1</Mensaje>
<!-- 1 = Aceptado, 2 = Aceptado Parcialmente, 3 = Rechazado -->
<DetalleMensaje>Comprobante recibido y aceptado correctamente</DetalleMensaje>
<MontoTotalImpuesto>13000.00000</MontoTotalImpuesto>
<TotalFactura>113000.00000</TotalFactura>
<NumeroCedulaReceptor>3102000001</NumeroCedulaReceptor>
<NumeroConsecutivoReceptor>00100001090000000001</NumeroConsecutivoReceptor>
<!-- Firma XAdES-BES del receptor al final -->
<Signature>...</Signature>
</MensajeHacienda>Campos críticos del mensaje de confirmación
El campo Mensaje define el tipo de respuesta: 1 (aceptación total), 2 (aceptación parcial), 3 (rechazo). El campo NumeroCedulaEmisor debe contener la cédula del emisor original del comprobante que se está confirmando. El NumeroConsecutivoReceptor es el consecutivo interno del receptor para este mensaje de confirmación — debe gestionarse como una secuencia independiente.
El NumeroConsecutivoReceptor tiene un formato específico: 20 dígitos que codifican tipo de establecimiento (3) + terminal (5) + tipo de comprobante (2) + secuencial (10). El tipo de comprobante para mensajes de confirmación es 09. Un consecutivo mal formado genera rechazo del mensaje.
Plazos de confirmación y consecuencias del incumplimiento
La regulación de Hacienda establece un plazo de 8 días hábiles para que el receptor confirme el comprobante desde la fecha de recepción. Un receptor que no confirme dentro del plazo puede perder el derecho a crédito fiscal del IVA correspondiente al comprobante no confirmado. Para sistemas de alto volumen, el monitoreo del estado de confirmación de cada comprobante es una función crítica.
Automatización del flujo de receptor electrónico en sistemas de cuentas por pagar
Un sistema de cuentas por pagar que integra el flujo de receptor electrónico necesita: un worker de polling que consulte el buzón ATV periódicamente; un componente de validación del comprobante recibido (XSD, firma, coincidencia de datos); un flujo de aprobación interna (manual o automático según umbrales); y el componente de envío del mensaje de confirmación a ATV.
# Flujo de receptor electrónico — automatización (pseudocódigo)
# Worker de polling (ejecutar cada 10 minutos)
1. GET /comprobante?receptor={cedula}&estado=procesando
→ lista de comprobantes pendientes
2. Por cada comprobante:
a. Decodificar Base64 → XML del comprobante
b. Validar XML contra XSD v4.3
c. Verificar firma XAdES-BES del emisor
d. Comparar datos con órdenes de compra internas (si aplica)
e. Determinar: aceptación (1), aceptación parcial (2) o rechazo (3)
3. Construir MensajeHacienda (tipo 05/06/07)
- Calcular consecutivo del receptor
- Firmar con XAdES-BES del receptor
- Codificar en Base64
4. POST /recepcion (ATV)
Body: mensaje de confirmación en Base64
→ HTTP 201: confirmación aceptada por ATV
5. Registrar en base de datos: clave + estado + timestampAceptación parcial: cuándo y cómo usarla
La aceptación parcial (tipo 06) se usa cuando el receptor acepta algunas líneas de la factura pero rechaza otras. Por ejemplo: se recibieron 8 de 10 ítems pedidos. El mensaje de aceptación parcial debe especificar el monto aceptado y el monto rechazado. Es el tipo de confirmación más complejo de implementar porque requiere lógica de negocio para calcular los montos parciales y sus impuestos proporcionales.
Preguntas frecuentes
¿Cuál es el plazo exacto para confirmar un comprobante electrónico recibido en Costa Rica?
El plazo establecido por la resolución de Hacienda es de 8 días hábiles contados desde la fecha de emisión del comprobante. Días hábiles en Costa Rica excluyen sábados, domingos y feriados nacionales. Un sistema de receptor electrónico debe calcular la fecha límite en días hábiles, no en días naturales.
¿Cómo puedo recibir notificaciones automáticas cuando llega un comprobante a mi buzón ATV?
ATV no envía notificaciones push nativas al receptor. La única forma estándar es polling periódico al endpoint de consulta. Algunos proveedores de API intermediarios ofrecen webhooks propios que envuelven el polling y notifican al ISV cuando llegan comprobantes nuevos, eliminando la necesidad de implementar el polling directamente.
¿Qué diferencia hay entre confirmar un comprobante en ATV y registrarlo en la contabilidad interna?
Son dos operaciones distintas. La confirmación en ATV es una obligación fiscal: el receptor notifica a Hacienda si acepta o rechaza el comprobante. El registro contable interno es un proceso del ERP o sistema contable del receptor. Ambos deben ocurrir, pero son independientes: un comprobante puede registrarse contablemente antes o después de la confirmación en ATV.
¿Es posible rechazar un comprobante electrónico en Costa Rica después de haberlo aceptado?
No. Una vez enviado y aceptado por Hacienda el mensaje de aceptación (tipo 05 o 06), no existe mecanismo para convertirlo en rechazo posteriormente. Si el receptor detectó un error en la factura después de aceptarla, la solución es coordinar con el emisor para que emita una Nota de Crédito que corrija o anule el comprobante original.
Sobre el autor
Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.
Artículos Relacionados
Checklist de habilitación como emisor electrónico ante Hacienda Costa Rica
Checklist completo para habilitar un nuevo emisor electrónico ante Hacienda Costa Rica: requisitos, pasos en ATV, configuración técnica, errores frecuentes y tiempos estimados.
Firma digital XAdES-BES en Costa Rica: requisitos técnicos para comprobantes electrónicos
Cómo funciona la firma digital XAdES-BES en Costa Rica, qué certificados acepta Hacienda, el proceso de firma sobre el XML del comprobante y qué errores genera una firma mal formada.
Tipos de comprobantes electrónicos en Costa Rica: FE, FEE, TE, NC, ND y TEC
Guía técnica sobre los seis tipos de comprobantes electrónicos en Costa Rica: cuándo emitir cada uno, reglas de negocio, campos obligatorios y consecuencias fiscales de una selección incorrecta.