DIAN Extensions

Colombian tax authority (DIAN) specific extensions for electronic invoicing

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

Basic Setup

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

Related

• UBL Extensions - General UBL extension system
• Invoice Document - Using DIAN extensions in invoices