Documento Equivalente POS DIAN: integración técnica paso a paso
Los comercios con sistemas POS (point of sale) que operan en Colombia enfrentan una confusión común: el tiquete de caja que imprime la máquina registradora no tiene validez como documento soporte para el comprador una vez que entró en vigencia el Documento Equivalente electrónico. Si tu sistema de POS sigue generando solo tiquetes físicos, las ventas B2C de tus clientes no tienen respaldo tributario ante la DIAN.
Esta guía cubre la integración técnica del Documento Equivalente de caja registradora (tipo 11) con la DIAN: qué es, cómo difiere de la factura electrónica, cómo construir el XML, calcular el CUDS y enviarlo correctamente al servicio de recepción. Incluye estrategias de envío masivo y consideraciones para POS de alto volumen.
Prerrequisitos
- NIT del comercio activo en el RUT de la DIAN
- Habilitación en el portal de la DIAN para emitir Documentos Equivalentes (proceso separado al de factura electrónica)
- Software de POS con capacidad de generar y enviar el XML del Documento Equivalente
- Certificado digital de firma para el software
- Conexión a internet en el punto de venta (o modo offline con sincronización posterior)
Qué es el Documento Equivalente POS y cuándo usarlo
El Documento Equivalente es el comprobante fiscal electrónico para transacciones con consumidores finales que no requieren una factura de venta con datos del comprador. A diferencia de la factura electrónica, no incluye los datos de identificación del receptor y no puede usarse para crédito de IVA.
| Característica | Factura Electrónica | Documento Equivalente POS |
|---|---|---|
| Receptor | Identificado (NIT/cédula) | Consumidor final anónimo |
| IVA descontable para comprador | Sí | No |
| Código de verificación | CUFE | CUDS |
| Tiempo de envío a DIAN | En el momento de emisión | Hasta 24 horas después del cierre de caja |
| Anulación | Nota crédito electrónica | Nota de ajuste del Documento Equivalente |
El Documento Equivalente aplica para transacciones en retail, gastronomía, servicios de belleza, farmacias, estaciones de servicio y cualquier negocio B2C donde el comprador es un consumidor final. Cuando el comprador solicita factura con sus datos antes del cierre de la transacción, el comercio debe emitir una factura electrónica en lugar del Documento Equivalente.
Cálculo del CUDS
El CUDS (Código Único del Documento Soporte) es el identificador único del Documento Equivalente. Se calcula como SHA-384 de la concatenación de los siguientes campos en orden exacto:
| Campo | Descripción | Formato requerido |
|---|---|---|
| Numero | Número del documento tal como se imprime | String exacto |
| FechaFactura | Fecha de la transacción | YYYY-MM-DD |
| HoraFactura | Hora de la transacción | HH:mm:ss |
| ValorFactura | Valor bruto de la transacción | Decimal 2 cifras, punto decimal |
| CodImpuesto1 | Código del impuesto (IVA = 01) | String “01” |
| ValorImpuesto1 | Valor del IVA de la transacción | Decimal 2 cifras, punto decimal |
| ValorTotal | Total a pagar por el consumidor | Decimal 2 cifras, punto decimal |
| NitOFE | NIT del comercio sin dígito de verificación | Solo dígitos |
| ClaveT | Clave técnica asignada por la DIAN | String exacto, sin modificar |
Nota: El código funcional de cálculo del CUDS está disponible en la documentación técnica de Alanube.
Estructura del XML del Documento Equivalente
El XML del Documento Equivalente tipo 11 usa el namespace UBL 2.1. La diferencia principal respecto a la factura electrónica es que el nodo AccountingCustomerParty (receptor) está vacío o contiene solo el código de consumidor final. Los campos obligatorios son el CUDS, el número de documento, la fecha y hora, los ítems vendidos con su IVA y los totales.
Nota: El XML de ejemplo completo está disponible en la documentación técnica de Alanube.
Envío masivo y sincronización diferida
Un POS puede tener cientos de transacciones diarias. La DIAN permite enviar los Documentos Equivalentes en batch hasta 24 horas después del cierre de caja del día. Estrategia recomendada:
- Almacenar cada transacción en cola local con estado
PENDING - Al cierre de caja, crear el set de documentos a enviar
- Enviar el batch al proveedor de API (máximo 50 documentos por request)
- Registrar los CUDS devueltos para cada documento
- Imprimir el CUDS en el tiquete físico del cliente
💡 Con Alanube: El endpoint POST /equivalent-documents/batch de Alanube Colombia acepta hasta 100 documentos en un solo request, calcula los CUDS automáticamente y devuelve el estado de la DIAN para cada uno en la misma respuesta.
Gestión de la cola y reintentos en POS
La gestión de la cola de documentos pendientes es el componente más crítico de la integración. Un POS con mala gestión de cola puede acumular miles de documentos sin enviar si la conexión falla, y el procesamiento posterior puede superar el límite de 24 horas.
El modelo de cola recomendado para un POS de alta disponibilidad tiene tres estados por documento:
- PENDING: Documento generado localmente pero no enviado a la DIAN. El tiquete se imprime sin CUDS.
- SENT: Documento enviado pero pendiente de confirmación de la DIAN (la respuesta aún no llegó o hubo timeout).
- CONFIRMED: DIAN devolvió el CUDS. El documento tiene validez tributaria.
Los documentos en estado SENT requieren especial atención: antes de reintentar el envío, el sistema debe consultar si el documento ya fue procesado por la DIAN usando el número del documento. Un reintento sin consulta previa puede generar duplicados que la DIAN luego exige anular mediante notas de ajuste.
Integración con sistemas POS: arquitecturas comunes
Las arquitecturas de integración varían según el nivel de centralización del negocio:
- POS con integración directa: El software POS en caja se conecta directamente a la API del proveedor de facturación. Requiere que cada terminal tenga conectividad y credenciales de API. Apropiado para negocios con pocos puntos de venta.
- Arquitectura centralizada: El POS envía las transacciones a un servidor central del negocio, que agrupa y envía a la DIAN. Reduce la complejidad en cada terminal y facilita el monitoreo. Requiere latencia aceptable entre el POS y el servidor central.
- Arquitectura híbrida con queue: El POS guarda localmente y un proceso de background sincroniza periódicamente con el proveedor de API. Diseñado para tolerancia a fallos de red. Es el patrón más robusto para retail de alto volumen.
Para cadenas de retail con docenas de puntos de venta, la arquitectura centralizada con queue es la más recomendada: permite auditoría centralizada, manejo de errores unificado y visibilidad sobre el estado de cada documento en todos los puntos de venta.
Casos de uso por vertical: retail, gastronomía y farmacias
La forma en que se implementa la integración del Documento Equivalente POS varía según el vertical del negocio. Estos son los patrones más comunes:
- Retail de ropa y calzado: El Documento Equivalente se emite por cada venta de mostrador. La complicación típica es el manejo de descuentos aplicados en caja: el XML debe reflejar el precio bruto, el descuento por ítem y el neto gravado para el cálculo correcto del IVA. Un error en el descuento produce diferencia en el CUDS.
- Restaurantes y cafeterías: La transacción puede incluir productos con tarifa de IVA diferenciada (comida preparada al 8%, bebidas al 19%). El XML debe agrupar los ítems por tarifa de IVA en nodos de impuesto separados. El error más frecuente es enviar todo el IVA en un único nodo con la tarifa dominante.
- Farmacias: Los medicamentos pueden ser exentos de IVA, lo que genera documentos con múltiples tarifas (0%, 5%, 19%) en la misma transacción. El CUDS debe calcularse con el total gravado correcto por cada tarifa. Además, los medicamentos controlados requieren registro del número de receta en campos adicionales del XML.
- Estaciones de servicio (combustible): Las ventas de combustible son exentas de IVA pero tienen el impuesto al consumo de gasolina (ICL). El Documento Equivalente debe clasificar correctamente el tipo de impuesto — un error común es poner el ICL en el nodo de IVA.
Errores comunes en el Documento Equivalente POS
Error: Regla: FAU05 — El tipo de documento no corresponde al software habilitado
Causa: El software fue habilitado para facturación electrónica pero no para Documento Equivalente (son habilitaciones separadas ante la DIAN).
Solución: Completar el proceso de habilitación para Documento Equivalente en el portal de la DIAN usando el mismo NIT.
Error: Regla: CUDS01 — CUDS no coincide
Causa: El CUDS calculado difiere del que la DIAN recalcula. Común cuando la clave técnica del software incluye espacios o caracteres especiales.
Solución: La clave técnica debe usarse exactamente como la DIAN la asignó, sin trim ni encoding adicional.
Error: Regla: DE-001 — Número de documento duplicado
Causa: Se intentó enviar un documento con el mismo número consecutivo que uno ya procesado por la DIAN.
Solución: Mantener control de consecutivos por punto de venta. Si ocurre por reintento sin consulta previa, verificar el estado del documento original antes de reintentar.
Error: Regla: DE-009 — Fecha de emisión fuera del rango permitido
Causa: El documento se intenta enviar con más de 24 horas de diferencia entre la fecha de transacción y el momento del envío.
Solución: Asegurar que los documentos del cierre del día se envíen antes de las 24 horas siguientes. Monitorear la cola de documentos PENDING activamente.
FAQ
¿Cuál es la diferencia entre el Documento Equivalente tipo 11 y tipo 12?
El tipo 11 es para tiquetes de máquinas registradoras POS (ventas al detal). El tipo 12 es para boletas de empaque (empresas de transporte y logística). Ambos se envían a la DIAN con el mismo servicio, pero tienen estructuras XML ligeramente diferentes según la Resolución DIAN 000042 de 2020.
¿El comprador puede solicitar que el Documento Equivalente se convierta en factura electrónica?
Sí. Según el artículo 616-1 del Estatuto Tributario colombiano, el comprador puede solicitar la factura electrónica en lugar del Documento Equivalente si necesita el soporte para deducción de IVA. El vendedor tiene la obligación de emitirla cuando se solicita antes del cierre de la transacción.
¿Cómo manejar operaciones de POS sin conexión a internet?
La DIAN permite la emisión offline con envío diferido de hasta 24 horas. El POS debe almacenar los documentos localmente y enviarlos cuando se restablezca la conexión, dentro del plazo máximo. El timestamp de emisión debe ser el momento real de la transacción, no el de envío a la DIAN.
¿La API de Alanube Colombia soporta el Documento Equivalente POS?
Sí, incluyendo el envío en batch para cierres de caja y el cálculo automático del CUDS. La API acepta el payload simplificado en JSON y gestiona la habilitación ante la DIAN. Obtén acceso sandbox en alanube.co.
¿Cuándo se debe emitir una nota de ajuste del Documento Equivalente?
Cuando hay devoluciones, cancelaciones o errores en un Documento Equivalente ya validado por la DIAN, se emite una nota de ajuste que referencia el CUDS original. A diferencia de la factura electrónica, la nota de ajuste del Documento Equivalente no requiere que el comprador la acepte — basta con enviarla a la DIAN dentro del plazo permitido. Esto simplifica el flujo de devoluciones en retail de alto volumen.
Fuentes
- DIAN. (2020). Resolución 000042 de 2020 — Documentos equivalentes electrónicos. https://www.dian.gov.co/impuestos/Paginas/Factura_Electronica.aspx
- DIAN. (2022). Anexo técnico documentos equivalentes versión 1.0. Dirección de Impuestos y Aduanas Nacionales.
- Congreso de Colombia. (2019). Estatuto Tributario — Artículo 616-1.
