El primer SDK open-source de facturacion electronica DIAN para TypeScript/Node.js.
dian-kit es el primer SDK open-source para facturacion electronica ante la DIAN (Direccion de Impuestos y Aduanas Nacionales de Colombia), escrito en TypeScript con soporte completo de tipos.
Cubre el pipeline completo de facturacion electronica:
XML UBL 2.1 -- Firma XAdES-EPES -- CUFE/CUDE -- WS-Security SOAP -- DIAN
Ya fue validado contra el sandbox de la DIAN: factura aceptada con isValid: true, statusCode: 00.
- Generacion XML UBL 2.1 -- Factura Electronica, Documento POS, Nota Credito, Nota Debito
- Firma digital XAdES-EPES -- Con certificados .p12 de cualquier CA acreditada por ONAC
- Calculo CUFE/CUDE -- SHA-384 con truncamiento de montos segun especificacion DIAN
- Transporte SOAP con WS-Security Signature -- Los 7 metodos del web service DIAN
- Validacion con Zod -- Esquemas tipados para todos los tipos de documento
- SDK de alto nivel -- Clase
DianKitque orquesta todo el pipeline en una sola llamada - Dual ESM/CJS -- Funciona con
importyrequire - 215 tests -- Cobertura completa del core y el SDK
- Zero dependencias externas de red -- Toda comunicacion es directamente con la DIAN, sin intermediarios
npm install @dian-kit/core @dian-kit/sdk-nodeO con pnpm:
pnpm add @dian-kit/core @dian-kit/sdk-nodeimport { readFileSync } from "node:fs";
import { DianKit } from "@dian-kit/sdk-node";
// 1. Configurar el SDK
const kit = new DianKit({
certificate: readFileSync("./your-certificate.p12"),
certificatePassword: "your-certificate-password",
environment: "2", // "1" = Produccion, "2" = Sandbox
supplier: {
name: "YOUR COMPANY NAME",
identification: { number: "900123456", type: "31", dv: "7" },
personType: "1",
fiscalResponsibilities: ["O-13"],
taxInfo: { /* ... */ },
address: { /* ... */ },
email: "facturacion@yourcompany.com",
},
software: {
id: "your-software-id",
pin: "your-software-pin",
providerNit: "900123456",
providerName: "YOUR COMPANY NAME",
},
numbering: {
authorizationNumber: "18760000001",
prefix: "SETP",
startNumber: 990000000,
endNumber: 995000000,
startDate: new Date(2019, 0, 19),
endDate: new Date(2030, 0, 19),
technicalKey: "fc8eac422eba16e22ffd8c6f94b3f40a6e38162c",
},
});
// 2. Crear y enviar una factura
const invoice = await kit.createInvoice({
id: "SETP990000001",
issueDate: new Date(),
issueTime: new Date(),
customer: {
name: "COMERCIALIZADORA ABC SAS",
identification: { number: "800111222", type: "31", dv: "9" },
personType: "1",
fiscalResponsibilities: ["R-99-PN"],
taxInfo: { /* ... */ },
address: { /* ... */ },
email: "contabilidad@abc.com",
},
lines: [
{
id: "1",
quantity: 10,
unitCode: "EA",
description: "Servicio de consultoria",
price: 150_000,
lineExtensionAmount: 1_500_000,
taxTotals: [{
taxAmount: 285_000,
subtotals: [{
taxableAmount: 1_500_000,
taxAmount: 285_000,
percent: 19,
taxScheme: { code: "01" }, // IVA
}],
}],
},
],
taxTotals: [{
taxAmount: 285_000,
subtotals: [{
taxableAmount: 1_500_000,
taxAmount: 285_000,
percent: 19,
taxScheme: { code: "01" },
}],
}],
legalMonetaryTotal: {
lineExtensionAmount: 1_500_000,
taxExclusiveAmount: 1_500_000,
taxInclusiveAmount: 1_785_000,
allowanceTotalAmount: 0,
chargeTotalAmount: 0,
prepaidAmount: 0,
payableAmount: 1_785_000,
},
paymentMeans: { paymentForm: "1", paymentMethod: "30" },
});
// 3. Enviar a la DIAN
const response = await kit.send(invoice);
console.log(response.isValid); // true
console.log(response.statusCode); // "00"
console.log(response.trackId); // UUID para consultar estadoPara el ejemplo completo con multiples items, consulta examples/basic-invoice.ts.
- Ejemplo completo -- Factura con dos items, envio y consulta de estado
- Guia de inicio rapido -- Paso a paso desde cero
- Guia de certificado .p12 -- Como obtener tu certificado digital
- Errores comunes DIAN -- 10+ errores con soluciones
- Referencia tecnica DIAN -- Especificaciones oficiales
- Documentacion tecnica DIAN -- Anexos tecnicos, esquemas XSD, catalogo de errores
| Paquete | Descripcion | Version |
|---|---|---|
@dian-kit/core |
Motor principal: XML UBL 2.1, firma digital XAdES-EPES, CUFE/CUDE, transporte SOAP | |
@dian-kit/sdk-node |
SDK de alto nivel: clase DianKit que orquesta el pipeline completo con type safety y validacion Zod |
- Node.js >= 20 -- Se requieren APIs nativas (
fetch,crypto.webcrypto) - Certificado digital .p12 -- Emitido por una CA acreditada por ONAC (GarKeM, Andes SCD, Certicamara, etc.)
- Registro ante la DIAN -- Software ID, PIN y resolucion de numeracion activa. Se configuran en el portal de habilitacion de la DIAN
| Tipo | Codigo DIAN | Hash |
|---|---|---|
| Factura Electronica de Venta | 01 | CUFE |
| Documento Equivalente POS | 102 | CUDE |
| Nota Credito | 91 | CUDE |
| Nota Debito | 92 | CUDE |
- El certificado .p12 y las claves privadas nunca salen de tu maquina
- Las claves privadas nunca aparecen en logs ni en mensajes de error
- dian-kit no envia datos a servidores propios -- toda comunicacion es directamente con la DIAN
- Validacion de todos los inputs con Zod antes de generar XML o contactar la DIAN
dian-kit is the first open-source TypeScript/Node.js SDK for Colombian electronic invoicing (DIAN -- Colombia's tax authority). It covers the full pipeline: UBL 2.1 XML generation, XAdES-EPES digital signing, CUFE/CUDE hash computation, and WS-Security SOAP transport to the DIAN web services.
Already validated against the DIAN sandbox: invoice accepted with isValid: true, statusCode: 00.
- UBL 2.1 XML generation for Invoice, POS, Credit Note, and Debit Note
- XAdES-EPES digital signing with .p12 certificates
- CUFE/CUDE SHA-384 computation per DIAN specification
- WS-Security Signature SOAP transport (all 7 DIAN web service methods)
- Full Zod validation schemas with TypeScript type safety
- High-level
DianKitclass orchestrating the entire pipeline - Dual ESM/CJS output -- works with
importandrequire - 215 tests covering core engine and SDK
npm install @dian-kit/core @dian-kit/sdk-nodeimport { readFileSync } from "node:fs";
import { DianKit } from "@dian-kit/sdk-node";
const kit = new DianKit({
certificate: readFileSync("./your-certificate.p12"),
certificatePassword: "your-password",
environment: "2", // "1" = Production, "2" = Sandbox
supplier: { /* your company data */ },
software: { id: "uuid", pin: "pin", providerNit: "900123456", providerName: "Your Co" },
numbering: { /* DIAN numbering authorization */ },
});
const invoice = await kit.createInvoice({
id: "SETP990000001",
issueDate: new Date(),
issueTime: new Date(),
customer: { /* buyer data */ },
lines: [{ id: "1", quantity: 1, description: "Service", price: 500_000,
lineExtensionAmount: 500_000,
taxTotals: [{ taxAmount: 95_000, subtotals: [{ taxableAmount: 500_000,
taxAmount: 95_000, percent: 19, taxScheme: { code: "01" } }] }] }],
taxTotals: [{ taxAmount: 95_000, subtotals: [{ taxableAmount: 500_000,
taxAmount: 95_000, percent: 19, taxScheme: { code: "01" } }] }],
legalMonetaryTotal: { lineExtensionAmount: 500_000, taxExclusiveAmount: 500_000,
taxInclusiveAmount: 595_000, allowanceTotalAmount: 0, chargeTotalAmount: 0,
prepaidAmount: 0, payableAmount: 595_000 },
paymentMeans: { paymentForm: "1", paymentMethod: "30" },
});
const response = await kit.send(invoice);
console.log(response.isValid); // trueSee examples/basic-invoice.ts for the full example with multiple line items.
- Node.js >= 20
- .p12 digital certificate from an ONAC-accredited CA
- DIAN registration -- Software ID, PIN, and active numbering resolution
| Package | Description |
|---|---|
@dian-kit/core |
Core engine: UBL 2.1 XML, XAdES-EPES signing, CUFE/CUDE, SOAP transport |
@dian-kit/sdk-node |
High-level SDK: DianKit class with full type safety and Zod validation |
MIT -- Usa dian-kit libremente en proyectos personales y comerciales.
Las contribuciones son bienvenidas. Para comenzar:
git clone https://github.com/sergioarojasm98/dian-kit.git
cd dian-kit
pnpm install
pnpm build
pnpm test # 215 testsEl proyecto usa Conventional Commits, Biome para linting/formatting, y Vitest para testing.