API de facturación electrónica Hacienda Costa Rica: guía de integración técnica
La integración de la API de facturación electrónica Hacienda Costa Rica requiere manejar la clave numérica de 50 dígitos, la firma digital del BCCR, el esquema XSD versión 4.4 y el flujo de aceptación del receptor. Esta guía cubre cómo funciona la API de facturación electrónica Hacienda Costa Rica, qué diferencia una integración directa de una integración a través de un proveedor tecnológico, y cómo implementar el flujo completo con la API de Alanube.
Índice de contenidos
- Cómo funciona la API de facturación electrónica Hacienda Costa Rica
- Integración directa con ATV vs. integración vía proveedor
- Prerrequisitos técnicos antes de integrar
- La clave numérica de 50 dígitos: estructura y cálculo
- Estructura del payload y campos obligatorios
- Flujo de respuesta de ATV y estados del comprobante
- Manejo del Mensaje Receptor en la integración
- Sandbox de Hacienda y ambiente de pruebas de Alanube
Cómo funciona la API de facturación electrónica Hacienda Costa Rica
El Ministerio de Hacienda de Costa Rica expone el sistema ATV (Administración Tributaria Virtual) como el punto de recepción de todos los comprobantes electrónicos. La API de facturación electrónica Hacienda Costa Rica recibe documentos XML firmados digitalmente y devuelve mensajes de confirmación o rechazo. El acceso a esta API se hace a través de los servicios web publicados por Hacienda, que requieren autenticación con las credenciales del contribuyente o del proveedor tecnológico autorizado.
La arquitectura del sistema tiene dos flujos distintos que toda integración debe manejar:
- Flujo del emisor: el emisor genera el comprobante, lo firma y lo transmite al ATV. ATV devuelve un mensaje de confirmación de recepción que no equivale a aceptación final.
- Flujo del receptor: el receptor recibe el comprobante, lo acepta o rechaza enviando un Mensaje Receptor al ATV. Si no hay respuesta en el plazo legal, ATV acepta el comprobante automáticamente.
Integración directa con ATV vs. integración vía proveedor
| Aspecto | Integración directa con ATV | Integración vía Alanube |
|---|---|---|
| Formato del payload | XML firmado según esquema 4.4 | JSON simplificado |
| Clave de 50 dígitos | Developer calcula e implementa el algoritmo | Alanube la genera automáticamente |
| Firma digital BCCR | Developer implementa el proceso de firma | Alanube firma con el certificado del emisor |
| Actualizaciones de esquema | Developer actualiza cuando Hacienda cambia el XSD | Alanube actualiza — integración no requiere cambios |
| Mensaje Receptor | Developer implementa el flujo de aceptación | Alanube gestiona el registro del Mensaje Receptor |
Prerrequisitos técnicos antes de integrar
- Certificado de firma digital del BCCR vigente: emitido por una entidad certificadora autorizada por el Banco Central de Costa Rica. Puede ser en tarjeta inteligente o token USB. El certificado del emisor se registra en Alanube durante el onboarding y se usa para firmar cada comprobante.
- Cédula jurídica o física activa en Hacienda: el registro tributario del emisor debe estar al día. Un emisor con obligaciones tributarias pendientes puede generar rechazos en ATV.
- Código de actividad económica del emisor: obligatorio en la versión 4.4 del esquema. Se obtiene del registro tributario en el Ministerio de Hacienda.
- Credenciales Sandbox de Alanube: para pruebas en el ambiente de Hacienda sin afectar el consecutivo productivo.
La clave numérica de 50 dígitos: estructura y cálculo
La clave numérica de 50 dígitos es el identificador único de cada comprobante electrónico en el sistema de la API de facturación electrónica Hacienda Costa Rica. Es obligatoria, no puede repetirse, y su estructura está definida por el Ministerio de Hacienda:
Posición Contenido Longitud
1-3 Código de país (506) 3 dígitos
4-9 Fecha (DDMMAA) 6 dígitos
10-21 Cédula del emisor 12 dígitos (con ceros a la izquierda)
22-22 Tipo de identificador 1 dígito
23-37 Consecutivo 15 dígitos
38-38 Situación del comprobante 1 dígito
39-50 Código de seguridad 12 dígitos (aleatorio)Un error en cualquiera de estos campos genera rechazo en ATV. El consecutivo (posiciones 23-37) debe gestionarse de forma centralizada — si el sistema emite desde múltiples instancias sin control de concurrencia, pueden generarse claves duplicadas que ATV rechaza. Con Alanube, la generación de la clave y el control del consecutivo se gestionan en la capa del proveedor.
Estructura del payload y campos obligatorios
La API de Alanube para Costa Rica recibe el payload en JSON. Los campos mínimos para emitir una Factura Electrónica (tipo 01) son:
POST https://api.alanube.co/v1/cri/invoices
Authorization: Bearer {token}
Content-Type: application/json
{
"emisor": {
"cedula": { "tipo": "02", "numero": "3456789012" },
"nombre": "Empresa Ejemplo SA",
"codigoActividad": "620900",
"correoElectronico": "facturacion@empresa.com"
},
"receptor": {
"cedula": { "tipo": "01", "numero": "1234567890" },
"nombre": "Cliente SA",
"correoElectronico": "compras@cliente.com"
},
"tipoComprobante": "01",
"medioPago": ["01"],
"detalleServicio": [{
"numeroLinea": 1,
"detalle": "Servicio de consultoría",
"cantidad": 1,
"unidadMedida": "Sp",
"precioUnitario": 500000,
"descuento": 0,
"impuesto": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13 }
}]
}Flujo de respuesta de ATV y estados del comprobante
La API de facturación electrónica Hacienda Costa Rica devuelve dos tipos de respuesta que es importante distinguir:
Confirmación de recepción: ATV confirma que recibió el documento. Esto no equivale a aceptación fiscal — solo significa que el documento llegó al sistema. El estado en este punto es procesando.
Resultado de validación: ATV procesa el documento y devuelve el resultado final: aceptado si el comprobante cumple con todos los requisitos, o rechazado con el código de error específico si hay un problema. Este resultado puede tardar entre segundos y varios minutos dependiendo de la carga del sistema de Hacienda.
La integración debe implementar una consulta de estado por clave numérica para obtener el resultado final cuando la respuesta inicial es procesando. Alanube gestiona este polling internamente y devuelve el estado final en la respuesta de la API.
Manejo del Mensaje Receptor en la integración
El Mensaje Receptor es el mecanismo mediante el cual el receptor de un comprobante electrónico en Costa Rica comunica al Ministerio de Hacienda si acepta o rechaza el documento. Para las integraciones de sistemas ERP o SaaS que actúan como receptor, esto implica implementar un endpoint que reciba los comprobantes de los proveedores y gestione la respuesta hacia ATV.
Los estados posibles del Mensaje Receptor son:
- Aceptado (1): el receptor confirma que el comprobante es correcto y lo acepta para efectos de crédito fiscal.
- Aceptado parcialmente (2): el receptor acepta parte del comprobante y rechaza otra — requiere indicar el monto aceptado.
- Rechazado (3): el receptor no acepta el comprobante. El emisor debe emitir una Nota de Crédito para anularlo.
Si el receptor no envía Mensaje Receptor dentro del plazo legal (generalmente 8 días hábiles), ATV acepta el comprobante automáticamente. La API de Alanube permite tanto emitir comprobantes como registrar los Mensajes Receptor correspondientes desde la misma integración.
Sandbox de Hacienda y ambiente de pruebas de Alanube
El Sandbox de Alanube para Costa Rica apunta al ambiente de pruebas del Ministerio de Hacienda. Las credenciales se obtienen sin contrato previo y permiten probar el flujo completo de emisión, validación y Mensaje Receptor antes de activar el ambiente productivo.
Para explorar la integración completa con la API de facturación electrónica Hacienda Costa Rica, acceda a la documentación y Sandbox de Alanube para Costa Rica.
Preguntas frecuentes sobre la API de facturación electrónica Hacienda Costa Rica
¿El Ministerio de Hacienda de Costa Rica tiene una API pública para desarrolladores?
La API de facturación electrónica Hacienda Costa Rica está disponible a través del WSDL publicado en el portal ATV. La mayoría de desarrolladores integran a través de un proveedor como Alanube para simplificar la firma digital, el esquema XSD y el flujo de aceptación del receptor.
¿La clave de 50 dígitos puede reutilizarse si el comprobante fue rechazado?
No. Cada clave es de uso único en el sistema ATV, independientemente de si el comprobante fue aceptado o rechazado. Si un documento es rechazado, debe generarse un nuevo comprobante con una nueva clave numérica. El consecutivo sigue avanzando sin importar el resultado.
¿Qué pasa si el sistema de Hacienda no responde durante la emisión?
Si ATV no responde dentro del timeout, la integración no debe asumir ni éxito ni error. Debe consultar el estado del comprobante por clave numérica antes de reintentarlo. Emitir el mismo documento dos veces puede generar duplicados si el primero fue recibido por ATV aunque no haya respondido.
¿La API de Alanube para Costa Rica soporta el flujo del Mensaje Receptor?
Sí. Alanube soporta tanto la emisión de comprobantes como el envío del Mensaje Receptor (aceptación, aceptación parcial o rechazo) desde la misma integración. También notifica al emisor cuando recibe un Mensaje Receptor de sus receptores.
Integre la API de facturación electrónica Hacienda Costa Rica con Alanube
Solicite acceso al Sandbox y pruebe el flujo completo de emisión, validación y Mensaje Receptor sin contrato previo.
Solicite acceso al Sandbox de Alanube para Costa Rica →
Fuentes
Ministerio de Hacienda de Costa Rica. (2023). Sistema ATV — Administración Tributaria Virtual. https://www.hacienda.go.cr
Ministerio de Hacienda de Costa Rica. (2023). Esquema XSD versión 4.4 y documentación técnica. https://www.hacienda.go.cr
