Si ya tiene un sistema y solo necesita que emita comprobantes válidos ante Hacienda, se integra por API en vez de reemplazarlo. Usted manda el documento; el certificado, la firma XAdES, el consecutivo y la conversación con Hacienda corren por nuestra cuenta.
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.
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.
| Recurso | Para qué |
|---|---|
POST /Token | Obtener el token de acceso |
POST /api/Documento | Emitir factura, tiquete, nota de crédito o débito |
GET /api/Documento | Consultar el documento y su estado ante Hacienda |
GET /api/Documento/Anula/{id} | Anular el documento |
POST /api/Documento/Reenvio | Reenviar el comprobante por correo al receptor |
Estas no tienen que ver con emitir, pero son las que un integrador termina necesitando y resolviendo a mano contra tres fuentes distintas:
| Recurso | Para qué |
|---|---|
GET /api/Padron | Datos del contribuyente por cédula: nombre y actividades registradas |
GET /api/Tipocambio | Tipo de cambio del día, para facturar en dólares |
GET /api/Provincia | Catálogo de provincias |
GET /api/Canton/{provincia} | Cantones de una provincia |
GET /api/Distrito/{provincia}/{canton} | Distritos de un cantón |
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.
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.
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.
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 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.
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.
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.
La documentación técnica —estructura del documento, ejemplos de llamada y códigos de respuesta— se entrega a quien va a integrar. Escríbanos a [email protected] o por WhatsApp al 6242-4229 contándonos qué sistema quiere integrar, y le respondemos con la documentación y las credenciales de pruebas.
¿Está listo para iniciar un proyecto con nosotros? Llámenos o envíenos un correo y te responderemos a la mayor brevedad!