Documentación Técnica NUC-XML Colombia
Especificación oficial V1.0 · esquema DIAN Anexo Técnico v1.9 · en vigencia desde el 04/09/2026 del formato NUC en XML. Misma estructura que la versión JSON — cambia solo la serialización.
1Funcionamiento
El objetivo principal de esta API es transformar una cadena con un esquema definido (NUC) en formato XML 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 XML 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
Endpoint a consumir
Tabla 1 — Detalle del endpoint a consumir
| URL | Tipo | Formato | Cuerpo / Body |
|---|---|---|---|
https://testnucco.digifact.com/api/transform/nuc | POST | XML | Ver sección 4 — Formato del NUC |
Query Params
| Key | Value |
|---|---|
TAXID | NIT 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 header Content-Type debe ser application/xml. El NUC se valida contra el esquema XSD antes de transformarse.
3Convenciones utilizadas en el formato XML
3.1 Columnas de las tablas de definición
Tabla 2 — Significado de cada columna en las tablas del NUC
| Título | Descripción |
|---|---|
C | Conjunto de campos |
ID | Identificador del campo, para fines de referencia |
Campo | Nombre del campo |
Descripción | Descripción del campo y su significado |
P | Referencia al ID del campo del grupo que contiene este campo específico (padre) |
T | Tipo de dato (ver Tabla 3) |
Tam | Tamaño del campo (ver Tabla 4) |
Ocu | Ocurrencias 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. |
Observaciones | Observaciones importantes sobre el elemento, incluyendo listas de posibles valores, validaciones relevantes, entre otras. |
3.2 Tipos de dato en el archivo XML
Tabla 3 — Tipos de dato
| Tipo | Descripción |
|---|---|
| xml | Documento XML, descrito en un esquema contenido en esta ficha técnica |
| G | Grupo de elementos |
| A | Alfanumérico |
| N | Numérico (patrón \d*\.\d{2,6} para montos y cantidades) |
| F | Fecha y hora xs:dateTime AAAA-MM-DDThh:mm:ss (hora local de Colombia, sin desfase) |
| I | Información adicional: elementos <Info Name="" Data="" Value=""/> |
3.3 Tamaños de los campos
Tabla 4 — Formato de tamaños
| Formato | Descripción |
|---|---|
x | Tamaño exacto del campo. Ejemplo: 5 |
x-y | Tamañ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") |
xpn | Tamaño de "x" enteros, y con "n" casillas decimales. Ejemplo: si el tamaño es 5p3, es válido 54321.103 |
xpn-m | Tamañ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-m | Tamañ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
| Conjunto | Descripción |
|---|---|
R | Campos que contienen información para la generación del documento electrónico |
A | Información general del documento (Header) |
B | Información del emisor (Seller) |
C | Información del adquirente (Buyer) |
E | Totales y pagos (Totals, Payments) |
F | Información adicional y referencia de notas crédito/débito (AdditionalDocumentInfo) |
D | Ítems del documento (Items) |
El XML es case-sensitive. Los nombres de los elementos y atributos deben ingresarse respetando mayúsculas y minúsculas exactamente como se especifican. Recordar que en XML los grupos se representan como elementos contenedores y los arreglos como elementos repetidos del mismo nombre.
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.
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
R | R01 | Root | Elemento raíz del NUC | | G | — | 1..1 | En XML el elemento se llama Root. En JSON es el objeto principal del body. |
R | R02 | Version | Versión del formato del NUC | R01 | A | — | 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". |
R | R03 | CountryCode | Código del país del documento | R01 | A | 2-3 | 1..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). |
R | R04 | ThirdParties | Información sobre terceros | R01 | G | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
R | R05 | Charges | Cargos adicionales sobre el documento | R01 | G | — | 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.3Información general del documento (Header)Conjunto A
Campos que contienen información general del documento electrónico. Se transforman en la cabecera UBL 2.1 (cbc:CustomizationID, cbc:ProfileID, cbc:ProfileExecutionID, cbc:ID, cbc:UUID, cbc:IssueDate, cbc:IssueTime, type code, cbc:DocumentCurrencyCode, cbc:LineCountNumeric).
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
A | A01 | Header | Información general del documento | R01 | G | — | 1..1 | |
A | A02 | DocType | Tipo de documento a generar | A01 | A | 2 | 1..1 | Valores: FE o 01 (Factura de Venta), FX o 02 (Exportación), 03 y 04 (contingencia), NC o 91 (Nota Crédito), ND o 92 (Nota Débito). Determina la raíz UBL (Invoice/CreditNote/DebitNote), el ProfileID, el CustomizationID y el esquema del UUID (CUFE/CUDE). Cualquier otro valor se rechaza con "DocType NUC no mapeable a DIAN". 02, 03 y 04: no soportados aún de punta a punta (ver catálogo). Valores permitidos
|
A | A03 | GUID | Identificador del documento | A01 | A | — | 0..1 | Solo se usa como número del documento (cbc:ID) si Header.Reference.Code no viene. |
A | A04 | IssuedDateTime | Fecha y hora de emisión | A01 | F | — | 1..1 | Formato AAAA-MM-DDThh:mm:ss. Se transforma en cbc:IssueDate (AAAA-MM-DD) y cbc:IssueTime (hh:mm:ss + "-05:00"). Enviar la hora local de Colombia SIN desfase horario: si se incluye un desfase (ej. -05:00) la hora se convierte a la zona del servidor y el documento sale con otra hora (y posiblemente otra fecha). La DIAN no tolera diferencia entre la fecha de emisión y la fecha de firma: usar la fecha del día. |
A | A05 | AdditionalIssueType | Ambiente de destino del documento | A01 | N | 1 | 1..1 | 1: Producción; 2: Pruebas. Se transforma en cbc:ProfileExecutionID y cbc:UUID@schemeID. Si viene vacío el API usa 2. Colombia solo opera en habilitación (pruebas): enviar 2. Valores permitidos
|
A | A06 | ExchangeRate | Tipo de cambio | A01 | N | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
A | A07 | Currency | Moneda del documento (ISO 4217) | A01 | A | 3 | 0..1 | Patrón [A-Z]{3}. Se transforma en cbc:DocumentCurrencyCode y en el atributo currencyID de todos los montos. Si viene vacío el API usa COP. |
A | A08 | Reference | Referencia del documento | A01 | G | — | 0..1 | |
A | A09 | Code | Número del documento (prefijo + consecutivo) | A08 | A | — | 0..1 | Se transforma en cbc:ID y en NumFac del QR. Aunque el esquema lo marca opcional, en la práctica es obligatorio: si no viene se usa Header.GUID. Para facturas debe pertenecer al prefijo y rango de numeración autorizados al emisor (los mismos configurados en el API para su NIT). Repetir un número ya certificado se rechaza por duplicado. |
A | A10 | Date | Fecha de la referencia | A08 | F | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
A | A11 | AdditionalIssueDocInfo | Información adicional general del documento | A01 | I | — | 1..1 | Obligatorio por el esquema XML (al menos un <Info>). El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
4.4Información del emisor (Seller)Conjunto B
Campos que contienen la información del facturador electrónico. Se transforman en cac:AccountingSupplierParty.
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
B | B01 | Seller | Información del emisor | R01 | G | — | 1..1 | |
B | B02 | TaxID | NIT del emisor | B01 | A | — | 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". |
B | B03 | TaxIDType | Tipo de documento de identificación del emisor | B01 | A | — | 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
|
B | B04 | TaxIDAdditionalInfo | Información tributaria adicional del emisor | B01 | I | — | 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í. |
B | B05 | Name | Razón social del emisor | B01 | A | 3- | 1..1 | Mínimo 3 caracteres. Se transforma en cac:PartyName/cbc:Name y cbc:RegistrationName. |
B | B06 | FiscalCategory | Responsabilidad fiscal del emisor | B01 | A | — | 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
|
B | B07 | Contact | Contacto del emisor | B01 | G | — | 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. |
B | B08 | AdditionlInfo | Información adicional del emisor | B01 | I | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
B | B09 | AddressInfo | Dirección del emisor | B01 | G | — | 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). |
B | B10 | BranchInfo | Establecimiento del emisor | B01 | G | — | 1..1 | |
B | B11 | Code | Código del establecimiento | B10 | A | 1- | 1..1 | Se devuelve en la respuesta (branchCode). El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
B | B12 | Name | Nombre del establecimiento | B10 | A | 3- | 0..1 | Se devuelve en la respuesta (branchName). El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
B | B13 | AddressInfo | Dirección del establecimiento | B10 | G | — | 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). |
B | B14 | Phone | Teléfono del establecimiento | B10 | A | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
B | B15 | AdditionalBranchInfo | Información adicional del establecimiento | B10 | I | — | 1..1 | Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
B | B16 | CityCode | Código DIVIPOLA del municipio (5 dígitos) | B13 | A | 5 | 0..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). |
B | B17 | StateCode | Código del departamento (2 dígitos) | B13 | A | 2 | 0..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.
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
C | C01 | Buyer | Información del adquirente | R01 | G | — | 1..1 | |
C | C02 | TaxID | Número de identificación del adquirente | C01 | A | — | 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. |
C | C03 | TaxIDType | Tipo de documento de identificación del adquirente | C01 | A | — | 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
|
C | C04 | TaxIDAdditionalInfo | Información tributaria adicional del adquirente | C01 | I | — | 1..1 | Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
C | C05 | Name | Nombre o razón social del adquirente | C01 | A | — | 0..1 | Se transforma en cbc:RegistrationName (y cac:PartyName/cbc:Name si es NIT). Se devuelve en la respuesta (receiverName). |
C | C06 | Contact | Contacto del adquirente | C01 | G | — | 0..1 | Solo se usa el primer correo de EmailList/Email → cac:Contact/cbc:ElectronicMail. Los correos en AdditionlInfo NO se usan. |
C | C07 | AdditionlInfo | Información adicional del adquirente | C01 | I | — | 1..1 | Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
C | C08 | AddressInfo | Dirección del adquirente | C01 | G | — | 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). |
C | C09 | CityCode | Código DIVIPOLA del municipio (5 dígitos) | C08 | A | 5 | 0..1 | Solo aplica si el adquirente es NIT (se emite su RegistrationAddress). Mismo formato y reglas que el CityCode del emisor. |
C | C10 | StateCode | Código del departamento (2 dígitos) | C08 | A | 2 | 0..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).
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
D | D01 | Items | Listado de ítems | R01 | G | — | 1..1 | En JSON es un arreglo de ítems; en XML contiene elementos <Item>. La cantidad de ítems se emite como cbc:LineCountNumeric. |
D | D02 | Item | Ítem | D01 | G | — | 0..n | |
D | D03 | Number | Número de línea | D02 | A | — | 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, …). |
D | D04 | Codes | Códigos del ítem | D02 | G | — | 0..1 | Hasta 5 <Code Name="" Data="" Value=""/>. Solo se usa el PRIMERO: Value → cac:StandardItemIdentification/cbc:ID, Data → @schemeID, Name → @schemeName. |
D | D05 | Type | Tipo o clasificación del ítem | D02 | A | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
D | D06 | Description | Descripción del ítem | D02 | A | 2-1000 | 1..1 | Se transforma en cac:Item/cbc:Description. |
D | D07 | Qty | Cantidad | D02 | N | — | 1..1 | Patrón \d*\.\d{2,6} (ej. 1.00). Se transforma en cbc:InvoicedQuantity / CreditedQuantity / DebitedQuantity y en cac:Price/cbc:BaseQuantity. |
D | D08 | UnitOfMeasure | Unidad de medida | D02 | A | 1-20 | 0..1 | Se transforma en el atributo unitCode de la cantidad. Si viene vacío el API usa 94. |
D | D09 | Price | Precio unitario | D02 | N | — | 1..1 | Patrón \d*\.\d{2,6}. Se transforma en cac:Price/cbc:PriceAmount. |
D | D10 | Discounts | Descuentos del ítem | D02 | G | — | 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. |
D | D11 | Taxes | Impuestos del ítem | D02 | G | — | 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
|
D | D12 | Charges | Cargos del ítem | D02 | G | — | 0..1 | Hasta 10 <Charge>. Mismo mapeo que los descuentos pero con cbc:ChargeIndicator true. |
D | D13 | Totals | Totales del ítem | D02 | G | — | 1..1 | |
D | D14 | TotalBTaxes | Total del ítem antes de impuestos | D13 | N | — | 0..1 | Se transforma en cbc:LineExtensionAmount de la línea. Si no viene se calcula Qty × Price. |
D | D15 | TotalItem | Total del ítem | D13 | N | — | 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.) |
D | D16 | TotalBDiscount / TotalWDiscount / TotalWTaxes / SpecificTotal | Otros totales del ítem | D13 | N | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
D | D17 | AdditionalInfo | Información adicional del ítem | D02 | I | — | 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).
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
E | E01 | Totals | Totales del documento | R01 | G | — | 1..1 | |
E | E02 | QtyItems | Cantidad de ítems | E01 | N | — | 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. |
E | E03 | TotalItems | Total de los ítems antes de impuestos | E01 | N | — | 0..1 | Se transforma en cbc:LineExtensionAmount del total y en ValFac del QR. Se devuelve en la respuesta (subTotal). |
E | E04 | TotalTaxableAmount | Base gravable total | E01 | N | — | 0..1 | Se transforma en cbc:TaxExclusiveAmount. Si no viene se usa TotalItems. |
E | E05 | TotalTaxes | Impuestos totales del documento | E01 | G | — | 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
|
E | E06 | TotalCharges / TotalDiscounts | Cargos y descuentos totales | E01 | G | — | 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. |
E | E07 | GrandTotal | Gran total | E01 | G | — | 1..1 | |
E | E08 | TotalWTaxes | Total con impuestos | E07 | N | — | 0..1 | Se transforma en cbc:TaxInclusiveAmount. Si no viene se usa InvoiceTotal. |
E | E09 | InvoiceTotal | Total a pagar | E07 | N | — | 1..1 | Se transforma en cbc:PayableAmount y en ValTolFac del QR. Se devuelve en la respuesta (totalAmount). |
E | E10 | TotalBTaxes / TotalBDiscounts / TotalWDiscounts / ExplicitTotal | Otros totales | E07 | N | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
E | E11 | InWords / AdditionalInfo | Total en letras e información adicional | E01 | A | — | 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.
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
E | E12 | Payments | Pagos | R01 | G | — | 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. |
E | E13 | Type | Tipo de pago | E12 | A | — | 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
|
E | E14 | Code | Código del medio de pago | E12 | A | — | 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
|
E | E15 | Date | Fecha de pago | E12 | F | — | 0..1 | Se transforma en cbc:PaymentDueDate (se toman los primeros 10 caracteres: AAAA-MM-DD). |
E | E16 | Amount | Monto pagado | E12 | N | — | 1..1 | Obligatorio por el esquema XML. El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
E | E17 | Description / AditionalData | Descripción e información adicional del pago | E12 | A | — | 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.
| C | ID | Campo | Descripción | P | T | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
F | F01 | AdditionalDocumentInfo | Información adicional del documento | R01 | G | — | 1..1 | Obligatorio por el esquema XML (al menos un AdditionalInfo). |
F | F02 | DocTemplate | Plantilla del documento | F01 | A | — | 0..1 | El builder UBL de Colombia no usa este campo (no se refleja en el XML DIAN). |
F | F03 | AdditionalInfo | Bloque de información adicional | F01 | G | — | 1..2 | Code, Type, Description, AddressInfo, Texts y AditionalInfo no los usa el builder de Colombia; solo se lee AditionalData (referencia de notas). |
F | F04 | AditionalData | Datos adicionales | F03 | G | — | 0..1 | Contiene uno o más <Data>. Para NC/ND el API toma el PRIMER Data que traiga la clave IDFacturaRef o UUIDRef. |
F | F05 | Data | Grupo de datos de referencia | F04 | G | — | 1..1000 | Atributos opcionales Name e Id; contiene elementos <Info Name="" Value=""/>. Las claves se comparan sin distinguir mayúsculas. Valores permitidos
|
F | F06 | Info Name="IDFacturaRef" | Número de la factura referenciada | F05 | A | — | 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/...". |
F | F07 | Info Name="UUIDRef" | CUFE de la factura referenciada | F05 | A | — | 1..1 (NC/ND) | Se transforma en .../cac:InvoiceDocumentReference/cbc:UUID con schemeName CUFE-SHA384. |
F | F08 | Info Name="FechaRef" | Fecha de emisión de la factura referenciada | F05 | F | 10 | 1..1 (NC/ND) | Formato AAAA-MM-DD. Se transforma en .../cac:InvoiceDocumentReference/cbc:IssueDate. |
F | F09 | Info Name="ResponseCode" | Concepto de corrección | F05 | A | — | 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. |
F | F10 | Info Name="Description" | Descripción de la corrección | F05 | A | — | 1..1 (NC/ND) | Se transforma en cac:DiscrepancyResponse/cbc:Description. |
F | F11 | Info Name="ReferenceID" | Sección de la factura original corregida | F05 | N | 1-4 | 0..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 (en XML), se obtiene como respuesta un objeto JSON que tiene la siguiente estructura.
Donde:
| Atributo | Descripción |
|---|---|
code | contiene el código de la respuesta obtenida |
message | contiene un mensaje informativo relacionado a la respuesta |
description | descripción adicional del mensaje |
responseData1 | XML UBL 2.1 firmado (XAdES-EPES) en base64, con el CUFE/CUDE ya calculado. |
responseData2 | Vacío: la certificación no devuelve HTML. Para obtenerlo usar GET DOCUMENT. |
responseData3 | Vacío: la certificación no devuelve PDF. Para obtenerlo usar GET DOCUMENT. |
authNumber | CUFE (factura) o CUDE (nota crédito/débito) del documento, algoritmo SHA-384 (96 caracteres hexadecimales). |
url | Vacío. |
infoDetails | Arreglo 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. |
suggestedFileName | nombre 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. |
suggestedFileName2 | otro nombre sugerido |
batch | Prefijo de numeración del documento (sts:Prefix). |
serial | Consecutivo del documento (dígitos finales de cbc:ID). |
issuedTimeStamp | fecha de emisión de la factura electrónica |
taxID | Identificador del contribuyente emisor del documento |
name | nombre o razón social del emisor |
branchCode | Copia de Seller.BranchInfo.Code del NUC. |
branchName | Copia de Seller.BranchInfo.Name del NUC. |
receiverTaxID | Copia de Buyer.TaxID del NUC. |
receiverName | nombre o razón social del receptor |
discounts | Vacío. |
taxes | Vacío. |
subTotal | Copia de Totals.TotalItems del NUC. |
totalAmount | Copia de Totals.GrandTotal.InvoiceTotal del NUC. |
enrolledTimeStamp | Fecha 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. |
backprocessor | servidor que realiza la consulta |
additionalInfo | Normalmente 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ódigo | Descripción |
|---|---|
-1 | Sin respuesta del backend de certificación. |
0 | Error 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. |
1 | Documento certificado: validado por Digifact, firmado y almacenado. La transmisión a la DIAN es posterior y asíncrona. |
400 | Error en realizar la consulta. Se mostrará en el atributo "message" la descripción del error. |
500 | Error inesperado. Se mostrará el contenido del error en los atributos "message" y "description". |
3010 | XML_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. |
3000 | Error no controlado del backend. |
3052 | DOCUMENT_ALREADY_EXISTS — el documento con ese NIT, prefijo y consecutivo ya existe. |
3079 | GET 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ódigo | Descripción |
|---|---|
200 | Petición procesada. En certificación revisar el campo code: un error de negocio también llega con 200. |
400 | Parámetro faltante, XML que no cumple el esquema o error al armar el documento (motivo en texto plano). |
401 | Token ausente, inválido, vencido o de otro NIT; o credenciales incorrectas en get_token. |
500 | Internal Server Error |