Ir al contenido

Emitir factura electrónica de venta

POST
/v1/invoices
curl --request POST \
--url 'https://example.com/v1/invoices?wait=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "operationType": "example", "currency": "example", "exchangeRate": { "rate": 1, "date": "2026-04-15", "currency": "example" }, "taxPointDate": "2026-04-15", "despatchReferences": [ { "id": "example", "issueDate": "2026-04-15" } ], "receiptReferences": [ { "id": "example", "issueDate": "2026-04-15" } ], "taxRepresentative": { "idType": "11", "idNumber": "example", "dv": "example" }, "delivery": { "date": "2026-04-15", "time": "example", "address": { "line": "example", "cityCode": "example", "cityName": "example", "departmentCode": "example", "departmentName": "example", "postalCode": "example", "countryCode": "CO", "countryName": "example" }, "party": { "personType": "1", "idType": "11", "idNumber": "example", "dv": "example", "name": "example", "tradeName": "example", "firstName": "example", "familyName": "example", "email": "hello@example.com", "phone": "example", "address": { "line": "example", "cityCode": "example", "cityName": "example", "departmentCode": "example", "departmentName": "example", "postalCode": "example", "countryCode": "CO", "countryName": "example" }, "taxResponsibilities": [ "example" ], "taxScheme": "01" } }, "deliveryTerms": { "incoterm": "CFR", "description": "example", "specialTerms": "example" }, "interoperability": [ { "group": "example", "collections": [ { "name": "example", "fields": [ { "name": "example", "value": "example", "schemeId": "example", "schemeName": "example" } ] } ] } ], "notes": [ "example" ], "orderReference": "example", "payment": { "form": "1", "method": "10", "dueDate": "2026-04-15", "paymentId": "example" }, "items": [ { "code": "example", "description": "example", "quantity": 1, "unitCode": "94", "unitPrice": 1, "discount": 1, "discountReason": "example", "taxes": [ { "code": "20", "rate": 1, "perUnitAmount": 1, "baseUnitMeasure": 1, "baseUnitCode": "example", "name": "example" } ], "standardCodeScheme": "999", "freeOfCharge": true, "note": "example", "sellersItemId": "example", "additionalIds": [ { "id": "example", "schemeName": "example" } ], "brand": "example", "model": "example", "attributes": [ { "name": "example", "value": "example", "quantity": 1, "unitCode": "example" } ], "principal": { "idType": "11", "idNumber": "example", "dv": "example", "name": "example" }, "transport": { "filingNumber": "example", "remittanceNumber": "example", "freightValue": 1, "quantity": 1, "unitCode": "KGM" }, "deliveryLocation": { "id": "example", "schemeName": "example" }, "packSize": 1, "purchaseDate": "2026-04-15" } ], "withholdings": [ { "code": "05", "rate": 1, "taxableAmount": 1 } ], "allowanceCharges": [ { "isCharge": true, "reason": "example", "amount": 1, "reasonCode": "example" } ], "prepayments": [ { "id": "example", "amount": 1, "receivedDate": "2026-04-15", "paidDate": "2026-04-15", "paidTime": "example", "instructions": "example" } ], "payableRounding": 1, "rangeId": "example", "customer": { "personType": "1", "idType": "11", "idNumber": "example", "dv": "example", "name": "example", "tradeName": "example", "firstName": "example", "familyName": "example", "email": "hello@example.com", "phone": "example", "address": { "line": "example", "cityCode": "example", "cityName": "example", "departmentCode": "example", "departmentName": "example", "postalCode": "example", "countryCode": "CO", "countryName": "example" }, "taxResponsibilities": [ "example" ], "taxScheme": "01" }, "dueDate": "2026-04-15", "contingency": true, "dueDiligence": "01", "export": true }'
X-Tenant-Id
string

Id o NIT del facturador. Obligatorio con llaves de cuenta; ignorado con llaves restringidas.

Idempotency-Key
string
<= 255 characters

Repetir la petición con la misma llave devuelve el mismo documento, sin emitir otro.

X-Sandbox-Outcome
string
<= 60 characters

Solo con API keys de sandbox (sk_sandbox_…): elige el resultado de la DIAN simulada: accepted (por defecto), rejected: (ej. rejected:FAD06), timeout, rule90:accepted, rule90:rejected: o rule90:pending. Se rechaza con otras llaves.

wait
string
Allowed values: true false

True: espera la respuesta de la DIAN en la misma petición

Media typeapplication/json

Una factura electrónica de venta

object
operationType

El tipo de operación (CustomizationID); cada tipo de documento tiene el suyo por defecto. Facturas: 10 estándar (por defecto), 09 AIU, 11 mandatos (ingresos para terceros: las líneas indican su mandante), 12 transporte de carga (las líneas llevan su remesa del RNDC), 14 notarios, 15 compra y 16 venta de divisas (envíe dueDiligence). Documentos soporte y sus notas de ajuste: 10 residente (por defecto), 11 no residente. POS: 10; sus notas de ajuste: 20. Notas crédito: 20 con referencia a una factura (por defecto) o 22 sin ella; notas débito: 30 (por defecto) o 32. Facturas y notas del sector salud: SS-CUFE, SS-CUDE, SS-POS (notas que referencian un documento), SS-SNum, SS-Recaudo, SS-Reporte, SS-SinAporte (con los datos del sector en interoperability). Cualquier otro se rechaza

string
<= 12 characters
currency

La moneda, ISO 4217 (tabla 13.3.3); COP si no se envía. Un documento en otra moneda necesita exchangeRate

string
>= 3 characters <= 3 characters
exchangeRate

La tasa de cambio (PaymentExchangeRate): obligatoria para un documento en moneda extranjera; opcional para uno en COP. Los totales del documento se informan también en la otra moneda (la extensión TotalesCop de la DIAN)

object
rate
required

Cuántos pesos vale una unidad de la moneda extranjera: la TRM o la tasa que pactaron las partes, p. ej. 3825.50 para USD; hasta 6 decimales

Any of:
number
date
required

El día en que se fijó la tasa

string format: date
currency

Para un documento en COP: la moneda extranjera (ISO 4217) en la que también se informan sus totales. No la envíe cuando el documento mismo está en moneda extranjera (la conversión es entonces a COP)

string
>= 3 characters <= 3 characters
taxPointDate

Cuándo se causa el impuesto, si no es la fecha de emisión (TaxPointDate)

string format: date
despatchReferences

Documentos de despacho relacionados con el documento (DespatchDocumentReference)

Array<object>
<= 20 items

Un documento relacionado: un documento de despacho o de recepción

object
id
required

Su número, con prefijo (hasta 20 caracteres)

string
>= 1 characters <= 20 characters
issueDate

Su fecha de emisión

string format: date
receiptReferences

Documentos de recepción relacionados con el documento (ReceiptDocumentReference)

Array<object>
<= 20 items

Un documento relacionado: un documento de despacho o de recepción

object
id
required

Su número, con prefijo (hasta 20 caracteres)

string
>= 1 characters <= 20 characters
issueDate

Su fecha de emisión

string format: date
taxRepresentative

La persona autorizada para descargar el documento en nombre del comprador (TaxRepresentativeParty)

object
idType
required

Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP

string
Allowed values: 11 12 13 21 22 31 41 42 47 48 50 91
idNumber
required

El número del documento de identidad, sin el dígito de verificación

string
>= 1 characters <= 20 characters
dv

El dígito de verificación del NIT; obligatorio si idType es 31

string
/^\d$/
delivery

La entrega de los bienes: cuándo, dónde y a quién

object
date

Cuándo se entregaron los bienes

string format: date
time

A qué hora, HH:mm:ss en hora de Bogotá

string
/^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/
address

Dónde se entregaron; en el exterior para una exportación

object
line
required

La dirección, ej. “Calle 100 # 10-20”

string
>= 1 characters <= 300 characters
cityCode

El código DIVIPOLA del municipio, 5 dígitos, p. ej. 11001 (Bogotá); obligatorio solo en Colombia

string
/^\d{5}$/
cityName
required

El nombre del municipio (o de la ciudad extranjera)

string
>= 1 characters <= 100 characters
departmentCode

El código DIVIPOLA del departamento, 2 dígitos, p. ej. 11; obligatorio solo en Colombia

string
/^\d{2}$/
departmentName
required

El nombre del departamento (un estado o provincia en el exterior)

string
>= 1 characters <= 100 characters
postalCode

Código postal

string
<= 10 characters
countryCode

País, ISO 3166-1 alfa-2; CO por defecto

string
default: CO >= 2 characters <= 2 characters
countryName

Nombre del país en español; Colombia si el país es CO y no se envía

string
<= 100 characters
party

Quién los recibió o los transportó: el destinatario o el transportador

object
personType
required

1 = persona jurídica, 2 = persona natural

string
Allowed values: 1 2
idType
required

Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP

string
Allowed values: 11 12 13 21 22 31 41 42 47 48 50 91
idNumber
required

Número del documento de identidad, sin dígito de verificación, puntos ni guiones

string
>= 1 characters <= 20 characters
dv

Dígito de verificación del NIT; obligatorio cuando idType es 31

string
/^\d$/
name
required

Razón social, o el nombre completo de una persona natural

string
>= 1 characters <= 450 characters
tradeName

Nombre comercial, si es distinto de la razón social

string
<= 450 characters
firstName

Nombres de una persona natural, por separado (se muestran en la representación gráfica)

string
<= 100 characters
familyName

Apellidos de una persona natural, por separado

string
<= 100 characters
email

Correo donde recibe los documentos electrónicos

string format: email
<= 200 characters
phone

Teléfono de contacto

string
<= 50 characters
address

Dirección; solo se puede omitir para el consumidor final de un documento POS

object
line
required

La dirección, ej. “Calle 100 # 10-20”

string
>= 1 characters <= 300 characters
cityCode

El código DIVIPOLA del municipio, 5 dígitos, p. ej. 11001 (Bogotá); obligatorio solo en Colombia

string
/^\d{5}$/
cityName
required

El nombre del municipio (o de la ciudad extranjera)

string
>= 1 characters <= 100 characters
departmentCode

El código DIVIPOLA del departamento, 2 dígitos, p. ej. 11; obligatorio solo en Colombia

string
/^\d{2}$/
departmentName
required

El nombre del departamento (un estado o provincia en el exterior)

string
>= 1 characters <= 100 characters
postalCode

Código postal

string
<= 10 characters
countryCode

País, ISO 3166-1 alfa-2; CO por defecto

string
default: CO >= 2 characters <= 2 characters
countryName

Nombre del país en español; Colombia si el país es CO y no se envía

string
<= 100 characters
taxResponsibilities

Responsabilidades fiscales del RUT (los códigos de GET /v1/catalogs/tax-responsibilities, del Anexo Técnico 1.9): O-13 gran contribuyente, O-15 autorretenedor, O-23 agente de retención de IVA, O-47 régimen simple, O-48 responsable de IVA, O-49 no responsable de IVA, R-99-PN no responsable (por defecto si no se envía)

Array<string>
<= 20 items
taxScheme

Régimen tributario: 01 IVA, 04 impuesto al consumo (INC), ZA IVA e INC, ZZ no aplica (por defecto)

string
Allowed values: 01 04 ZA ZZ
deliveryTerms

Las condiciones de la entrega (DeliveryTerms): quién asume el costo y el riesgo

object
incoterm
required

El INCOTERM (tabla 13.3.7): CFR, CIF, CIP, CPT, DAP, DAT, DDP, EXW, FAS, FCA, FOB

string
Allowed values: CFR CIF CIP CPT DAP DAT DDP EXW FAS FCA FOB
description

La condición en palabras (LossRisk); si no se envía, el nombre del catálogo, p. ej. ‘Franco a bordo’

string
>= 1 characters <= 100 characters
specialTerms

Condiciones especiales pactadas para la entrega, en palabras, p. ej. ‘Portes pagados’

string
>= 1 characters <= 500 characters
interoperability

Valores con nombre de un sector (la extensión Interoperabilidad de la DIAN): el sector salud informa aquí sus datos, una exportación sus datos adicionales

Array<object>
<= 10 items

Un grupo de la extensión Interoperabilidad: valores con nombre de un sector (los del sector salud, los datos adicionales de una exportación)

object
group
required

El nombre del grupo, como lo definen las reglas del sector (p. ej. ‘Sector Salud’ o ‘Exportación’)

string
>= 1 characters <= 100 characters
collections
required

Sus colecciones

Array<object>
>= 1 items <= 50 items

Una colección de valores con nombre

object
name
required

El nombre de la colección, p. ej. ‘Usuario’

string
>= 1 characters <= 100 characters
fields
required

Sus valores

Array<object>
>= 1 items <= 100 items

Un valor con nombre

object
name
required

El nombre del campo, p. ej. ‘CODIGO_PRESTADOR’

string
>= 1 characters <= 100 characters
value
required

Su valor

string
<= 500 characters
schemeId

El identificador del esquema del valor, cuando el sector lo define

string
>= 1 characters <= 50 characters
schemeName

El nombre del esquema del valor, cuando el sector lo define

string
>= 1 characters <= 100 characters
notes

Notas de texto libre, se imprimen en el documento

Array<string>
<= 50 items
orderReference

Número de la orden de compra del comprador

string
<= 100 characters
payment
required

Cómo se paga el documento

object
form
required

1 = contado (se paga ya), 2 = crédito (se paga después: envíe dueDate)

string
Allowed values: 1 2
method

Medio de pago (tabla 13.3.4.2): 10 efectivo (por defecto), 42 consignación bancaria, 47 transferencia, 48 tarjeta crédito, 49 tarjeta débito, ZZZ otro

string
default: 10 >= 1 characters <= 3 characters
dueDate

Cuándo se debe pagar una venta a crédito

string format: date
paymentId

La referencia propia del pago (PaymentID): un número de transferencia, un acuerdo de pago

string
>= 1 characters <= 100 characters
items
required

Las líneas: de 1 a 1000

Array<object>
>= 1 items <= 1000 items

Una línea del documento: un producto o servicio

object
code
required

Código del producto en su estándar (ver standardCodeScheme)

string
>= 1 characters <= 100 characters
description
required

Lo que se vende

string
>= 1 characters <= 1000 characters
quantity
required

Cuántas unidades

Any of:
number
unitCode

Unidad de medida, recomendación 20 de UN/ECE: 94 unidad (por defecto), KGM kilogramo, HUR hora, MTR metro…

string
default: 94 >= 1 characters <= 10 characters
unitPrice
required

El precio de una unidad, antes del descuento y los impuestos; hasta 6 decimales

Any of:
number
discount

Descuento sobre la línea, como valor (no porcentaje); los impuestos de la línea se aplican después de él

Any of:
number
discountReason

Por qué se da el descuento

string
<= 500 characters
taxes

Impuestos de la línea; vacío (por defecto) para una línea que no lleva

Array<object>
<= 20 items

Un tributo de una línea, como porcentaje de su valor o como valor por unidad

object
code
required

El tributo (tabla 13.2.6.1): 01 IVA, 02 impuesto al consumo (IC), 03 ICA, 04 impuesto nacional al consumo (INC), 20 a 36 los tributos especiales (22 bolsas, 23 carbono, 24 combustibles, 32 licores ICL, 33 plásticos de un solo uso INPP, 34 bebidas azucaradas IBUA, 35 comestibles ultraprocesados ICUI, 36 ad valorem ADV…), ZZ otro tributo (envíe su nombre)

string
Allowed values: 20 21 22 23 24 25 26 30 32 33 34 35 36 01 02 03 04 ZZ
rate

El porcentaje, hasta 3 decimales, p. ej. 19 para el IVA del 19 % o 0.966 para ICA; 0 para una línea exenta. Envíe rate o perUnitAmount, no ambos: 01 IVA, 03 ICA, 04 INC y 35 ICUI siempre van en porcentaje

Any of:
number
perUnitAmount

Para un tributo que se cobra por unidad: el valor por unidad de medida, con máximo 2 decimales — por bolsa en el 22, por cada 100 ml en el IBUA (34), por gramo en el INPP (33), por grado alcoholimétrico en el ICL (32), por galón en los combustibles. El tributo es perUnitAmount × baseUnitMeasure (÷ 100 en el IBUA; × la cantidad en las bolsas). Envíe rate o perUnitAmount, no ambos: 21 timbre, 22 bolsas, 23 carbono, 24 combustibles, 33 INPP y 34 IBUA siempre van por unidad

Any of:
number
baseUnitMeasure

Para un tributo por unidad: a cuántas unidades de medida se aplica (los mililitros, gramos, grados alcoholimétricos o galones vendidos en la línea). Por defecto, la cantidad de la línea; no se acepta en el impuesto a las bolsas (22), que siempre se cobra por bolsa sobre la cantidad

Any of:
number
baseUnitCode

Para un tributo por unidad: la unidad de baseUnitMeasure, recomendación 20 de UN/ECE (MLT mililitro, GRM gramo, GLL galón, LTR litro…). Por defecto, el unitCode de la línea

string
>= 1 characters <= 10 characters
name

El nombre del tributo: obligatorio para ZZ (p. ej. ‘Impuesto especial para la estabilidad fiscal’); no se acepta en los demás códigos

string
>= 1 characters <= 100 characters
standardCodeScheme

Estándar del código: 999 propio del facturador (por defecto), 001 UNSPSC, 010 GTIN, 020 partida arancelaria

string
Allowed values: 999 001 010 020
freeOfCharge

Muestra o regalo: la línea declara su valor comercial (unitPrice) pero se cobra en 0 y no suma a los totales

boolean
note

Una nota en la línea

string
<= 500 characters
sellersItemId

El código propio del emisor para el producto (SellersItemIdentification), cuando es distinto de code

string
>= 1 characters <= 100 characters
additionalIds

Otros códigos con los que se conoce el producto: códigos de barras (EAN13…), códigos de catálogo

Array<object>
<= 10 items

Otro código con el que se conoce el producto

object
id
required

El código

string
>= 1 characters <= 100 characters
schemeName

El nombre del esquema del código, p. ej. EAN13

string
>= 1 characters <= 50 characters
brand

La marca del producto (BrandName); las exportaciones la declaran

string
>= 1 characters <= 100 characters
model

El modelo del producto (ModelName); las exportaciones lo declaran

string
>= 1 characters <= 100 characters
attributes

Propiedades del producto (AdditionalItemProperty): un nombre, un valor y, opcionalmente, una cantidad

Array<object>
<= 20 items

Una propiedad del producto, con una cantidad opcional

object
name
required

El nombre de la propiedad

string
>= 1 characters <= 100 characters
value
required

Su valor, como texto

string
>= 1 characters <= 500 characters
quantity

Una cantidad que la acompaña

Any of:
number
unitCode

La unidad de quantity, recomendación 20 de UN/ECE; obligatoria si se envía quantity

string
>= 1 characters <= 10 characters
principal

El tercero para quien se recibe el ingreso de la línea (el mandante), en una factura de mandato (operationType 11), que lo necesita en al menos una línea (las demás son ingresos propios del emisor), y en sus notas. No se acepta en otros documentos

object
idType
required

Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP

string
Allowed values: 11 12 13 21 22 31 41 42 47 48 50 91
idNumber
required

El número del documento de identidad, sin el dígito de verificación

string
>= 1 characters <= 20 characters
dv

El dígito de verificación del NIT; obligatorio si idType es 31

string
/^\d$/
name

El nombre del tercero

string
>= 1 characters <= 450 characters
transport

La remesa de transporte de la línea, en una factura de transporte de carga (operationType 12): al menos una línea la lleva; las demás son servicios adicionales. La línea de una remesa no admite attributes

object
filingNumber
required

El número de radicación de la remesa en el RNDC (la aceptación que le entrega a la empresa)

string
/^\d{1,12}$/
remittanceNumber
required

El número propio de la remesa en la empresa de transporte, hasta 15 caracteres (admite prefijos)

string
>= 1 characters <= 15 characters
freightValue
required

El valor del flete de la remesa, sin decimales

Any of:
integer
<= 9007199254740991
quantity
required

La cantidad transportada, sin decimales

Any of:
integer
<= 9007199254740991
unitCode
required

Su unidad: KGM kilogramos o GLL galones

string
Allowed values: KGM GLL
deliveryLocation

Dónde se entregan los bienes de la línea

object
id
required

El código del lugar, p. ej. un GLN

string
>= 1 characters <= 100 characters
schemeName

El nombre de su esquema, p. ej. EAN

string
>= 1 characters <= 50 characters
packSize

Cuántas unidades trae un empaque del artículo (PackSizeNumeric), p. ej. 6 para un six-pack

Any of:
integer
<= 9007199254740991
purchaseDate

Cuándo se hizo la compra: solo en un documento soporte de acumulado semanal (generationForm 2), donde cada línea la indica, hasta 6 días antes de la fecha de emisión

string format: date
withholdings

Retenciones que aplica el comprador; se informan, no se restan del total a pagar

Array<object>
<= 20 items
object
code
required

La retención: 05 ReteIVA, 06 ReteFuente (renta), 07 ReteICA

string
Allowed values: 05 06 07
rate
required

El porcentaje retenido, hasta 3 decimales (p. ej. 0.966 para ReteICA)

Any of:
number
taxableAmount

Base sobre la que aplica. Si no se envía: el total de las líneas antes de impuestos para ReteFuente y ReteICA, y el IVA del documento para ReteIVA

Any of:
number
allowanceCharges

Descuentos y cargos sobre todo el documento (no sobre una línea), ej. un flete o un descuento global

Array<object>
<= 50 items
object
isCharge
required

True para un cargo (suma), false para un descuento (resta)

boolean
reason
required

El motivo, en palabras, ej. “Flete”

string
>= 1 characters <= 500 characters
amount
required

El valor

Any of:
number
reasonCode

El código del motivo (tabla 13.3.8): descuentos 00 no condicionado, 01 condicionado; recargos 02 no condicionado, 03 condicionado (las propinas son un recargo 03 con el motivo “Propina”)

string
<= 2 characters
prepayments

Pagos que el comprador hizo antes del documento (PrepaidPayment); se restan del valor a pagar y su suma es el PrepaidAmount. No se aceptan en las notas crédito

Array<object>
<= 50 items

Un pago recibido antes del documento

object
id
required

La referencia propia del pago (un número de recibo o de transferencia); única

string
>= 1 characters <= 150 characters
amount
required

Cuánto se pagó; mayor que cero

Any of:
number
receivedDate
required

Cuándo se recibió el pago

string format: date
paidDate

Cuándo lo hizo el comprador

string format: date
paidTime

A qué hora lo hizo el comprador, HH:mm:ss en hora de Bogotá

string
/^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/
instructions

Instrucciones sobre el pago

string
>= 1 characters <= 500 characters
payableRounding

El redondeo del valor a pagar (PayableRoundingAmount), el único valor que puede ser negativo: los centavos entre el total calculado y el que se cobra. Su valor absoluto debe ser menor que 1

Any of:
number
rangeId

Rango de numeración a usar, por su id; si no se envía, el rango activo más reciente del facturador para ese tipo

string
<= 36 characters
customer
required

El comprador

object
personType
required

1 = persona jurídica, 2 = persona natural

string
Allowed values: 1 2
idType
required

Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP

string
Allowed values: 11 12 13 21 22 31 41 42 47 48 50 91
idNumber
required

Número del documento de identidad, sin dígito de verificación, puntos ni guiones

string
>= 1 characters <= 20 characters
dv

Dígito de verificación del NIT; obligatorio cuando idType es 31

string
/^\d$/
name
required

Razón social, o el nombre completo de una persona natural

string
>= 1 characters <= 450 characters
tradeName

Nombre comercial, si es distinto de la razón social

string
<= 450 characters
firstName

Nombres de una persona natural, por separado (se muestran en la representación gráfica)

string
<= 100 characters
familyName

Apellidos de una persona natural, por separado

string
<= 100 characters
email

Correo donde recibe los documentos electrónicos

string format: email
<= 200 characters
phone

Teléfono de contacto

string
<= 50 characters
address

Dirección; solo se puede omitir para el consumidor final de un documento POS

object
line
required

La dirección, ej. “Calle 100 # 10-20”

string
>= 1 characters <= 300 characters
cityCode

El código DIVIPOLA del municipio, 5 dígitos, p. ej. 11001 (Bogotá); obligatorio solo en Colombia

string
/^\d{5}$/
cityName
required

El nombre del municipio (o de la ciudad extranjera)

string
>= 1 characters <= 100 characters
departmentCode

El código DIVIPOLA del departamento, 2 dígitos, p. ej. 11; obligatorio solo en Colombia

string
/^\d{2}$/
departmentName
required

El nombre del departamento (un estado o provincia en el exterior)

string
>= 1 characters <= 100 characters
postalCode

Código postal

string
<= 10 characters
countryCode

País, ISO 3166-1 alfa-2; CO por defecto

string
default: CO >= 2 characters <= 2 characters
countryName

Nombre del país en español; Colombia si el país es CO y no se envía

string
<= 100 characters
taxResponsibilities

Responsabilidades fiscales del RUT (los códigos de GET /v1/catalogs/tax-responsibilities, del Anexo Técnico 1.9): O-13 gran contribuyente, O-15 autorretenedor, O-23 agente de retención de IVA, O-47 régimen simple, O-48 responsable de IVA, O-49 no responsable de IVA, R-99-PN no responsable (por defecto si no se envía)

Array<string>
<= 20 items
taxScheme

Régimen tributario: 01 IVA, 04 impuesto al consumo (INC), ZA IVA e INC, ZZ no aplica (por defecto)

string
Allowed values: 01 04 ZA ZZ
dueDate

Cuándo se debe pagar la factura (ventas a crédito)

string format: date
contingency

Emitida durante una contingencia del propio facturador (InvoiceTypeCode 03 en vez de 01)

boolean
dueDiligence

La debida diligencia del cliente que aplicó el profesional de cambio (tabla 18.3): 01 general, 02 reforzada, 03 simplificada, 04 intensificada. Obligatoria en los tipos de operación 15 y 16, rechazada en los demás

string
Allowed values: 01 02 03 04
export

Una factura de exportación (InvoiceTypeCode 02): bienes o servicios vendidos al exterior. Cada línea declara su marca y modelo, y la dirección del comprador puede estar en el exterior

boolean

Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)

Media typeapplication/json
object
data
required

Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)

object
id
required

Id del documento

string
kind
required

Tipo de documento

string
Allowed values: invoice credit_note debit_note support_document support_document_adjustment pos_document pos_credit_adjustment pos_debit_adjustment payroll payroll_adjustment radian_event
status
required

Pending → sent → accepted / rejected; retrying y failed cuando la DIAN no responde

string
Allowed values: pending sent retrying accepted rejected failed
environment
required

Ambiente DIAN: 1 = producción, 2 = habilitación (pruebas)

string
Allowed values: 1 2
sandbox
required

True cuando se emitió con una API key de sandbox (DIAN simulada, sin consumir bolsa)

boolean
number
required

Número completo (prefijo + consecutivo)

string
prefix
required

Prefijo del rango de numeración (puede estar vacío)

string
consecutive
required

Consecutivo dentro del rango

integer
>= -9007199254740991 <= 9007199254740991
uniqueCode
required

CUFE, CUDE, CUDS o CUNE

string
uniqueCodeScheme
required

Tipo y algoritmo del código único, ej. CUFE-SHA384

string
issuedAt
required

Cuándo se emitió; la fecha y hora del XML son este instante en hora de Bogotá

string format: date-time
summary
required

Sus valores y su contraparte

object
total
required

Valor del documento: el total a pagar, o el total de la nómina

string
subtotal

Valor antes de impuestos (en nómina, los devengados)

string
taxes

Impuestos (en nómina, las deducciones)

string
currency
required

Moneda, ISO 4217

string
counterpartyId

Número de identificación de la contraparte: el comprador, el vendedor o el empleado

string
counterpartyName

Nombre de la contraparte

string
qrData
required

Contenido del código QR de la representación gráfica

string
dian
required

Lo que respondió la DIAN

object
statusCode
required

Último código de estado de la DIAN: 00 procesado correctamente, 99 rechazado (null: aún sin respuesta)

string | null
statusMessage
required

Último texto de estado de la DIAN (null: aún sin respuesta)

string | null
errors
required

Reglas de validación que la DIAN reportó

Array<string>
zipKey
required

Llave de seguimiento de la DIAN (ZipKey), para documentos enviados al set de pruebas (null en los demás)

string | null
attempts
required

Cuántas veces se envió o se consultó su estado

integer
>= -9007199254740991 <= 9007199254740991
nextAttemptAt
required

Cuándo toca el próximo envío o consulta (null: ninguno pendiente)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
lastError
required

Último error transitorio (la DIAN caída, un timeout); null una vez pasa

string | null
referencedDocumentId
required

Documento al que hace referencia: una nota, a su factura; un ajuste, a su nómina (null: ninguno)

string | null
acceptedAt
required

Cuándo lo aceptó la DIAN (null: no aceptado)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
createdAt
required

Cuándo se creó

string format: date-time
updatedAt
required

Cuándo cambió por última vez

string format: date-time

Example

{
"data": {
"kind": "invoice",
"status": "pending",
"environment": "1",
"issuedAt": "2026-01-15T15:30:00.000Z",
"nextAttemptAt": "2026-01-15T15:30:00.000Z",
"acceptedAt": "2026-01-15T15:30:00.000Z",
"createdAt": "2026-01-15T15:30:00.000Z",
"updatedAt": "2026-01-15T15:30:00.000Z"
}
}

La petición no cumple el esquema (VALIDATION_ERROR, con details por campo)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Falta la credencial o no es válida (UNAUTHORIZED)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Sin saldo de documentos (INSUFFICIENT_BALANCE)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

La llave no puede hacer esto (FORBIDDEN)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

No existe, o no es de esta cuenta (NOT_FOUND)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Conflicto con el estado actual (CONFLICT, INVALID_STATE)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Regla de negocio (VALIDATION_ERROR, NUMBERING_*, CERTIFICATE_UNAVAILABLE…)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Demasiadas peticiones para esta cuenta (RATE_LIMITED; vea X-RateLimit-* y Retry-After)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Error del servicio o de la DIAN (DIAN_UNAVAILABLE, DIAN_PROTOCOL_ERROR)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}