Checklist técnico para evaluar un proveedor de API de facturación electrónica en Colombia

Un ISV colombiano que ha integrado facturación electrónica sabe que el primer mes en producción siempre revela lo que el sandbox no mostró: errores de CUFE que el proveedor no documenta, tiempos de respuesta que triplican el SLA prometido, o actualizaciones normativas de la DIAN que llegan sin previo aviso. El problema no fue elegir mal — fue no saber qué preguntar antes de firmar.

Este checklist recoge 8 criterios técnicos para evaluar cualquier proveedor de API de facturación electrónica en Colombia. Cada punto viene con una prueba concreta que se puede ejecutar antes de comprometerse con un contrato. El objetivo es que el equipo de desarrollo pueda completarlo en una tarde con acceso al sandbox del proveedor.

Criterio 1 — Habilitación ante la DIAN y alcance del servicio

La DIAN exige que los Proveedores Tecnológicos de facturación electrónica cumplan un proceso de habilitación formal. Antes de evaluar cualquier aspecto técnico, verificar que el proveedor esté listado en el registro oficial de la DIAN como Proveedor Tecnológico habilitado. Un proveedor no habilitado obliga al ISV a operar bajo la figura de Facturador Directo, lo cual implica obligaciones técnicas y legales adicionales para el emisor.

Qué verificar

Verificación mínima antes de evaluar el sandbox:
☐ Proveedor aparece en el listado DIAN de Proveedores Tecnológicos habilitados
☐ Proveedor emite facturas bajo el Régimen de Facturación Electrónica (no solo contingencia)
☐ El servicio cubre Factura Electrónica de Venta (tipo 01) y Nota Crédito (tipo 91)
☐ Declaran soporte para RADIAN (si el caso de uso lo requiere)
☐ Tienen NIT propio de Proveedor Tecnológico, no operan bajo NIT de cliente

Criterio 2 — Sandbox con validación real de la DIAN

Colombia usa validación previa síncrona: el documento XML firmado se envía a la DIAN antes de entregar la factura al receptor, y la DIAN responde con el estado de aceptación. Un sandbox válido simula exactamente ese flujo, incluyendo los rechazos. Un sandbox que acepta cualquier documento bien formado sin simular la validación DIAN no es útil para preparar el equipo para producción.

Prueba de rechazo intencional en sandbox

// Prueba 1: NIT inválido
POST /v1/invoices
{
  "issuer": { "taxId": "900000000-0" }  // dígito de verificación incorrecto
}
// Esperado: error con código DIAN o mensaje que identifica el campo
// Red flag: 201 Created o error genérico sin campo identificado

// Prueba 2: Fecha fuera de rango
{
  "issueDate": "2019-01-01"  // fecha anterior al régimen vigente
}
// Esperado: rechazo con mensaje sobre fecha inválida
// Red flag: documento aceptado o 500 Internal Server Error

// Prueba 3: Nota crédito sin CUFE de referencia
POST /v1/credit-notes
{
  "relatedInvoice": { "cufe": "cufe-inexistente-00000" }
}
// Esperado: rechazo por CUFE de referencia no encontrado
// Red flag: nota crédito creada sin validar referencia

Criterio 3 — Generación y estructura del CUFE

El CUFE (Código Único de Factura Electrónica) se calcula con el algoritmo SHA-384 sobre campos específicos del documento según la resolución vigente de la DIAN. Un CUFE mal calculado causa rechazo inmediato. El proveedor debe generar el CUFE internamente y exponerlo en la respuesta de la API para que el ISV pueda verificar el documento.

Lo mínimo que debe devolver la API tras emitir una factura

// Respuesta mínima esperada tras emisión exitosa
{
  "invoiceId": "FE-0001",
  "cufe": "<hash SHA-384 de 96 caracteres>",
  "status": "accepted",
  "dianResponse": {
    "code": "00",
    "description": "Documento validado por la DIAN"
  },
  "xmlUrl": "https://...",     // URL del XML firmado
  "pdfUrl": "https://..."      // URL del PDF/representación gráfica
}
// Red flag: respuesta sin cufe, sin dianResponse, sin URLs de documento

Criterio 4 — Cobertura de documentos electrónicos

La facturación electrónica en Colombia cubre más documentos que la factura de venta básica. Dependiendo del modelo de negocio del ISV, pueden ser necesarios: Nota de Débito (tipo 92), Documento Soporte de Compras (tipo 05 para régimen simple sin obligación de facturar), facturas de exportación, facturas de contingencia y, en algunos sectores, soporte RADIAN para endoso y transferencia de facturas.

Matriz de cobertura por tipo de documento

Antes de integrar, mapear qué tipos de documento necesita el ISV y verificar en el sandbox de cada proveedor si están disponibles: Factura de Venta (01), Nota Crédito (91), Nota Débito (92), Documento Soporte (05), Factura de Exportación (02), Factura de Contingencia y eventos RADIAN (Acuse de Recibo, Recibo del Bien, Aceptación Expresa, Rechazo). Si el proveedor no soporta algún tipo necesario, ese gap aparecerá como trabajo custom durante la integración.

Criterio 5 — Mensajes de error granulares y accionables

La DIAN devuelve códigos de rechazo específicos cuando rechaza un documento. El proveedor tiene dos opciones: traducir esos códigos en mensajes claros para el ISV, o simplemente reenviar el XML de respuesta DIAN sin procesar. La segunda opción obliga al equipo de desarrollo a mantener internamente la tabla de códigos DIAN y a abrir tickets para cada rechazo no documentado.

Criterio 6 — Webhooks y gestión de estado asíncrono

Aunque Colombia usa validación síncrona para la factura de venta básica, algunos documentos y eventos RADIAN tienen procesamiento asíncrono. Además, los ISVs con alto volumen necesitan gestionar estados de entrega al receptor y eventos del ciclo de vida del documento (acuses, aceptaciones, rechazos por parte del comprador). Sin webhooks nativos, el ISV debe implementar polling, lo cual es ineficiente a escala.

Qué verificar sobre webhooks

Checklist de webhooks:
☐ El proveedor ofrece webhooks nativos (no solo polling)
☐ Los webhooks incluyen firma HMAC o mecanismo de verificación de origen
☐ Hay reintentos automáticos con backoff exponencial documentado
☐ El evento incluye el cufe y el estado del documento
☐ Hay webhook para eventos RADIAN si el caso de uso los requiere
☐ Hay endpoint de prueba en sandbox para simular el evento

Criterio 7 — Actualizaciones normativas y SLA de implementación

La DIAN actualiza periódicamente las resoluciones de facturación electrónica, el Anexo Técnico y los requisitos de habilitación. Un proveedor que tarda semanas en implementar los cambios expone a sus clientes a documentos rechazados durante el período de transición. La pregunta no es si el proveedor se actualiza — es cuánto tarda y cómo comunica los cambios.

Preguntar explícitamente: ¿cuando la DIAN publicaron la última versión del Anexo Técnico, en cuántos días estaba disponible en producción? ¿Hay changelog público con fechas de implementación? ¿Los clientes reciben notificación con antelación suficiente antes de que entre en vigor un cambio? Un proveedor maduro tiene esas respuestas documentadas, no solo en el pitch de ventas.

Criterio 8 — Documentación viva y tiempo al primer request funcional

El tiempo al primer request funcional es la métrica más honesta de la DX de un proveedor. Un ISV con experiencia en integraciones debería poder ejecutar su primera factura de prueba en sandbox en menos de 30 minutos si la documentación es completa. Si tarda más de dos horas, el problema no es el equipo — es la documentación.

Señales de alerta en la documentación

Señales negativas: documentación solo en PDF descargable sin versión web; ejemplos de código con tokens placeholder sin instrucción de cómo obtener las credenciales reales; ausencia de colección Postman o equivalente; changelog con última entrada de hace más de seis meses; acceso al sandbox condicionado a pasar por el equipo de ventas. Señales positivas: referencia de API interactiva con ejemplos ejecutables, sandbox self-service con credenciales automáticas, guía de onboarding que lleva al primer request en pasos concretos.

Cómo usar este checklist antes de firmar

El proceso recomendado: solicitar acceso al sandbox sin contactar a ventas — si requieren una demo previa, descontar puntos de DX. Ejecutar las tres pruebas de rechazo intencional del Criterio 2. Verificar la respuesta de emisión del Criterio 3 y confirmar que el CUFE sea correcto. Mapear los tipos de documento del Criterio 4 contra las necesidades del ISV. Pedir el catálogo de errores del Criterio 5 antes de avanzar. Si el proveedor pasa los ocho criterios, la decisión final puede basarse en precio y SLA comercial.

Para ver cómo se aplican estos criterios en otros mercados de la región, revisar la guía multi-país sobre los 5 criterios técnicos para elegir una API de facturación en LATAM.

Preguntas frecuentes

¿Cuál es la diferencia entre un Proveedor Tecnológico y un Facturador Directo ante la DIAN?

Un Proveedor Tecnológico habilitado por la DIAN puede emitir facturas a nombre de sus clientes usando su propio set de certificados y su conexión directa con la DIAN. Un Facturador Directo es el propio emisor de la factura, que mantiene su conexión directa con la DIAN, sus certificados propios y gestiona el ciclo de vida del documento sin intermediario. Los ISVs que integran facturación para sus clientes generalmente trabajan con un Proveedor Tecnológico habilitado para no tener que mantener esa infraestructura ellos mismos.

¿Cómo puedo verificar si el sandbox de un proveedor realmente simula la validación de la DIAN?

La prueba más rápida es enviar un documento con un NIT con dígito de verificación incorrecto. Un sandbox que simula validación DIAN debe rechazarlo con un código o mensaje que indique el problema en el campo taxId del emisor o receptor. Si el documento se acepta o si el error devuelto es genérico como “400 Bad Request” sin contexto, el sandbox no está simulando la validación real de la autoridad fiscal.

¿Qué diferencia hay entre soporte de RADIAN básico y soporte completo?

El soporte básico de RADIAN cubre el Acuse de Recibo del Bien o Servicio y la Aceptación Expresa — los dos eventos mínimos para que una factura sea título valor ejecutable. El soporte completo incluye además el endoso, la transferencia, el pago parcial, la limitación de circulación y la consulta del estado en el registro RADIAN. Para ISVs que operan en factoring o confirming, el soporte completo es necesario; para casos de uso estándar, el soporte básico suele ser suficiente.

¿Es posible integrar RADIAN sin que el ISV tenga un software de gestión documental propio?

Sí, siempre que el proveedor de API exponga los endpoints de eventos RADIAN como parte de su servicio. El ISV puede enviar los eventos vía API sin necesidad de un módulo de gestión documental separado. Lo que sí requiere es que el flujo de negocio del ISV esté diseñado para capturar los eventos del comprador — acuse, aceptación o rechazo — y enviarlos al proveedor dentro de los plazos que establece la norma, que actualmente son de tres días hábiles para el acuse de recibo.

Este checklist es la aplicación Colombia de los 5 criterios técnicos generales para LATAM. Los requisitos de habilitación están documentados directamente en el portal de la DIAN.

Los principales proveedores con integración vía API en Colombia incluyen: Aliaddo (API REST y archivos planos para altos volúmenes), Factus, LaFactura (especializados en API de facturación), Plemsi (paquetes específicos para integradores), Facturatech, Carvajal Tecnología y Servicios y Alanube. Aplica el checklist anterior sobre la documentación pública de cada uno para identificar las diferencias técnicas reales antes de integrar.