CUFE: Estructura, Cálculo y Errores Frecuentes

Un solo error en el cálculo del CUFE basta para que la DIAN rechace una factura electrónica con código FAB14b — y el problema casi nunca está en el conector de red ni en el certificado, sino en una sutileza del orden de concatenación o del formato de las cifras decimales. Para equipos de ingeniería que integran facturación electrónica por primera vez, ese error suele aparecer cuando la integración ya pasó sandbox y el primer documento de producción se devuelve con la misma respuesta lacónica del validador.

Esta guía recorre la estructura matemática completa del CUFE: qué campos lo componen, en qué orden se concatenan, qué algoritmo de hash aplica y cómo se valida una vez generado. Al final encontrará los códigos de error más frecuentes que devuelve la DIAN cuando el CUFE local no coincide con el que ella misma calcula sobre el XML recibido, y las verificaciones que conviene automatizar antes de transmitir.

¿Qué es el CUFE y por qué la DIAN lo exige?

Definición técnica del CUFE

El CUFE (Código Único de Factura Electrónica) es un identificador único de 96 caracteres hexadecimales que se calcula como hash SHA-384 sobre una concatenación específica de campos de la factura. Su propósito es triple: garantizar la integridad del documento (cualquier alteración cambia el CUFE), facilitar la trazabilidad de la transacción dentro del repositorio DIAN, y servir como identificador unívoco para consultas y validaciones posteriores.

Marco normativo que lo regula

El CUFE está definido en el Anexo Técnico de la Resolución DIAN 0042 de 2020 (sección "Generación del CUFE") y aplica a todos los documentos electrónicos de venta. Existe una variante específica para nota crédito y nota débito (el CUDE) que sigue la misma lógica con campos ligeramente distintos. Cualquier documento que viaja a la DIAN debe llevarlo en el elemento UUID con el atributo schemeID="2" para CUFE versión 2.

Estructura matemática del CUFE

Los campos que entran al hash

Para calcular el CUFE se concatenan los siguientes campos del XML de la factura en un orden estricto, sin separadores entre ellos:

NumFac — número de la factura incluyendo prefijo (por ejemplo SETP990000001).
FecFac — fecha de emisión en formato YYYY-MM-DD.
HorFac — hora de emisión en formato HH:MM:SS con offset -05:00.
ValFac — subtotal antes de impuestos, formato decimal con dos posiciones.
CodImp1, ValImp1 — código y valor del primer impuesto (típicamente 01 para IVA).
CodImp2, ValImp2 — segundo impuesto. Si no aplica se rellenan con "0" y "0.00", nunca cadena vacía.
CodImp3, ValImp3 — tercer impuesto. Mismo criterio que el segundo cuando no aplica.
ValTot — valor total a pagar (subtotal más impuestos).
NitOFE — NIT del obligado a facturar, sin dígito de verificación.
NumAdq — número de identificación del adquiriente.
ClTec — clave técnica del software, entregada por la DIAN al habilitar el emisor.
TipoAmb — tipo de ambiente: "1" para producción, "2" para habilitación.

Algoritmo aplicado

Sobre la cadena resultante se aplica SHA-384 (no SHA-256, una confusión común al iniciar la integración). El digest se convierte a hexadecimal en minúsculas y se obtiene una cadena de 96 caracteres. Esa es el CUFE final que va al elemento UUID del XML. La elección de SHA-384 sobre SHA-256 obedece a la política de criptografía de la DIAN, que busca un margen de seguridad mayor frente a colisiones en un horizonte de validez documental de 5 años.

Ejemplo numérico paso a paso

Generación correcta: las tres sutilezas que producen rechazo

Formato exacto de los campos numéricos

Aquí está el origen del 70% de los errores. Los campos ValFac, ValImp1 y ValTot deben tener formato decimal con punto (no coma) y siempre dos decimales explícitos. Es decir: 1190.00, no 1190.0, no 1.190,00, no 1190. Los valores en cero también llevan los dos decimales: 0.00. Cuando no hay segundo o tercer impuesto, los campos CodImpN y ValImpN se rellenan con "0" y "0.00" — no se omiten ni se sustituyen por cadenas vacías.

La clave técnica nunca coincide entre ambientes

La clave técnica (ClTec) que la DIAN entrega al habilitarse es distinta para habilitación y producción. Es el error de migración más frecuente cuando un equipo pasa del sandbox a producción: el código sigue calculando el CUFE con la clave del ambiente equivocado, la DIAN responde con rechazo y nadie entiende por qué — porque los datos de la factura son correctos. Vale la pena mantener la clave técnica fuera del código y leerla por variable de entorno distinta en cada ambiente.

Codificación de caracteres y zona horaria

La cadena debe construirse en UTF-8 sin BOM, y la hora en HorFac siempre lleva el offset de Colombia (-05:00) — sin importar la zona horaria del servidor donde se genere. Si el servidor está en UTC o en otra región, hay que convertir explícitamente antes de concatenar. Un servidor con NTP desincronizado puede producir CUFEs intermitentes válidos e inválidos en producción, escenario que toma horas de diagnosticar si no se mira primero el reloj del sistema.

Errores frecuentes y cómo detectarlos antes de transmitir

Código de rechazo FAB14b — CUFE inválido

La DIAN responde con FAB14b cuando el CUFE enviado no coincide con el que ella misma calcula sobre los campos del XML. La causa casi siempre es una de tres: formato decimal incorrecto, clave técnica del ambiente equivocado, o algún campo concatenado en el orden incorrecto. Una técnica de diagnóstico útil es loguear la cadena completa que se está hasheando y compararla campo por campo con el XML transmitido — cuando la cadena local difiere de la reconstruida desde el XML, la falla se aísla en milisegundos.

Código FAB16 — CUFE duplicado

Aparece cuando dos facturas distintas terminan con el mismo CUFE. En la práctica significa que la integración está reutilizando un número de factura previamente transmitido. La validación local recomendada es mantener un índice de los CUFEs ya enviados y rechazar la transmisión cuando se intente reenviar uno existente con un payload distinto.

Anomalías intermitentes en producción

Cuando el CUFE falla aleatoriamente en uno de cada N envíos pero el código no cambió, casi siempre hay un problema de concurrencia: dos procesos pidiendo el siguiente consecutivo simultáneamente, o un servidor con reloj desincronizado generando timestamps en orden no monótono. Sincronizar NTP es la primera verificación; aislar la generación de consecutivos en una transacción atómica es la segunda.

Validación y verificación del CUFE generado

Verificación local antes de transmitir

Antes de enviar el XML a la DIAN, conviene volver a calcular el CUFE desde el documento que se acaba de construir y compararlo con el que se embebió en el elemento UUID. Si no coinciden, hay un bug entre la lógica de cálculo y la serialización del XML — y se detecta antes de la transmisión, no después del rechazo en producción.

Verificación contra el repositorio DIAN tras la respuesta

Una vez que la DIAN acepta el documento, el endpoint público de consulta (catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=CUFE) permite confirmar que la factura quedó indexada. Para integraciones que necesitan validar facturas de terceros — por ejemplo, módulos de cuentas por pagar o plataformas de factoring — esa verificación es la única forma de probar autenticidad sin depender del proveedor tecnológico emisor.

Para arquitecturas donde el cliente quiere apoyarse en herramientas listas para automatizar la verificación de CUFE en post-aceptación, la documentación técnica de la API de Alanube para Colombia incluye endpoints específicos de consulta de estado y validación de CUFE contra el repositorio DIAN, sin necesidad de orquestar la llamada al catálogo público manualmente.

Preguntas frecuentes

¿Cuál es la diferencia entre CUFE y CUDE en Colombia? El CUFE es el identificador único para facturas electrónicas de venta y se calcula sobre los campos de la factura misma. El CUDE (Código Único de Documento Electrónico) aplica a documentos asociados — notas crédito, notas débito y documento soporte — y agrega campos del documento referenciado (por ejemplo, el CUFE de la factura original a la que la nota corresponde). El algoritmo es el mismo (SHA-384 en minúsculas), pero la cadena de entrada es diferente. Ambos se transmiten dentro del elemento UUID del XML con scheme distinto. Confundir el cálculo es uno de los rechazos más comunes al añadir soporte para notas en una integración que ya manejaba facturas.

¿Cómo puedo depurar un CUFE rechazado por la DIAN sin trazas claras? La estrategia más rápida es construir un test unitario que tome el XML transmitido, extraiga los campos en el orden definido por el Anexo Técnico, los concatene exactamente y aplique SHA-384, comparando el resultado contra el CUFE que iba en el elemento UUID. Si no coinciden, el problema está antes de la transmisión y se aísla en la función de cálculo. Si coinciden, el problema es de datos: la DIAN recalculó el CUFE sobre el XML que recibió y obtuvo uno distinto, lo que apunta a una alteración entre la generación y el envío (firma rota, namespace alterado, encoding cambiado). Loguear ambas cadenas — la local y la reconstruida desde el XML transmitido — acelera el diagnóstico.

¿Qué diferencia hay entre el CUFE versión 1 y la versión 2? La versión 1, vigente hasta 2019, usaba SHA-1 como algoritmo de hash. La versión 2, introducida con la Resolución DIAN 0042 de 2020 y actualmente obligatoria, usa SHA-384 y modificó ligeramente el orden y los campos que entran al cálculo. En el XML se declara con el atributo schemeID="2" dentro del elemento UUID. Las integraciones nuevas trabajan exclusivamente con versión 2; la versión 1 solo aparece al consultar facturas históricas en el repositorio DIAN previas a la migración. Si una integración heredada todavía calcula CUFE versión 1, los documentos serán rechazados en la transmisión a producción.

¿Es posible verificar un CUFE recibido de un proveedor sin firmar facturas propias en la DIAN? Sí. El endpoint público del catálogo DIAN (catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=CUFE) acepta consultas anónimas y devuelve el estado del documento (aceptado, rechazado, anulado) y los datos básicos del emisor y el adquiriente. No requiere autenticación con certificado ni habilitación previa como emisor. Esto es útil para sistemas que reciben facturas de terceros — por ejemplo, módulos de cuentas por pagar o plataformas de factoring — y necesitan validar que la factura existe formalmente en la DIAN antes de procesarla. La única limitación es el rate limit del endpoint, moderado pero suficiente para flujos de validación post-recepción.

CUFE: Estructura, Cálculo y Errores Frecuentes en su Generación