API de facturación electrónica
Emita comprobantes electrónicos de Costa Rica desde su propio sistema. Su sistema envía los datos de la venta en JSON. El API arma el comprobante en la versión 4.4, lo firma, lo envía a Hacienda y le devuelve el XML firmado, la respuesta de Hacienda y el PDF.
Qué es
Es un servicio de servidor a servidor. Su sistema no arma XML, no firma y no habla con Hacienda: de eso se encarga el API. Su sistema solo necesita enviar una solicitud HTTPS con los datos del documento y guardar lo que recibe.
- Documentos: factura electrónica, tiquete electrónico, factura de exportación, nota de crédito, nota de débito y factura de compra.
- Con todos los códigos de los catálogos de Hacienda de la versión 4.4: condición de venta, medio de pago, moneda, tarifas, descuentos, exoneraciones, otros cargos y referencias.
- Cada comprobante se arma con la misma estructura que revisan los esquemas oficiales de Hacienda.
- El API asigna el consecutivo y la clave, y calcula los totales y el IVA.
- Cada documento lleva la referencia de su sistema. Con ella el API evita los duplicados.
- Cuando Hacienda responde, el API le avisa a su sistema, si usted registra su dirección. Vea Avisos automáticos.
- En el perfil del API usted ve cada documento con su estado y descarga sus archivos.
Antes de empezar
- Pida su perfil del API a e-FacturaCR con el formulario de aquí abajo, por WhatsApp o al correo e-facturacr@fenixcrsolutions.com. Recibe un correo de usuario y una contraseña temporal.
- La primera vez que entra, lea y acepte los Términos del API.
- Entre al perfil y complete el emisor: dirección, actividad económica, usuario y contraseña de Hacienda del ambiente de pruebas y el certificado .p12 de pruebas con su PIN.
- En Numeración, use una sucursal y una terminal que ningún otro sistema use con esa cédula.
- Cree una llave de acceso y guárdela en su sistema.
Pedir mi perfil de pruebas
Llene los datos del emisor: la empresa o la persona que va a facturar. Le respondemos al correo que indique, con su usuario y su contraseña temporal. No tiene costo ni lo compromete a nada.
La llave de acceso
Cada solicitud lleva la llave en la cabecera Authorization. Las llaves de pruebas empiezan con efcr_test_ y las de producción con efcr_live_. La llave decide el ambiente: una de pruebas nunca emite un comprobante real.
Authorization: Bearer efcr_test_SU_LLAVE
- La llave completa se muestra una sola vez, al crearla. Si la pierde, anúlela y cree otra.
- Guárdela en el servidor. Nunca la ponga en una página web ni en una aplicación de teléfono.
- Hay llaves que emiten y consultan, y llaves que solo consultan.
- Dirección base:
https://e-facturacr.com/api/v1. Siempre por HTTPS y con el cuerpo en JSON, UTF-8.
Para probar la llave:
curl https://e-facturacr.com/api/v1/emisor \ -H 'Authorization: Bearer efcr_test_SU_LLAVE'
{
"version": "v1",
"ambiente": "pruebas",
"emisor": {
"identificacion": "3101987654",
"nombre": "Distribuidora Montaña Verde S.A.",
"actividad": "4663.0"
},
"listo": true,
"falta": [],
"llave": {
"nombre": "Odoo 19 pruebas",
"permiso": "emitir"
},
"limites": {
"solicitudes_por_minuto": 120,
"documentos_por_dia": 500,
"lineas_por_documento": 200
},
"plan": null
}
Si listo es false, la lista falta dice qué le falta al emisor. Con una llave de producción, plan trae el plan y el consumo del ciclo. Vea Producción y plan.
Su primer documento
Una factura de contado con una línea:
curl -X POST https://e-facturacr.com/api/v1/documentos \
-H 'Authorization: Bearer efcr_test_SU_LLAVE' \
-H 'Content-Type: application/json' \
-d '{"tipo": "FE", "referencia": "INV/2026/00412", "condicion_venta": "01", "medio_pago": "04", "receptor": {"tipo_identificacion": "02", "identificacion": "3101456789", "nombre": "Constructora Los Robles S.A.", "correo": "compras@losrobles.example"}, "lineas": [{"cabys": "3744001000100", "detalle": "Cemento Portland blanco 50 kg", "cantidad": 20, "unidad": "Unid", "precio_unitario": 7500, "tarifa_iva": "08"}], "observaciones": "Entregar en bodega 2"}'
El API responde de inmediato con el consecutivo y la clave. El estado empieza en procesando:
{
"id": "doc_8Jq2mXw4Tz1RbYc6",
"referencia": "INV/2026/00412",
"tipo": "FE",
"consecutivo": "00100003010000002318",
"clave": "50613112600310198765400100003010000002318158241973",
"estado": "procesando",
"mensaje_hacienda": "",
"fecha_emision": "2026-11-13T10:42:07-06:00",
"moneda": "CRC",
"tipo_cambio": 1,
"subtotal": 150000.0,
"descuento": 0.0,
"impuesto": 19500.0,
"otros_cargos": 0.0,
"total": 169500.0,
"receptor": {
"identificacion": "3101456789",
"nombre": "Constructora Los Robles S.A."
},
"ambiente": "pruebas",
"repetida": false,
"archivos": {
"xml": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/xml",
"respuesta": null,
"pdf": null
}
}
Hacienda suele responder en pocos segundos. Consulte el documento hasta que el estado cambie:
curl https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6 \ -H 'Authorization: Bearer efcr_test_SU_LLAVE'
Recomendación: consulte cada 5 segundos durante el primer minuto y después cada minuto. Cuando el estado sea aceptado, las tres direcciones de archivos ya responden. Si prefiere no preguntar, registre la dirección de su sistema y el API le avisa: vea Avisos automáticos.
Operaciones
| Método y dirección | Para qué |
|---|---|
POST /documentos | Emitir un documento. Crea la factura, el tiquete, la nota o la factura de compra y lo envía a Hacienda. |
POST /documentos/validar | Revisar sin emitir. Revisa el documento como lo haría la emisión y responde si está bien, con sus totales. No guarda nada, no gasta consecutivo y no envía a Hacienda. |
GET /documentos/{id} | Consultar el estado. Devuelve el documento con su estado más reciente. |
GET /documentos | Listar documentos. Los documentos del emisor, del más reciente al más antiguo. Se filtra por referencia, estado, tipo y fechas. |
GET /documentos/{id}/xml | Descargar el XML firmado. El comprobante electrónico tal como se envió a Hacienda. |
GET /documentos/{id}/respuesta | Descargar la respuesta de Hacienda. El mensaje de aceptación o de rechazo. |
GET /documentos/{id}/pdf | Descargar el PDF. La representación impresa. Existe cuando Hacienda acepta. |
GET /emisor | Probar la llave. Devuelve el emisor de la llave y si ya puede emitir. Sirve para probar la conexión. |
Revisar sin emitir
POST /documentos/validar
Recibe el mismo cuerpo que la emisión y hace todo lo que ella haría: revisa cada dato, calcula los totales y arma el comprobante. Pero no guarda nada: no gasta consecutivo, no firma un documento de verdad y no envía a Hacienda. Sirve para avisarle al usuario de su sistema antes de confirmar la factura.
curl -X POST https://e-facturacr.com/api/v1/documentos/validar \ -H 'Authorization: Bearer efcr_test_SU_LLAVE' \ -H 'Content-Type: application/json' \ -d @documento.json
Si el documento está bien responde 200 con lo que saldría:
{
"valido": true,
"repetida": false,
"documento": null,
"tipo": "FE",
"referencia": "INV/2026/00412",
"moneda": "CRC",
"tipo_cambio": 1,
"subtotal": 150000.0,
"descuento": 0.0,
"impuesto": 19500.0,
"otros_cargos": 0.0,
"total": 169500.0,
"avisos": [],
"ambiente": "pruebas"
}
| Dato | Qué es |
|---|---|
valido | true: el documento pasa todas las revisiones y se puede emitir tal cual. Si algo no pasa, la respuesta es el mismo error que daría la emisión. |
repetida | true cuando esa referencia ya se emitió con los mismos datos: emitir devolvería ese documento, sin crear otro. |
documento | El «id» del documento que ya existe con esa referencia, o null. |
tipo | FE, TE, FEE, NC, ND o FEC. |
referencia | La referencia que envió su sistema. |
moneda | La moneda con que saldría el documento. En una nota, la de su documento original. |
tipo_cambio | El tipo de cambio con que saldría. En una nota, el de su documento original. |
subtotal | Suma de cantidad por precio de las líneas, antes de descuentos. |
descuento | Suma de los descuentos. |
impuesto | El IVA que pagaría el cliente, sin lo exonerado. |
otros_cargos | Suma de los otros cargos. |
total | El total que tendría el comprobante. |
avisos | Lista de observaciones que no impiden emitir, pero conviene revisar. Vacía si no hay. |
ambiente | pruebas o produccion, según la llave usada. |
Si algo no pasa, responde el mismo error que daría la emisión, con el dato y el motivo. Vea Errores.
Emitir un documento
POST /documentos
El API no acepta datos que no conoce: si envía un nombre mal escrito, responde con un error de validación y no emite nada. Los montos van como números, no como texto: la cantidad con hasta 3 decimales y los precios y descuentos con hasta 5. Los textos se guardan en una sola línea, sin saltos de línea, caracteres de control ni emojis.
El documento
| Dato | Obligatorio | Qué es |
|---|---|---|
tipo | Sí | FE factura, TE tiquete, FEE factura de exportación, NC nota de crédito, ND nota de débito o FEC factura de compra. |
referencia | Sí | El número del documento en su sistema, hasta 60 caracteres. Es único por emisor y es lo que evita los duplicados. |
receptor | En FE y FEE | El cliente: tipo y número de identificación, nombre y correo. En un tiquete puede faltar. En la factura de exportación es un cliente del extranjero, con su dirección. Una nota lleva siempre el cliente del documento original: si este se emitió con el API se toma solo (si lo envía, debe ser el mismo) y si es de fuera hay que enviarlo. En la factura de compra no va: se envía «proveedor». |
proveedor | En FEC | Solo en la factura de compra: a quién se le compra, con su dirección y su correo. |
lineas | Sí | De 1 a 200 líneas. De cada una: CABYS, detalle, cantidad, precio y tarifa de IVA. El API calcula los totales. |
condicion_venta | No | Código de Hacienda. Si falta: 01, contado. Una nota toma la condición, el plazo y el medio de pago del original. |
condicion_venta_otros | Con la condición 99 | Descripción de la condición, de 5 a 100 caracteres. |
plazo_credito | En ventas a crédito | Días de plazo. Obligatorio con las condiciones 02, 08 y 10. |
medio_pago | No | Código de Hacienda. Si falta: 01, efectivo. |
medio_pago_otros | Con el medio 99 | Descripción del medio de pago, de 3 a 100 caracteres. |
medios_pago | No | En vez de «medio_pago», cuando se paga con dos a cuatro medios: cada uno con su monto. La suma debe ser el total del documento. |
moneda | No | Código de la moneda. Si falta: CRC. Una nota va en la moneda y con el tipo de cambio de su documento original. |
tipo_cambio | En moneda extranjera | Colones por unidad de la moneda. En dólares, si falta, se usa el de venta del día. En las demás monedas es obligatorio. Una nota lleva el del documento original: si este se emitió con el API se toma solo, y si es de fuera hay que enviarlo. |
actividad | No | Código de la actividad económica del emisor. Si falta: la principal. |
observaciones | No | Texto libre de hasta 500 caracteres. Viaja en el XML y sale en el PDF. |
otros_datos | No | Hasta 20 datos adicionales de uso comercial, cada uno con su nombre. Viajan en el XML y salen en el PDF. |
otros_cargos | No | Hasta 15 cargos que se suman al total sin ser líneas: timbres, impuesto de servicio, cobros de terceros. |
documento_referencia | En NC, ND y FEC | El documento al que este hace referencia y el motivo. En una nota, el que corrige o anula. En la factura de compra, el comprobante del proveedor. En los demás es opcional. |
El cliente: receptor
| Dato | Obligatorio | Qué es |
|---|---|---|
receptor.tipo_identificacion | Sí | 01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE. En la factura de exportación, 05: cliente del extranjero; el tiquete también lo admite. |
receptor.identificacion | Sí | El número, sin guiones ni espacios. La de un cliente del extranjero: hasta 20 letras y números. |
receptor.nombre | Sí | Nombre o razón social, hasta 100 caracteres. |
receptor.correo | No | Correo del cliente. Sale en el comprobante. |
receptor.direccion | No | Dirección del cliente en el extranjero, de 5 a 300 caracteres. Solo con el tipo 05. |
receptor.actividad | No | Código de la actividad económica del cliente, de 6 caracteres. En facturas y notas, cuando el cliente la pide para su crédito fiscal. |
Cada línea: lineas[]
| Dato | Obligatorio | Qué es |
|---|---|---|
cabys | Sí | Código CABYS de 13 dígitos del bien o servicio. Puede faltar en una nota financiera, con el código de referencia 09 o 10. |
detalle | Sí | Descripción de la línea, de 3 a 200 caracteres. |
cantidad | Sí | Mayor que cero, con hasta 3 decimales. |
precio_unitario | Sí | Precio de una unidad, sin el IVA, con hasta 5 decimales. |
unidad | No | Unidad de medida de Hacienda. Si falta: Unid para bienes y Sp para servicios. |
tarifa_iva | No | Código de la tarifa. Si falta: 08, la general del 13 %. En la factura de exportación y en sus notas, si falta: 10, exento. |
descuento | No | Monto del descuento de la línea, con hasta 5 decimales. Menor que el monto de la línea. No se envía en una regalía o bonificación. |
descuento_codigo | No | Código del descuento. Si falta: 07, comercial. 01, 02 o 03 convierten la línea en una regalía o bonificación: se entrega completa y la tarifa debe llevar IVA. |
descuento_naturaleza | No | Explicación del descuento, de 3 a 80 caracteres. |
descuento_otro | Con el código 99 | Descripción del descuento, de 5 a 100 caracteres. |
base_imponible | No | Solo con el descuento 02: el valor sobre el que el cliente paga el IVA. Si falta: el monto de la línea. |
codigo | No | Código del producto en su sistema, hasta 20 caracteres. |
codigo_tipo | No | Tipo del código del producto. Si falta: 04, de uso interno. |
tipo_transaccion | No | Tipo de transacción de la línea. En facturas, notas y facturas de compra. Vea el catálogo. |
partida_arancelaria | En exportación de mercancías | Partida arancelaria, de 12 dígitos. Obligatoria en la factura de exportación y en sus notas cuando la línea es una mercancía: CABYS que empieza por 0, 1, 2, 3 o 4. En servicios no va. |
exoneracion | No | El documento que exonera el IVA de la línea. No se usa en la factura de exportación. |
numero_vin | En vehículos | Número VIN o de serie del vehículo, de hasta 17 caracteres. Obligatorio cuando el CABYS empieza por 4911 o 4991. Un vehículo por línea. |
registro_medicamento | No | Registro sanitario del medicamento, hasta 100 caracteres. Solo con CABYS que empieza por 3562 a 3565. |
forma_farmaceutica | No | Código de la forma farmacéutica, hasta 3 caracteres. Solo con CABYS que empieza por 3562 a 3565. |
iva_devuelto | No | true en un servicio de salud con la tarifa reducida del 4 % (código 04) pagado con tarjeta: el IVA de la línea se devuelve y no se cobra. |
El precio unitario va sin el IVA. El API calcula el impuesto de cada línea con la tarifa indicada y suma los totales.
La exoneración de una línea: lineas[].exoneracion
| Dato | Obligatorio | Qué es |
|---|---|---|
exoneracion.tipo_documento | Sí | Tipo del documento de exoneración. Vea el catálogo. |
exoneracion.tipo_documento_otro | Con el tipo 99 | Descripción del tipo, de 5 a 100 caracteres. |
exoneracion.numero | Sí | Número del documento de exoneración, de 3 a 40 caracteres. |
exoneracion.articulo | Con los tipos 02, 03, 06, 07 y 08 | Número del artículo de la ley, entero. |
exoneracion.inciso | No | Número del inciso, entero, cuando el artículo lo tiene. |
exoneracion.institucion | Sí | Institución que emitió la exoneración. Vea el catálogo. |
exoneracion.institucion_otros | Con la institución 99 | Nombre de la institución, de 5 a 160 caracteres. |
exoneracion.fecha | Sí | Fecha de emisión del documento de exoneración, AAAA-MM-DD. |
exoneracion.tarifa | Sí | Tarifa exonerada, en puntos del IVA: 13 exonera todo el IVA de una línea al 13 %. Si supera la tarifa de la línea se usa la de la línea. |
Varios medios de pago: medios_pago[]
| Dato | Obligatorio | Qué es |
|---|---|---|
codigo | Sí | Código del medio de pago. Vea el catálogo. |
monto | Sí | Lo pagado con ese medio, mayor que cero y con hasta 2 decimales. |
Otros cargos: otros_cargos[]
| Dato | Obligatorio | Qué es |
|---|---|---|
tipo | Sí | Código del cargo. Vea el catálogo. |
tipo_otros | Con el tipo 99 | Descripción del cargo, de 5 a 100 caracteres. |
detalle | Sí | Detalle del cargo, de 3 a 160 caracteres. |
monto | Sí | Monto del cargo, mayor que cero y con hasta 5 decimales. |
porcentaje | No | Porcentaje que representa el cargo, por ejemplo 10. Es informativo. |
tercero | Con el tipo 04 | A nombre de quién se cobra. |
| Dato | Obligatorio | Qué es |
|---|---|---|
tercero.tipo_identificacion | Sí | 01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE. |
tercero.identificacion | Sí | El número, sin guiones ni espacios. |
tercero.nombre | Sí | Nombre o razón social del tercero, de 5 a 100 caracteres. |
Datos adicionales: otros_datos[]
| Dato | Obligatorio | Qué es |
|---|---|---|
codigo | Sí | Nombre del dato, hasta 60 caracteres. Por ejemplo OrdenCompra. |
texto | Sí | Su valor, hasta 500 caracteres. |
El documento al que se hace referencia: documento_referencia
| Dato | Obligatorio | Qué es |
|---|---|---|
documento_referencia.id | Para un documento del API | El «id» que el API le dio al documento original. |
documento_referencia.referencia | Para un documento del API | La referencia de su sistema con que emitió el original. |
documento_referencia.clave | Para un documento del API | La clave de 50 dígitos del original. |
documento_referencia.tipo_documento | Para un documento de fuera | Tipo del documento al que se hace referencia, cuando no se emitió con este API. Vea el catálogo. |
documento_referencia.tipo_documento_otros | Con el tipo 99 | Descripción del tipo, de 5 a 100 caracteres. |
documento_referencia.numero | Para un documento de fuera | El número del documento de fuera, hasta 50 caracteres. Con los tipos de documento 01, 02, 03, 04, 09, 11, 12, 15, 19 y 20 es la clave de 50 caracteres del comprobante: con otro número Hacienda lo rechaza. |
documento_referencia.fecha | Para un documento de fuera | Fecha de emisión del documento de fuera: AAAA-MM-DD, o con la hora, AAAA-MM-DDTHH:MM:SS. No puede tener más de 10 años. |
documento_referencia.codigo | No | Qué hace la referencia. Si falta: 01, anula, en una nota de crédito; 02, corrige el monto, en una nota de débito; 04, referencia a otro documento, en los demás. |
documento_referencia.codigo_otros | Con el código 99 | Descripción del motivo, de 5 a 100 caracteres. |
documento_referencia.razon | Sí | El motivo, de 3 a 180 caracteres. |
El proveedor de una factura de compra: proveedor
| Dato | Obligatorio | Qué es |
|---|---|---|
proveedor.tipo_identificacion | Sí | 01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE. 06 no contribuyente, solo con la condición de venta 13. |
proveedor.identificacion | Sí | El número, sin guiones ni espacios. |
proveedor.nombre | Sí | Nombre o razón social del proveedor, de 5 a 100 caracteres. |
proveedor.correo | Sí | Correo del proveedor. Sale en el comprobante. |
proveedor.telefono | No | Teléfono, de 8 a 20 dígitos. |
proveedor.provincia | Sí | Código de la provincia, de 1 a 7. Con el tipo 06 la dirección puede faltar, completa. |
proveedor.canton | Sí | Código del cantón, de dos dígitos. |
proveedor.distrito | Sí | Código del distrito, de dos dígitos. |
proveedor.otras_senas | Sí | Otras señas de la dirección, de 5 a 250 caracteres. |
proveedor.actividad | No | Código de la actividad económica del proveedor, de 6 caracteres. |
Ejemplo sencillo
{
"tipo": "FE",
"referencia": "INV/2026/00412",
"condicion_venta": "01",
"medio_pago": "04",
"receptor": {
"tipo_identificacion": "02",
"identificacion": "3101456789",
"nombre": "Constructora Los Robles S.A.",
"correo": "compras@losrobles.example"
},
"lineas": [
{
"cabys": "3744001000100",
"detalle": "Cemento Portland blanco 50 kg",
"cantidad": 20,
"unidad": "Unid",
"precio_unitario": 7500,
"tarifa_iva": "08"
}
],
"observaciones": "Entregar en bodega 2"
}
Ejemplo con casi todo
Una factura con la actividad del cliente, un descuento, una exoneración, un otro cargo, dos medios de pago y un dato adicional:
{
"tipo": "FE",
"referencia": "INV/2026/00413",
"condicion_venta": "01",
"medios_pago": [
{
"codigo": "01",
"monto": 50000
},
{
"codigo": "02",
"monto": 73100
}
],
"receptor": {
"tipo_identificacion": "02",
"identificacion": "3101456789",
"nombre": "Constructora Los Robles S.A.",
"correo": "compras@losrobles.example",
"actividad": "410001"
},
"lineas": [
{
"cabys": "3744001000100",
"detalle": "Cemento Portland blanco 50 kg",
"cantidad": 10,
"unidad": "Unid",
"precio_unitario": 7500,
"tarifa_iva": "08",
"codigo": "CEM-50",
"codigo_tipo": "01",
"tipo_transaccion": "01",
"descuento": 5000,
"descuento_codigo": "04",
"descuento_naturaleza": "Descuento por volumen de la obra"
},
{
"cabys": "8314100000000",
"detalle": "Asesoría técnica en obra",
"cantidad": 2,
"unidad": "h",
"precio_unitario": 20000,
"tarifa_iva": "08",
"exoneracion": {
"tipo_documento": "03",
"numero": "LEY-9635-2026-000123",
"articulo": 8,
"inciso": 1,
"institucion": "01",
"fecha": "2026-01-15",
"tarifa": 13
}
}
],
"otros_cargos": [
{
"tipo": "06",
"detalle": "Impuesto de servicio",
"monto": 4000,
"porcentaje": 10
}
],
"otros_datos": [
{
"codigo": "OrdenCompra",
"texto": "OC-2026-0098"
}
],
"observaciones": "Entregar en bodega 2"
}
La respuesta
Emitir responde 201 cuando crea el documento y 200 cuando la referencia ya existía con los mismos datos. Consultar responde 200. El cuerpo es siempre el mismo:
| Dato | Qué es |
|---|---|
id | Identificador del documento en el API. Con él se consulta y se descargan sus archivos. |
referencia | La referencia que envió su sistema. |
tipo | FE, TE, FEE, NC, ND o FEC. |
consecutivo | El consecutivo de 20 dígitos. Lo asigna el API. |
clave | La clave de 50 dígitos. |
estado | procesando, aceptado, rechazado o error. |
mensaje_hacienda | El motivo cuando Hacienda rechaza, o por qué el documento todavía no sale o no llegó. Vacío en los demás casos. |
fecha_emision | Fecha y hora de emisión, hora de Costa Rica. |
moneda | El código de la moneda. |
tipo_cambio | El tipo de cambio usado. 1 en colones. |
subtotal | Suma de cantidad por precio de las líneas, antes de descuentos. |
descuento | Suma de los descuentos. |
impuesto | El IVA que paga el cliente, sin lo exonerado. |
otros_cargos | Suma de los otros cargos. |
total | El total del comprobante. |
receptor | Identificación y nombre del cliente, o null en un tiquete sin cliente. En la factura de compra, el proveedor. |
ambiente | pruebas o produccion, según la llave usada. |
repetida | true cuando la referencia ya existía y se devolvió el mismo documento. |
archivos | Las direcciones del XML firmado, la respuesta de Hacienda y el PDF. null mientras no existan. |
Estados
| Estado | Qué significa |
|---|---|
procesando | El documento ya tiene consecutivo y clave. Hacienda todavía no responde, o el envío está en reintento: «mensaje_hacienda» lo dice. |
aceptado | Hacienda lo aceptó. Ya están el XML, la respuesta y el PDF. |
rechazado | Hacienda lo rechazó. «mensaje_hacienda» trae el motivo. Corrija y envíe de nuevo con la misma referencia. |
error | El documento no llegó a Hacienda: «mensaje_hacienda» dice por qué. Corrija y envíe de nuevo con la misma referencia. |
Un documento rechazado no se corrige: se emite otro. Arregle el dato en su sistema y envíe de nuevo con la misma referencia. El API crea un documento nuevo con otro consecutivo.
Notas de crédito y de débito
Una nota se emite contra una factura, un tiquete o una factura de exportación. Si el original se emitió con el API y Hacienda ya lo aceptó, indíquelo con su id, con la referencia de su sistema o con la clave, y el motivo.
{
"tipo": "NC",
"referencia": "RINV/2026/00031",
"lineas": [
{
"cabys": "3744001000100",
"detalle": "Cemento Portland blanco 50 kg",
"cantidad": 20,
"unidad": "Unid",
"precio_unitario": 7500,
"tarifa_iva": "08"
}
],
"documento_referencia": {
"referencia": "INV/2026/00412",
"codigo": "01",
"razon": "Anula la factura por error en el pedido"
}
}
- Las líneas son las que la nota acredita o cobra. Para anular una factura completa, envíe las mismas líneas de la factura.
- La nota va con el cliente, la moneda, el tipo de cambio, la condición de venta y el medio de pago del documento original. Hacienda compara esos datos con los del comprobante que la nota corrige. El API los toma solos del original: no hace falta enviarlos.
- La suma de las notas de crédito de una factura no puede pasar del total de la factura. Si pasa, el API responde con un error de validación.
- Si no envía
codigo, la nota de crédito va con 01, anula, y la de débito con 02, corrige el monto.
Nota contra un documento que no se emitió con el API
Indique el documento con su tipo, su número y su fecha de emisión. Cuando es un comprobante electrónico, el número es su clave de 50 caracteres. La nota lleva entonces su propio cliente, su condición de venta y su medio de pago.
{
"tipo": "NC",
"referencia": "RINV/2026/00032",
"moneda": "USD",
"tipo_cambio": 448.37,
"receptor": {
"tipo_identificacion": "02",
"identificacion": "3101456789",
"nombre": "Constructora Los Robles S.A.",
"correo": "compras@losrobles.example"
},
"lineas": [
{
"cabys": "3744001000100",
"detalle": "Cemento Portland blanco 50 kg",
"cantidad": 20,
"unidad": "Unid",
"precio_unitario": 7500,
"tarifa_iva": "08"
}
],
"documento_referencia": {
"tipo_documento": "01",
"numero": "50601102600310198765400100001010000000045123456789",
"fecha": "2026-10-01",
"codigo": "02",
"razon": "Corrige el monto facturado"
}
}
- Envíe el mismo cliente del documento original. Hacienda compara los datos de la nota con los del comprobante que corrige. La nota de una factura de exportación lleva el cliente del extranjero, tipo 05.
- Un comprobante que sí se emitió con el API no se indica de esta forma. Use su
id, sureferenciao suclave: así la nota toma sola sus datos. - La fecha del documento original no puede tener más de 10 años.
tipo_cambio el tipo de cambio de la factura original, no el del día. En una nota el API nunca pone el tipo de cambio del día.Notas financieras
Una nota con el código 09, nota de crédito financiera, o 10, nota de débito financiera, ajusta un valor: un descuento por pronto pago, intereses, una diferencia de cambio. Sus líneas pueden ir sin CABYS. Si no envía la tarifa, van exentas.
{
"tipo": "NC",
"referencia": "RINV/2026/00033",
"lineas": [
{
"detalle": "Descuento por pronto pago",
"cantidad": 1,
"precio_unitario": 5000
}
],
"documento_referencia": {
"referencia": "INV/2026/00412",
"codigo": "09",
"razon": "Descuento por pronto pago"
}
}
Factura de exportación
La factura de exportación lleva tipo FEE. Va a un cliente del extranjero y, por lo general, en dólares.
{
"tipo": "FEE",
"referencia": "EXP/2026/00027",
"condicion_venta": "02",
"plazo_credito": 30,
"medio_pago": "04",
"moneda": "USD",
"receptor": {
"tipo_identificacion": "05",
"identificacion": "US841234567",
"nombre": "Pacific Trading LLC",
"correo": "ap@pacifictrading.example",
"direccion": "1200 Harbor Blvd, Suite 400, Long Beach, CA 90802, Estados Unidos"
},
"lineas": [
{
"cabys": "8314100000000",
"detalle": "Servicios de desarrollo de software, octubre de 2026",
"cantidad": 1,
"unidad": "Sp",
"precio_unitario": 4500
}
]
}
- El cliente lleva
tipo_identificacion05, su identificación de hasta 20 letras y números, y sudireccionen el extranjero. - Si no envía
tarifa_iva, la línea va con10, exento. - Una línea de mercancías, con CABYS que empieza por 0, 1, 2, 3 o 4, necesita la
partida_arancelariade 12 dígitos. En servicios no va. - En dólares, si no envía el
tipo_cambio, el API usa el de venta del día. - Una nota de crédito o de débito contra una factura de exportación se emite igual que las demás: toma el cliente del extranjero del documento original.
Factura de compra
La factura de compra lleva tipo FEC. La emite quien compra, cuando quien vende no entrega factura electrónica: por ejemplo, un contribuyente del régimen simplificado.
{
"tipo": "FEC",
"referencia": "COMPRA/2026/00007",
"condicion_venta": "01",
"medio_pago": "01",
"proveedor": {
"tipo_identificacion": "01",
"identificacion": "205550123",
"nombre": "María Fernández Rojas",
"correo": "maria.fernandez@correo.example",
"telefono": "88887777",
"provincia": "2",
"canton": "01",
"distrito": "01",
"otras_senas": "200 metros norte de la iglesia, casa esquinera"
},
"lineas": [
{
"cabys": "8314100000000",
"detalle": "Mantenimiento del jardín, noviembre de 2026",
"cantidad": 1,
"unidad": "Os",
"precio_unitario": 60000,
"tarifa_iva": "08"
}
],
"documento_referencia": {
"tipo_documento": "14",
"numero": "RECIBO-0087",
"fecha": "2026-11-10",
"codigo": "04",
"razon": "Compra a un contribuyente del régimen simplificado"
}
}
- En lugar de
receptorse envíaproveedor, con su dirección y su correo. En el comprobante el proveedor figura como emisor y su empresa como receptor. documento_referenciaes obligatorio: el comprobante o recibo que entregó el proveedor, con su tipo, su número y su fecha.- El IVA de las líneas es el que su empresa declara por esa compra.
- El tipo de identificación 06, no contribuyente, se usa solo con la condición de venta 13, bienes usados. En ese caso la dirección puede faltar.
- La respuesta trae al proveedor en
receptor.
Descuentos y regalías
El descuento de una línea va en descuento, como monto. Con descuento_codigo se dice de qué clase es. Si no lo envía, va con 07, descuento comercial.
- Un descuento comercial, códigos 04 a 09 y 99, es siempre menor que el monto de la línea. Con 99 envíe además
descuento_otro. - Los códigos 01 y 03 son la regalía y la bonificación: la línea se entrega completa y su empresa asume el IVA. No envíe
descuento. - El código 02 es la regalía en la que el cliente paga solo el IVA. Con
base_imponiblese indica el valor sobre el que lo paga. Si falta, es el monto de la línea. - Una regalía o bonificación va en una línea con IVA, y no se usa en la factura de exportación ni en la factura de compra.
Exoneraciones
Cuando su cliente tiene una exoneración del IVA, envíe en cada línea exonerada el documento que la respalda, en exoneracion.
tarifava en puntos del IVA: 13 exonera todo el IVA de una línea al 13 %, y 9 exonera nueve de los trece puntos. El cliente paga el resto.- Con los tipos de documento 02, 03, 06, 07 y 08 el
articuloes obligatorio. - Una línea sin IVA no lleva exoneración. La factura de exportación tampoco.
- Un tiquete con exoneración necesita los datos del cliente.
Otros cargos
Son montos que se suman al total sin ser líneas de venta: timbres, el impuesto de servicio del 10 %, costos de exportación o un cobro por cuenta de un tercero. No llevan IVA.
- Cada cargo lleva su
tipo, sudetalley sumonto. - Con el tipo 04, cobro de un tercero, envíe
tercero: a nombre de quién se cobra. - Con el tipo 99 envíe
tipo_otros, la descripción del cargo.
Condición y medios de pago
- Con la condición de venta 99 envíe
condicion_venta_otros. Con el medio de pago 99,medio_pago_otros. - Las ventas a crédito, condiciones 02, 08 y 10, llevan
plazo_creditoen días. - Si el cliente paga con varios medios, envíe
medios_pagoen lugar demedio_pago: de dos a cuatro medios, cada uno con su monto. La suma debe ser el total del documento. Se admite una diferencia por redondeo de hasta 1 colón, o 0.05 en otra moneda, que el API ajusta en el medio de mayor monto. - El IVA devuelto de los servicios de salud con la tarifa reducida del 4 %, código 04, se indica en la línea con
iva_devuelto, y se usa cuando todo el documento se paga con tarjeta.
Referencias a otros documentos
Una factura, un tiquete o una factura de exportación también puede llevar documento_referencia: un contrato, una orden de compra, una nota de despacho, o el comprobante que sustituye.
- Un documento de fuera se indica con
tipo_documento,numeroyfecha. La fecha no puede tener más de 10 años. - Con los tipos de documento que son comprobantes electrónicos, 01, 02, 03, 04, 09, 11, 12, 15, 19, 20, el
numeroes la clave de 50 caracteres. Con otro número Hacienda rechaza el documento. - Un documento del API se indica con su
id, sureferenciao suclave. Debe tener ya la respuesta de Hacienda. - Con el tipo de documento 99 envíe
tipo_documento_otros. Con el código 99,codigo_otros. - Cuando reenvía con la misma referencia un documento que Hacienda rechazó, el API le pone solo al nuevo la referencia al rechazado, con el código 16. No tiene que enviarla.
Referencia y duplicados
La referencia es el número del documento en su sistema, por ejemplo INV/2026/00412. Es única por emisor.
- Si su sistema repite una solicitud con la misma referencia y los mismos datos, el API devuelve el documento que ya existía, con
repetida: true. No emite otro. Lo reconoce antes de revisar el documento: recibe ese mismo documento aunque entre tanto haya cambiado la configuración del emisor o el tipo de cambio del día. - Si la referencia ya existe con datos distintos, el API responde
409 referencia_repetida. - Si el documento anterior con esa referencia fue rechazado por Hacienda, el API emite uno nuevo.
Consultar y listar
GET /documentos/{id} devuelve un documento. GET /documentos devuelve la lista, del más reciente al más antiguo, con estos filtros opcionales:
| Parámetro | Qué filtra |
|---|---|
referencia | La referencia exacta de su sistema. Sirve para buscar un documento cuando no guardó el id. |
estado | procesando, aceptado, rechazado o error. |
tipo | FE, TE, FEE, NC, ND o FEC. |
desde, hasta | Fecha de emisión, en formato AAAA-MM-DD. |
pagina, por_pagina | Página desde 1 y documentos por página, hasta 100. Si faltan: página 1 con 50. |
{
"documentos": [
"…"
],
"pagina": 1,
"por_pagina": 50,
"total": 128
}
XML, respuesta y PDF
Las direcciones vienen en archivos y se piden con la misma llave. Valen null mientras el archivo no existe.
xml: el comprobante firmado, tal como se envió a Hacienda. Existe a los pocos segundos de emitir.respuesta: el mensaje de aceptación o de rechazo de Hacienda.pdf: la representación impresa. Existe cuando Hacienda acepta.
Su sistema es quien entrega estos archivos a su cliente. En pruebas el API no envía correos. En producción, si prefiere que e-FacturaCR le envíe el comprobante a su cliente cuando Hacienda lo acepta, lo activa en su perfil: es un extra mensual. Vea Producción y plan.
Avisos automáticos
Cuando Hacienda acepta o rechaza un documento, el API se lo avisa a su sistema con una solicitud a la dirección que usted registre. Así su sistema no tiene que estar preguntando por el estado de cada documento. Son opcionales: consultar sigue funcionando igual.
- En su perfil, en «Avisos y bitácora», escriba la dirección de su sistema que va a recibir los avisos. Debe empezar con
https://, llevar un nombre de dominio y poder recibirse desde internet. - Marque los avisos que quiere recibir.
- Guarde en su sistema la llave de firma que se le muestra. Empieza con
efcr_whsec_y se muestra completa una sola vez. - Use «Enviar un aviso de prueba» para comprobar que su sistema lo recibe.
Cada ambiente tiene su propia dirección y su propia llave de firma: los avisos de pruebas y los de producción se configuran por separado.
Qué se avisa
| Evento | Cuándo sale |
|---|---|
documento.aceptado | Hacienda aceptó el comprobante. Ya están el XML, la respuesta y el PDF. |
documento.rechazado | Hacienda rechazó el comprobante. «mensaje_hacienda» trae el motivo. |
documento.error | El documento no llegó a Hacienda y no se va a reintentar. «mensaje_hacienda» dice por qué. |
prueba | Usted presionó «Enviar un aviso de prueba» en su perfil. No trae documento. |
El aviso
Es una solicitud POST a su dirección, con el cuerpo en JSON, UTF-8:
{
"id": "avs_Q2x8Lm4TzK1RbYc6",
"evento": "documento.aceptado",
"creado": "2026-11-13T10:42:12-06:00",
"ambiente": "pruebas",
"documento": {
"id": "doc_8Jq2mXw4Tz1RbYc6",
"referencia": "INV/2026/00412",
"tipo": "FE",
"consecutivo": "00100003010000002318",
"clave": "50613112600310198765400100003010000002318158241973",
"estado": "aceptado",
"mensaje_hacienda": "",
"fecha_emision": "2026-11-13T10:42:07-06:00",
"moneda": "CRC",
"tipo_cambio": 1,
"subtotal": 150000.0,
"descuento": 0.0,
"impuesto": 19500.0,
"otros_cargos": 0.0,
"total": 169500.0,
"receptor": {
"identificacion": "3101456789",
"nombre": "Constructora Los Robles S.A."
},
"ambiente": "pruebas",
"archivos": {
"xml": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/xml",
"respuesta": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/respuesta",
"pdf": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/pdf"
}
}
}
| Dato | Qué es |
|---|---|
id | Identificador del aviso. Si llega uno repetido, su sistema ya lo procesó. |
evento | documento.aceptado, documento.rechazado, documento.error o prueba. |
creado | Fecha y hora en que se generó el aviso, hora de Costa Rica. |
ambiente | pruebas o produccion. |
documento | El documento, con los mismos datos de GET /documentos/{id}. null en el aviso de prueba. |
Y lleva estas cabeceras:
POST /efacturacr/aviso HTTP/1.1 Content-Type: application/json; charset=utf-8 X-Efcr-Evento: documento.aceptado X-Efcr-Aviso: avs_Q2x8Lm4TzK1RbYc6 X-Efcr-Firma: t=1794588132,v1=5f2c…e91a
| Cabecera | Qué es |
|---|---|
X-Efcr-Evento | El evento: documento.aceptado, documento.rechazado, documento.error o prueba. |
X-Efcr-Aviso | El identificador del aviso. Es el «id» del cuerpo y no cambia entre reintentos. |
X-Efcr-Firma | t=<tiempo>,v1=<firma>. El tiempo va en segundos (Unix). La firma es el HMAC-SHA256, en hexadecimal, de «<tiempo>.<cuerpo>» con la llave de firma de su perfil. |
El aviso de prueba trae documento en null y un mensaje:
{
"id": "avs_h3Kp9ZtQ0wVx7Nd2",
"evento": "prueba",
"creado": "2026-11-13T10:40:05-06:00",
"ambiente": "pruebas",
"documento": null,
"mensaje": "Aviso de prueba enviado desde su perfil del API de e-FacturaCR."
}
Cómo debe responder su sistema
- Responda con un código
2xxen menos de 12 segundos. Con eso el aviso queda entregado. El cuerpo de su respuesta no se lee. - Guarde el aviso y procéselo después de responder. Descargar el XML y el PDF puede esperar unos segundos.
- Con cualquier otra respuesta, o sin respuesta, el API lo reintenta 5 veces en 24 horas. Espera 1 minuto, 10 minutos, 1 hora, 6 horas y 16 horas después de cada intento fallido.
- No se siguen redirecciones: registre la dirección final.
- Un aviso puede llegar repetido. Guarde su
idy, si llega otra vez, responda200sin procesarlo de nuevo. - Si dos avisos se cruzan, manda el estado de
GET /documentos/{id}, que es siempre el oficial.
Comprobar la firma
Cualquiera que conozca su dirección podría enviarle una solicitud. Por eso cada aviso va firmado con su llave de firma, y su sistema debe comprobar la firma antes de confiar en él. La firma se calcula sobre el cuerpo tal como llega, antes de leerlo como JSON:
import hashlib
import hmac
import time
LLAVE_DE_FIRMA = 'efcr_whsec_SU_LLAVE'
def aviso_valido(cabecera, cuerpo, tolerancia=300):
"""cabecera: el valor de X-Efcr-Firma. cuerpo: los bytes recibidos, sin modificar."""
try:
partes = dict(parte.strip().split('=', 1) for parte in cabecera.split(','))
tiempo, firma = int(partes['t']), partes['v1']
except (AttributeError, KeyError, ValueError):
return False
if abs(time.time() - tiempo) > tolerancia:
return False # un aviso viejo: puede ser una copia de uno anterior
mensaje = str(tiempo).encode('ascii') + b'.' + cuerpo
esperada = hmac.new(LLAVE_DE_FIRMA.encode('utf-8'), mensaje, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, firma)
Si la firma no coincide, responda 401 y no procese el aviso. Si cree que la llave de firma se expuso, cámbiela en su perfil: la anterior deja de servir de inmediato.
Cuando un aviso no llega
- En «Avisos y bitácora» ve los últimos avisos con su resultado, por 90 días, y puede reenviar los que no se entregaron.
- Mientras su sistema esté fallando, los avisos en cola salen de uno en uno, con al menos un minuto entre intentos. Por eso un reintento puede salir algo después de lo indicado.
- Si su sistema lleva más de 24 horas sin dar una respuesta correcta a ningún aviso y ya van 30 intentos seguidos fallidos, los avisos se desactivan solos y se le avisa por correo al contacto del perfil. Se reactivan desde el perfil. Una caída corta no los desactiva.
- Mientras no haya una dirección registrada, o esté en pausa o desactivada, no se generan avisos. Los documentos que llegan a su estado final en ese tiempo no se avisan después: consúltelos por el API. Lo que ya estaba en cola sale al reactivarlos.
- Sus documentos se emiten igual con o sin avisos. Un aviso que falla nunca afecta a un comprobante.
Producción y plan
En pruebas no se cobra nada. El plan empieza el día en que su perfil pasa a producción.
Cómo se pasa a producción
- Emita en pruebas los tipos de documento que va a usar, y que Hacienda los acepte.
- En su perfil, en «Plan y consumo», prepare su ambiente de producción. Se crea su emisor de producción, todavía sin habilitar, con los datos de su emisor de pruebas.
- Cambie arriba a «Producción» y cargue el usuario, la contraseña y el certificado .p12 de producción de Hacienda. Revise la sucursal y la terminal: los consecutivos de producción no pueden repetir los que ya usó con otro sistema.
- Pida el paso a producción. e-FacturaCR lo revisa y lo habilita. Ese día empieza su plan.
- Cree una llave de producción y póngala en su sistema. Lo demás no cambia: son las mismas operaciones y los mismos datos.
El plan
| Plan API 1000 | US$75.00 al mes, con el IVA incluido |
| Documentos incluidos en cada ciclo | 1,000 |
| Documento adicional | US$0.22 cada uno, con el IVA incluido |
| Tope de adicionales por ciclo | 1,000 |
| Correo del comprobante a su cliente, enviado por e-FacturaCR (opcional) | US$50.00 más por ciclo, con el IVA incluido |
- El ciclo es mensual y empieza el día en que el perfil pasa a producción. Cada ciclo se factura por adelantado, con factura electrónica en dólares.
- Cuenta cada documento que el API recibe y crea en producción: factura, tiquete, factura de exportación, nota de crédito, nota de débito y factura de compra. No cuentan los que Hacienda rechaza, los que quedan con un error definitivo sin enviarse ni los de pruebas. El conteo se toma al cerrar el ciclo: un documento que en ese momento sigue en proceso cuenta en ese ciclo. Revisar sin emitir, consultar y descargar no tiene costo.
- Al pasar de los incluidos su sistema sigue facturando. Los adicionales de un ciclo se cobran en la factura del ciclo siguiente.
- El tope de adicionales protege de una cuenta inesperada si su sistema falla. Al llegar al tope el API responde
tope_adicionalesy deja de emitir hasta el ciclo siguiente. Usted puede pedir otro tope en su perfil. - La factura se paga con tarjeta, transferencia o SINPE dentro de los 5 días siguientes. El enlace de pago llega en el correo de la factura y está en «Plan y consumo». Con tarjeta se cobra en colones, por el equivalente al tipo de cambio de la factura. Si pasa 5 días vencida, el API responde
cuenta_morosay deja de emitir. Vuelve a emitir en cuanto se registra el pago. Consultar y descargar siguen funcionando siempre. - Su perfil le avisa por correo al usar el 80 % de los documentos incluidos, al pasarlos y al llegar al tope.
El plan en la respuesta de GET /emisor
Con una llave de producción, plan dice cómo va el ciclo. Con una de pruebas vale null.
| Dato | Qué es |
|---|---|
plan.nombre | El plan del perfil. |
plan.ciclo_desde | Primer día del ciclo en curso, AAAA-MM-DD. |
plan.ciclo_hasta | Último día del ciclo en curso, AAAA-MM-DD. |
plan.documentos_incluidos | Documentos que el plan incluye en cada ciclo. |
plan.documentos_usados | Documentos emitidos en el ciclo. No cuentan los que Hacienda rechazó. |
plan.adicionales | Documentos del ciclo por encima de los incluidos. Se cobran en la factura del ciclo siguiente. |
plan.tope_adicionales | Cuántos adicionales admite el ciclo. Al llegar, el API deja de emitir hasta el ciclo siguiente. |
plan.puede_emitir | false si el API no emitiría en este momento: pausa, factura vencida o tope alcanzado. |
plan.motivo | Por qué no puede emitir. Vacío si puede. |
{
"nombre": "Plan API 1000",
"ciclo_desde": "2026-11-01",
"ciclo_hasta": "2026-11-30",
"documentos_incluidos": 1000,
"documentos_usados": 612,
"adicionales": 0,
"tope_adicionales": 1000,
"puede_emitir": true,
"motivo": ""
}
Errores
Un error responde con el código HTTP que corresponde y este cuerpo. detalles aparece en los errores de validación y dice qué dato corregir.
{
"error": {
"codigo": "validacion",
"mensaje": "Línea 1: el código CABYS tiene 13 dígitos.",
"detalles": [
{
"campo": "lineas[0].cabys",
"mensaje": "Línea 1: el código CABYS tiene 13 dígitos."
}
]
}
}
| HTTP | Código | Qué pasó y qué hacer |
|---|---|---|
| 400 | solicitud_invalida | El cuerpo no es un JSON válido o pasa del tamaño permitido. |
| 401 | llave_anulada | La llave fue anulada. Cree otra en el perfil. |
| 401 | llave_invalida | Falta la llave, está mal escrita o no existe. |
| 402 | cuenta_morosa | La factura del plan está vencida y el API dejó de emitir. Vuelve a emitir en cuanto se registre el pago. Consultar y descargar siguen funcionando. |
| 403 | perfil_suspendido | El perfil está suspendido. Entre al perfil o escríbanos. |
| 403 | produccion_no_habilitada | El perfil todavía no está habilitado para producción. |
| 403 | sin_permiso | La llave es de solo consulta y no puede emitir. |
| 403 | tope_adicionales | El ciclo llegó a su tope de documentos adicionales. Pida otro tope en el perfil o espere al ciclo siguiente. |
| 404 | archivo_no_disponible | Ese archivo todavía no existe. El PDF y la respuesta llegan cuando Hacienda acepta. |
| 404 | no_encontrado | No existe un documento con ese identificador para este emisor. |
| 409 | emisor_incompleto | Al emisor le falta configuración. El mensaje dice qué. |
| 409 | referencia_repetida | Esa referencia ya existe con otros datos. Con los mismos datos se devuelve el documento que ya existía. |
| 422 | no_generado | El comprobante no se pudo armar con esos datos y quedó con estado «error». Su consecutivo no se reutiliza. Corrija y envíe de nuevo con la misma referencia. |
| 422 | validacion | Un dato no pasa la validación. El mensaje dice cuál y en qué línea. No se gasta consecutivo. |
| 429 | demasiadas_solicitudes | Demasiadas solicitudes en un minuto. Espere y repita. |
| 429 | tope_diario | La llave llegó a su tope de documentos del día. |
| 500 | error_interno | Algo falló de nuestro lado. Repita con la misma referencia: no se duplica. |
| 503 | api_en_pausa | El API está en pausa y no emite por el momento. Consultar y descargar siguen funcionando. |
Un error de validación no gasta consecutivo. Con un error 500 o un corte de conexión, repita la solicitud con la misma referencia.
Catálogos
Son los códigos de Hacienda de la versión 4.4, los mismos de sus esquemas oficiales.
Tipo de documento: tipo
| Código | Significado |
|---|---|
FE | Factura electrónica |
TE | Tiquete electrónico |
FEE | Factura electrónica de exportación |
NC | Nota de crédito electrónica |
ND | Nota de débito electrónica |
FEC | Factura electrónica de compra |
Tipo de identificación
El número va sin guiones ni espacios: 9 dígitos la cédula física, 10 la jurídica y el NITE, 11 o 12 el DIMEX. El cliente lleva 01 a 04; el 05, extranjero, va en la factura de exportación y en el tiquete, con hasta 20 letras y números. El 06 es solo del proveedor de una factura de compra.
| Código | Significado |
|---|---|
01 | Cédula física |
02 | Cédula jurídica |
03 | DIMEX |
04 | NITE |
05 | Extranjero no domiciliado |
06 | No contribuyente |
Tarifa del IVA: lineas[].tarifa_iva
| Código | Tarifa | Significado |
|---|---|---|
08 | 13 % | Tarifa general 13 % |
04 | 4 % | Tarifa reducida 4 % |
03 | 2 % | Tarifa reducida 2 % |
02 | 1 % | Tarifa reducida 1 % |
09 | 0.5 % | Tarifa reducida 0.5 % |
10 | 0 % | Exento |
01 | 0 % | Tarifa 0 % (artículo 32 del reglamento) |
11 | 0 % | Tarifa 0 % sin derecho a crédito |
05 | 0 % | Transitorio 0 % |
06 | 4 % | Transitorio 4 % |
07 | 8 % | Transitorio 8 % |
Condición de venta: condicion_venta
La 12 no se usa en el tiquete, en la factura de exportación ni en la factura de compra. La 13 es solo de la factura de compra.
| Código | Significado |
|---|---|
01 | Contado |
02 | Crédito |
03 | Consignación |
04 | Apartado |
05 | Arrendamiento con opción de compra |
06 | Arrendamiento en función financiera |
07 | Cobro a favor de un tercero |
08 | Servicios prestados al Estado a crédito |
10 | Venta a crédito en IVA hasta 90 días |
12 | Venta de mercancía no nacionalizada |
13 | Venta de bienes usados no contribuyente |
14 | Arrendamiento operativo |
15 | Arrendamiento financiero |
99 | Otros |
Medio de pago: medio_pago y medios_pago[].codigo
| Código | Significado |
|---|---|
01 | Efectivo |
02 | Tarjeta |
03 | Cheque |
04 | Transferencia o depósito bancario |
05 | Recaudado por terceros |
06 | SINPE Móvil |
07 | Plataforma digital |
99 | Otros |
Moneda: moneda
En dólares, si no envía el tipo de cambio, el API usa el de venta del día. En las demás monedas debe enviarlo. Una nota lleva el del documento original.
| Código | Significado |
|---|---|
CRC | Colones |
USD | Dólares |
EUR | Euros |
También se admiten los demás códigos de moneda del catálogo de Hacienda, siempre con su tipo de cambio: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USN, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, XSU, XUA, YER, ZAR, ZMW, ZWL.
Código del descuento: lineas[].descuento_codigo
| Código | Significado |
|---|---|
01 | Regalía: el emisor asume el IVA |
02 | Regalía con el IVA cobrado al cliente |
03 | Bonificación: el emisor asume el IVA |
04 | Descuento por volumen |
05 | Descuento por temporada |
06 | Descuento promocional |
07 | Descuento comercial |
08 | Descuento por frecuencia |
09 | Descuento sostenido |
99 | Otros descuentos |
Tipo de transacción: lineas[].tipo_transaccion
Se usa en facturas, notas y facturas de compra. No se usa en el tiquete ni en la factura de exportación.
| Código | Significado |
|---|---|
01 | Venta normal de bienes y servicios |
02 | Mercancía de autoconsumo exento |
03 | Mercancía de autoconsumo gravado |
04 | Servicio de autoconsumo exento |
05 | Servicio de autoconsumo gravado |
06 | Cuota de afiliación |
07 | Cuota de afiliación exenta |
08 | Bienes de capital para el emisor |
09 | Bienes de capital para el receptor |
10 | Bienes de capital para el emisor y el receptor |
11 | Bienes de capital de autoconsumo exento para el emisor |
12 | Bienes de capital sin contraprestación a terceros, exento para el emisor |
13 | Sin contraprestación a terceros |
Tipo del código del producto: lineas[].codigo_tipo
| Código | Significado |
|---|---|
01 | Código del producto del vendedor |
02 | Código del producto del comprador |
03 | Código asignado por la industria |
04 | Código de uso interno |
99 | Otros |
Otros cargos: otros_cargos[].tipo
| Código | Significado |
|---|---|
01 | Contribución parafiscal |
02 | Timbre de la Cruz Roja |
03 | Timbre del Benemérito Cuerpo de Bomberos |
04 | Cobro de un tercero |
05 | Costos de exportación |
06 | Impuesto de servicio 10 % |
07 | Timbre de colegios profesionales |
08 | Depósitos de garantía |
09 | Multas o penalizaciones |
10 | Intereses moratorios |
99 | Otros cargos |
Documento de exoneración: exoneracion.tipo_documento
| Código | Significado |
|---|---|
01 | Compras autorizadas por la Dirección General de Tributación |
02 | Ventas exentas a diplomáticos |
03 | Autorizado por ley especial |
04 | Exenciones de la Dirección General de Hacienda: autorización local genérica |
05 | Exenciones de la Dirección General de Hacienda: transitorio V |
06 | Servicios turísticos inscritos ante el ICT |
07 | Transitorio XVII: reciclaje y reutilizables |
08 | Exoneración a zona franca |
09 | Servicios complementarios para la exportación |
10 | Órgano de las corporaciones municipales |
11 | Exenciones de la Dirección General de Hacienda: autorización de impuesto local concreta |
99 | Otros |
Institución de la exoneración: exoneracion.institucion
| Código | Significado |
|---|---|
01 | Ministerio de Hacienda |
02 | Ministerio de Relaciones Exteriores y Culto |
03 | Ministerio de Agricultura y Ganadería |
04 | Ministerio de Economía, Industria y Comercio |
05 | Cruz Roja Costarricense |
06 | Benemérito Cuerpo de Bomberos de Costa Rica |
07 | Asociación Obras del Espíritu Santo |
08 | Federación Cruzada Nacional de Protección al Anciano (Fecrunapa) |
09 | Escuela de Agricultura de la Región Húmeda (EARTH) |
10 | Instituto Centroamericano de Administración de Empresas (INCAE) |
11 | Junta de Protección Social (JPS) |
12 | Autoridad Reguladora de los Servicios Públicos (Aresep) |
99 | Otros |
Código de la referencia: documento_referencia.codigo
El 09 y el 12 son de la nota de crédito y el 10, de la nota de débito.
| Código | Significado |
|---|---|
01 | Anula documento de referencia |
02 | Corrige monto |
04 | Referencia a otro documento |
05 | Sustituye comprobante provisional por contingencia |
06 | Devolución de mercancía |
07 | Sustituye comprobante electrónico |
08 | Factura endosada |
09 | Nota de crédito financiera |
10 | Nota de débito financiera |
12 | Nota de crédito financiera por exoneración posterior a la facturación |
13 | Anula documento de referencia por error material |
14 | Corrige monto por error material |
15 | Sustituye comprobante electrónico por error material |
16 | Sustituye comprobante electrónico rechazado |
99 | Otros |
Tipo del documento de referencia: documento_referencia.tipo_documento
El 09, devolución de mercancía, se usa solo en notas.
| Código | Significado |
|---|---|
01 | Factura electrónica |
02 | Nota de débito electrónica |
03 | Nota de crédito electrónica |
04 | Tiquete electrónico |
05 | Nota de despacho |
06 | Contrato |
07 | Procedimiento |
08 | Comprobante emitido en contingencia |
09 | Devolución de mercancía |
10 | Comprobante electrónico rechazado por el Ministerio de Hacienda |
11 | Sustituye factura rechazada por el receptor del comprobante |
12 | Sustituye factura de exportación |
13 | Facturación mes vencido |
14 | Comprobante aportado por contribuyente de régimen especial |
15 | Sustituye una factura electrónica de compra |
19 | Factura electrónica de exportación |
20 | Recibo electrónico de pago |
99 | Otros |
Unidad de medida: lineas[].unidad
Las unidades de Hacienda. Las más usadas: Unid unidad, Sp servicios profesionales, Os otros servicios, h hora, D día, Kg kilogramo, G gramo, L litro, M metro, m² metro cuadrado, Al alquiler de uso habitacional y Alc alquiler de uso comercial. El código distingue mayúsculas y minúsculas. Si no la envía, el API pone Unid en los bienes y Sp en los servicios, según el CABYS.
Forma farmacéutica: lineas[].forma_farmaceutica
El catálogo de Hacienda, con 229 códigos. Puede descargarlo en JSON.
Lo que todavía no hace esta versión
- Impuestos distintos del IVA en la línea: selectivo de consumo, combustibles, bebidas, tabaco y cemento.
- Más de un descuento por línea y más de un documento de referencia por comprobante.
- El detalle de surtido de una línea y el IVA cobrado a nivel de fábrica.
- La factura de compra a un proveedor del extranjero, y la factura a un cliente del extranjero por mercancía no nacionalizada.
- Las notas de crédito y de débito contra una factura de compra.
- Las monedas cuya unidad vale un colón o menos, como el peso colombiano: el tipo de cambio debe ser mayor que 1.
- El recibo electrónico de pago y la aceptación o el rechazo de los comprobantes recibidos.
Si necesita alguno, escríbanos.
Límites
| Solicitudes por minuto, por llave | 120 |
| Documentos por día, por llave | 500 |
| Líneas por documento | 200 |
| Tamaño del cuerpo | 256 KB |
| Largo de la referencia | 60 caracteres |
Al pasar de las solicitudes por minuto el API responde 429 con la cabecera Retry-After, que dice cuántos segundos esperar.
Seguridad
- Todo viaja por HTTPS. La llave va en la cabecera, nunca en la dirección.
- La llave completa existe solo en el momento de crearla: el sistema guarda una huella, no la llave. Nadie de e-FacturaCR puede verla. Si se pierde o se expone, anúlela en el perfil y cree otra.
- Cada emisor tiene su propia base de datos. Una llave solo ve y emite los documentos de su emisor.
- El certificado, su PIN y la contraseña de Hacienda se guardan cifrados.
- Los avisos automáticos van firmados y solo salen por HTTPS, a una dirección pública. La llave de firma se guarda cifrada y ninguna pantalla la vuelve a mostrar.
- El API revisa cada dato antes de usarlo y rechaza lo que no conoce. Los textos se limpian antes de llegar al comprobante.
- Cada solicitud queda en la bitácora del perfil por 90 días, con su resultado. La llave nunca se anota.
- Muchas solicitudes con llaves que no existen bloquean por unos minutos la dirección de donde vienen.
Ejemplo en Python
import requests
API = 'https://e-facturacr.com/api/v1'
LLAVE = 'efcr_test_SU_LLAVE'
cabeceras = {'Authorization': 'Bearer ' + LLAVE}
documento = {'tipo': 'FE',
'referencia': 'INV/2026/00412',
'condicion_venta': '01',
'medio_pago': '04',
'receptor': {'tipo_identificacion': '02',
'identificacion': '3101456789',
'nombre': 'Constructora Los Robles S.A.',
'correo': 'compras@losrobles.example'},
'lineas': [{'cabys': '3744001000100',
'detalle': 'Cemento Portland blanco 50 kg',
'cantidad': 20,
'unidad': 'Unid',
'precio_unitario': 7500,
'tarifa_iva': '08'}],
'observaciones': 'Entregar en bodega 2'}
r = requests.post(API + '/documentos', json=documento, headers=cabeceras, timeout=30)
datos = r.json()
if r.status_code in (200, 201):
print(datos['id'], datos['consecutivo'], datos['estado'])
else:
print(datos['error']['codigo'], datos['error']['mensaje'])
Y para esperar la respuesta de Hacienda y bajar los archivos:
import time
def esperar_respuesta(doc_id, intentos=12, pausa=5):
for _ in range(intentos):
d = requests.get(API + '/documentos/' + doc_id, headers=cabeceras, timeout=30).json()
if d['estado'] != 'procesando':
return d
time.sleep(pausa)
return d
d = esperar_respuesta(datos['id'])
if d['estado'] == 'aceptado':
xml = requests.get(d['archivos']['xml'], headers=cabeceras, timeout=30).content
pdf = requests.get(d['archivos']['pdf'], headers=cabeceras, timeout=60).content
Conectar Odoo 19
La conexión con Odoo 19 sigue los mismos pasos que con cualquier sistema. Esta es la forma que recomendamos:
- Antes de confirmar la factura en Odoo, envíela a
POST /documentos/validar. Si algo falta, muéstrele el aviso al usuario. - Al validar la factura en Odoo, envíe
POST /documentoscon el número de la factura de Odoo comoreferencia. - Guarde en la factura de Odoo el
id, el consecutivo y la clave que devuelve el API. - Con una tarea programada cada minuto, consulte los documentos que sigan en
procesando. Si su Odoo se puede alcanzar desde internet, registre su dirección en los avisos automáticos: el estado llega solo y la tarea queda como respaldo. - Cuando el estado sea
aceptado, descargue el XML, la respuesta y el PDF y adjúntelos a la factura. Desde ahí Odoo se los envía a su cliente. - Una nota de crédito de Odoo se envía como
NC, con la referencia de la factura original endocumento_referencia.referencia.
Los datos que Odoo debe tener por producto son el CABYS y la tarifa del IVA, y por cliente el tipo y el número de identificación.
Archivo OpenAPI
El contrato del API en formato OpenAPI 3.0, para importarlo en Postman, Insomnia u otra herramienta:
Términos del API
El uso del API se rige por los Términos del API de facturación, versión 1.0, que son un anexo de los Términos de Servicio de e-FacturaCR. El usuario del perfil los acepta la primera vez que entra, y de nuevo cuando hay una versión nueva.