# Documentación Técnica NUC-JSON Colombia V1.0

> Especificación oficial del formato NUC en JSON. Misma estructura que la versión XML — cambia solo la serialización.


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

## Versión del documento

- **Versión:** V1.0 (VIGENTE)
- **Clave para `?v=`:** `v1-0`
- **Esquema de la entidad fiscal:** DIAN Anexo Técnico v1.9
- **En vigencia desde:** 04/09/2026
- **Es la versión por defecto:** sí
- **Ficha de la versión actualizada el:** 02/10/2026
- **URL de esta versión:** `/co/nuc/json.md`

## 1. Funcionamiento

Esta API transforma una cadena con un esquema definido (NUC) en formato JSON a su factura electrónica correspondiente del país donde pertenezca.

**NUC:** archivo JSON que contiene la información necesaria para generar el XML de la factura electrónica.

## 2. Arquitectura

**Endpoint:** `POST https://testnucco.digifact.com/api/v2/transform/nuc_json`
**Content-Type:** `application/json`

**Query Params:** `TAXID`, `FORMAT`, `USERNAME`

## 3. Convenciones

## Convenciones de las tablas

### Columnas de las tablas (Tabla 2)

| 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. |

### Tipos de dato en JSON (Tabla 3)

| Tipo | Descripción |
|---|---|
| `JSON` | Documento JSON, descrito en un esquema contenido en esta ficha técnica |
| `O` | Objeto JSON, grupo de atributos |
| `A` | Alfanumérico |
| `N` | Numérico (montos y cantidades como texto con patrón \d*\.\d{2,6}) |
| `F` | Fecha y hora AAAA-MM-DDThh:mm:ss (hora local de Colombia, sin desfase) |
| `L` | Arreglo o lista de objetos |
| `I` | Información adicional: lista de objetos { "Name": "", "Data": "", "Value": "" } |

### Formato de tamaños (Tabla 4)

| 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) |

## 4. Formato del NUC

### 4.1 Conjuntos de campos (Tabla 5)

| 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) |

> ⚠️ La API es **case-sensitive**. Respetar mayúsculas y minúsculas exactamente.

### 4.2 — Elemento raíz del NUC (Conjunto 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 | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| R | `R01` | `Root` | Elemento raíz del NUC |  | O | `—` | `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 | L | `—` | `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 | O | `—` | `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.3 — Informació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 | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| A | `A01` | `Header` | Información general del documento | R01 | O | `—` | `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: `01`=Factura electrónica de Venta (Alias NUC aceptado: FE. Raíz UBL Invoice, CustomizationID 10, UUID CUFE-SHA384.); `02`=Factura electrónica de venta - exportación (Alias NUC: FX. NO SOPORTADO AÚN de punta a punta: el API lo emite como Invoice con CustomizationID fijo 10 (Estándar); no emite el tipo de operación 04 Exportación ni la extensión de Interoperabilidad (Suplemento K).); `03`=Documento electrónico de transmisión - tipo 03 (contingencia del facturador) (NO SOPORTADO AÚN de punta a punta: el API lo acepta y lo emite como Invoice, pero el procedimiento de contingencia (§12.1) no está implementado.); `04`=Factura electrónica de Venta - tipo 04 (contingencia DIAN) (NO SOPORTADO AÚN: el flujo de contingencia tipo 04 (§12.2: reintentos, re-firma, AttachedDocument) no está implementado en el backend.); `91`=Nota Crédito (Alias NUC: NC. Raíz UBL CreditNote, CreditNoteTypeCode 91, CustomizationID 20 (con referencia a factura), UUID CUDE-SHA384. Requiere el bloque de referencia en AdditionalDocumentInfo.); `92`=Nota Débito (Alias NUC: ND. Raíz UBL DebitNote (UBL 2.1 no define type code para la ND), CustomizationID 30 (con referencia a factura), UUID CUDE-SHA384. Requiere el bloque de referencia en AdditionalDocumentInfo.) |
| 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: `1`=Producción (Produce efectos legales (§13.2). Digifact Colombia NO tiene ambiente de producción: no usar.); `2`=Pruebas (habilitación) (Sin efectos legales. Es el valor que aplica el API si AdditionalIssueType viene vacío y el único ambiente disponible hoy.) |
| 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 | O | `—` | `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.4 — Informació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 | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `B01` | `Seller` | Información del emisor | R01 | O | `—` | `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: `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) |
| 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: `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).) |
| B | `B07` | `Contact` | Contacto del emisor | B01 | O | `—` | `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 | O | `—` | `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 | O | `—` | `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 | O | `—` | `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.5 — Información del adquirente (Buyer) (Conjunto C)

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

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| C | `C01` | `Buyer` | Información del adquirente | R01 | O | `—` | `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: `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) |
| 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 | O | `—` | `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 | O | `—` | `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 | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| D | `D01` | `Items` | Listado de ítems | R01 | L | `—` | `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 | O | `—` | `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 | L | `—` | `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 | L | `—` | `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 | L | `—` | `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: `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) |
| D | `D12` | `Charges` | Cargos del ítem | D02 | L | `—` | `0..1` | Hasta 10 <Charge>. Mismo mapeo que los descuentos pero con cbc:ChargeIndicator true. |
| D | `D13` | `Totals` | Totales del ítem | D02 | O | `—` | `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.7 — Totales (Totals) (Conjunto E)

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

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| E | `E01` | `Totals` | Totales del documento | R01 | O | `—` | `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 | L | `—` | `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: `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) |
| E | `E06` | `TotalCharges / TotalDiscounts` | Cargos y descuentos totales | E01 | L | `—` | `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 | O | `—` | `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.8 — Pagos (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 | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| E | `E12` | `Payments` | Pagos | R01 | L | `—` | `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: `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).) |
| 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: `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).) |
| 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.9 — Informació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 | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `F01` | `AdditionalDocumentInfo` | Información adicional del documento | R01 | O | `—` | `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 | L | `—` | `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 | O | `—` | `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 | L | `—` | `1..1000` | Atributos opcionales Name e Id; contiene elementos <Info Name="" Value=""/>. Las claves se comparan sin distinguir mayúsculas. — Valores: `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".) |
| 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. |


## Respuesta de la API

### 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 de respuesta (Tabla 8)

| 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 HTTP (Tabla 9)

| 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 |
