e-FacturaCR API
Pruebas sin costo y producción

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.

Todo perfil empieza en el ambiente de pruebas de Hacienda, sin costo: ahí los documentos no tienen validez fiscal y sirven para construir y probar la conexión completa. Cuando su sistema está listo, pide el paso a producción. Vea Producción y plan.

Antes de empezar

  1. 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.
  2. La primera vez que entra, lea y acepte los Términos del API.
  3. 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.
  4. En Numeración, use una sucursal y una terminal que ningún otro sistema use con esa cédula.
  5. 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.

Con este correo entra al perfil.

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

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ónPara qué
POST /documentosEmitir un documento. Crea la factura, el tiquete, la nota o la factura de compra y lo envía a Hacienda.
POST /documentos/validarRevisar 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 /documentosListar documentos. Los documentos del emisor, del más reciente al más antiguo. Se filtra por referencia, estado, tipo y fechas.
GET /documentos/{id}/xmlDescargar el XML firmado. El comprobante electrónico tal como se envió a Hacienda.
GET /documentos/{id}/respuestaDescargar la respuesta de Hacienda. El mensaje de aceptación o de rechazo.
GET /documentos/{id}/pdfDescargar el PDF. La representación impresa. Existe cuando Hacienda acepta.
GET /emisorProbar 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"
}
DatoQué es
validotrue: 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.
repetidatrue cuando esa referencia ya se emitió con los mismos datos: emitir devolvería ese documento, sin crear otro.
documentoEl «id» del documento que ya existe con esa referencia, o null.
tipoFE, TE, FEE, NC, ND o FEC.
referenciaLa referencia que envió su sistema.
monedaLa moneda con que saldría el documento. En una nota, la de su documento original.
tipo_cambioEl tipo de cambio con que saldría. En una nota, el de su documento original.
subtotalSuma de cantidad por precio de las líneas, antes de descuentos.
descuentoSuma de los descuentos.
impuestoEl IVA que pagaría el cliente, sin lo exonerado.
otros_cargosSuma de los otros cargos.
totalEl total que tendría el comprobante.
avisosLista de observaciones que no impiden emitir, pero conviene revisar. Vacía si no hay.
ambientepruebas 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.

La emisión hace siempre estas mismas revisiones antes de reservar el consecutivo y de firmar. Un documento con un dato malo nunca gasta consecutivo, se revise antes o no.

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

DatoObligatorioQué es
tipoSíFE factura, TE tiquete, FEE factura de exportación, NC nota de crédito, ND nota de débito o FEC factura de compra.
referenciaSíEl número del documento en su sistema, hasta 60 caracteres. Es único por emisor y es lo que evita los duplicados.
receptorEn FE y FEEEl 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».
proveedorEn FECSolo en la factura de compra: a quién se le compra, con su dirección y su correo.
lineasSíDe 1 a 200 líneas. De cada una: CABYS, detalle, cantidad, precio y tarifa de IVA. El API calcula los totales.
condicion_ventaNoCódigo de Hacienda. Si falta: 01, contado. Una nota toma la condición, el plazo y el medio de pago del original.
condicion_venta_otrosCon la condición 99Descripción de la condición, de 5 a 100 caracteres.
plazo_creditoEn ventas a créditoDías de plazo. Obligatorio con las condiciones 02, 08 y 10.
medio_pagoNoCódigo de Hacienda. Si falta: 01, efectivo.
medio_pago_otrosCon el medio 99Descripción del medio de pago, de 3 a 100 caracteres.
medios_pagoNoEn 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.
monedaNoCódigo de la moneda. Si falta: CRC. Una nota va en la moneda y con el tipo de cambio de su documento original.
tipo_cambioEn moneda extranjeraColones 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.
actividadNoCódigo de la actividad económica del emisor. Si falta: la principal.
observacionesNoTexto libre de hasta 500 caracteres. Viaja en el XML y sale en el PDF.
otros_datosNoHasta 20 datos adicionales de uso comercial, cada uno con su nombre. Viajan en el XML y salen en el PDF.
otros_cargosNoHasta 15 cargos que se suman al total sin ser líneas: timbres, impuesto de servicio, cobros de terceros.
documento_referenciaEn NC, ND y FECEl 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

DatoObligatorioQué es
receptor.tipo_identificacionSí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.identificacionSíEl número, sin guiones ni espacios. La de un cliente del extranjero: hasta 20 letras y números.
receptor.nombreSíNombre o razón social, hasta 100 caracteres.
receptor.correoNoCorreo del cliente. Sale en el comprobante.
receptor.direccionNoDirección del cliente en el extranjero, de 5 a 300 caracteres. Solo con el tipo 05.
receptor.actividadNoCó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[]

DatoObligatorioQué es
cabysSí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.
detalleSíDescripción de la línea, de 3 a 200 caracteres.
cantidadSíMayor que cero, con hasta 3 decimales.
precio_unitarioSíPrecio de una unidad, sin el IVA, con hasta 5 decimales.
unidadNoUnidad de medida de Hacienda. Si falta: Unid para bienes y Sp para servicios.
tarifa_ivaNoCó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.
descuentoNoMonto 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_codigoNoCó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_naturalezaNoExplicación del descuento, de 3 a 80 caracteres.
descuento_otroCon el código 99Descripción del descuento, de 5 a 100 caracteres.
base_imponibleNoSolo con el descuento 02: el valor sobre el que el cliente paga el IVA. Si falta: el monto de la línea.
codigoNoCódigo del producto en su sistema, hasta 20 caracteres.
codigo_tipoNoTipo del código del producto. Si falta: 04, de uso interno.
tipo_transaccionNoTipo de transacción de la línea. En facturas, notas y facturas de compra. Vea el catálogo.
partida_arancelariaEn exportación de mercancíasPartida 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.
exoneracionNoEl documento que exonera el IVA de la línea. No se usa en la factura de exportación.
numero_vinEn vehículosNú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_medicamentoNoRegistro sanitario del medicamento, hasta 100 caracteres. Solo con CABYS que empieza por 3562 a 3565.
forma_farmaceuticaNoCódigo de la forma farmacéutica, hasta 3 caracteres. Solo con CABYS que empieza por 3562 a 3565.
iva_devueltoNotrue 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

DatoObligatorioQué es
exoneracion.tipo_documentoSíTipo del documento de exoneración. Vea el catálogo.
exoneracion.tipo_documento_otroCon el tipo 99Descripción del tipo, de 5 a 100 caracteres.
exoneracion.numeroSíNúmero del documento de exoneración, de 3 a 40 caracteres.
exoneracion.articuloCon los tipos 02, 03, 06, 07 y 08Número del artículo de la ley, entero.
exoneracion.incisoNoNúmero del inciso, entero, cuando el artículo lo tiene.
exoneracion.institucionSíInstitución que emitió la exoneración. Vea el catálogo.
exoneracion.institucion_otrosCon la institución 99Nombre de la institución, de 5 a 160 caracteres.
exoneracion.fechaSíFecha de emisión del documento de exoneración, AAAA-MM-DD.
exoneracion.tarifaSí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[]

DatoObligatorioQué es
codigoSíCódigo del medio de pago. Vea el catálogo.
montoSíLo pagado con ese medio, mayor que cero y con hasta 2 decimales.

Otros cargos: otros_cargos[]

DatoObligatorioQué es
tipoSíCódigo del cargo. Vea el catálogo.
tipo_otrosCon el tipo 99Descripción del cargo, de 5 a 100 caracteres.
detalleSíDetalle del cargo, de 3 a 160 caracteres.
montoSíMonto del cargo, mayor que cero y con hasta 5 decimales.
porcentajeNoPorcentaje que representa el cargo, por ejemplo 10. Es informativo.
terceroCon el tipo 04A nombre de quién se cobra.
DatoObligatorioQué es
tercero.tipo_identificacionSí01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE.
tercero.identificacionSíEl número, sin guiones ni espacios.
tercero.nombreSíNombre o razón social del tercero, de 5 a 100 caracteres.

Datos adicionales: otros_datos[]

DatoObligatorioQué es
codigoSíNombre del dato, hasta 60 caracteres. Por ejemplo OrdenCompra.
textoSíSu valor, hasta 500 caracteres.

El documento al que se hace referencia: documento_referencia

DatoObligatorioQué es
documento_referencia.idPara un documento del APIEl «id» que el API le dio al documento original.
documento_referencia.referenciaPara un documento del APILa referencia de su sistema con que emitió el original.
documento_referencia.clavePara un documento del APILa clave de 50 dígitos del original.
documento_referencia.tipo_documentoPara un documento de fueraTipo del documento al que se hace referencia, cuando no se emitió con este API. Vea el catálogo.
documento_referencia.tipo_documento_otrosCon el tipo 99Descripción del tipo, de 5 a 100 caracteres.
documento_referencia.numeroPara un documento de fueraEl 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.fechaPara un documento de fueraFecha 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.codigoNoQué 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_otrosCon el código 99Descripción del motivo, de 5 a 100 caracteres.
documento_referencia.razonSíEl motivo, de 3 a 180 caracteres.

El proveedor de una factura de compra: proveedor

DatoObligatorioQué es
proveedor.tipo_identificacionSí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.identificacionSíEl número, sin guiones ni espacios.
proveedor.nombreSíNombre o razón social del proveedor, de 5 a 100 caracteres.
proveedor.correoSíCorreo del proveedor. Sale en el comprobante.
proveedor.telefonoNoTeléfono, de 8 a 20 dígitos.
proveedor.provinciaSíCódigo de la provincia, de 1 a 7. Con el tipo 06 la dirección puede faltar, completa.
proveedor.cantonSíCódigo del cantón, de dos dígitos.
proveedor.distritoSíCódigo del distrito, de dos dígitos.
proveedor.otras_senasSíOtras señas de la dirección, de 5 a 250 caracteres.
proveedor.actividadNoCó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:

DatoQué es
idIdentificador del documento en el API. Con él se consulta y se descargan sus archivos.
referenciaLa referencia que envió su sistema.
tipoFE, TE, FEE, NC, ND o FEC.
consecutivoEl consecutivo de 20 dígitos. Lo asigna el API.
claveLa clave de 50 dígitos.
estadoprocesando, aceptado, rechazado o error.
mensaje_haciendaEl motivo cuando Hacienda rechaza, o por qué el documento todavía no sale o no llegó. Vacío en los demás casos.
fecha_emisionFecha y hora de emisión, hora de Costa Rica.
monedaEl código de la moneda.
tipo_cambioEl tipo de cambio usado. 1 en colones.
subtotalSuma de cantidad por precio de las líneas, antes de descuentos.
descuentoSuma de los descuentos.
impuestoEl IVA que paga el cliente, sin lo exonerado.
otros_cargosSuma de los otros cargos.
totalEl total del comprobante.
receptorIdentificación y nombre del cliente, o null en un tiquete sin cliente. En la factura de compra, el proveedor.
ambientepruebas o produccion, según la llave usada.
repetidatrue cuando la referencia ya existía y se devolvió el mismo documento.
archivosLas direcciones del XML firmado, la respuesta de Hacienda y el PDF. null mientras no existan.

Estados

EstadoQué significa
procesandoEl documento ya tiene consecutivo y clave. Hacienda todavía no responde, o el envío está en reintento: «mensaje_hacienda» lo dice.
aceptadoHacienda lo aceptó. Ya están el XML, la respuesta y el PDF.
rechazadoHacienda lo rechazó. «mensaje_hacienda» trae el motivo. Corrija y envíe de nuevo con la misma referencia.
errorEl 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"
  }
}

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"
  }
}
En moneda extranjera, envíe en 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
    }
  ]
}

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"
  }
}

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.

Exoneraciones

Cuando su cliente tiene una exoneración del IVA, envíe en cada línea exonerada el documento que la respalda, en exoneracion.

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.

Condición y medios de pago

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.

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 no recibe respuesta por un corte de conexión, repita la misma solicitud. Con la misma referencia nunca se emiten dos documentos.

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ámetroQué filtra
referenciaLa referencia exacta de su sistema. Sirve para buscar un documento cuando no guardó el id.
estadoprocesando, aceptado, rechazado o error.
tipoFE, TE, FEE, NC, ND o FEC.
desde, hastaFecha de emisión, en formato AAAA-MM-DD.
pagina, por_paginaPá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.

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.

  1. 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.
  2. Marque los avisos que quiere recibir.
  3. Guarde en su sistema la llave de firma que se le muestra. Empieza con efcr_whsec_ y se muestra completa una sola vez.
  4. 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

EventoCuándo sale
documento.aceptadoHacienda aceptó el comprobante. Ya están el XML, la respuesta y el PDF.
documento.rechazadoHacienda rechazó el comprobante. «mensaje_hacienda» trae el motivo.
documento.errorEl documento no llegó a Hacienda y no se va a reintentar. «mensaje_hacienda» dice por qué.
pruebaUsted 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"
    }
  }
}
DatoQué es
idIdentificador del aviso. Si llega uno repetido, su sistema ya lo procesó.
eventodocumento.aceptado, documento.rechazado, documento.error o prueba.
creadoFecha y hora en que se generó el aviso, hora de Costa Rica.
ambientepruebas o produccion.
documentoEl 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
CabeceraQué es
X-Efcr-EventoEl evento: documento.aceptado, documento.rechazado, documento.error o prueba.
X-Efcr-AvisoEl identificador del aviso. Es el «id» del cuerpo y no cambia entre reintentos.
X-Efcr-Firmat=<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

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

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

  1. Emita en pruebas los tipos de documento que va a usar, y que Hacienda los acepte.
  2. 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.
  3. 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.
  4. Pida el paso a producción. e-FacturaCR lo revisa y lo habilita. Ese día empieza su plan.
  5. 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 1000US$75.00 al mes, con el IVA incluido
Documentos incluidos en cada ciclo1,000
Documento adicionalUS$0.22 cada uno, con el IVA incluido
Tope de adicionales por ciclo1,000
Correo del comprobante a su cliente, enviado por e-FacturaCR (opcional)US$50.00 más por ciclo, con el IVA incluido

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.

DatoQué es
plan.nombreEl plan del perfil.
plan.ciclo_desdePrimer día del ciclo en curso, AAAA-MM-DD.
plan.ciclo_hastaÚltimo día del ciclo en curso, AAAA-MM-DD.
plan.documentos_incluidosDocumentos que el plan incluye en cada ciclo.
plan.documentos_usadosDocumentos emitidos en el ciclo. No cuentan los que Hacienda rechazó.
plan.adicionalesDocumentos del ciclo por encima de los incluidos. Se cobran en la factura del ciclo siguiente.
plan.tope_adicionalesCuántos adicionales admite el ciclo. Al llegar, el API deja de emitir hasta el ciclo siguiente.
plan.puede_emitirfalse si el API no emitiría en este momento: pausa, factura vencida o tope alcanzado.
plan.motivoPor 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."
      }
    ]
  }
}
HTTPCódigoQué pasó y qué hacer
400solicitud_invalidaEl cuerpo no es un JSON válido o pasa del tamaño permitido.
401llave_anuladaLa llave fue anulada. Cree otra en el perfil.
401llave_invalidaFalta la llave, está mal escrita o no existe.
402cuenta_morosaLa 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.
403perfil_suspendidoEl perfil está suspendido. Entre al perfil o escríbanos.
403produccion_no_habilitadaEl perfil todavía no está habilitado para producción.
403sin_permisoLa llave es de solo consulta y no puede emitir.
403tope_adicionalesEl ciclo llegó a su tope de documentos adicionales. Pida otro tope en el perfil o espere al ciclo siguiente.
404archivo_no_disponibleEse archivo todavía no existe. El PDF y la respuesta llegan cuando Hacienda acepta.
404no_encontradoNo existe un documento con ese identificador para este emisor.
409emisor_incompletoAl emisor le falta configuración. El mensaje dice qué.
409referencia_repetidaEsa referencia ya existe con otros datos. Con los mismos datos se devuelve el documento que ya existía.
422no_generadoEl 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.
422validacionUn dato no pasa la validación. El mensaje dice cuál y en qué línea. No se gasta consecutivo.
429demasiadas_solicitudesDemasiadas solicitudes en un minuto. Espere y repita.
429tope_diarioLa llave llegó a su tope de documentos del día.
500error_internoAlgo falló de nuestro lado. Repita con la misma referencia: no se duplica.
503api_en_pausaEl 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ódigoSignificado
FEFactura electrónica
TETiquete electrónico
FEEFactura electrónica de exportación
NCNota de crédito electrónica
NDNota de débito electrónica
FECFactura 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ódigoSignificado
01Cédula física
02Cédula jurídica
03DIMEX
04NITE
05Extranjero no domiciliado
06No contribuyente

Tarifa del IVA: lineas[].tarifa_iva

CódigoTarifaSignificado
0813 %Tarifa general 13 %
044 %Tarifa reducida 4 %
032 %Tarifa reducida 2 %
021 %Tarifa reducida 1 %
090.5 %Tarifa reducida 0.5 %
100 %Exento
010 %Tarifa 0 % (artículo 32 del reglamento)
110 %Tarifa 0 % sin derecho a crédito
050 %Transitorio 0 %
064 %Transitorio 4 %
078 %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ódigoSignificado
01Contado
02Crédito
03Consignación
04Apartado
05Arrendamiento con opción de compra
06Arrendamiento en función financiera
07Cobro a favor de un tercero
08Servicios prestados al Estado a crédito
10Venta a crédito en IVA hasta 90 días
12Venta de mercancía no nacionalizada
13Venta de bienes usados no contribuyente
14Arrendamiento operativo
15Arrendamiento financiero
99Otros

Medio de pago: medio_pago y medios_pago[].codigo

CódigoSignificado
01Efectivo
02Tarjeta
03Cheque
04Transferencia o depósito bancario
05Recaudado por terceros
06SINPE Móvil
07Plataforma digital
99Otros

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ódigoSignificado
CRCColones
USDDólares
EUREuros

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ódigoSignificado
01Regalía: el emisor asume el IVA
02Regalía con el IVA cobrado al cliente
03Bonificación: el emisor asume el IVA
04Descuento por volumen
05Descuento por temporada
06Descuento promocional
07Descuento comercial
08Descuento por frecuencia
09Descuento sostenido
99Otros 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ódigoSignificado
01Venta normal de bienes y servicios
02Mercancía de autoconsumo exento
03Mercancía de autoconsumo gravado
04Servicio de autoconsumo exento
05Servicio de autoconsumo gravado
06Cuota de afiliación
07Cuota de afiliación exenta
08Bienes de capital para el emisor
09Bienes de capital para el receptor
10Bienes de capital para el emisor y el receptor
11Bienes de capital de autoconsumo exento para el emisor
12Bienes de capital sin contraprestación a terceros, exento para el emisor
13Sin contraprestación a terceros

Tipo del código del producto: lineas[].codigo_tipo

CódigoSignificado
01Código del producto del vendedor
02Código del producto del comprador
03Código asignado por la industria
04Código de uso interno
99Otros

Otros cargos: otros_cargos[].tipo

CódigoSignificado
01Contribución parafiscal
02Timbre de la Cruz Roja
03Timbre del Benemérito Cuerpo de Bomberos
04Cobro de un tercero
05Costos de exportación
06Impuesto de servicio 10 %
07Timbre de colegios profesionales
08Depósitos de garantía
09Multas o penalizaciones
10Intereses moratorios
99Otros cargos

Documento de exoneración: exoneracion.tipo_documento

CódigoSignificado
01Compras autorizadas por la Dirección General de Tributación
02Ventas exentas a diplomáticos
03Autorizado por ley especial
04Exenciones de la Dirección General de Hacienda: autorización local genérica
05Exenciones de la Dirección General de Hacienda: transitorio V
06Servicios turísticos inscritos ante el ICT
07Transitorio XVII: reciclaje y reutilizables
08Exoneración a zona franca
09Servicios complementarios para la exportación
10Órgano de las corporaciones municipales
11Exenciones de la Dirección General de Hacienda: autorización de impuesto local concreta
99Otros

Institución de la exoneración: exoneracion.institucion

CódigoSignificado
01Ministerio de Hacienda
02Ministerio de Relaciones Exteriores y Culto
03Ministerio de Agricultura y Ganadería
04Ministerio de Economía, Industria y Comercio
05Cruz Roja Costarricense
06Benemérito Cuerpo de Bomberos de Costa Rica
07Asociación Obras del Espíritu Santo
08Federación Cruzada Nacional de Protección al Anciano (Fecrunapa)
09Escuela de Agricultura de la Región Húmeda (EARTH)
10Instituto Centroamericano de Administración de Empresas (INCAE)
11Junta de Protección Social (JPS)
12Autoridad Reguladora de los Servicios Públicos (Aresep)
99Otros

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ódigoSignificado
01Anula documento de referencia
02Corrige monto
04Referencia a otro documento
05Sustituye comprobante provisional por contingencia
06Devolución de mercancía
07Sustituye comprobante electrónico
08Factura endosada
09Nota de crédito financiera
10Nota de débito financiera
12Nota de crédito financiera por exoneración posterior a la facturación
13Anula documento de referencia por error material
14Corrige monto por error material
15Sustituye comprobante electrónico por error material
16Sustituye comprobante electrónico rechazado
99Otros

Tipo del documento de referencia: documento_referencia.tipo_documento

El 09, devolución de mercancía, se usa solo en notas.

CódigoSignificado
01Factura electrónica
02Nota de débito electrónica
03Nota de crédito electrónica
04Tiquete electrónico
05Nota de despacho
06Contrato
07Procedimiento
08Comprobante emitido en contingencia
09Devolución de mercancía
10Comprobante electrónico rechazado por el Ministerio de Hacienda
11Sustituye factura rechazada por el receptor del comprobante
12Sustituye factura de exportación
13Facturación mes vencido
14Comprobante aportado por contribuyente de régimen especial
15Sustituye una factura electrónica de compra
19Factura electrónica de exportación
20Recibo electrónico de pago
99Otros

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

Si necesita alguno, escríbanos.

Límites

Solicitudes por minuto, por llave120
Documentos por día, por llave500
Líneas por documento200
Tamaño del cuerpo256 KB
Largo de la referencia60 caracteres

Al pasar de las solicitudes por minuto el API responde 429 con la cabecera Retry-After, que dice cuántos segundos esperar.

Seguridad

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:

  1. Antes de confirmar la factura en Odoo, envíela a POST /documentos/validar. Si algo falta, muéstrele el aviso al usuario.
  2. Al validar la factura en Odoo, envíe POST /documentos con el número de la factura de Odoo como referencia.
  3. Guarde en la factura de Odoo el id, el consecutivo y la clave que devuelve el API.
  4. 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.
  5. 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.
  6. Una nota de crédito de Odoo se envía como NC, con la referencia de la factura original en documento_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:

Descargar openapi.json

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.