API de facturación electrónica para Costa Rica

Lo que se ahorra al no hacerlo usted

Emitir un comprobante electrónico en Costa Rica no es enviar un JSON a una dirección. Hay que armar el XML según el esquema vigente, calcular los impuestos por línea con la tarifa que le corresponde a cada código CABYS, generar la clave de cincuenta dígitos, llevar el consecutivo por sucursal, terminal y tipo de documento, firmar con un certificado XAdES, autenticarse contra el API de Hacienda, enviar, esperar la respuesta —que no llega de inmediato—, interpretarla y guardar el XML de respuesta.

Y después mantenerlo. El esquema vigente es la versión 4.4, y ya hay un cambio anunciado para el 1.º de noviembre de 2026 con nuevos códigos de referencia en las notas de crédito. Cada resolución de Hacienda es trabajo de desarrollo si el esquema lo mantiene usted.

Con la API, su sistema manda el documento y recibe el estado. Lo demás es nuestro problema, incluidos los cambios de esquema.

Cómo se ve

Es una API REST sobre HTTPS con autenticación OAuth 2.0: se pide un token y se manda en la cabecera Authorization de cada llamada. La referencia técnica —parámetros, estructura del comprobante y códigos de respuesta— se entrega a quien va a integrar: aquí está cómo pedirla.

Emisión y ciclo de vida del documento

Consultas que le ahorran trabajo

Estas no tienen que ver con emitir, pero son las que un integrador termina necesitando y resolviendo a mano contra tres fuentes distintas:

El catálogo de ubicaciones importa más de lo que parece: la dirección del comprobante no admite texto libre, va por código de provincia, cantón y distrito, y equivocarse ahí es un rechazo.

Si integra a varios contribuyentes

Para casas de software y contadores que atienden a varias empresas hay un juego de recursos aparte, bajo /api/Integracion, que permite listar los contribuyentes bajo su cuenta y emitir, consultar estados y anular indicando por cuál de ellos se está actuando. Un solo integrador, una sola credencial, muchos emisores.

Lo que sigue siendo suyo

Conviene decirlo claro para que nadie descubra tarde el alcance. La API emite comprobantes: no es un ERP por HTTP. Su inventario, sus precios, sus clientes y su lógica de negocio siguen en su sistema, y lo que viaja es el documento ya armado con sus líneas, sus impuestos y su receptor.

Y hay dos cosas que necesitamos de su lado: el certificado de firma digital del contribuyente con su PIN, que es lo que Hacienda exige para firmar a su nombre, y que los códigos CABYS de sus productos sean correctos, porque de ahí sale la tarifa de IVA de cada línea. Para lo segundo tenemos el buscador de códigos CABYS, que es gratuito y no pide registro.

Preguntas frecuentes

¿Hay ambiente de pruebas?

Sí. Se integra primero contra el ambiente de pruebas de Hacienda, con su propio certificado y sus propios consecutivos, y se pasa a producción cuando los documentos salen aceptados. Nadie estrena una integración facturando de verdad.

¿En qué lenguaje se integra?

En el que use su sistema. Es HTTP con JSON: sirve igual desde .NET, PHP, Node, Python o Java, y no hay que instalar ninguna librería nuestra.

¿Qué pasa cuando Hacienda cambia el esquema?

Lo actualizamos nosotros. Ese es buena parte del sentido de integrarse en vez de implementarlo: usted no reescribe su código cada vez que sale una resolución.

¿Puedo usar la API y el sistema web a la vez?

Sí. Hay quien emite por API desde su punto de venta y entra al sistema web para revisar lo emitido, recibir documentos de proveedores o sacar los reportes del mes. Es la misma cuenta y los mismos documentos.