SDK de JavaScript para Facturación Electrónica DIAN

SDK oficial para interactuar con la API de Facturación Electrónica DIAN de URAWEB. Este SDK simplifica la integración con la API, permitiendo crear facturas electrónicas y gestionar resoluciones sin necesidad de realizar peticiones HTTP manuales.

📋 Requisitos Previos

Antes de usar este SDK, es OBLIGATORIO:

• Estar registrado y habilitado como facturador electrónico ante la DIAN
• Contar con un Certificado Digital (Firma Electrónica) válido
• Disponer de un token de la empresa con Soluciones URAWEB

🚀 Instalación

npm install @uraweb/dian-facturacion-sdk

O si prefieres usar el código directamente:

git clone <repository-url>
cd js-sdk

📖 Uso Básico

Inicialización

const DianFacturacionSDK = require('@uraweb/dian-facturacion-sdk');

// Inicializar el SDK con tu token
const sdk = new DianFacturacionSDK({
  apiToken: 'tu-token-aqui',
  baseUrl: 'https://api.uraweb.com' // Opcional, tiene un valor por defecto
});

Configurar Resoluciones

Resolución de Facturación Electrónica

const resolution = await sdk.resolutions.configureElectronicInvoice({
  prefix: 'SETP',
  resolution: '18760000001',
  resolution_date: '2019-01-19',
  technical_key: 'fc8eac422eba16e22ffd8c6f94b3f40a6e38162c',
  from: 990000000,
  to: 995000000,
  generated_to_date: 0,
  date_from: '2019-01-19',
  date_to: '2030-01-19'
});

Resolución de Nota Crédito

const creditNoteResolution = await sdk.resolutions.configureCreditNote({
  prefix: 'NC',
  from: 1,
  to: 99999999
});

Resolución de Nota Débito

const debitNoteResolution = await sdk.resolutions.configureDebitNote({
  prefix: 'ND',
  from: 1,
  to: 99999999
});

Resolución de Nómina Electrónica

const payrollResolution = await sdk.resolutions.configureElectronicPayroll({
  prefix: 'NOM',
  from: 1,
  to: 99999999
});

Resolución de Nota a Nómina

const payrollNoteResolution = await sdk.resolutions.configurePayrollNote({
  prefix: 'NNOM',
  from: 1,
  to: 99999999
});

Resolución de Documento Soporte

const supportDocResolution = await sdk.resolutions.configureSupportDocument({
  prefix: 'DS',
  resolution: '18760000002',
  resolution_date: '2019-01-19',
  from: 990000000,
  to: 995000000,
  generated_to_date: 0,
  date_from: '2019-01-19',
  date_to: '2030-01-19'
});

Resolución de Nota Crédito a Documento Soporte

const creditNoteToSupportResolution = await sdk.resolutions.configureCreditNoteToSupportDocument({
  prefix: 'NCDS',
  from: 1,
  to: 99999999
});

Crear Factura Electrónica

const invoice = await sdk.invoices.createElectronic({
  items: [
    {
      name: 'Producto A - Laptop',
      code: '000004',
      amount: 1000,
      quantity: 1,
      discount: 0,
      tax: {
        id: 1,
        percentage: 19,
        amount: 159.66,
        base: 840.33
      }
    }
  ],
  customer: {
    identification_number: '222222222222',
    name: 'Cliente POS',
    phone: '999993333',
    address: 'direccion POS',
    email: '[email protected]',
    merchant_registration: '000000',
    type_document_identification_id: 3,
    type_organization_id: 2,
    city_code_dane: 12688,
    type_regime_id: 2,
    type_liability_id: 117,
    dv: 7
  },
  subtotal: 840.33,
  totalTaxes: 159.66,
  taxesBreakdown: [
    {
      id: 1,
      percentage: 19,
      amount: 159.66,
      base: 840.33
    }
  ],
  total: 1000,
  date: '2025-12-03',
  time: '22:50:06',
  payment_form: {
    payment_form_id: 1,
    payment_method_id: 10,
    payment_due_date: '2025-12-03',
    duration_measure: 0
  },
  orderReference: {
    id_order: 'ORD-45678',
    issue_date_order: '2025-11-28'
  },
  prefix: 'SETP',
  resolution_number: '18760000002',
  number_invoice: '990000102',
  notes: null,
  foot_note: 'Nota a pie de página opcional'
});

Descargar Factura

Descargar PDF

const pdfBlob = await sdk.invoices.downloadPDF('123456789', 'FES-SETP990000000.pdf');

// Guardar el archivo
const fs = require('fs');
const buffer = Buffer.from(await pdfBlob.arrayBuffer());
fs.writeFileSync('factura.pdf', buffer);

Descargar XML

const xmlBlob = await sdk.invoices.downloadXML('123456789', 'FES-SETP990000000.xml');

// Guardar el archivo
const fs = require('fs');
const buffer = Buffer.from(await xmlBlob.arrayBuffer());
fs.writeFileSync('factura.xml', buffer);

Descargar con formato específico

// Descargar como PDF
const pdfBlob = await sdk.invoices.download('123456789', 'FES-SETP990000000.pdf', 'pdf');

// Descargar como XML
const xmlBlob = await sdk.invoices.download('123456789', 'FES-SETP990000000.xml', 'xml');

🔧 Manejo de Errores

El SDK lanza errores específicos según el tipo de respuesta de la API:

try {
  const invoice = await sdk.invoices.createElectronic(invoiceData);
  console.log('Factura creada:', invoice);
} catch (error) {
  if (error.status === 422) {
    // Factura rechazada por la DIAN
    console.error('Errores de validación:', error.data.errors);
  } else if (error.status === 409) {
    // Documento duplicado
    console.error('Documento duplicado:', error.data);
  } else if (error.status === 401) {
    // No autorizado
    console.error('Token inválido o faltante');
  } else {
    // Otro error
    console.error('Error:', error.message);
  }
}

📚 API Reference

DianFacturacionSDK

Constructor

new DianFacturacionSDK(config)

Parámetros:

• config.apiToken (string, requerido): Token de autenticación de la API
• config.baseUrl (string, opcional): URL base de la API

Resolutions

configureElectronicInvoice(data)

Configura una resolución de facturación electrónica.

configureCreditNote(data)

Configura una resolución de nota crédito.

configureDebitNote(data)

Configura una resolución de nota débito.

configureElectronicPayroll(data)

Configura una resolución de nómina electrónica.

configurePayrollNote(data)

Configura una resolución de nota a nómina electrónica.

configureSupportDocument(data)

Configura una resolución de documento soporte.

configureCreditNoteToSupportDocument(data)

Configura una resolución de nota crédito a documento soporte.

Invoices

createElectronic(invoiceData)

Crea una factura electrónica.

Retorna:

• CreateElectronicInvoiceSuccessResponseDto si la factura es aceptada
• Lanza error con status: 422 si es rechazada por la DIAN
• Lanza error con status: 409 si el documento ya existe

downloadPDF(nit, filename)

Descarga una factura en formato PDF.

downloadXML(nit, filename)

Descarga una factura en formato XML.

download(nit, filename, format)

Descarga una factura en el formato especificado ('pdf' o 'xml').

🔒 Seguridad

• Nunca compartas tu token de API
• Nunca commits tu token en el código fuente
• Usa variables de entorno para almacenar credenciales sensibles

const sdk = new DianFacturacionSDK({
  apiToken: process.env.DIAN_API_TOKEN,
  baseUrl: process.env.DIAN_API_URL
});

📝 Notas

• El SDK utiliza fetch para las peticiones HTTP. En Node.js < 18, necesitarás instalar un polyfill como node-fetch.
• Todas las fechas deben estar en formato YYYY-MM-DD
• Todas las horas deben estar en formato HH:mm:ss
• Los montos deben ser números, no strings

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request.

📄 Licencia

MIT

📞 Soporte

Para soporte, contacta a Soluciones URAWEB.