Notas Crédito y Débito Electrónicas DIAN: Guía Técnica para ISVs en Colombia

Cuando un ISV colombiano añade soporte para notas de ajuste a su plataforma, la primera confusión no es técnica sino conceptual: ¿cuándo corresponde una nota crédito (NC) y cuándo una nota débito (ND)? La DIAN define las reglas en el Anexo Técnico 1.9, pero la documentación dispersa y los mensajes de error poco descriptivos llevan a implementaciones incorrectas que producen rechazos en producción y, en casos graves, divergencias entre el registro del ISV y el repositorio oficial de la DIAN.

Esta guía cubre el flujo técnico completo para emitir NC y ND ante la DIAN desde la API de un ISV: cuándo aplicar cada tipo, los campos obligatorios en UBL 2.1, cómo calcular y referenciar el CUDE, los estados del ciclo de vida del documento y la arquitectura de reintentos recomendada para plataformas de alto volumen.

Cuándo emitir una nota crédito vs una nota débito

Casos de uso de la nota crédito (NC)

La nota crédito reduce o anula el valor de una factura ya aceptada por la DIAN. Los cuatro casos que admite el Anexo 1.9 son: motivo 1 (devolución de bienes o parte de ellos), motivo 2 (anulación total de la factura), motivo 3 (rebaja o ajuste del precio pactado) y motivo 4 (descuento comercial aplicado con posterioridad a la facturación). El código del motivo va en DiscrepancyResponse/ReferenceID y la descripción libre en DiscrepancyResponse/Description. Omitir el elemento DiscrepancyResponse o enviar un código fuera del rango 1-4 produce un error de validación estructural antes de que la DIAN evalúe el contenido económico del documento.

Casos de uso de la nota débito (ND)

La nota débito incrementa el valor de una factura ya emitida. La norma reconoce dos motivos: motivo 1 (intereses de mora acordados contractualmente) y motivo 2 (ajuste de precio cuando el valor cobrado es inferior al pactado). La ND no cancela la factura base, la complementa. En implementaciones multi-tenant es frecuente ver notas débito generadas incorrectamente como facturas nuevas, lo que crea duplicaciones fiscales difíciles de corregir dentro del mismo período contable y que pueden alertar al área de auditoría del adquiriente.

El CUDE: el identificador de notas de ajuste, distinto al CUFE

Por qué las notas usan CUDE y no CUFE

Las notas crédito y débito no usan CUFE sino CUDE (Código Único de Documento Electrónico). El CUDE se calcula con el mismo algoritmo SHA-384 pero sobre una cadena diferente que agrega, entre otros, el UUID de la factura original referenciada. Si la integración reutiliza la función de cálculo de CUFE para notas, el documento será rechazado con el código FAB14b porque la DIAN calcula el CUDE del lado servidor y el resultado no coincide. La cadena de entrada del CUDE incluye campos adicionales definidos en la sección de documentos asociados del Anexo 1.9; cualquier diferencia en el orden o el formato de esos campos produce un hash distinto.

BillingReference: referencia obligatoria a la factura original

El campo más crítico en ambas notas es la referencia al documento que se ajusta. En UBL 2.1 para Colombia se declara dentro de BillingReference > InvoiceDocumentReference con dos subfields obligatorios: ID (número de la factura, por ejemplo FE-001234) y UUID (el CUFE de 96 caracteres de esa factura). Si el UUID referenciado no existe en la base DIAN o corresponde a un documento en estado RECHAZADO, la nota se rechaza con error 89. Almacenar el CUFE de cada factura emitida como campo no nulo en la base de datos del ISV inmediatamente después de la confirmación DIAN es un requisito de arquitectura, no solo un dato de auditoría.

Campos de totales: coherencia entre nota y factura original

LegalMonetaryTotal en anulaciones totales

Para notas crédito de anulación total (motivo 2), el LegalMonetaryTotal debe coincidir exactamente con el de la factura original: LineExtensionAmount, TaxExclusiveAmount, TaxInclusiveAmount y PayableAmount con los mismos valores incluyendo decimales. Una discrepancia de un peso en el PayableAmount genera error 101 de inconsistencia de totales. Se recomienda recuperar estos valores desde la respuesta DIAN almacenada de la factura original, no recalcularlos desde el pedido de negocio. El recalculo introduce riesgo de redondeo, especialmente en facturas con múltiples líneas y descuentos aplicados a nivel de cabecera.

Notas crédito parciales y líneas de ajuste

En ajustes parciales, las líneas de la nota deben corresponder exactamente a los ítems que se ajustan. No es válido emitir una nota crédito con una sola línea de ajuste global si la factura original tenía múltiples líneas con distintas tarifas de IVA; la DIAN validará que el IVA declarado en la nota sea consistente con las líneas que la componen. Para el cálculo de IVA en notas parciales se aplican las mismas reglas de la factura original: tarifa por código de producto, sin redondeos acumulativos entre líneas.

Flujo de transmisión a la DIAN: estados y errores frecuentes

Validación síncrona y estados esperados

Las notas crédito y débito siguen el modelo de validación previa síncrona de la Resolución 0042 de 2020. El ISV transmite el documento firmado con XAdES-BES y recibe en el mismo ciclo HTTP uno de tres estados: ACEPTADO (el CUDE queda registrado), ACEPTADO_CON_NOTIFICACION (válido con advertencias no bloqueantes) o RECHAZADO. Un timeout de red antes de recibir respuesta deja el documento en estado ambiguo: la DIAN puede haberlo procesado aunque el ISV no tenga confirmación local. La consulta por CUDE al endpoint de verificación DIAN es el mecanismo correcto para resolver esa ambigüedad sin retransmitir un documento que ya fue aceptado.

Errores más frecuentes en notas de ajuste

Los errores más comunes según el Anexo 1.9: Error 89, UUID referenciado no encontrado o en estado inválido (verificar que la factura original esté ACEPTADA). Error 101, inconsistencia en totales. Error 090, firma digital inválida o certificado expirado, frecuente cuando el certificado se renueva sin actualizar la configuración del proveedor de firma. Error 041, NIT del emisor no corresponde al habilitado, frecuente en migraciones multi-tenant. Un sistema de monitoreo que clasifique rechazos por código de error y NIT emisor permite detectar patrones de fallo sistémico antes de que escalen a soporte de primer nivel.

Arquitectura recomendada para ISVs multi-emisor

Aislamiento de CUFE por NIT en multi-tenant

En plataformas que gestionan múltiples emisores, el almacenamiento de CUFEs para referencia en notas debe estar particionado por NIT. Una consulta que devuelva el CUFE de la factura FE-001234 del NIT A cuando el emisor activo es el NIT B genera un error 89 difícil de diagnosticar porque el XML parece sintácticamente correcto. La clave primaria de la tabla de documentos emitidos debe incluir siempre el NIT como parte del índice primario, tanto en bases relacionales como en almacenes NoSQL usados como caché de respuestas DIAN. Para ISVs que necesitan delegar esta capa de gestión, la API de facturación electrónica para Colombia de Alanube gestiona el aislamiento de contexto por emisor como parte de su infraestructura multi-tenant.

Tabla de estados local y conciliación nocturna

Todo ISV de mediana escala debería mantener una tabla de estado local para notas con tres estados mínimos: PENDING (creada localmente, sin transmitir), TRANSMITTED (enviada, esperando confirmación) y CONFIRMED (CUDE recibido y almacenado). Un proceso de conciliación que revise documentos en TRANSMITTED por más de 5 minutos usando el endpoint de consulta DIAN resuelve el problema de timeouts de red. Sin este mecanismo, una NC de anulación que la DIAN procesó exitosamente pero cuya respuesta no llegó al ISV queda marcada como pendiente y el sistema podría retransmitirla, generando error de documento duplicado.

Preguntas frecuentes