Skip to main content

Overview

DIAN Extensions are specialized UBL extensions for Colombian electronic invoicing requirements. These extensions contain regulatory information required by the Dirección de Impuestos y Aduanas Nacionales (DIAN). The DIAN extension system consists of:
  • DianExtensions - Main container for DIAN-specific content
  • DianExtensionsContent - Core DIAN data including invoice control, software provider, and QR code
  • Supporting components - InvoiceControl, InvoiceSource, SoftwareProvider, and AuthorizationProvider

DianExtensions

Main container class that wraps DIAN-specific extension content.

Constructor

import { DianExtensions } from 'ubl-builder';

const dianExtensions = new DianExtensions({
  dianExtensions: dianExtensionsContent
});
dianExtensions
DianExtensionsContent
required
The DIAN extension content containing invoice control, software provider information, and other regulatory data.

Methods

getDianExtensionsContent()

Retrieve the DIAN extensions content.
getDianExtensionsContent(): DianExtensionsContent
Returns: The DianExtensionsContent object containing all DIAN-specific data. Example:
const content = dianExtensions.getDianExtensionsContent();
console.log('QR Code:', content.getQRCode());

DianExtensionsContent

Core class containing all DIAN regulatory information.

Constructor

import { DianExtensionsContent } from 'ubl-builder';

const content = new DianExtensionsContent({
  invoiceControl?: InvoiceControl,
  invoiceSource?: InvoiceSource,
  softwareProvider?: SoftwareProvider,
  softwareSecurityCode?: string | UdtIdentifier,
  authorizationProvider?: AuthorizationProvider,
  QRCode?: string | UdtText
});

Parameters

invoiceControl
InvoiceControl
Invoice authorization and control information including authorization number, period, and authorized invoice range.UBL Field: sts:InvoiceControl
invoiceSource
InvoiceSource
Source identification code for the invoice.UBL Field: sts:InvoiceSource
softwareProvider
SoftwareProvider
Software provider and software identification information.UBL Field: sts:SoftwareProvider
softwareSecurityCode
string | UdtIdentifier
Security code for the invoicing software.UBL Field: sts:SoftwareSecurityCode
authorizationProvider
AuthorizationProvider
Authorization provider identification.UBL Field: sts:AuthorizationProvider
QRCode
string | UdtText
QR code content for the invoice (typically used for validation).UBL Field: sts:QRCode

Methods

setQRCode()

Set or update the QR code value.
setQRCode(value: string | UdtText): void
value
string | UdtText
required
QR code content as a string or UdtText instance.
Example:
content.setQRCode('https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=...');

getQRCode()

Retrieve the QR code value.
getQRCode(raw: boolean = true): string | UdtText
raw
boolean
default:"true"
If true, returns the raw string content. If false, returns the full UdtText object.
Returns: QR code as a string (if raw=true) or UdtText object (if raw=false).

Supporting Components

InvoiceControl

Contains invoice authorization and control information.

Constructor

import { InvoiceControl } from 'ubl-builder';

const invoiceControl = new InvoiceControl({
  invoiceAuthorization: string | UdtText,
  authorizationPeriod: string | PeriodType,
  authorizedInvoices: AuthorizedInvoices
});
invoiceAuthorization
string | UdtText
required
Invoice authorization number from DIAN.UBL Field: sts:InvoiceAuthorization
authorizationPeriod
string | PeriodType
required
Period during which the authorization is valid.UBL Field: sts:AuthorizationPeriod
authorizedInvoices
AuthorizedInvoices
required
Range of authorized invoice numbers.UBL Field: sts:AuthorizedInvoices

AuthorizedInvoices

Defines the range of authorized invoice numbers.

Constructor

import { AuthorizedInvoices } from 'ubl-builder';

const authorizedInvoices = new AuthorizedInvoices({
  prefix: string | UdtText,
  from: string | UdtText,
  to: string | UdtText
});
prefix
string | UdtText
required
Invoice number prefix.UBL Field: sts:Prefix
from
string | UdtText
required
Starting invoice number in the authorized range.UBL Field: sts:From
to
string | UdtText
required
Ending invoice number in the authorized range.UBL Field: sts:To

InvoiceSource

Source identification for the invoice.

Constructor

import { InvoiceSource } from 'ubl-builder';

const invoiceSource = new InvoiceSource({
  identificationCode?: string | UdtCode
});
identificationCode
string | UdtCode
Identification code for the invoice source.UBL Field: cbc:IdentificationCode

SoftwareProvider

Software provider and software identification.

Constructor

import { SoftwareProvider } from 'ubl-builder';

const softwareProvider = new SoftwareProvider({
  providerID: string | UdtIdentifier,
  softwareID: string | UdtIdentifier
});
providerID
string | UdtIdentifier
required
Identifier for the software provider.UBL Field: sts:ProviderID
softwareID
string | UdtIdentifier
required
Identifier for the invoicing software.UBL Field: sts:SoftwareID

AuthorizationProvider

Authorization provider identification.

Constructor

import { AuthorizationProvider } from 'ubl-builder';

const authProvider = new AuthorizationProvider({
  authorizationProviderID: string | UdtIdentifier
});
authorizationProviderID
string | UdtIdentifier
required
Identifier for the authorization provider.UBL Field: sts:AuthorizationProviderID

Usage Examples

Complete DIAN Extension

import {
  DianExtensions,
  DianExtensionsContent,
  InvoiceControl,
  AuthorizedInvoices,
  SoftwareProvider,
  PeriodType
} from 'ubl-builder';

// Create authorized invoice range
const authorizedInvoices = new AuthorizedInvoices({
  prefix: 'SETP',
  from: '990000000',
  to: '995000000'
});

// Create authorization period
const authPeriod = new PeriodType({
  startDate: '2024-01-01',
  endDate: '2024-12-31'
});

// Create invoice control
const invoiceControl = new InvoiceControl({
  invoiceAuthorization: '18764003532335',
  authorizationPeriod: authPeriod,
  authorizedInvoices: authorizedInvoices
});

// Create software provider
const softwareProvider = new SoftwareProvider({
  providerID: '800197268',
  softwareID: '56f2ae4e-9812-4fad-9255-08fcfcd5ccb0'
});

// Create DIAN content
const dianContent = new DianExtensionsContent({
  invoiceControl: invoiceControl,
  softwareProvider: softwareProvider,
  softwareSecurityCode: 'bdaa51c9e48c09e2d4c4895715b43b396fb2e5130c8d5a05906e0c63e144a7bb5b5ff0c6e1c10e628ea6cf4001d7c123',
  QRCode: 'https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=...'
});

// Wrap in DianExtensions
const dianExtensions = new DianExtensions({
  dianExtensions: dianContent
});

Adding DIAN Extensions to an Invoice

import {
  Invoice,
  UBLExtensions,
  UBLExtensionType,
  DianExtensions,
  DianExtensionsContent
} from 'ubl-builder';

// Create DIAN content (as shown above)
const dianContent = new DianExtensionsContent({
  // ... DIAN parameters
});

// Wrap in DianExtensions
const dianExt = new DianExtensions({
  dianExtensions: dianContent
});

// Create UBL extension
const ublExtension = new UBLExtensionType({
  extensionContent: dianExt
});

// Create extensions container
const extensions = new UBLExtensions();
extensions.addUBLExtension(ublExtension);

// Add to invoice
const invoice = new Invoice({
  UBLExtensions: extensions,
  // ... other invoice fields
});

Updating QR Code

import { DianExtensionsContent } from 'ubl-builder';

const dianContent = new DianExtensionsContent({
  softwareProvider: softwareProvider
});

// Set QR code later
const qrUrl = 'https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=abc123';
dianContent.setQRCode(qrUrl);

// Retrieve QR code
const qrCode = dianContent.getQRCode(); // Returns raw string
console.log('QR Code:', qrCode);
All DIAN extension parameters are optional in DianExtensionsContent, but you should include at least the information required by DIAN regulations for your specific use case.
The softwareSecurityCode must be a valid security code provided by DIAN for your registered invoicing software. Using an incorrect or invalid code will result in invoice rejection.

Best Practices

  1. Authorization Information: Always include complete InvoiceControl data with valid authorization numbers and periods
  2. Software Registration: Ensure your SoftwareProvider IDs match your DIAN registration
  3. QR Code Generation: Generate QR codes according to DIAN specifications
  4. Security Codes: Keep softwareSecurityCode secure and never expose it in client-side code
  5. Invoice Ranges: Ensure invoice numbers fall within your AuthorizedInvoices range

Build docs developers (and LLMs) love