Colombia: documentación del ambiente de pruebas (habilitación DIAN). No hay ambiente de producción.

1Funcionamiento

El objetivo principal de esta API es transformar una cadena con un esquema definido (NUC) en formato JSON a su documento electrónico correspondiente de Colombia: Factura Electrónica de Venta, Nota Crédito o Nota Débito en UBL 2.1, y certificarlo.

📄

NUC: archivo JSON que contiene la información necesaria para generar el XML del documento electrónico. Se detalla el esquema completo en la sección 4.

El funcionamiento de la API va de la mano con el Anexo Técnico de Factura Electrónica de Venta v1.9 de la Dirección de Impuestos y Aduanas Nacionales (DIAN), Resolución 000165 del 01/NOV/2023. Digifact calcula el CUFE/CUDE, firma el documento (XAdES-EPES) y lo transmite a la DIAN de forma asíncrona.

⚠️

Colombia opera solo en ambiente de pruebas (habilitación DIAN), sin efectos legales. No hay ambiente de producción.

2Arquitectura

🖥️
Cliente
NUC en formato JSON →
← XML UBL firmado + CUFE/CUDE
⚙️
API NUC Colombia

Endpoint a consumir

Tabla 1 — Detalle del endpoint a consumir

URLTipoFormatoCuerpo / Body
https://testnucco.digifact.com/api/transform/nuc_jsonPOSTJSONVer sección 4 — Formato del NUC

Query Params

KeyValue
TAXIDNIT del emisor sin dígito de verificación, sin puntos ni guiones. Ej: 902052428. Debe coincidir con el NIT del token y con Seller.TaxID.
ℹ️

Header Authorization con el token vigente, sin el prefijo Bearer.

⚠️

El JSON no se valida contra el esquema antes de transformarse: un campo mal nombrado se ignora sin error.

3Convenciones utilizadas en el formato JSON

3.1 Columnas de las tablas de definición

Tabla 2 — Significado de cada columna en las tablas del NUC

TítuloDescripción
CConjunto de campos
IDIdentificador del campo, para fines de referencia
CampoNombre del campo
DescripciónDescripción del campo y su significado
PReferencia al ID del campo del grupo que contiene este campo específico (padre)
TTipo de dato (ver Tabla 3)
TamTamaño del campo (ver Tabla 4)
OcuOcurrencias en el formato m-n, en el cual m: número mínimo de veces que el campo debe aparecer en el grupo; n: número máximo de veces que el campo puede aparecer en el grupo. Cabe recalcar que si un campo contiene un valor de 1-n, este campo es Obligatorio. Si un campo contiene un valor de 0-n, este campo es Opcional a excepción que pertenezca a una validación condicional dependiendo del valor que tenga otro campo.
ObservacionesObservaciones importantes sobre el elemento, incluyendo listas de posibles valores, validaciones relevantes, entre otras.

3.2 Tipos de dato en el archivo JSON

Tabla 3 — Tipos de dato

TipoDescripción
JSONDocumento JSON, descrito en un esquema contenido en esta ficha técnica
OObjeto JSON, grupo de atributos
AAlfanumérico
NNumérico (montos y cantidades como texto con patrón \d*\.\d{2,6})
FFecha y hora AAAA-MM-DDThh:mm:ss (hora local de Colombia, sin desfase)
LArreglo o lista de objetos
IInformación adicional: lista de objetos { "Name": "", "Data": "", "Value": "" }

3.3 Tamaños de los campos

Tabla 4 — Formato de tamaños

FormatoDescripción
xTamaño exacto del campo. Ejemplo: 5
x-yTamaño mínimo de "x", máximo de "y". Ejemplo: 0-10 (en este caso es posible expresar ningún valor, porque se permite el tamaño "0")
xpnTamaño de "x" enteros, y con "n" casillas decimales. Ejemplo: si el tamaño es 5p3, es válido 54321.103
xpn-mTamaño de "x" enteros, y con un mínimo de "n" casillas decimales y un máximo de "m" casillas decimales. Ejemplo: 11p0-6
x-ypn-mTamaño mínimo de "x" enteros, máximo de "y" enteros; y con un mínimo de "n" casillas decimales y un máximo de "m" casillas decimales. Ejemplo: 1-11p0-6 (es obligatorio expresar algún valor en la parte entera, porque no se permite el tamaño "0", pero la parte decimal es opcional)

4Formato del NUC

4.1 Información que debe contener el NUC

Tabla 5 — Conjuntos de campos del NUC

ConjuntoDescripción
RCampos que contienen información para la generación del documento electrónico
AInformación general del documento (Header)
BInformación del emisor (Seller)
CInformación del adquirente (Buyer)
ETotales y pagos (Totals, Payments)
FInformación adicional y referencia de notas crédito/débito (AdditionalDocumentInfo)
DÍtems del documento (Items)
⚠️

La API es case-sensitive. Los nombres de los campos y datos que hagan referencia a información deben ingresarse respetando mayúsculas y minúsculas exactamente como se especifican.

4.2Elemento raíz del NUCConjunto R

Campos que contienen la información para la generación del documento electrónico. En XML el elemento raíz es <Root>; en JSON es el objeto principal.

CIDCampoDescripciónPTTamOcuObservaciones
RR01RootElemento raíz del NUCO—1..1
En XML el elemento se llama Root. En JSON es el objeto principal del body.
RR02VersionVersión del formato del NUCR01A—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). Los ejemplos usan "1.0".
RR03CountryCodeCódigo del país del documentoR01A2-31..1
Patrón [A-Z]{2,3}. Enviar "CO". El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
RR04ThirdPartiesInformación sobre tercerosR01L—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
RR05ChargesCargos adicionales sobre el documentoR01O—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). Los cargos se informan por ítem (Items/Item/Charges).

4.4Información del emisor (Seller)Conjunto B

Campos que contienen la información del facturador electrónico. Se transforman en cac:AccountingSupplierParty.

CIDCampoDescripciónPTTamOcuObservaciones
BB01SellerInformación del emisorR01O—1..1
BB02TaxIDNIT del emisorB01A—1..1
NIT sin dígito de verificación, sin puntos ni guiones (ej. 902052428). Se transforma en cbc:CompanyID (PartyTaxScheme y PartyLegalEntity) y en NitFac del QR. Debe coincidir con el TAXID de la URL y el emisor debe estar dado de alta en el API con su resolución y rango de numeración DIAN; si no, el API responde "El facturador NIT=... no esta configurado en DIAN:FACTURADORES".
BB03TaxIDTypeTipo de documento de identificación del emisorB01A—1..1
Código DIAN (ej. 31) o alias NUC (ej. NIT). Se transforma en cbc:CompanyID@schemeName. Con 31 el emisor se declara persona jurídica (cbc:AdditionalAccountID 1); con cualquier otro, persona natural (2). Valores fuera del catálogo se rechazan con "TaxIDType NUC no mapeable a DIAN".
Valores permitidos
  • 11 · Registro civil (Alias NUC: RC)
  • 12 · Tarjeta de identidad (Alias NUC: TI)
  • 13 · Cédula de ciudadanía (Alias NUC: CC. Para consumidor final el anexo indica tipo 13 con el número 222222222222 (§6.1, p.48 y p.54).)
  • 21 · Tarjeta de extranjería (Alias NUC: TE)
  • 22 · Cédula de extranjería (Alias NUC: CE)
  • 31 · NIT (Alias NUC: NIT. Es el único tipo con el que el adquirente se trata como responsable (PartyName, TaxLevelCode del emisor/adquirente, dirección fiscal). Cualquier otro tipo se emite como consumidor final.)
  • 41 · Pasaporte (Alias NUC: PA)
  • 42 · Documento de identificación extranjero (Alias NUC: DEX)
  • 50 · NIT de otro país (Alias NUC: NITX)
  • 91 · NUIP (solo para adquirente) (Alias NUC: NUIP)
BB04TaxIDAdditionalInfoInformación tributaria adicional del emisorB01I—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). En particular el dígito de verificación NO se toma de aquí.
BB05NameRazón social del emisorB01A3-1..1
Mínimo 3 caracteres. Se transforma en cac:PartyName/cbc:Name y cbc:RegistrationName.
BB06FiscalCategoryResponsabilidad fiscal del emisorB01A—0..1
Se transforma en cbc:TaxLevelCode (listName 49). Si viene vacío el API envía O-47. El anexo permite varias responsabilidades separadas por ; (ej. O-13;O-15).
Valores permitidos
  • O-47 · Valor por defecto que aplica el API (Se usa para el emisor cuando Seller.FiscalCategory viene vacío, y SIEMPRE para el adquirente con NIT (el NUC no tiene campo de responsabilidad del adquirente). El nombre oficial del código está en la Caja de Herramientas DIAN (ver la Caja de Herramientas de la DIAN).)
  • R-99-PN · Consumidor final (El API lo emite para todo adquirente cuyo TaxIDType no sea 31 (listName "No aplica", TaxScheme ZZ "No aplica"). El anexo indica este valor para consumidor final (p.54).)
BB07ContactContacto del emisorB01O—0..1
Solo se usa el primer correo de EmailList/Email → cac:Contact/cbc:ElectronicMail. Si se envía Contact en XML, el esquema exige PhoneList con al menos un Phone.
BB08AdditionlInfoInformación adicional del emisorB01I—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
BB09AddressInfoDirección del emisorB01O—0..1
Solo se usa si BranchInfo/AddressInfo no viene (en XML BranchInfo/AddressInfo es obligatorio, así que en la práctica manda la dirección del establecimiento).
BB10BranchInfoEstablecimiento del emisorB01O—1..1
BB11CodeCódigo del establecimientoB10A1-1..1
Se devuelve en la respuesta (branchCode). El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
BB12NameNombre del establecimientoB10A3-0..1
Se devuelve en la respuesta (branchName). El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
BB13AddressInfoDirección del establecimientoB10O—1..1
Se transforma en cac:PartyTaxScheme/cac:RegistrationAddress y en cac:PhysicalLocation/cac:Address del emisor. En XML todos sus hijos son obligatorios. Address → cac:AddressLine/cbc:Line; City → cbc:CityName; District → cbc:CountrySubentity; Country → cac:Country/cbc:IdentificationCode (si viene vacío, CO); CityCode → cbc:ID (municipio DIVIPOLA); StateCode → cbc:CountrySubentityCode (departamento). State no se usa. Sin CityCode la DIAN rechaza la factura (FAJ08/FAJ09/FAJ12/FAJ28/FAJ29/FAJ32).
BB14PhoneTeléfono del establecimientoB10A—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
BB15AdditionalBranchInfoInformación adicional del establecimientoB10I—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
BB16CityCodeCódigo DIVIPOLA del municipio (5 dígitos)B13A50..1
Se transforma en cbc:ID de la dirección del emisor (RegistrationAddress y PhysicalLocation). Ejemplo Bogotá D.C.: 11001. Aunque el esquema lo marca opcional, la DIAN rechaza la factura si falta (FAJ28/FAJ29). En XML va DESPUÉS de <Country>; si va antes, falla la validación del esquema. El código debe existir en el catálogo de municipios de la DIAN (si no: FAM19).
BB17StateCodeCódigo del departamento (2 dígitos)B13A20..1
Se transforma en cbc:CountrySubentityCode. Ejemplo Bogotá D.C.: 11. Opcional: si no viene y el país es CO, se toman los 2 primeros dígitos de CityCode. En XML va después de <CityCode>.

4.5Información del adquirente (Buyer)Conjunto C

Campos que contienen la información del adquirente. Se transforman en cac:AccountingCustomerParty.

CIDCampoDescripciónPTTamOcuObservaciones
CC01BuyerInformación del adquirenteR01O—1..1
CC02TaxIDNúmero de identificación del adquirenteC01A—1..1
Se transforma en cbc:CompanyID y en DocAdq del QR; para consumidor final también en cac:PartyIdentification/cbc:ID. Para consumidor final el anexo indica el número 222222222222 con tipo 13.
CC03TaxIDTypeTipo de documento de identificación del adquirenteC01A—0..1
Aunque el esquema lo marca opcional, el API lo exige (sin él responde "TaxIDType NUC no mapeable a DIAN"). Con 31 (NIT) el adquirente se emite como responsable: cac:PartyName, cbc:AdditionalAccountID 1, TaxLevelCode O-47, TaxScheme 01 IVA y dirección fiscal si viene AddressInfo. Con CUALQUIER otro tipo se emite como consumidor final: cac:PartyIdentification, AdditionalAccountID 2, TaxLevelCode R-99-PN y TaxScheme ZZ "No aplica".
Valores permitidos
  • 11 · Registro civil (Alias NUC: RC)
  • 12 · Tarjeta de identidad (Alias NUC: TI)
  • 13 · Cédula de ciudadanía (Alias NUC: CC. Para consumidor final el anexo indica tipo 13 con el número 222222222222 (§6.1, p.48 y p.54).)
  • 21 · Tarjeta de extranjería (Alias NUC: TE)
  • 22 · Cédula de extranjería (Alias NUC: CE)
  • 31 · NIT (Alias NUC: NIT. Es el único tipo con el que el adquirente se trata como responsable (PartyName, TaxLevelCode del emisor/adquirente, dirección fiscal). Cualquier otro tipo se emite como consumidor final.)
  • 41 · Pasaporte (Alias NUC: PA)
  • 42 · Documento de identificación extranjero (Alias NUC: DEX)
  • 50 · NIT de otro país (Alias NUC: NITX)
  • 91 · NUIP (solo para adquirente) (Alias NUC: NUIP)
CC04TaxIDAdditionalInfoInformación tributaria adicional del adquirenteC01I—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
CC05NameNombre o razón social del adquirenteC01A—0..1
Se transforma en cbc:RegistrationName (y cac:PartyName/cbc:Name si es NIT). Se devuelve en la respuesta (receiverName).
CC06ContactContacto del adquirenteC01O—0..1
Solo se usa el primer correo de EmailList/Email → cac:Contact/cbc:ElectronicMail. Los correos en AdditionlInfo NO se usan.
CC07AdditionlInfoInformación adicional del adquirenteC01I—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
CC08AddressInfoDirección del adquirenteC01O—0..1
Solo se emite (cac:RegistrationAddress) cuando el adquirente es NIT (TaxIDType 31). Mismo mapeo que la dirección del emisor, incluidos CityCode y StateCode (DIVIPOLA).
CC09CityCodeCódigo DIVIPOLA del municipio (5 dígitos)C08A50..1
Solo aplica si el adquirente es NIT (se emite su RegistrationAddress). Mismo formato y reglas que el CityCode del emisor.
CC10StateCodeCódigo del departamento (2 dígitos)C08A20..1
Mismo formato y derivación que el StateCode del emisor.

4.6Ítems del documento (Items)Conjunto D

Campos que describen cada ítem. Cada ítem se transforma en una cac:InvoiceLine (factura), cac:CreditNoteLine (nota crédito) o cac:DebitNoteLine (nota débito).

CIDCampoDescripciónPTTamOcuObservaciones
DD01ItemsListado de ítemsR01L—1..1
En JSON es un arreglo de ítems; en XML contiene elementos <Item>. La cantidad de ítems se emite como cbc:LineCountNumeric.
DD02ItemÍtemD01O—0..n
DD03NumberNúmero de líneaD02A—0..1
Atributo en XML (<Item Number="1">). Se transforma en cbc:ID de la línea; si no viene se usa la posición (1, 2, …).
DD04CodesCódigos del ítemD02L—0..1
Hasta 5 <Code Name="" Data="" Value=""/>. Solo se usa el PRIMERO: Value → cac:StandardItemIdentification/cbc:ID, Data → @schemeID, Name → @schemeName.
DD05TypeTipo o clasificación del ítemD02A—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
DD06DescriptionDescripción del ítemD02A2-10001..1
Se transforma en cac:Item/cbc:Description.
DD07QtyCantidadD02N—1..1
Patrón \d*\.\d{2,6} (ej. 1.00). Se transforma en cbc:InvoicedQuantity / CreditedQuantity / DebitedQuantity y en cac:Price/cbc:BaseQuantity.
DD08UnitOfMeasureUnidad de medidaD02A1-200..1
Se transforma en el atributo unitCode de la cantidad. Si viene vacío el API usa 94.
DD09PricePrecio unitarioD02N—1..1
Patrón \d*\.\d{2,6}. Se transforma en cac:Price/cbc:PriceAmount.
DD10DiscountsDescuentos del ítemD02L—0..1
Hasta 5 <Discount>. Cada uno se transforma en cac:AllowanceCharge con cbc:ChargeIndicator false: Description → cbc:AllowanceChargeReason, Rate → cbc:MultiplierFactorNumeric, Amount → cbc:Amount, TaxableAmount (o ChargableAmount) → cbc:BaseAmount.
DD11TaxesImpuestos del ítemD02L—1..1
Hasta 15 <Tax>; en XML cada Tax exige Description y Amount. Se transforma en cac:TaxTotal de la línea: cbc:TaxAmount = suma de Amount; un cac:TaxSubtotal por impuesto con TaxableAmount, Amount, Rate → cbc:Percent y Code → cac:TaxScheme (ID y Name). Code fuera del catálogo se rechaza con "TaxScheme NUC no mapeable a DIAN".
Valores permitidos
  • 01 · IVA (Alias NUC: IVA)
  • 02 · IC (Alias NUC: IC)
  • 03 · ICA (Alias NUC: ICA)
  • 04 · INC (Alias NUC: INC)
  • 05 · ReteIVA (Alias NUC: ReteIVA)
  • 06 · ReteFuente (Alias NUC: ReteFuente)
  • 07 · ReteICA (Alias NUC: ReteICA)
  • 20 · FtoHorticultura (Alias NUC: FtoHorticultura)
DD12ChargesCargos del ítemD02L—0..1
Hasta 10 <Charge>. Mismo mapeo que los descuentos pero con cbc:ChargeIndicator true.
DD13TotalsTotales del ítemD02O—1..1
DD14TotalBTaxesTotal del ítem antes de impuestosD13N—0..1
Se transforma en cbc:LineExtensionAmount de la línea. Si no viene se calcula Qty × Price.
DD15TotalItemTotal del ítemD13N—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). (No se usa como LineExtensionAmount porque incluye impuestos.)
DD16TotalBDiscount / TotalWDiscount / TotalWTaxes / SpecificTotalOtros totales del ítemD13N—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
DD17AdditionalInfoInformación adicional del ítemD02I—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).

4.7Totales (Totals)Conjunto E

Campos que describen los totales del documento (cac:TaxTotal, cac:LegalMonetaryTotal / cac:RequestedMonetaryTotal).

CIDCampoDescripciónPTTamOcuObservaciones
EE01TotalsTotales del documentoR01O—1..1
EE02QtyItemsCantidad de ítemsE01N—0..1
Número ENTERO, sin decimales (xs:integer en NUCSchema.xsd, integer en NUCSchema.json): es la excepción al patrón N de montos. El builder UBL de Colombia no usa este campo; la cantidad de líneas se calcula a partir de Items.
EE03TotalItemsTotal de los ítems antes de impuestosE01N—0..1
Se transforma en cbc:LineExtensionAmount del total y en ValFac del QR. Se devuelve en la respuesta (subTotal).
EE04TotalTaxableAmountBase gravable totalE01N—0..1
Se transforma en cbc:TaxExclusiveAmount. Si no viene se usa TotalItems.
EE05TotalTaxesImpuestos totales del documentoE01L—0..1
Hasta 10 <TotalTax>. Se transforma en el cac:TaxTotal del documento: cbc:TaxAmount = suma de Amount y un cac:TaxSubtotal por impuesto (mismo mapeo que los impuestos del ítem). Si no viene, el documento no lleva TaxTotal de cabecera.
Valores permitidos
  • 01 · IVA (Alias NUC: IVA)
  • 02 · IC (Alias NUC: IC)
  • 03 · ICA (Alias NUC: ICA)
  • 04 · INC (Alias NUC: INC)
  • 05 · ReteIVA (Alias NUC: ReteIVA)
  • 06 · ReteFuente (Alias NUC: ReteFuente)
  • 07 · ReteICA (Alias NUC: ReteICA)
  • 20 · FtoHorticultura (Alias NUC: FtoHorticultura)
EE06TotalCharges / TotalDiscountsCargos y descuentos totalesE01L—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). No se emiten cargos ni descuentos a nivel de documento.
EE07GrandTotalGran totalE01O—1..1
EE08TotalWTaxesTotal con impuestosE07N—0..1
Se transforma en cbc:TaxInclusiveAmount. Si no viene se usa InvoiceTotal.
EE09InvoiceTotalTotal a pagarE07N—1..1
Se transforma en cbc:PayableAmount y en ValTolFac del QR. Se devuelve en la respuesta (totalAmount).
EE10TotalBTaxes / TotalBDiscounts / TotalWDiscounts / ExplicitTotalOtros totalesE07N—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
EE11InWords / AdditionalInfoTotal en letras e información adicionalE01A—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).

4.8Pagos (Payments)Conjunto E

Campos que describen los medios de pago del documento (cac:PaymentMeans). Payments es nodo padre propio, hijo directo de Root, igual que Totals.

CIDCampoDescripciónPTTamOcuObservaciones
EE12PaymentsPagosR01L—1..1
En XML contiene al menos un <Payment>. Cada pago se transforma en un cac:PaymentMeans cuyo cbc:ID es la POSICIÓN del pago (1, 2, …). Limitación conocida: en el Anexo DIAN ese ID es la forma de pago (1 contado, 2 crédito), así que hoy no se puede emitir una venta a crédito con un solo pago, y con dos pagos el segundo sale como crédito. Usar un solo pago de contado.
EE13TypeTipo de pagoE12A—1..1
Texto libre obligatorio (xs:string). Solo se usa como código de medio de pago si Code viene vacío, y en ese caso se envía TAL CUAL a la DIAN como cbc:PaymentMeansCode (salvo los alias EFECTIVO/CASH, CHEQUE, DEBITO, TRANSFERENCIA/WIRE, TARJETA_CREDITO/CC, TARJETA_DEBITO/DC). Por eso, si Type trae un texto como "Contado", Code es obligatorio en la práctica.
Valores permitidos
  • 1 · Instrumento no definido (Lo aplica el API cuando Payment.Code y Payment.Type vienen vacíos.)
  • 10 · Código que el API emite para los alias EFECTIVO / CASH (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 20 · Código que el API emite para el alias CHEQUE (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 31 · Código que el API emite para el alias DEBITO (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 42 · Código que el API emite para los alias TRANSFERENCIA / WIRE (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 47 · Código que el API emite para los alias TARJETA_CREDITO / CC (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 48 · Código que el API emite para los alias TARJETA_DEBITO / DC (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
EE14CodeCódigo del medio de pagoE12A—0..1
Se transforma en cbc:PaymentMeansCode. Acepta el código DIAN (se envía tal cual) o los alias EFECTIVO/CASH, CHEQUE, DEBITO, TRANSFERENCIA/WIRE, TARJETA_CREDITO/CC, TARJETA_DEBITO/DC. Sin Code ni Type se envía 1. Ojo: un alias no reconocido también se envía tal cual.
Valores permitidos
  • 1 · Instrumento no definido (Lo aplica el API cuando Payment.Code y Payment.Type vienen vacíos.)
  • 10 · Código que el API emite para los alias EFECTIVO / CASH (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 20 · Código que el API emite para el alias CHEQUE (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 31 · Código que el API emite para el alias DEBITO (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 42 · Código que el API emite para los alias TRANSFERENCIA / WIRE (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 47 · Código que el API emite para los alias TARJETA_CREDITO / CC (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
  • 48 · Código que el API emite para los alias TARJETA_DEBITO / DC (La etiqueta oficial DIAN está en la Caja de Herramientas (ver la Caja de Herramientas de la DIAN).)
EE15DateFecha de pagoE12F—0..1
Se transforma en cbc:PaymentDueDate (se toman los primeros 10 caracteres: AAAA-MM-DD).
EE16AmountMonto pagadoE12N—1..1
Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
EE17Description / AditionalDataDescripción e información adicional del pagoE12A—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).

4.9Información adicional y referencia de notas (AdditionalDocumentInfo)Conjunto F

Información adicional del documento. Para Nota Crédito y Nota Débito aquí viaja la factura referenciada, como pares Name/Value dentro de AdditionalInfo/AditionalData/Data/Info.

CIDCampoDescripciónPTTamOcuObservaciones
FF01AdditionalDocumentInfoInformación adicional del documentoR01O—1..1
Obligatorio por el esquema XML (al menos un AdditionalInfo).
FF02DocTemplatePlantilla del documentoF01A—0..1
El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN).
FF03AdditionalInfoBloque de información adicionalF01L—1..2
Code, Type, Description, AddressInfo, Texts y AditionalInfo no los usa el builder de Colombia; solo se lee AditionalData (referencia de notas).
FF04AditionalDataDatos adicionalesF03O—0..1
Contiene uno o más <Data>. Para NC/ND el API toma el PRIMER Data que traiga la clave IDFacturaRef o UUIDRef.
FF05DataGrupo de datos de referenciaF04L—1..1000
Atributos opcionales Name e Id; contiene elementos <Info Name="" Value=""/>. Las claves se comparan sin distinguir mayúsculas.
Valores permitidos
  • IDFacturaRef · Número de la factura referenciada → cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID (Obligatorio para NC/ND.)
  • UUIDRef · CUFE de la factura referenciada → .../cbc:UUID (schemeName CUFE-SHA384) (Obligatorio para NC/ND. Es el CUFE real de la factura, no un placeholder.)
  • FechaRef · Fecha de emisión de la factura referenciada → .../cbc:IssueDate (Obligatorio para NC/ND. Formato AAAA-MM-DD.)
  • ResponseCode · Concepto de corrección → cac:DiscrepancyResponse/cbc:ResponseCode (Obligatorio para NC/ND. Valores: tablas 13.2.4 (NC) y 13.2.5 (ND) de la Caja de Herramientas DIAN. El API no valida el valor.)
  • Description · Descripción de la corrección → cac:DiscrepancyResponse/cbc:Description (Obligatorio para NC/ND.)
  • ReferenceID · Sección de la factura original a la que aplica la corrección → cac:DiscrepancyResponse/cbc:ReferenceID (Solo Nota Débito. Opcional: si no viene, el API envía "1".)
FF06Info Name="IDFacturaRef"Número de la factura referenciadaF05A—1..1 (NC/ND)
Se transforma en cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID. Sin esta clave (y sin UUIDRef) la nota se rechaza: "... requiere la factura referenciada en NUC.AdditionalDocumentInfo/...".
FF07Info Name="UUIDRef"CUFE de la factura referenciadaF05A—1..1 (NC/ND)
Se transforma en .../cac:InvoiceDocumentReference/cbc:UUID con schemeName CUFE-SHA384.
FF08Info Name="FechaRef"Fecha de emisión de la factura referenciadaF05F101..1 (NC/ND)
Formato AAAA-MM-DD. Se transforma en .../cac:InvoiceDocumentReference/cbc:IssueDate.
FF09Info Name="ResponseCode"Concepto de correcciónF05A—1..1 (NC/ND)
Se transforma en cac:DiscrepancyResponse/cbc:ResponseCode. Los valores válidos están en las tablas 13.2.4 (NC) y 13.2.5 (ND) de la Caja de Herramientas DIAN; el API no los valida.
FF10Info Name="Description"Descripción de la correcciónF05A—1..1 (NC/ND)
Se transforma en cac:DiscrepancyResponse/cbc:Description.
FF11Info Name="ReferenceID"Sección de la factura original corregidaF05N1-40..1 (solo ND)
Solo Nota Débito. Se transforma en cac:DiscrepancyResponse/cbc:ReferenceID; si no viene el API envía 1.

5Respuesta de la API

Al enviar el contenido del NUC, se obtiene como respuesta un objeto JSON que tiene la siguiente estructura.

Donde:

AtributoDescripción
codecontiene el código de la respuesta obtenida
messagecontiene un mensaje informativo relacionado a la respuesta
descriptiondescripción adicional del mensaje
responseData1XML UBL 2.1 firmado (XAdES-EPES) en base64, con el CUFE/CUDE ya calculado.
responseData2Vacío: la certificación no devuelve HTML. Para obtenerlo usar GET DOCUMENT.
responseData3Vacío: la certificación no devuelve PDF. Para obtenerlo usar GET DOCUMENT.
authNumberCUFE (factura) o CUDE (nota crédito/débito) del documento, algoritmo SHA-384 (96 caracteres hexadecimales).
urlVacío.
infoDetailsArreglo de eventos {evento, dCodRes, dMsgRes}. En un rechazo 3010 por validación previa trae una posición por regla incumplida: evento SCHEMATRON_DIAN (regla DIAN, p.ej. dCodRes FAM19) o XSD_UBL21 (esquema UBL). Vacío si code = 1.
suggestedFileNamenombre sugerido para nombrar y guardar el contenido de la información que contiene el responseData1, responseData2, responseData3 o algún otro documento relacionado con la información de la factura emitida.
suggestedFileName2otro nombre sugerido
batchPrefijo de numeración del documento (sts:Prefix).
serialConsecutivo del documento (dígitos finales de cbc:ID).
issuedTimeStampfecha de emisión de la factura electrónica
taxIDIdentificador del contribuyente emisor del documento
namenombre o razón social del emisor
branchCodeCopia de Seller.BranchInfo.Code del NUC.
branchNameCopia de Seller.BranchInfo.Name del NUC.
receiverTaxIDCopia de Buyer.TaxID del NUC.
receiverNamenombre o razón social del receptor
discountsVacío.
taxesVacío.
subTotalCopia de Totals.TotalItems del NUC.
totalAmountCopia de Totals.GrandTotal.InvoiceTotal del NUC.
enrolledTimeStampFecha y hora de certificación devuelta por el backend, en UTC (ISO 8601 con +00:00). issuedTimeStamp, en cambio, es la hora local de Colombia enviada en el NUC.
backprocessorservidor que realiza la consulta
additionalInfoNormalmente null. Si el backend devuelve una sugerencia llega como { "hint": "..." }.

5.1 Códigos dentro de la Respuesta

Tabla 8 — Códigos de respuesta de la API

CódigoDescripción
-1Sin respuesta del backend de certificación.
0Error en el contenido del XML NUC. Este tipo de error se mostrará si en el proceso de transformar xml surge un error, puede ser causado por la ausencia de un valor importante, un tipo de dato incorrecto, etc. Se indicará en los atributos "message" y "description" el detalle y la descripción del error informado, indicando donde se encuentra el error y la referencia hacia esta documentación.
1Documento certificado: validado por Digifact, firmado y almacenado. La transmisión a la DIAN es posterior y asíncrona.
400Error en realizar la consulta. Se mostrará en el atributo "message" la descripción del error.
500Error inesperado. Se mostrará el contenido del error en los atributos "message" y "description".
3010XML_INVALID — falló una validación del documento (fecha, numeración, datos obligatorios, referencia de nota, cuenta o paquete del emisor, etc.). Solo se informa el primer error.
3000Error no controlado del backend.
3052DOCUMENT_ALREADY_EXISTS — el documento con ese NIT, prefijo y consecutivo ya existe.
3079GET DOCUMENT: el objeto solicitado no se encuentra en la base de datos.

5.2 Códigos de Estado HTTP

Tabla 9 — Códigos de estado HTTP

CódigoDescripción
200Petición procesada. En certificación revisar el campo code: un error de negocio también llega con 200.
400Parámetro faltante, XML que no cumple el esquema o error al armar el documento (motivo en texto plano).
401Token ausente, inválido, vencido o de otro NIT; o credenciales incorrectas en get_token.
500Internal Server Error