Qué es esta API
La API de Facturación Electrónica DIAN es una API REST construida en NestJS que se integra directamente con los Web Services de la DIAN (Colombia) para emitir facturas electrónicas de venta, notas crédito y notas débito, cumpliendo la normativa vigente (Resolución 000227 del 23-sep-2025, Anexo Técnico v1.9).
Modelo multi-tenant (software propio)
La plataforma opera en modo multi-tenant: cada empresa cliente es un tenant
identificado por su NIT, con su propio certificado digital, softwareId y configuración
ante la DIAN.
La plataforma no opera como Proveedor Tecnológico habilitado: cada empresa se habilita individualmente ante la DIAN usando esta API como su software propio. Esto implica que cada tenant debe completar su propio proceso de habilitación antes de emitir en producción (ver Prerrequisitos por tenant y Proceso de habilitación DIAN).
Cada tenant mantiene de forma aislada:
- Su certificado PKCS#12 (cifrado con AES-256 y almacenado como BLOB en la base de datos, nunca en disco).
- Sus credenciales DIAN:
softwareId,softwarePin,testSetId,contributorId, clave técnica. - Su ambiente (
habilitacionoproduccion) y sus resoluciones de numeración.
El aislamiento se aplica en la capa de autorización: un usuario de tipo tenant solo puede
operar sobre su propio NIT (ver Autenticación).
Stack tecnológico
| Capa | Tecnología |
|---|---|
| Runtime | Node.js 20 LTS |
| Framework | NestJS 10+ |
| Lenguaje | TypeScript (strict mode) |
| Construcción XML | xmlbuilder2 (UBL v2.1) |
| Firma digital | node-forge + xml-crypto (XAdES-ENVELOPED) |
| Cliente SOAP | soap (Web Services DIAN) |
| Validación | class-validator + class-transformer |
| Persistencia | PostgreSQL + TypeORM |
| Autenticación | JWT (@nestjs/jwt + Passport) |
| Tests | Jest + Supertest |
Flujo de emisión (resumen)
- Recibir el DTO y validarlo.
- Construir el XML UBL v2.1 según el Anexo Técnico v1.9.
- Validar el XML contra el XSD oficial de la DIAN.
- Firmar con XAdES-ENVELOPED usando el certificado del tenant.
- Codificar en Base64 y enviar por SOAP (
SendBillSync). - Procesar la respuesta: extraer CUFE/CUDE, estado, errores y notificaciones.
Referencia de endpoints (Swagger)
La referencia técnica completa de todos los endpoints (parámetros, cuerpos, respuestas y el botón Authorize) está disponible en la UI de Swagger:
Siguiente paso
Antes de dar de alta una empresa, revisa qué necesita cada tenant: Prerrequisitos por tenant →