PHPackages lopezsoft/ubl21dian - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Parsing & Serialization](/categories/parsing) 4. / 5. lopezsoft/ubl21dian ActiveLibrary[Parsing & Serialization](/categories/parsing) lopezsoft/ubl21dian =================== Core for electronic invoicing pre-validation - DIAN UBL 2.1 3.6.8(4mo ago)7216101MITPHPPHP >= 8.0 Since May 17Pushed 3mo ago1 watchersCompare [ Source](https://github.com/lopezsoft/ubl21dian)[ Packagist](https://packagist.org/packages/lopezsoft/ubl21dian)[ Docs](https://matias-api.com)[ RSS](/packages/lopezsoft-ubl21dian/feed)WikiDiscussions main Synced today READMEChangelog (6)Dependencies (2)Versions (32)Used By (1) DIAN SDK Node ============= [](#dian-sdk-node) [](https://www.google.com/search?q=https://www.npmjs.com/package/dian-sdk-node)[](https://opensource.org/licenses/MIT) Librería para Node.js y TypeScript diseñada para facilitar la integración con los servicios web de la DIAN en Colombia. Permite la firma de documentos electrónicos (facturas, notas, nómina) bajo el estándar XAdES-EPES y la comunicación SOAP con los endpoints de la DIAN. Este proyecto es una migración y modernización de la librería PHP `lopezsoft/ubl21dian`, aplicando principios de Clean Code, SOLID y Patrones de Diseño para una mayor mantenibilidad y extensibilidad. ✨ Características ----------------- [](#-características) - **Arquitectura Moderna**: Construida con TypeScript y siguiendo patrones de diseño como Facade, Command y Template Method. - **Firma XAdES-EPES**: Firma de documentos UBL 2.1 según los requerimientos de la DIAN. - **Firma SOAP con WS-Security**: Aseguramiento de los mensajes enviados al web service. - **Soporte Completo para Operaciones DIAN**: - Envío de facturas (síncrono y asíncrono). - Envío de Nómina Electrónica. - Envío de eventos (ApplicationResponse). - Consulta de estado de documentos y ZIPs. - Consulta de rangos de numeración. - Consulta de adquirientes (`GetAcquirer`). - ¡Y más! - **Fácilmente Extensible**: Añadir nuevas operaciones de la DIAN es tan simple como crear una nueva clase `Command`, sin modificar el código existente. 📦 Instalación ------------- [](#-instalación) ``` npm install dian-sdk-node ``` 🚀 Uso Básico ------------ [](#-uso-básico) La librería se utiliza a través de la clase `DianClient`, que actúa como una fachada para todas las operaciones. El flujo de trabajo es simple: 1. **Instanciar** el cliente con la configuración necesaria. 2. **Inicializarlo** con las credenciales del certificado. 3. **Ejecutar comandos** para cada operación, pasándole los parámetros requeridos. ### Ejemplo Completo: Enviar una Factura Electrónica [](#ejemplo-completo-enviar-una-factura-electrónica) A continuación, un ejemplo completo de cómo firmar y enviar una factura electrónica. ``` import * as fs from 'fs/promises'; import { DianClient, SendBillSyncCommand, ISendBillSyncParams } from 'dian-sdk-node'; async function enviarFactura() { try { // 1. Configurar el cliente (environment: 1 = PRODUCCION, 2 = HABILITACION) const client = new DianClient({ environment: 2 }); // 2. Inicializar con el certificado digital (.p12) const certificate = await fs.readFile('./certificados/certificado_pruebas.p12'); await client.initialize({ certificate, passwordPsswrd: 'tu_contraseña_del_certificado', }); console.log('Cliente DIAN inicializado correctamente.'); // 3. Cargar el XML de la factura sin firmar const unsignedInvoiceXml = await fs.readFile('./ejemplos/factura-sin-firmar.xml', 'utf-8'); // 4. Preparar y ejecutar el comando const command = new SendBillSyncCommand(); const params: ISendBillSyncParams = { fileName: 'FV-DEMO-001.xml', unsignedUblXml: unsignedInvoiceXml, }; console.log('Enviando factura a la DIAN...'); const dianResponse = await client.execute(command, params); // 5. Procesar la respuesta de la DIAN console.log('Respuesta de la DIAN:', JSON.stringify(dianResponse, null, 2)); if (dianResponse.IsValid) { console.log('¡Factura enviada y validada con éxito!'); console.log('CUFE:', dianResponse.XmlDocumentKey); } else { console.error('Error al validar la factura:', dianResponse.StatusMessage); } } catch (error) { console.error('Ha ocurrido un error en el proceso:', error); } } enviarFactura(); ``` ### Ejemplo 2: Consultar el Estado de un Documento [](#ejemplo-2-consultar-el-estado-de-un-documento) ``` import * as fs from 'fs/promises'; import { DianClient, GetStatusCommand } from 'dian-sdk-node'; async function consultarEstado() { const client = new DianClient({ environment: 2 }); const certificate = await fs.readFile('./certificados/certificado_pruebas.p12'); await client.initialize({ certificate, passwordPsswrd: 'tu_contraseña_del_certificado', }); const command = new GetStatusCommand(); const dianResponse = await client.execute(command, { trackId: 'el-track-id-devuelto-por-la-dian', }); console.log('Estado del documento:', dianResponse); } consultarEstado(); ``` ### Ejemplo 3: Enviar Nómina Electrónica [](#ejemplo-3-enviar-nómina-electrónica) ``` import * as fs from 'fs/promises'; import { DianClient, SendNominaSyncCommand } from 'dian-sdk-node'; async function enviarNomina() { const client = new DianClient({ environment: 2 }); const certificate = await fs.readFile('./certificados/certificado_pruebas.p12'); await client.initialize({ certificate, passwordPsswrd: 'tu_contraseña_del_certificado', }); const unsignedPayrollXml = await fs.readFile('./ejemplos/nomina-sin-firmar.xml', 'utf-8'); const command = new SendNominaSyncCommand(); const result = await client.execute(command, { unsignedPayrollXml, }); console.log('Resultado nómina:', result); } enviarNomina(); ``` 📚 API (Resumen) --------------- [](#-api-resumen) ### `DianClient` [](#dianclient) Es la clase principal y el único punto de entrada a la librería. - **`new DianClient(options)`**: Crea una nueva instancia del cliente. - `options.environment`: `1` para PRODUCCIÓN o `2` para HABILITACIÓN. - **`initialize(options)`**: Método asíncrono que carga y valida el certificado. **Debe ser llamado antes de ejecutar cualquier comando.** - `options.certificate`: `Buffer` con el contenido del archivo `.p12`. - `options.passwordPsswrd`: Contraseña del certificado. - **`execute(command, params)`**: Método asíncrono que ejecuta una operación. - `command`: Una instancia de la clase de comando que representa la operación (ej. `new SendBillSyncCommand()`). - `params`: Un objeto con los parámetros que requiere ese comando específico. --- ### **Comandos Disponibles (`/commands`)** [](#comandos-disponibles-commands) Cada clase representa una operación de la DIAN. Debes instanciar el comando que necesitas y pasarlo al método `execute` del cliente. ComandoDescripciónParámetros (`params`)**`SendBillSyncCommand`**Envía una factura síncronamente.`{ fileName: string, unsignedUblXml: string }`**`SendBillAsyncCommand`**Envía una factura asíncronamente.`{ fileName: string, unsignedUblXml: string }`**`SendNominaSyncCommand`**Envía un documento de Nómina Electrónica.`{ unsignedPayrollXml: string }`**`SendEventCommand`**Envía un evento (ej. acuse de recibo).`{ unsignedEventXml: string }`**`SendBillAttachmentAsyncCommand`**Envía un documento adjunto (`AttachedDocument`).`{ fileName: string, unsignedAttachedDocumentXml: string }`**`SendTestSetAsyncCommand`**Envía un Set de Pruebas para habilitación.`{ fileName: string, contentFile: string, testSetId: string }`**`GetStatusCommand`**Consulta el estado de un documento.`{ trackId: string }`**`GetStatusZipCommand`**Consulta el estado de un envío asíncrono (ZIP).`{ trackId: string }`**`GetNumberingRangeCommand`**Consulta los rangos de numeración.`{ accountCode: string, accountCodeT: string, softwareCode: string }`**`GetXmlByDocumentKeyCommand`**Obtiene el XML de un documento por su CUFE/CUDE.`{ trackId: string }`**`GetExchangeEmailsCommand`**Obtiene los correos de intercambio del facturador.`null` (no requiere)**`GetReferenceNotesCommand`**Obtiene las notas asociadas a un documento.`{ trackId: string }`**`GetAcquirerCommand`**Consulta la información de un adquiriente por su ID.`{ identificationType: string, identificationNumber: string }`📄 Licencia ---------- [](#-licencia) Este proyecto está bajo la **Licencia MIT**. Puedes usarlo libremente en tus proyectos comerciales y de código abierto. ### Health Score 47 — FairBetter than 93% of packages Maintenance79 Regular maintenance activity Popularity22 Limited adoption so far Community16 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 78.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~33 days Recently: every ~23 days Total 31 Last Release 130d ago PHP version history (3 changes)3.0.0PHP >= 5.4 3.1.0PHP >= 7.0 3.2.0PHP >= 8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/d53b507bd672a04ef105e1d15082e0472c422780b2aac811bd7eca509cf4ec85?d=identicon)[lopezsoft](/maintainers/lopezsoft) --- Top Contributors [![lopezsoft](https://avatars.githubusercontent.com/u/12355118?v=4)](https://github.com/lopezsoft "lopezsoft (63 commits)")[![dazza-dev](https://avatars.githubusercontent.com/u/21293561?v=4)](https://github.com/dazza-dev "dazza-dev (11 commits)")[![LEWISLOPEZGOMEZ](https://avatars.githubusercontent.com/u/173327063?v=4)](https://github.com/LEWISLOPEZGOMEZ "LEWISLOPEZGOMEZ (6 commits)") --- Tags xmlweb servicecoreubldiansoap dian ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/lopezsoft-ubl21dian/health.svg) ``` [![Health](https://phpackages.com/badges/lopezsoft-ubl21dian/health.svg)](https://phpackages.com/packages/lopezsoft-ubl21dian) ``` ### Alternatives [spatie/laravel-sitemap Create and generate sitemaps with ease 2.6k16.6M147](/packages/spatie-laravel-sitemap)[easybill/e-invoicing A package to read and create EN16931 e-invoices or CIUS like: XRechnung, ZUGFeRD etc. 14158.3k](/packages/easybill-e-invoicing)[japanese-date/japanese-date 日本の暦、祝日を取り扱うライブラリ 1610.0k](/packages/japanese-date-japanese-date) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)