Campos del documento

Cada campo de document en la emisión (el mismo cuerpo que POST /v1/companies/{company_id}/documents): qué es, de dónde sale el valor, reglas y nodo UBL. Montos, cantidades y porcentajes van como texto decimal.

`resolution_id`

Qué es: Número de la resolución de numeración de la DIAN bajo la que se emite.
De dónde sale: La resolución que la DIAN le autorizó a la empresa (portal MUISCA) y que se registró en el portal de la plataforma. Cada resolución tiene prefijo, rango, vigencia y modo (automático o manual).
Reglas: Solo dígitos. Obligatorio para una factura; una nota crédito o débito se numera con su propia serie y nunca lo necesita (si llega, se acepta y se ignora).
Ejemplos: 18760000001
DIAN: sts:InvoiceControl/sts:InvoiceAuthorization (FAB04-FAB12).

`number`

Qué es: Número consecutivo del documento, sin prefijo.
De dónde sale: En modo automático lo asigna la plataforma: no lo envíes. En modo manual lo decide tu sistema (por ejemplo el del punto de venta) y debe estar dentro del rango de la resolución.
Reglas: Entero. Obligatorio en modo manual, prohibido en automático (numbering_mode_mismatch).
Ejemplos: 42
DIAN: cbc:ID junto con el prefijo (FAD05).

`type`

Qué es: Tipo de documento.
De dónde sale: Lo decide la operación: venta (invoice), corrección a favor del comprador (credit_note) o cobro adicional (debit_note).
Reglas: invoice, credit_note o debit_note.
Ejemplos: invoice
DIAN: Raíz Invoice / CreditNote / DebitNote; cbc:InvoiceTypeCode (FAD12).

`invoice_type`

Qué es: Clase de factura.
De dónde sale: sale para la factura de venta nacional; export si es exportación.
Reglas: Solo facturas. Por defecto sale (01).
Ejemplos: sale, export
DIAN: cbc:InvoiceTypeCode 01/02 (FAD12, 13.2.4).

`operation`

Qué es: Tipo de operación de la factura.
De dónde sale: La mayoría de ventas son standard. aiu para contratos de construcción con Administración, Imprevistos y Utilidad; mandates y transport para esos regímenes. El cambiario (13) ya no está en la tabla de la DIAN y no se puede emitir.
Reglas: Solo facturas. Por defecto standard (10).
Ejemplos: standard, aiu
DIAN: cbc:CustomizationID (FAD02, 13.2.5).

`correction`

Qué es: Qué corrige una nota crédito o débito.
De dónde sale: La factura original (número, CUFE y fecha, de get_document) o, si la nota no referencia una factura, el periodo.
Reglas: Obligatorio en notas: concept, description y exactamente uno de billing_reference o period.
Ejemplos: {"concept":"partial_return","description":"Devolución de 1 hora","billing_reference":{"number":"SETP990000001","cufe":"…","issue_date":"2026-10-01"}}
DIAN: cac:DiscrepancyResponse y cac:BillingReference (13.2.7.4-13.2.7.5).

`correction.concept`

Qué es: Motivo de la nota.
De dónde sale: Lo decide quien corrige.
Reglas: Nota crédito: partial_return, annulment, discount, price_adjustment, early_payment_discount, volume_discount. Nota débito: interest, expenses, value_change, other. annulment exige billing_reference.
Ejemplos: partial_return, interest
DIAN: cac:DiscrepancyResponse/cbc:ResponseCode.

`correction.description`

Qué es: Explicación de la corrección en texto libre.
De dónde sale: La redacta quien emite la nota.
Reglas: Texto no vacío.
Ejemplos: Devolución de 1 hora
DIAN: cac:DiscrepancyResponse/cbc:Description.

`correction.billing_reference`

Qué es: Factura que la nota corrige.
De dónde sale: get_document de la factura: number (prefijo y consecutivo), cufe e issued_at (solo la fecha).
Reglas: number, cufe y issue_date (YYYY-MM-DD), todos obligatorios.
Ejemplos: {"number":"SETP990000001","cufe":"8bb6…","issue_date":"2026-10-01"}
DIAN: cac:BillingReference/cac:InvoiceDocumentReference.

`correction.period`

Qué es: Periodo que corrige una nota sin factura de referencia.
De dónde sale: Las fechas del periodo facturado.
Reglas: start y end (YYYY-MM-DD), end >= start.
Ejemplos: {"start":"2026-09-01","end":"2026-09-30"}
DIAN: cac:InvoicePeriod.

`customer`

Qué es: El comprador (adquiriente).
De dónde sale: Al comprador solo se le pide documento, nombre y correo (Res. 202 de 2025, art. 69; Circular Externa 7 de 2022): no le pidas dirección, teléfono ni RUT. Si se omite, la factura va al consumidor final anónimo de la DIAN (222222222222).
Reglas: Opcional. Con customer, solo identification es obligatorio: el nombre y el correo que falten se completan con la consulta de la DIAN (lookup_acquirer) y lo que envíes siempre gana. Sin nombre propio ni de la DIAN: name_required. El resto toma los valores por defecto del anexo 1.9 (persona según el documento, R-99-PN, ZZ, sin dirección).
Ejemplos: {"identification":{"type":"citizenship_card","number":"1020304050"}}, {"identification":{"type":"nit","number":"900373076"},"name":"Comercializadora Andina S.A.S.","emails":["facturas@andina.example"]}
DIAN: cac:AccountingCustomerParty (FAK).

`customer.person_type`

Qué es: Persona jurídica o natural.
De dónde sale: El RUT del comprador (casilla de tipo de contribuyente). No hace falta pedirlo.
Reglas: juridical o natural. Opcional: por defecto juridical con NIT (nit, foreign_nit) y natural con cualquier otro documento.
Ejemplos: juridical
DIAN: cbc:AdditionalAccountID (FAK02, 13.2.7.3).

`customer.identification.type`

Qué es: Tipo de documento de identidad.
De dónde sale: El documento del comprador.
Reglas: nit, citizenship_card, foreigner_id, passport, foreign_document, foreign_nit, nuip, civil_registry, identity_card, foreigner_card, special_stay_permit, temporary_protection_permit.
Ejemplos: nit, citizenship_card
DIAN: cbc:CompanyID/@schemeName (FAK61-FAK64).

`customer.identification.number`

Qué es: Número de identificación sin dígito de verificación.
De dónde sale: RUT o cédula del comprador.
Reglas: Solo dígitos para NIT y cédula; sin puntos, guiones ni el DV.
Ejemplos: 900373076
DIAN: cbc:CompanyID y cac:PartyIdentification/cbc:ID.

`customer.identification.check_digit`

Qué es: Dígito de verificación (DV) del NIT.
De dónde sale: El RUT, al lado del NIT. Se calcula con el algoritmo de módulo 11 de la DIAN; si lo envías y no coincide, el error indica el esperado.
Reglas: Opcional con NIT (se calcula si falta); prohibido con cualquier otro tipo.
Ejemplos: 4
DIAN: cbc:CompanyID/@schemeID.

`customer.name`

Qué es: Razón social o nombre completo.
De dónde sale: Tal como figura en el RUT: la DIAN compara este nombre con el registro (reglas FAK). Si falta, se toma el de la consulta de la DIAN.
Reglas: Texto de hasta 450 caracteres. Opcional: sin él se consulta la DIAN; si la DIAN no lo tiene o no responde, name_required (FAK20 lo exige).
Ejemplos: Comercializadora Andina S.A.S.
DIAN: cac:PartyTaxScheme/cbc:RegistrationName y cac:PartyLegalEntity/cbc:RegistrationName.

`customer.trade_name`

Qué es: Nombre comercial.
De dónde sale: El RUT o la marca del cliente.
Reglas: Opcional.
Ejemplos: Andina
DIAN: cac:PartyName/cbc:Name.

`customer.tax_scheme`

Qué es: Régimen de tributos del comprador.
De dónde sale: El RUT (responsabilidades de IVA/INC).
Reglas: iva, inc, iva_and_inc o not_applicable (por defecto).
Ejemplos: iva
DIAN: cac:PartyTaxScheme/cac:TaxScheme (13.2.7.6).

`customer.responsibilities`

Qué es: Responsabilidades fiscales del RUT.
De dónde sale: Casilla 53 del RUT del comprador.
Reglas: Lista de large_taxpayer (O-13), self_withholder (O-15), iva_withholding_agent (O-23), simple_regime (O-47), not_applicable (R-99-PN, por defecto).
Ejemplos: ["not_applicable"], ["large_taxpayer","self_withholder"]
DIAN: cbc:TaxLevelCode separado por ; (FAK26).

`customer.address`

Qué es: Dirección del comprador.
De dónde sale: El RUT o la dirección de facturación del cliente. No se le puede exigir al comprador (Comunicado DIAN 026 de 2025).
Reglas: Opcional; el anexo la exige solo en ventas por fuera del establecimiento (FAK07). Colombia: municipality_code y line. Exterior: country, city, line y opcionalmente region.
Ejemplos: {"country":"CO","municipality_code":"11001","line":"Carrera 7 # 71-21"}
DIAN: cac:PhysicalLocation/cac:Address y cac:RegistrationAddress (FAJ08-FAJ19, 13.2.9).

`customer.address.country`

Qué es: País.
De dónde sale: La dirección del cliente.
Reglas: ISO 3166-1 alfa-2. Por defecto CO.
Ejemplos: CO, US
DIAN: cac:Country/cbc:IdentificationCode.
Catálogo: Países ISO 3166-1 alfa-2 (13.2.9.1)

`customer.address.municipality_code`

Qué es: Municipio colombiano en código DIVIPOLA del DANE.
De dónde sale: La ciudad de la dirección, convertida a su código de 5 dígitos: los 2 primeros son el departamento. Usa value para verificar un código.
Reglas: 5 dígitos, obligatorio en direcciones de Colombia (municipality_required). El departamento y el nombre de la ciudad se derivan del código.
Ejemplos: 11001, 05001, 76001
DIAN: cbc:ID, cbc:CityName, cbc:CountrySubentity y cbc:CountrySubentityCode (13.2.9.3).
Catálogo: DIVIPOLA (municipios, anexo 1.9, 13.2.9.3)

`customer.address.city`

Qué es: Ciudad, solo en el exterior.
De dónde sale: La dirección del cliente extranjero.
Reglas: Texto. No se usa en Colombia (allí manda municipality_code).
Ejemplos: Miami
DIAN: cbc:CityName.

`customer.address.region`

Qué es: Estado o provincia, solo en el exterior.
De dónde sale: La dirección del cliente extranjero.
Reglas: Opcional.
Ejemplos: Florida
DIAN: cbc:CountrySubentity.

`customer.address.line`

Qué es: Línea de la dirección.
De dónde sale: La dirección del cliente.
Reglas: Texto no vacío.
Ejemplos: Carrera 7 # 71-21
DIAN: cac:AddressLine/cbc:Line.

`customer.address.postal_code`

Qué es: Código postal.
De dónde sale: La dirección del cliente (en Colombia, el de 6 dígitos de 4-72).
Reglas: Opcional.
Ejemplos: 110231
DIAN: cbc:PostalZone.

`customer.emails`

Qué es: Correos del comprador.
De dónde sale: El correo que da el comprador. Si falta, se toma el de la consulta de la DIAN (el de recepción registrado si es facturador, o el de su última factura): confírmalo con la persona.
Reglas: Lista de correos válidos; el primero va al XML. Opcional: sin correo propio ni de la DIAN la factura no se envía por correo.
Ejemplos: ["facturas@andina.example"]
DIAN: cac:Contact/cbc:ElectronicMail (FAJ71).

`lines`

Qué es: Líneas del documento: qué se vende.
De dónde sale: El detalle de la venta en tu sistema.
Reglas: Al menos una línea.
Ejemplos: [{"code":"PARQ-HORA","description":"Parqueadero por horas","quantity":"3","unit":"HUR","unit_price":"4000.00","taxes":[{"scheme":"iva","percent":"19"}]}]
DIAN: cac:InvoiceLine / CreditNoteLine / DebitNoteLine (FAV, FAX).

`lines[].code`

Qué es: Código interno del producto o servicio.
De dónde sale: Tu catálogo de productos (SKU).
Reglas: Opcional: texto de hasta 50 caracteres. Sin código (ausente o en blanco) el XML no lleva SellersItemIdentification; la DIAN solo lo notifica, no rechaza. Si existe, también es el código del estándar 999 cuando no das standard_code.
Ejemplos: PARQ-HORA
DIAN: cac:Item/cac:SellersItemIdentification/cbc:ID (FAZ06/FAZ07, 0..1, regla de notificación).

`lines[].standard_code`

Qué es: Código estándar del producto.
De dónde sale: UNSPSC o GTIN (código de barras) si lo tienes; own para un código propio.
Reglas: Opcional: standard (unspsc, gtin, own) y code; si no lo das, el sistema usa 999 (estándar propio) con el código de la línea, o ITEM-{n} si la línea tampoco tiene código.
Ejemplos: {"standard":"unspsc","code":"78111800"}
DIAN: cac:Item/cac:StandardItemIdentification.

`lines[].description`

Qué es: Descripción del producto o servicio.
De dónde sale: Tu catálogo de productos.
Reglas: Texto no vacío.
Ejemplos: Parqueadero por horas
DIAN: cac:Item/cbc:Description.

`lines[].quantity`

Qué es: Cantidad.
De dónde sale: La venta.
Reglas: Texto decimal mayor que cero (“3”, “1.5”), nunca número JSON.
Ejemplos: 3, 1.5
DIAN: cbc:InvoicedQuantity con @unitCode.

`lines[].unit`

Qué es: Unidad de medida de la cantidad.
De dónde sale: La unidad en que vendes: unidad (94), hora (HUR), kilogramo (KGM)… Usa value para verificar un código.
Reglas: Código de la lista de la DIAN. Por defecto 94 (unidad).
Ejemplos: 94, HUR, KGM
DIAN: @unitCode de la cantidad (13.2.8.6).
Catálogo: Unidades de medida (13.2.8.6)

`lines[].unit_price`

Qué es: Precio por unidad antes de impuestos.
De dónde sale: Tu lista de precios, sin IVA.
Reglas: Texto decimal >= 0 (“4000.00”). El valor de la línea es cantidad x precio - descuentos + cargos de la línea.
Ejemplos: 4000.00
DIAN: cac:Price/cbc:PriceAmount; cbc:LineExtensionAmount.

`lines[].taxes`

Qué es: Impuestos de la línea.
De dónde sale: La tarifa que aplica al producto (IVA 19 %, 5 %, exento, excluido, INC…).
Reglas: Lista; cada tributo una vez por línea. Gravado: exactamente uno de percent o per_unit. Exento o excluido: category sin tarifa.
Ejemplos: [{"scheme":"iva","percent":"19"}], [{"scheme":"iva","category":"excluded"}]
DIAN: cac:TaxTotal de la línea (FAX).

`lines[].taxes[].scheme`

Qué es: Tributo.
De dónde sale: La tarifa del producto.
Reglas: iva, inc, ica, ic, stamp, plastic_bags, carbon, fuels, sugary_drinks, ultra_processed_food, other (con name)…
Ejemplos: iva, inc
DIAN: cac:TaxScheme/cbc:ID (lista Tributo).

`lines[].taxes[].category`

Qué es: Gravado, exento o excluido.
De dónde sale: El tratamiento del producto en el Estatuto Tributario.
Reglas: taxed (por defecto), exempt (IVA 0 %, se reporta) o excluded (no se reporta).
Ejemplos: taxed, exempt, excluded
DIAN: Excluido no genera TaxSubtotal; exento sí, al 0 %.

`lines[].taxes[].percent`

Qué es: Tarifa porcentual.
De dónde sale: La tarifa del tributo (IVA general 19, reducido 5).
Reglas: Texto decimal 0-100.
Ejemplos: 19, 5
DIAN: cbc:Percent del TaxSubtotal.

`lines[].taxes[].per_unit`

Qué es: Tarifa por unidad (impuestos de valor fijo, como bolsas plásticas).
De dónde sale: La norma del tributo.
Reglas: amount por base_quantity unidades de base_unit.
Ejemplos: {"amount":"66","base_quantity":"1","base_unit":"94"}
DIAN: cbc:PerUnitAmount y cbc:BaseUnitMeasure.

`lines[].allowance_charges`

Qué es: Descuentos o cargos de la línea.
De dónde sale: Promociones o recargos del producto.
Reglas: kind, reason, base y exactamente uno de amount o percent. El descuento condicionado no va en línea.
Ejemplos: [{"kind":"discount","reason":"Promoción","percent":"10","base":"12000.00"}]
DIAN: cac:AllowanceCharge de la línea (FAU10).

`allowance_charges`

Qué es: Descuentos o cargos globales del documento.
De dónde sale: Descuentos comerciales sobre el total.
Reglas: Igual que en la línea; reason_code unconditional (00) o conditional (01).
Ejemplos: [{"kind":"discount","reason":"Pronto pago","reason_code":"conditional","amount":"1000.00","base":"14280.00"}]
DIAN: cac:AllowanceCharge (13.2.8.8, FAU08).

`prepaid_payments`

Qué es: Anticipos recibidos.
De dónde sale: Tu cartera: pagos que el cliente hizo antes de la factura.
Reglas: id, amount, received_date, paid_date. Informativos: no restan del total (11.9.2).
Ejemplos: [{"id":"ANT-1","amount":"5000.00","received_date":"2026-09-30","paid_date":"2026-09-30"}]
DIAN: cac:PrepaidPayment.

`withholdings`

Qué es: Retenciones que practica el comprador.
De dónde sale: Lo que el cliente te retiene (retefuente, reteIVA, reteICA) según su condición de agente retenedor.
Reglas: scheme (rete_fuente, rete_iva, rete_ica), rate y taxable_amount. No cambian el total a pagar de la DIAN.
Ejemplos: [{"scheme":"rete_fuente","rate":"2.5","taxable_amount":"12000.00"}]
DIAN: cac:WithholdingTaxTotal (FAT01-FAT07).

`payment`

Qué es: Forma y medio de pago.
De dónde sale: Cómo paga el cliente.
Reglas: Por defecto contado con medio 10 (efectivo).
Ejemplos: {"form":"cash","means":"10"}, {"form":"credit","due_date":"2026-11-02","means":"42"}
DIAN: cac:PaymentMeans (FAN01-FAN05).

`payment.form`

Qué es: Contado o crédito.
De dónde sale: Las condiciones de la venta.
Reglas: cash (sin vencimiento) o credit (con due_date).
Ejemplos: cash, credit
DIAN: cac:PaymentMeans/cbc:ID 1/2.

`payment.due_date`

Qué es: Fecha de vencimiento del crédito.
De dónde sale: Las condiciones de pago acordadas.
Reglas: YYYY-MM-DD, igual o posterior a la emisión. Solo con credit.
Ejemplos: 2026-11-02
DIAN: cbc:DueDate y cbc:PaymentDueDate (FAD11, FAN04).

`payment.means`

Qué es: Medio de pago.
De dónde sale: Cómo se pagó: efectivo (10), transferencia (31), tarjeta débito (49) o crédito (48), consignación (42)… Usa value para verificar un código.
Reglas: Código de la lista de la DIAN. Por defecto 10.
Ejemplos: 10, 31, 48
DIAN: cbc:PaymentMeansCode (13.2.8.4.2).
Catálogo: Medios de pago (13.2.8.4.2)

`payment.reference`

Qué es: Referencia del pago.
De dónde sale: El id de la transacción en la pasarela o la transferencia.
Reglas: Opcional.
Ejemplos: PSE-123456
DIAN: cbc:PaymentID.

`currency`

Qué es: Moneda del documento.
De dónde sale: La moneda en que se factura.
Reglas: ISO 4217. Por defecto COP; otra moneda exige exchange_rate.
Ejemplos: COP, USD
DIAN: cbc:DocumentCurrencyCode y @currencyID (FAD15).
Catálogo: Monedas ISO 4217 (13.2.8.3)

`exchange_rate`

Qué es: Tasa de cambio a pesos.
De dónde sale: La TRM del día (Banco de la República) o la pactada.
Reglas: rate (COP por unidad) y date. Solo con moneda distinta de COP.
Ejemplos: {"rate":"4100.50","date":"2026-10-03"}
DIAN: cac:PaymentExchangeRate.

`notes`

Qué es: Notas en texto libre.
De dónde sale: Mensajes para el cliente.
Reglas: Hasta 500 caracteres cada una.
Ejemplos: ["Gracias por su compra"]
DIAN: cbc:Note (FAD13).

`period`

Qué es: Periodo facturado.
De dónde sale: Servicios públicos, arriendos, mensualidades.
Reglas: start y end (YYYY-MM-DD), end >= start.
Ejemplos: {"start":"2026-09-01","end":"2026-09-30"}
DIAN: cac:InvoicePeriod (FAE01-FAE05).

`rounding`

Qué es: Redondeo del total a pagar.
De dónde sale: Tu medio de cobro: PSE, transferencias y códigos de barras no admiten centavos.
Reglas: Opcional; exactamente uno de to_nearest o amount. No toca bases ni impuestos (el IVA conserva sus decimales); el CUFE usa el total ya redondeado (11.4.2). El ajuste queda entre -2.00 y 2.00 (tolerancia de 5.2.1.1).
Ejemplos: {"to_nearest":"1"}, {"amount":"-0.41"}
DIAN: cbc:PayableRoundingAmount (5.2.1), único valor que puede ser negativo (5.2.3.1); cbc:PayableAmount ya redondeado (FAU14).

`rounding.to_nearest`

Qué es: Múltiplo al que se redondea el total.
De dónde sale: “1” para redondear al peso; mitades hacia arriba.
Reglas: Decimal mayor que 0 y hasta 4, con hasta dos decimales.
Ejemplos: 1, 0.50
DIAN: cbc:PayableRoundingAmount = total redondeado - total sin redondear.

`rounding.amount`

Qué es: Ajuste de redondeo ya calculado.
De dónde sale: El redondeo que hizo tu punto de venta.
Reglas: Decimal con signo, entre -2.00 y 2.00, con hasta dos decimales.
Ejemplos: -0.41, 0.30
DIAN: cbc:PayableRoundingAmount.