AI-Ready:

Descargar .md Ver .md ChatGPT Claude Descargar Skill IA

📋 Campos de todos los documentos electrónicos

📖 Referencia Completa de Campos
En esta sección se describen todos los campos que se deben considerar para la generación de factura electrónica, nota de crédito y nota de débito, documento soporte y documento equivalente, con sus respectivas notas de ajuste.

📄

Factura Electrónica
Tipos 7, 8, 9, 10

📝

Notas de Ajuste
Crédito (5) / Débito (4)

🏪

POS Electrónico
Tipo 20

📑

Documento Soporte
Tipo 11

🎯 Referencia Rápida de Tipos de Documento

⚠️ IMPORTANTE: IDs del API vs Códigos DIAN

Los valores en la columna ID (API) son los que debes usar en type_document_id. El Code (DIAN) es solo para referencia con la normativa DIAN.
🔑 REGLA DE ORO: En el API SIEMPRE usas el ID de la DB, NUNCA el code DIAN.

ID (API)	Code (DIAN)	Tipo	Descripción	Normativa	Notas
7	01	Factura de Venta	Documento estándar de venta	Res. 165	`type_document_id: 7`
8	02	Factura de Exportación	Factura para operaciones con exterior	Res. 165	`type_document_id: 8`
9	03	Factura de Contingencia Tipo 03	Emitida cuando falla conexión DIAN	Res. 165	`type_document_id: 9` ⚠️ Requiere `additional_document_reference`
10	04	Factura de Contingencia Tipo 04	Protocolo alternativo especial	Res. 165	`type_document_id: 10` - Opcional `additional_document_reference`
11	05	Documento Soporte	Para servicios y operaciones especiales	Res. 165	`type_document_id: 11`
20	20	Documento Equivalente POS	Factura de Punto de Venta	Res. 165	`type_document_id: 20` ⚠️ Requiere `point_of_sale`
5	91	Nota Crédito	Devolución o descuento	Res. 165	`type_document_id: 5` ⚠️ Genera CUDE
4	92	Nota Débito	Ajuste por aumento	Res. 165	`type_document_id: 4` ⚠️ Genera CUDE

✅ Compatibilidad de Campos por Tipo

📊 Matriz de Compatibilidad: Verifica qué campos son obligatorios (🔴), opcionales (🟢) o condicionales (🟡) según el tipo de documento.

Campo	Factura (1,2)	Contingencia (3,4)	Documento Soporte (7)	POS (9)	Nota Crédito (91)	Nota Débito (92)
`resolution_number`	🔴	🔴	🔴	🔴	🔴	🔴
`prefix`	🔴	🔴	🔴	🔴	🔴	🔴
`date`	🟢	🟢	🟢	🟢	🟢	🟢
`document_number`	🔴	🔴	🔴	🔴	🔴	🔴
`operation_type_id`	🔴	🔴	🔴	🔴	🔴	🔴
`type_document_id`	🔴	🔴	🔴	🔴	🔴	🔴
`payments`	🔴	🔴	🔴	🔴	🔴	🔴
`customer`	🔴	🔴	🔴	🔴	🔴	🔴
`legal_monetary_totals`	🔴	🔴	🔴	🔴	🔴	🔴
`lines`	🔴	🔴	🔴	🔴	🔴	🔴
`additional_document_reference`	🟢	🔴	🟢	🟢	🟢	🟢
`point_of_sale`	🟢	🟢	🟢	🔴	🟢	🟢
`billing_reference`	🟢	🟢	🟢	🟢	🔴	🔴
`order_reference`	🟢	🟢	🟢	🟢	🟢	🟢
`notes`	🟢	🟢	🟢	🟢	🟢	🟢
`shareholders`	🟢	🟢	🟢	🟢	🟢	🟢

🔴 Obligatorio

🟢 Opcional

🟡 Condicional

🔧 Referencia de Campos

Guía de Uso

A continuación se describe el uso detallado de cada campo del request body. Los campos están agrupados por función para facilitar la navegación.

`resolution_number` 🔴

Número de resolución de facturación asignado por la DIAN. Debe coincidir exactamente con el valor configurado en el portal web del proveedor tecnológico. Este campo es obligatorio para todos los documentos y debe ser un string.

`prefix` 🟡

Prefijo asociado a la resolución de facturación. Identifica la serie o rango del documento (ej. "FEV", "NC", "DS"). Este campo es condicional: obligatorio cuando la resolución tiene prefijo configurado. Debe ser un string.

`date` 🟢

Fecha de emisión del documento. Este campo es opcional. Si no se envía, la API asigna la fecha actual del servidor. Debe ser un string en formato YYYY-MM-DD (ej. "2025-05-25").

`expiration_date` 🟢

Fecha de vencimiento del documento. Este campo es opcional y debe ser un string en formato YYYY-MM-DD. Se utiliza principalmente en documentos equivalentes electrónicos y debe corresponder con las fechas negociadas o acordadas de pago.

`time` 🟢

Hora de emisión del documento. Este campo es opcional. Si no se envía, la API asigna la hora actual del servidor. Debe ser un string en formato HH:mm:ss (ej. "14:30:00").

`notes` 🟢

Notas u observaciones adicionales a nivel de encabezado del documento. Se incluye en el XML como cbc:Note (en facturas, documento soporte, POS y notas crédito y débito, incluidas las de POS) y se imprime en la representación gráfica (PDF). Este campo es opcional y debe ser un string. Acepta texto libre de cualquier longitud.

`document_number` 🔴

Número consecutivo del documento sin prefijo. Este campo es obligatorio para todos los documentos. Debe ser un número entero (ej. 990000001). Este número debe estar dentro del rango autorizado por la resolución DIAN vigente.

Numeración automática

En los endpoints /auto-increment/* no se envía document_number: la plataforma lo asigna. Ver Numeración Automática.

`uuid` 🟢 NEW

Identificador del documento de tu lado (anti-duplicados). Este campo es opcional y va en la raíz del body. Se recomienda enviar un UUID (ej. "3d6f1a8e-2b4c-4f7d-9e0a-6c1b5d8f2a47"): la emisión no valida su formato, pero la consulta GET /documents/{uuid} sí exige un UUID válido.

El uuid se registra antes de transmitir el documento a la DIAN, de modo que un reintento con el mismo uuid no emite un documento distinto:

Situación	Resultado
Reintentas el mismo número con el mismo `uuid`	Se procesa normalmente (no choca).
El `uuid` ya pertenece a otro documento de la empresa (`POST /invoice`, `/notes/`, `/ds/` y los `PATCH /auto-increment/*`)	HTTP `409`: `El uuid proporcionado ya se usó en otro documento de la empresa. No se emitió de nuevo: consulte ese documento o envíe un uuid nuevo.` El consecutivo no se consume.
El `uuid` ya fue usado y lo envías en `POST /auto-increment/*`	HTTP `400` con el estado del envío original. Ver UUID ya usado.
La emisión falla antes de transmitir a la DIAN	El `uuid` se libera y puedes volver a usarlo.

Puedes consultar el documento con GET /documents/{uuid} usando tu uuid o el uuid del envío que devuelve la respuesta de emisión.

Ejemplo

  "uuid": "3d6f1a8e-2b4c-4f7d-9e0a-6c1b5d8f2a47"

`operation_type_id` 🔴

Se refiere al tipo de operación que afecta al documento. Este campo es obligatorio para todos los documentos y debe ser un entero que corresponda al ID de la tabla operation_types del API.

IMPORTANTE

En el API siempre se envía el ID (columna izquierda), NUNCA el code DIAN. El valor más común es 1 (Estándar).

📄 Factura Electrónica y Documento Soporte

ID (API)	Code DIAN	Tipo de Operación	Uso
1	10	Estándar	✅ Valor por defecto para la mayoría de facturas
2	09	Servicios AIU	Administración, Imprevistos y Utilidad
3	11	Mandatos	Operaciones de mandato (ver `lines->mandate`)
4	12	Transporte	Sector transporte
5	14	Notarios	Sector notarial
6	15	Compra Divisas	Operaciones de compra de divisas
7	16	Venta Divisas	Operaciones de venta de divisas

📑 Documento Soporte (Residente / No Residente)

ID (API)	Code DIAN	Tipo de Operación	Uso
9	10	Residente	Proveedor residente en Colombia
10	11	No Residente	Proveedor no residente — Requiere `payment_exchange_rate`

📝 Notas de Ajuste (Crédito / Débito)

ID (API)	Code DIAN	Tipo de Operación	Uso
11	20	Nota ajuste Doc. Equivalente POS	Ajuste al documento equivalente POS
12	20	Nota Crédito → Factura Electrónica	Referencia una factura electrónica existente
13	24	Nota Ajuste → FE Aceptada	Para facturas electrónicas de venta aceptadas
14	30	Nota Débito → Factura Electrónica	Referencia una factura electrónica existente
15	22	Nota Crédito sin referencia FE	Sin referencia a una factura electrónica
16	32	Nota Débito sin referencia FE	Sin referencia a una factura electrónica

Ejemplo
```
  "operation_type_id": 1
```

`type_document_id` 🔴

Se refiere al tipo de documento que se está enviando a la DIAN. Este campo es obligatorio para todos los documentos y debe ser un entero que corresponda al id de la tabla accounting_documents del API (NO el code DIAN).

CRÍTICO

En el API SIEMPRE se usa el id de la base de datos (columna izquierda). NUNCA el code DIAN. Confundir estos valores es el error más común de integración.

Columnas de referencia

id → Valor que se envía en type_document_id
code → Código DIAN (solo referencia normativa)
cufe_algorithm → Algoritmo de hash que genera la DIAN para el documento
apply_notes → 1 si el documento acepta notas de crédito/débito

📄 Facturas Electrónicas

`id`	`code`	Documento	Algoritmo	Notas	Requisitos especiales
7	01	Factura electrónica	CUFE-SHA384	✅	—
8	02	Factura de Exportación	CUFE-SHA384	✅	Requiere `payment_exchange_rate`
9	03	Factura por Contingencia Facturador	CUDE-SHA384	✅	⚠️ Requiere `additional_document_reference`
10	04	Factura por Contingencia DIAN	CUFE-SHA384	✅	—

📑 Documento Soporte

`id`	`code`	Documento	Algoritmo	Notas	Requisitos especiales
11	05	Documento de Soporte	CUDS-SHA384	✅	Requiere `invoice_period` en cada línea
15	95	Nota de ajuste documento soporte	CUDS-SHA384	❌	Requiere `billing_reference`

🏪 Documento Equivalente POS

`id`	`code`	Documento	Algoritmo	Notas	Requisitos especiales
20	20	P.O.S Electrónico	CUDE-SHA384	✅	⚠️ Requiere `point_of_sale` y `software_manufacturer`
93	93	Nota débito P.O.S Electrónico	CUDE-SHA384	❌	Requiere `billing_reference`
94	94	Nota crédito P.O.S Electrónico	CUDE-SHA384	❌	Requiere `billing_reference` con `scheme_name`

📝 Notas Crédito y Débito

`id`	`code`	Documento	Algoritmo	Requisitos especiales
5	91	Nota crédito	CUDE-SHA384	Requiere `discrepancy_response` y `billing_reference`
4	92	Nota débito	CUDE-SHA384	Requiere `discrepancy_response` y `billing_reference`

👷 Nómina Electrónica

`id`	`code`	Documento	Algoritmo	Notas
13	102	Documento Soporte Nómina Electrónica	CUNE-SHA384	✅
14	103	Nota de Ajuste Nómina Electrónica	CUNE-SHA384	✅

🔔 Eventos y Otros

`id`	`code`	Documento	Algoritmo	Descripción
12	96	Eventos (ApplicationResponse)	CUDE-SHA384	Acuse de recibo, aceptación/rechazo
99	999	Attached Document	CUDS-SHA384	Documento adjunto

🎫 Otros Documentos Equivalentes (próximamente)

`id`	`code`	Documento	Estado
25	25	Boleta de ingreso a cine	🔜 Inactivo
27	27	Boleta espectáculos públicos	🔜 Inactivo
30	30	Juegos localizados y no localizados	🔜 Inactivo
35	35	Tiquete transporte terrestre de pasajeros	🔜 Inactivo
40	40	Cobro de peajes	🔜 Inactivo
45	45	Extracto sociedades financieras y fondos	🔜 Inactivo
50	50	Tiquete transporte aéreo de pasajeros	🔜 Inactivo
55	55	Operación bolsa de valores y comodities	🔜 Inactivo
60	60	Servicios públicos domiciliarios	🔜 Inactivo

Ejemplo
```
  "type_document_id": 7
```

Consultar también: Referencia Rápida de Tipos de Documento | Glosario: Contingencia

`graphic_representation` 🟢

Indicador para solicitar que la API genere el PDF de representación gráfica del documento. Este campo es opcional. Enviar 1 para generar el PDF, 0 o no enviar si no se requiere. Debe ser un entero.

Ejemplo
```
  "graphic_representation": 1
```

`send_email` 🟢

Indicador para solicitar que la API envíe automáticamente por email el documento al cliente (al correo definido en customer.email). Este campo es opcional. Enviar 1 para enviar, 0 o no enviar si no se requiere. Debe ser un entero.

Ejemplo

"send_email": 1

`currency_id` 🟢

ID de la moneda del documento (cbc:DocumentCurrencyCode). Este campo es opcional: si no se envía, la API asume Peso Colombiano (COP) (id: 272). Solo se debe enviar cuando el documento está en moneda extranjera. Debe ser un entero.

Importante

La moneda debe estar habilitada en su cuenta del proveedor tecnológico. Si envía un currency_id de una moneda no configurada en su cuenta, el API rechazará el documento. Consulte las monedas disponibles en el ENDPOINT {{url}}/currencies.

💱 Monedas activas

`id`	ISO	Moneda	Símbolo
272	COP	Peso Colombiano (predeterminado)	$
188	USD	Dólar Americano	$
213	EUR	Euro	€
277	MXN	Peso Mexicano	$
270	ARS	Peso Argentino	$
271	CLP	Peso Chileno	$
194	CAD	Dólar Canadiense	$
266	PEN	Nuevo Sol (Perú)	S
278	UYU	Peso Uruguayo	$
274	DOP	Peso Dominicano	R
273	CUP	Peso Cubano	$
225	PYG	Guaraní (Paraguay)	₲
165	BOB	Boliviano (Bolivia)	B
164	VEF	Bolívar Fuerte (Venezuela)	B
168	CRC	Colón Costarricense	₡
169	SVC	Colón Salvadoreño	₡
195	GYD	Dólar de Guyana	G

Ejemplo

"currency_id": 188

`send_to_queue` 🟢

NO IMPLEMENTADO

Este campo aún no está disponible. No lo envíe: con send_to_queue: 1 la emisión se rechaza con HTTP 400 y no se consume el consecutivo.

{
  "success": false,
  "message": "El envío a cola de procesamiento aún no está habilitado."
}

Para procesamiento asíncrono use POST /bulk/documents.

Indicador reservado para enviar el documento a una cola de procesamiento asíncrono. Omítalo o envíe 0. En la respuesta de emisión, send_to_queue siempre es 0.

`rounding` 🟢

Valor de redondeo aplicado al total del documento (cbc:PayableRoundingAmount). Este campo es opcional y debe ser un string con valor flotante. Se utiliza principalmente en Nómina Electrónica para ajustar centavos o decimales en el total pagable.

Uso principal

Este campo aplica para documentos de Nómina Electrónica (type_document_id: 13, 14). En facturación electrónica estándar generalmente no se requiere.

`attachments`: NEW

Archivos adjuntos opcionales cargados y vinculados al documento (máximo 4 archivos, almacenados de forma segura en Amazon S3). Este campo es opcional (nullable) y debe ser un arreglo de objetos con los siguientes campos:

💻 JSON de ejemplo

"attachments": [
  {
    "filename": "Soporte.pdf",
    "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago...",
    "content_type": "application/pdf"
  }
]

📎 Campos del adjunto

Campo	Tipo	Requerido	Descripción / Reglas
`filename`	`string`	⚠️ Condicional	Nombre del archivo adjunto con extensión. Obligatorio si se envía `attachments`. Max: 255 chars.
`content`	`string`	⚠️ Condicional	Contenido del archivo en base64. Obligatorio si se envía `attachments`.
`content_type`	`string`	Opcional	Tipo MIME del archivo (ej. `application/pdf`, `image/png`). Max: 100 chars.

`invoice_period` 🟢

Periodo de facturación del documento a nivel general (cac:InvoicePeriod). Diferente al invoice_period dentro de lines. Este campo es opcional y debe ser un objeto.

¿Cuándo se usa?

Documento Soporte (type_document_id: 11): para indicar el periodo de prestación del servicio.
Sector Salud: periodo de facturación del servicio médico.
Notas Crédito/Débito sin referencia a factura (operation_type_id: 15, 16): obligatorio para indicar el periodo que cubre la nota.

Ejemplo

"invoice_period": {
    "start_date": "2024-01-01",
    "start_time": "00:00:00",
    "end_date": "2024-01-31",
    "end_time": "23:59:59"
  }

Detalle de los campos
- start_date
  Fecha de inicio del periodo. Formato YYYY-MM-DD.
- start_time
  Hora de inicio del periodo. Formato HH:mm:ss.
- end_date
  Fecha de fin del periodo. Formato YYYY-MM-DD.
- end_time
  Hora de fin del periodo. Formato HH:mm:ss.

`deliveries`: NEW

Grupo de información de la entrega de bienes o prestación de servicios (cac:Delivery). Este campo es opcional y debe ser un arreglo de objetos. Permite informar la dirección, fecha, transportador y contacto de la entrega física de mercancías.

📦 Ejemplo JSON completo

"deliveries": [
    {
      "date": "2026-05-21",
      "time": "14:00:00",
      "address": "NORTE DE VIRGINIA H10",
      "country_id": "239",
      "delivery_party": {
        "identity_document_id": "10",
        "type_organization_id": 1,
        "tax_regime_id": 2,
        "tax_level_id": "5",
        "company_name": "Nombre de la empresa transportadora",
        "address": "cra prueba",
        "dni": "1019016005",
        "country_id": "45",
        "city_id": "149",
        "postal_code": "110121",
        "merchant_registration": "12454"
      },
      "delivery_contact": {
        "email": "cliente1@ejemplo.com",
        "mobile": "3164444444",
        "contact_name": "Nombre del contacto",
        "note": "Nota adicional de contacto"
      }
    }
  ]

📍 Campos del delivery — Lugar y fecha de entrega

Campo	Tipo	Requerido	XPath UBL	Descripción
`date`	string	Opcional	`cbc:ActualDeliveryDate`	Fecha real o estimada de entrega. Formato `YYYY-MM-DD`
`time`	string	Opcional	`cbc:ActualDeliveryTime`	Hora real o estimada de entrega. Formato `HH:mm:ss`
`address`	string	Sí	`cac:DeliveryAddress`	Dirección del lugar de entrega
`country_id`	string	Opcional	`cac:Country`	ID del país de entrega. Por defecto `"45"` (Colombia). Endpoint: `{{url}}/countries`
`city_id`	string	⚠️ Condicional	`cac:DeliveryAddress`	Ciudad/municipio de entrega. Obligatorio si `country_id = "45"` (Colombia). Endpoint: `{{url}}/cities`
`postal_code`	string	⚠️ Condicional	`cac:DeliveryAddress`	Código postal de entrega. Obligatorio si `country_id = "45"` (Colombia)

Entregas en Colombia

Cuando el país de entrega es Colombia (country_id: "45"), los campos city_id y postal_code son obligatorios. La DIAN rechazará el documento si no se informan.

🏢 delivery_party — Transportador o parte que entrega

Información fiscal y de identificación del transportador (cac:DeliveryParty). Opcional.

Campo	Tipo	Requerido	Descripción
`identity_document_id`	string	Sí	Tipo de documento de identidad. Endpoint: `{{url}}/identity-documents`
`type_organization_id`	int	Sí	`1` = Persona Jurídica, `2` = Persona Natural
`company_name`	string	Sí	Razón social o nombre completo del transportador
`dni`	string	Sí	Número de identificación sin dígito de verificación
`tax_regime_id`	int	Opcional	Régimen fiscal. Por defecto `2` (No responsable de IVA). Endpoint: `{{url}}/accounting-regime`
`tax_level_id`	string	Opcional	Responsabilidad tributaria. Por defecto `"5"` (No aplica). Endpoint: `{{url}}/fiscal-regime`
`address`	string	Opcional	Dirección fiscal del transportador
`country_id`	string	Opcional	País del transportador. Por defecto `"45"` (Colombia)
`city_id`	string	⚠️ Condicional	Ciudad/municipio. Obligatorio si `country_id = "45"`. Endpoint: `{{url}}/cities`
`postal_code`	string	⚠️ Condicional	Código postal. Obligatorio si `country_id = "45"`. Por defecto `"000000"`
`merchant_registration`	string	Opcional	Matrícula mercantil (`cbc:CorporateRegistrationScheme`)

👤 delivery_contact — Contacto de la entrega

Persona responsable de recibir o coordinar la entrega (cac:Contact). Opcional.

Campo	Tipo	Requerido	Descripción
`contact_name`	string	Opcional	Nombre de la persona de contacto
`email`	string	Opcional	Correo electrónico de contacto
`mobile`	string	Opcional	Teléfono o celular de contacto
`note`	string	Opcional	Nota adicional sobre la entrega

`delivery_terms` 🟢

Términos de entrega o condiciones INCOTERM del documento. Este campo es opcional y debe ser un objeto. Aplicable en facturas de exportación o cuando se negocian condiciones de entrega.

Ejemplo

"delivery_terms": {
    "delivery_id": "1",
    "terms": "FOB"
  }

Detalle de los campos
- delivery_id
  ID de la condición de entrega. Puede consultar las diferentes condiciones en el ENDPOINT {{url}}/delivery-conditions.
- terms
  Texto descriptivo de los términos de entrega. Este campo es opcional y debe ser un string.

`despatch_document_references` 🟢

Referencias a documentos de despacho asociados al documento electrónico. Este campo es opcional y debe ser un arreglo de objetos.

Ejemplo

"despatch_document_references": [
    {
      "number": "DESP-001",
      "date": "2024-02-28"
    }
  ]

Detalle de los campos
- number
  Número del documento de despacho referenciado. Obligatorio y debe ser un string.
- date
  Fecha del documento de despacho. Formato YYYY-MM-DD.

`receipt_document_references` 🟢

Referencias a documentos de recepción asociados al documento electrónico. Este campo es opcional y debe ser un arreglo de objetos.

Ejemplo

"receipt_document_references": [
    {
      "number": "REC-001",
      "date": "2024-03-01"
    }
  ]

Detalle de los campos
- number
  Número del documento de recepción referenciado. Obligatorio y debe ser un string.
- date
  Fecha del documento de recepción. Formato YYYY-MM-DD.

`showroomInformation` 🟢

NO IMPLEMENTADO

Este campo aún no está disponible en la versión actual de la API. Se documenta como referencia para futuras versiones. No lo envíe en el request body, será ignorado.

Información de la sala de ventas o punto de exhibición. Este campo es opcional y debe ser un objeto. Utilizado cuando la venta se realiza en una ubicación diferente a la sede principal.

Ejemplo

"showroomInformation": {
    "showroom": "Sala de Ventas Norte",
    "showroomAddress": "Cra 15 #100-45 Local 201",
    "dataShow": "Información adicional de la sala"
  }

`prepaid_payments` 🟢

Información de anticipos recibidos que se deben descontar del total a pagar del documento. Este campo es opcional y debe ser un objeto.

Ejemplo

"prepaid_payments": {
    "id": "SFR3123856",
    "paid_amount": "10.00",
    "received_date": "2018-09-29",
    "paid_date": "2018-09-29",
    "instruction_id": "Prepago recibido"
  }

Detalle de los campos
- id
  Identificador del anticipo o prepago. Este campo es obligatorio y debe ser un string.
- paid_amount
  Monto del anticipo pagado. Este campo es obligatorio y debe ser un string con valor flotante de máximo dos decimales.
- received_date
  Fecha en que se recibió el anticipo. Este campo es obligatorio y debe ser un string en formato YYYY-MM-DD.
- paid_date
  Fecha en que se realizó el pago del anticipo. Este campo es obligatorio y debe ser un string en formato YYYY-MM-DD.
- instruction_id
  Descripción o instrucción del prepago. Este campo es opcional y debe ser un string.

`payments` 🔴

Información de los pagos del documento. Define el método (contado/crédito), medio de pago y valor. Permite múltiples pagos. Este campo es obligatorio para todos los documentos y debe ser un arreglo de objetos.

Ejemplo

"payments": [
    {
      "payment_method_id": 1,
      "means_payment_id": 10,
      "value_paid": "141100.00",
      "payment_due_date": "2024-02-22"
    }
  ]

Detalle de los campos
- payment_method_id
  Método de pago: 1 = Contado, 2 = Crédito. Este campo es obligatorio y debe ser un entero.
- means_payment_id
  Medio de pago (ej. 10 = Efectivo, 42 = Consignación bancaria, 47 = Transferencia). Este campo es obligatorio y debe ser un entero. Puede consultar todos los medios de pago disponibles en el ENDPOINT {{url}}/payment-means.
- value_paid
  Valor pagado. Este campo es obligatorio para todos los documentos y debe ser un número flotante con máximo dos decimales, encerrado entre "".
- payment_due_date
  Fecha de vencimiento del pago. Este campo es usado para indicar la fecha de vencimiento de un pago a crédito. Es obligatorio solo para las ventas a crédito y debe ser un string en formato YYYY-MM-DD.
- duration_measure
  Duración de la medida del pago en días. Este campo es opcional y se utiliza para indicar la duración del periodo de pago a crédito. Debe ser un string.

`report_header`: NEW

Plantilla para personalizar el encabezado y pie de página de la representación gráfica (PDF). La API renderiza dinámicamente los valores proporcionados sobre una plantilla prediseñada. Este campo es opcional y debe ser un objeto.

¿Cómo funciona?

Se proporciona el uuid de una plantilla previamente creada en el sistema y un arreglo de vars con los valores a inyectar. La API busca la plantilla y reemplaza los marcadores de posición (placeholders) con los valores proporcionados.

🧩 Estructura del objeto

Campo	Tipo	Requerido	Descripción
`uuid`	string	Sí	UUID de la plantilla de diseño previamente creada en el sistema
`vars`	array	Sí	Lista de variables para reemplazar los placeholders de la plantilla

Cada objeto dentro de vars:

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del placeholder sin llaves `{}`. Ej: si el marcador es `{sucursal}`, enviar `"sucursal"`
`value`	string	Sí	Valor de texto o HTML que reemplazará el marcador. Se inserta tal cual en la plantilla

📦 Ejemplo JSON

"report_header": {
  "uuid": "101413670038274164",
  "vars": [
    {
      "name": "sucursal",
      "value": "Bodega Principal Cali"
    },
    {
      "name": "direccion",
      "value": "Zona Franca Palmaseca Bodega 5"
    },
    {
      "name": "celular",
      "value": "315 112 4411"
    }
  ]
}

`due_diligence`: NEW

Información para control cambiario
Control Cambiario - Debida Diligencia. Los tipos de operación que se encuentran permitidos son los que se encuentran en la columna “Código” que están dentro de la tabla 18.3 Control Cambiario - Debida Diligencia, ubicada en la Caja de Herramientas en la siguiente ruta “Caja_de_herramientas_Factura_Electronica_Validacion_Previa.zip\Anexo Tecnico\Tablas Referenciadas”, en formato Excel “.xlsx”
Ejemplo

"due_diligence": {
  "code": "01"
}

Tabla debida diligencia - Control cambiario

Código	Descripción
01	Debida Diligencia del Cliente – DDC General
02	Debida Diligencia del Cliente – DDC Reforzada
03	Debida diligencia intensificada por razón de la cuantía de las operaciones – DDC intensificada.
04	Debida Diligencia del Cliente – DDC simplificada

`document_signature`: NEW

Información de la firma del documento. Este campo es opcional y debe ser un objeto.

Ejemplo

"document_signature": {
    "cashier": "Nombre del cajero(a)",
    "seller": "Nombre del vendedor(a)"
  }

Detalle de los campos
- cashier
  Nombre del cajero(a). Este campo es opcional y debe ser un string.
- cashier_title
  Título o etiqueta que se muestra debajo de la firma del cajero en la representación gráfica. Este campo es opcional y debe ser un string.
- seller
  Nombre del vendedor(a). Este campo es opcional y debe ser un string.
- seller_title
  Título o etiqueta que se muestra debajo de la firma del vendedor en la representación gráfica. Este campo es opcional y debe ser un string.

`payment_exchange_rate` 🟡

Tasa de cambio aplicada al documento. Este campo es obligatorio cuando currency_id indica una moneda extranjera (diferente a COP). Define la equivalencia entre la moneda extranjera y el Peso Colombiano. Debe ser un objeto.

Ejemplo

"payment_exchange_rate": {
    "exchange_rate": "3950.00",
    "rate_date": "2022-06-28",
    "currency_id": 188
  }

Detalle de los campos
- exchange_rate
  Valor equivalente de 1 unidad de la moneda extranjera en Pesos Colombianos (COP). Por ejemplo, si el documento es en USD y 1 USD = 3950 COP, el valor debe ser "3950.00". Este campo es obligatorio y debe ser un string con valor flotante.
- rate_date
  Fecha de la tasa de cambio utilizada. Este campo es obligatorio y debe ser un string en formato YYYY-MM-DD.
- currency_id
  ID de la moneda extranjera del documento. Este campo es obligatorio y debe ser un entero. Consulte los valores en currency_id.

`point_of_sale` 🟡

Información del punto de venta físico donde se realizó la transacción. Este campo es obligatorio para documentos de tipo P.O.S Electrónico (type_document_id = 20) y debe ser un objeto.

📦 Ejemplo JSON

"point_of_sale": {
    "cashier_name": "LEWIS LOPEZ",
    "terminal_number": "CJ001aB",
    "cashier_type": "Caja de apoyo",
    "sales_code": "POS01",
    "address": "Gilbarco Encore 4 L1 Mangue ra 17 AC",
    "sub_total": "2000.10"
  }

🏪 Campos del punto de venta

Campo	Tipo	Descripción
`cashier_name`	string	Nombre del cajero que realiza la venta
`terminal_number`	string	Número de terminal del punto de venta (ej. `"CJ001aB"`)
`cashier_type`	string	Tipo de caja (ej. `"GENÉRICA"`, `"Caja de apoyo"`)
`sales_code`	string	Código o ID de la venta (ej. `"POS01"`, `"45212"`)
`address`	string	Dirección física del punto de venta
`sub_total`	string	Subtotal de la venta (total sin IVA). Formato `"0.00"`

Todos los campos son obligatorios para type_document_id = 20.

`software_manufacturer` 🟡

Información del fabricante del software POS que generó el documento. Este campo es obligatorio para documentos equivalentes P.O.S (type_document_id = 20) y debe ser un objeto.

Ejemplo

{
  "owner_name": "LEWIS LOPEZ GOMEZ",
  "company_name": "LOPEZSOFT SAS",
  "software_name": "SOFTWARE POS MATIAS APP"
}

Detalle de los campos
- owner_name
  Nombre del propietario. Este campo es obligatorio solo para los documentos equivalentes P.O.S y debe ser un string.
- company_name
  Nombre de la compañía. Este campo es obligatorio solo para los documentos equivalentes P.O.S y debe ser un string.
- software_name
  Nombre del software. Este campo es obligatorio solo para los documentos equivalentes P.O.S y debe ser un string.

`order_reference` 🟢

Referencia de la orden de compra. Este campo es opcional y debe ser usado de acuerdo al giro del documento. Debe ser un objeto.

Diferencia con additional_document_reference:

Use order_reference para UNA SOLA orden de compra
Use additional_document_reference para MÚLTIPLES documentos de referencia
Ejemplo

"order_reference": {
    "reference_number": "4545478787",
    "reference_date": "2021-05-19"
  }

Detalle de los campos
- reference_number
  Número de referencia. Este campo es opcional debe ser usado de acuerdo al giro del documento y debe ser un string.
- reference_date
  Fecha de referencia. Este campo es opcional debe ser usado de acuerdo al giro del documento y debe ser un string.

`health` 🟢

Información específica y obligatoria para documentos electrónicos del Sector Salud (reglamentada por la Resolución 000948 de 2026 [14 de mayo de 2026] del Ministerio de Salud y Protección Social —que deroga expresamente las Resoluciones 2275 de 2023, 558 y 1884 de 2024—, Resolución 866 de 2021 y el Documento Técnico 2 versión 001 - FEV Sector Salud del MinSalud / DIAN). Este campo es requerido cuando el emisor sea un prestador de servicios de salud (IPS, profesional independiente, transporte asistencial) o proveedor de tecnologías en salud que facture a EPS, entidades territoriales, ADRES, aseguradoras SOAT o planes voluntarios de salud. Debe ser un objeto.

📋 Ejemplo de Payload JSON — Objeto health

"health": {
  "operation_type": "SS-CUFE",
  "provider_code": "2341702036",
  "payment_modality": "02",
  "coverage": "01",
  "contract_number": "c12bab98915513f00c50e7efdde112763c65b421afcc1f3cea76302e1c80e21c",
  "policy_number": "",
  "copayment": 0,
  "moderator_fee": 0,
  "shared_payments": 0,
  "advance": 0,
  "justification_without_contract": "",
  "invoice_period": {
    "start_date": "2026-07-01",
    "start_time": "00:00:00",
    "end_date": "2026-07-30",
    "end_time": "23:59:59"
  },
  "download_attachments": {
    "url": "www.ips-1.com.co",
    "arguments": [
      {
        "name": "excelFile",
        "value": "a1b2c3.xlsx"
      },
      {
        "name": "txtFile",
        "value": "a1b2c3.txt"
      }
    ]
  },
  "document_delivery": {
    "ws": "https://ws4erp.ips-987.com.co/WcfRecibiendoDocs4ERP.svc?wsdl",
    "arguments": [
      {
        "name": "Método-1",
        "value": "ClienteEntregaAcuseDeReciboDeFEV-VP"
      },
      {
        "name": "Método-2",
        "value": "ClienteEntregaConstanciaDeMercanciaEntregada"
      }
    ]
  }
}

🏥 Campos Principales del Prestador y Contrato (Extensión Salud)

Campo	Tipo	Requerido	Descripción
`operation_type`	string	✅ Sí	Tipo de operación del sector salud. Valores habituales: `"SS-CUFE"` (Factura electrónica con CUFE), `"SS-CUDE"` (Notas débito/crédito), `"SS-POS"`, `"SS-SinAporte"`.
`provider_code`	string	✅ Sí	Código asignado en el SGSSS al prestador en el Registro Especial de Prestadores de Servicios de Salud (REPS - tabla `IPSCodHabilitación`) o código asignado por MinSalud (tabla `IPSnoREPS`) para Proveedores de Tecnologías en Salud.
`payment_modality`	string	✅ Sí	Código de la modalidad de pago pactada objeto de facturación (Catálogo `modalidadPago` de SISPRO). En facturas multiusuario, todos deben compartir la misma modalidad.
`coverage`	string	✅ Sí	Código de la entidad/fuente responsable de financiar la cobertura o plan de beneficios (Catálogo `coberturaPlan` de SISPRO).
`contract_number`	string	⚠️ Condicional	Número del contrato suscrito objeto de facturación. Si la entidad está obligada por la Ley 1966/2019, debe registrar el código CUCON expedido por la plataforma de contratación. En caso de no existir contrato, enviar vacío `""`.
`policy_number`	string	⚠️ Condicional	Número de la póliza de seguro. Obligatorio cuando se trate de atenciones cubiertas por póliza SOAT (cobertura `04`) o planes voluntarios de salud (pólizas de salud `12`). En los demás casos debe ir vacío `""`.
`justification_without_contract`	string	⚠️ Condicional	Código de justificación de atención cuando se factura sin contrato previo con el pagador (Catálogo `facturaSinContrato` de SISPRO). Obligatorio según causal específica (ej. urgencias, tutelas, portabilidad). Si hay contrato, enviar vacío `""`.

Campos que el API exige

Cuando envías health, el API exige operation_type, provider_code, payment_modality, coverage e invoice_period (con sus fechas y horas). contract_number y policy_number son opcionales para el API: si se omiten se informan vacíos (""). Si omites contract_number (o lo envías null), el API exige justification_without_contract y responde 422 sin él: El campo health.justification_without_contract es requerido cuando no se envía health.contract_number. Si hay contrato, envía contract_number y deja justification_without_contract vacío. Las columnas ⚠️ Condicional indican cuándo la normativa del sector salud exige el valor real.

📌 Catálogo de Modalidades de Pago (`payment_modality`)

Código	Modalidad	Definición (Decreto 780 de 2016)
`01`	Pago individual por caso / Paquete / Canasta	Conjunto integral de atenciones por patología, grupo relacionado de diagnóstico o procedimiento quirúrgico.
`02`	Pago global prospectivo	Tarifa global pactada anticipadamente para cubrir un volumen o grupo de servicios durante un periodo acordado.
`03`	Pago por capitación	Pago anticipado de una suma fija por persona que se pacta para atender un conjunto definido de servicios durante un periodo.
`04`	Pago por evento	Mecanismo en el que el pago se realiza por cada actividad, procedimiento, intervención, insumo o medicamento efectivamente prestado.

📌 Catálogo de Cobertura o Plan de Beneficios (`coverage`)

Código	Cobertura / Plan de Beneficios	Descripción y Base Normativa
`01`	UPC Contributiva	Plan de beneficios en salud financiado con UPC contributiva (Resolución 2765 de 2025).
`02`	Presupuesto Máximo	Servicios y tecnologías no financiados con UPC y no excluidos de la financiación con recursos del SGSSS (Resolución 067 de 2025).
`03`	Prima EPS, no asegurados SOAT	Víctimas de accidentes de tránsito ocasionados por vehículos no asegurados por SOAT o no identificados (Art. 106 D.L. 2106/2019).
`04`	Cobertura póliza SOAT	Servicios prestados a víctimas de accidentes con póliza SOAT vigente (Decreto 780 de 2016). Requiere `policy_number`.
`05`	Cobertura ARL	Prestaciones asistenciales derivadas de accidentes de trabajo y enfermedad laboral a cargo de la ARL (Dec. 1295/1994).
`06`	Cobertura ADRES	Coberturas en salud a cargo de la Administradora de los Recursos del SGSSS (Ley 1955/2019).
`07`	Cobertura Salud Pública	Acciones colectivas de gestión en salud pública Nación / Entidades Territoriales (Res. 1597 de 2025).
`08`	Entidad Territorial (Recursos de Oferta)	Prestación a cargo de la entidad territorial para población no afiliada al SGSSS (Leyes 715/2001 y 1955/2019).
`09`	Urgencias Población Migrante	Atención de urgencias a población migrante regular no afiliada o irregular (Art. 232 Ley 1955/2019).
`10`	Plan Complementario en Salud	Coberturas contratadas voluntariamente financiadas por afiliado/empleador (Dec. 780/2016).
`11`	Plan Medicina Prepagada	Coberturas de medicina prepagada contratadas voluntariamente (Dec. 780/2016).
`12`	Pólizas en Salud	Pólizas de hospitalización y cirugía contratadas voluntariamente (Dec. 780/2016). Requiere `policy_number`.
`13`	Régimen Especial o Excepción	Servicios a regímenes de excepción: Fuerzas Militares, Policía, Magisterio, Ecopetrol, Universidades (Ley 647/2001).
`14`	Fondo Nacional PPL / INPEC	Población privada de la libertad en custodia del INPEC (Ley 1709 de 2014 / Dec. 1069 de 2015).
`15`	Particular	Servicios y tecnologías asumidos directamente por el paciente con recursos propios.
`16`	UPC Subsidiada	Plan de beneficios en salud financiado con UPC subsidiada (Resolución 2765 de 2025).

📌 Causales de Factura Sin Contrato (`justification_without_contract`)

Se diligencia exclusivamente cuando el prestador no cuenta con acuerdo de voluntades previo con el pagador:

Atención de urgencias vitales.
Atención a cargo de ADRES, aseguradora SOAT o pólizas voluntarias / medicina prepagada.
Atención en salud por fallos de tutela u órdenes judiciales.
Atención en salud por Portabilidad o asignación masiva de afiliados (Art. 2.5.3.4.7.9 Decreto 780/2016).
Atención excepcional por cotizaciones o autorizaciones adicionales de servicios.
Gestión y recuperación de órganos para trasplante (Ley Estatutaria 1751 de 2015).
Profesionales independientes en atención a pacientes particulares.

💰 Copagos, Cuotas Moderadoras, Pagos Compartidos y Anticipos (PrepaidPayment)

Todos los montos numéricos deben ser mayores o iguales a 0, expresados sin separadores de miles y con punto decimal. Estos valores se descuentan o informan de acuerdo con las reglas de interoperabilidad con RIPS.

Para el API los cuatro montos son opcionales (aceptan null): si no se envían, se informan como 0. Aun así, la DIAN y la validación de RIPS pueden exigir el valor real recaudado, así que envíalos siempre que apliquen.

Campo	Tipo	Requerido	Descripción
`copayment`	number	No (por defecto `0`)	Valor total efectivamente recaudado por el prestador correspondiente a Copago. En facturas multiusuario corresponde a la sumatoria de copagos. Debe coincidir exactamente con el valor reportado en el JSON de RIPS.
`moderator_fee`	number	No (por defecto `0`)	Valor efectivamente recaudado por concepto de Cuota Moderadora. En facturas multiusuario es la sumatoria de cuotas. Debe coincidir con el valor de RIPS.
`shared_payments`	number	No (por defecto `0`)	Valor recaudado por Pagos Compartidos en planes voluntarios de salud (medicina prepagada, pólizas, planes complementarios). Debe coincidir con RIPS.
`advance`	number	No (por defecto `0`)	Valor del Anticipo a legalizar que se descuenta del valor de la factura en ejecución del contrato pactado.

📅 Periodo de Facturación (invoice_period)

Define el lapso temporal de la prestación de los servicios de salud (obligatorio para usuario único o facturación multiusuario / capitación):

Campo	Tipo	Requerido	Formato	Descripción
`start_date`	string	✅ Sí	`YYYY-MM-DD`	Fecha de inicio de prestación del servicio o inicio del periodo facturado (ej. `"2026-07-01"`).
`start_time`	string	✅ Sí	`HH:mm:ss`	Hora de inicio de la atención o inicio de periodo (ej. `"00:00:00"`).
`end_date`	string	✅ Sí	`YYYY-MM-DD`	Fecha final de prestación del servicio o fin del periodo facturado (ej. `"2026-07-30"`).
`end_time`	string	✅ Sí	`HH:mm:ss`	Hora final de la atención o cierre de periodo (ej. `"23:59:59"`).

📎 Descarga de Adjuntos y Entrega Electrónica (download_attachments / document_delivery)

Permite configurar canales automatizados para la descarga de soportes clínicos y la entrega de acuses entre el prestador y el pagador/ERP. Ambos bloques son opcionales: si no se envían, no se incluyen en el XML. Si se envían, url / ws toman "" y arguments toma [] cuando se omiten.

Objeto `download_attachments` (Descarga de Soportes)

Campo	Tipo	Requerido	Descripción
`url`	string	No	Dominio o URL del servicio web donde el pagador puede descargar los anexos y soportes clínicos (ej. `"www.ips-1.com.co"`).
`arguments`	array	No	Arreglo de objetos `{ "name": "...", "value": "..." }` con los nombres y rutas de los archivos adjuntos (ej. soportes en Excel, PDF de historia clínica o archivos RIPS).

Objeto `document_delivery` (Integración de Web Service)

Campo	Tipo	Requerido	Descripción
`ws`	string	No	Endpoint WSDL/SOAP o REST para la recepción de acuses de recibo y constancias de entrega de la factura electrónica. Si se envía, debe ser una URL válida.
`arguments`	array	No	Arreglo de objetos `{ "name": "...", "value": "..." }` con métodos o parámetros de consumo (ej. `"ClienteEntregaAcuseDeReciboDeFEV-VP"`).

`customer` 🔴

Información del cliente o proveedor. Este campo es obligatorio para todos los documentos y debe ser un objeto.

📄 Factura Electrónica y Documento Soporte

Campo	Tipo	Requerido	Default	Descripción
`company_name`	string	Sí	—	Razón social o nombre de persona natural
`dni`	string	Sí	—	Número de identificación sin dígito de verificación
`email`	string	Sí	—	Correo para envío del documento electrónico
`identity_document_id`	int	Opcional	`3` (NIT)	Tipo de documento de identidad. Endpoint: `{{url}}/identity-documents`
`type_organization_id`	int	Opcional	`2`	`1` = Persona Jurídica, `2` = Persona Natural
`tax_regime_id`	int	Opcional	`2`	Régimen fiscal (código `49` = No responsable IVA). Endpoint: `{{url}}/accounting-regime`
`tax_level_id`	int	Opcional	`5`	Responsabilidad tributaria (`R-99-PN` = No aplica). Endpoint: `{{url}}/fiscal-regime`
`country_id`	int	Opcional	`45`	País del cliente (Colombia). Endpoint: `{{url}}/countries`
`city_id`	int	Opcional	—	Ciudad del cliente. Endpoint: `{{url}}/cities`
`address`	string	Opcional	`""`	Dirección del cliente
`postal_code`	string	Opcional	`"000000"`	Código postal del cliente
`mobile`	string	Opcional	`""`	Teléfono o celular del cliente
`city_name`	string	Opcional	—	NEW — Nombre de la ciudad. Solo para clientes/proveedores extranjeros
`extra_data`	array	Opcional	—	NEW — Información adicional para la representación gráfica (no se envía a DIAN)

🏷️ extra_data — Campos adicionales del cliente

Arreglo de objetos {title, value} con datos propios del adquiriente que se muestran en el PDF pero no se envían a la DIAN. Útil para mostrar número de socio, categoría, fecha de vinculación, etc.

"extra_data": [
  { "title": "No. Socio", "value": "78-54121-454" },
  { "title": "FECHA DE VINCULACIÓN", "value": "02/02/2026" }
]

Campo	Tipo	Requerido	Descripción
`title`	string	Sí	Etiqueta del campo. Máx. 60 caracteres
`value`	string	Sí	Valor a mostrar. Máx. 500 caracteres

¿Dato del cliente o del documento?

Si el dato es sobre la operación (centro de costo, orden de servicio), usa additional_data a nivel de documento. customer.extra_data es exclusivamente para datos que describen al adquiriente.

🏪 Documento P.O.S Electrónico — Campos del cliente POS

Campo	Tipo	Requerido	Default	Descripción
`company_name`	string	Sí	—	Nombre de la empresa o persona natural
`dni`	string	Sí	—	Número de identificación sin dígito de verificación
`email`	string	Opcional	—	Correo para envío del documento
`points`	int	Opcional	`0`	Puntos acumulados del cliente

`shareholders` 🟢 NEW

Participantes o consorciados cuando el documento es emitido por un Consorcio o Unión Temporal. Este campo es opcional y debe ser un arreglo de objetos.

Genera un bloque cac:ShareholderParty por cada partícipe dentro del nodo del emisor (cac:AccountingSupplierParty / cac:Party), sin alterar la estructura ni los datos del adquiriente (customer). Además, los consorciados asociados al documento se conservan automáticamente en los reenvíos (POST /documents/{uuid}/resend).

📦 Ejemplo JSON

"shareholders": [
  {
    "dni": "1063279307",
    "company_name": "LEWIS LOPEZ A S.A.S.",
    "tax_level_id": 5,
    "tax_regime_id": 2,
    "participation_percent": 60
  },
  {
    "dni": "900123456",
    "company_name": "INGENIERIA Y PROYECTOS S.A.S.",
    "tax_level_id": 5,
    "tax_regime_id": 1,
    "participation_percent": 40
  }
]

🤝 Campos de cada consorciado

Campo	Tipo	Requerido	Descripción
`dni`	string	Sí	NIT del consorciado o partícipe (sin dígito de verificación). No se permiten NITs duplicados en el arreglo
`dv`	string / int	Opcional	Dígito de verificación del NIT. Si se envía, se valida contra el cálculo módulo 11 de la DIAN; si se omite, el sistema lo calcula a partir del `dni`
`company_name`	string	Sí	Razón social o nombre completo del consorciado
`tax_level_id`	int	Sí	Responsabilidad fiscal del consorciado (`1`: `O-13`, `2`: `O-15`, `3`: `O-23`, `4`: `O-47`, `5`: `R-99-PN`). Endpoint: `{{url}}/tax-level`
`tax_regime_id`	int	Sí	Régimen tributario (`1`: Responsable de IVA `48`, `2`: No responsable de IVA `49`). Endpoint: `{{url}}/tax-regime`
`participation_percent`	number	Sí	Porcentaje de participación del consorciado en la operación (ej. `60`, `40`, `100`)

Validaciones de shareholders (HTTP 422)

Dígito de verificación (dv): si se informa dv, debe coincidir con el dígito de verificación módulo 11 correspondiente al dni.
Sin NITs repetidos: no puede haber dos consorciados con el mismo dni dentro del arreglo shareholders.
Suma de porcentajes igual a 100: la suma de participation_percent de todos los elementos de shareholders debe ser exactamente 100 (si hay un único consorciado registrado en el arreglo, su participation_percent debe ser 100).

📦 Ver ejemplo completo de Factura con Consorciados

`discrepancy_response` 🟢

Respuesta a discrepancias. Este campo es obligatorio solo para las notas de crédito, débito y de ajustes de todos los documentos y debe ser un objeto.

Ejemplo

"discrepancy_response": {
    "reference_id": "EPOS2",
    "response_id": "9"
  }

Detalle de los campos
- reference_id
  Número del documento al que se le hace la nota, con el prefijo, ejemplo(FE4578). Este campo es obligatorio solo para las notas de crédito, débito y de ajustes de todos los documentos y debe ser un string.
- response_id
  Hace referencia al tipo de corrección aplicado a la nota. Este campo es obligatorio solo para las notas de crédito, débito y de ajustes de todos los documentos y debe ser un string. Puede consultar los diferentes tipos de corrección en el ENDPOINT {{url}}/correction-notes.

`billing_reference` 🟡

🔴 Obligatorio para Notas Crédito/Débito (referencia a factura original)
🟢 Opcional para otros documentos

Referencia al documento original sobre el cual se emite la nota. Debe ser un objeto.

📦 Ejemplo JSON

"billing_reference": {
    "number": "EPOS2",
    "date": "2023-12-22",
    "uuid": "b1b5d93a2918...031aea39",
    "scheme_name": "CUDE-SHA384"
  }

🧾 Campos de la referencia

Campo	Tipo	Requerido	Descripción
`number`	string	Sí	Número del documento referenciado con prefijo (ej. `"FE4578"`)
`date`	string	Sí	Fecha del documento referenciado. Formato `YYYY-MM-DD`
`uuid`	string	Sí	CUFE o CUDE del documento referenciado
`scheme_name`	string	⚠️ Condicional	Obligatorio para notas POS Electrónico y notas de ajuste Doc. Soporte. Valores: `CUFE-SHA384`, `CUDE-SHA384`, `CUDS-SHA384`

`allowance_charges` 🟢

Descuentos o cargos a nivel de factura que no afectan las bases gravables. Los que afectan bases gravables se informan a nivel de ítem. Este campo es opcional y debe ser un arreglo de objetos.

📦 Ejemplo JSON

"allowance_charges": [
    {
        "amount": "10000",
        "base_amount": "725000",
        "charge_indicator": true,
        "allowance_charge_reason": "Motivo del cargo a la factura"
    },
    {
        "amount": "10000",
        "base_amount": "725000",
        "charge_indicator": false,
        "discount_id": 2,
        "allowance_charge_reason": "Motivo del descuento a la factura"
    }
  ]

🧾 Campos del cargo/descuento

Campo	Tipo	Requerido	Descripción
`charge_indicator`	boolean	Sí	`true` = Cargo (aumenta el total), `false` = Descuento (reduce el total)
`amount`	string	Sí	Valor del cargo o descuento. Si es descuento, no puede superar `base_amount`
`base_amount`	string	Sí	Valor base sobre el cual se calcula el cargo o descuento
`allowance_charge_reason`	string	Sí	Razón o motivo del cargo/descuento
`discount_id`	int	⚠️ Condicional	Obligatorio si es descuento (`charge_indicator: false`). Endpoint: `{{url}}/discount-codes`
`multiplier_factor_numeric`	string	Opcional	Porcentaje como decimal (ej. `"10.00"` = 10%)

`legal_monetary_totals` 🔴

Totales monetarios del documento. Agrupa los valores brutos, impuestos, cargos, descuentos y el total a pagar. La DIAN valida que estos valores sean matemáticamente consistentes con las líneas y los impuestos. Este campo es obligatorio y debe ser un objeto.

📦 Ejemplo JSON

"legal_monetary_totals": {
    "line_extension_amount": "50000",
    "tax_exclusive_amount": "50000",
    "tax_inclusive_amount": "59500",
    "total_charges": 0,
    "total_allowance": 0,
    "payable_amount": "59500"
  }

🔴 Campos obligatorios

Campo	Tipo	Descripción
`line_extension_amount`	string	Suma de las líneas antes de impuestos (Valor Bruto)
`tax_exclusive_amount`	string	Base imponible total. Si no hay impuestos = `"0"`
`tax_inclusive_amount`	string	Valor Bruto + tributos de todas las líneas
`payable_amount`	string	Total a pagar: ítems + tributos + cargos globales − descuentos globales

🟢 Campos opcionales

Campo	Tipo	Default	Descripción
`total_charges`	string	`0`	Suma de todos los cargos globales
`total_allowance`	string	`0`	Suma de todos los descuentos globales
`allowance_total_amount`	string	—	Alternativa detallada a `total_allowance`
`charge_total_amount`	string	—	Alternativa detallada a `total_charges`
`pre_paid_amount`	string	—	Anticipos o prepagos que se descuentan del total

`lines` 🔴

Líneas de detalle del documento. Cada elemento del arreglo representa un ítem (producto o servicio) con su cantidad, precio, impuestos y descripción. Mínimo 1 línea por documento. Este campo es obligatorio y debe ser un arreglo de objetos.

📋 Campos obligatorios del ítem

Campo	Tipo	Default	Descripción
`invoiced_quantity`	string	—	Cantidad del producto o servicio
`line_extension_amount`	string	—	Valor total de la línea sin impuesto: C × PU - D + R. Formato `"0.00"`
`description`	string	—	Descripción del artículo o servicio
`code`	string	—	Código interno del artículo o servicio
`price_amount`	string	—	Valor unitario del artículo o servicio. Formato `"0.00"`
`base_quantity`	string	—	Cantidad sobre la que aplica el precio. Se recomienda igual a `invoiced_quantity`
`quantity_units_id`	string	`1093`	Unidad de medida. Endpoint: `{{url}}/quantity-units`
`type_item_identifications_id`	string	`4`	Estándar de identificación del ítem. Endpoint: `{{url}}/type-item-identifications`
`reference_price_id`	string	`1`	Precio de referencia. Endpoint: `{{url}}/reference-price`
`free_of_charge_indicator`	boolean	`false`	`true` = producto gratis o muestra

📝 Campos opcionales del ítem

Campo	Tipo	Descripción
`notes`	string	Nota adicional a nivel de línea (`cbc:Note` en el XML para facturas, documento soporte y notas crédito y débito, incluidas las de POS). Obligatorio en la línea de Administración para AIU (`operation_type_id: 2`), donde debe iniciar con: `"Contrato de servicios AIU por concepto de:"`
`brand_name`	string	Marca del producto. Se muestra en la representación gráfica
`model_name`	string	Modelo del producto
`sellers_item_identification`	string	Código interno alterno del vendedor
`pack_size_numeric`	string	Unidades por paquete o empaque
`um` / `mu` / `unit_measure_code`	string	Unidad de medida alternativa para la representación gráfica

`lines->mandate`

Grupo de información que describe el mandatario de la operación de venta. Este campo es obligatorio solo para facturas de mandato y debe ser un objeto.

Este campo se informa a nivel de ítem y aplica solo para mandatos. Un mandante por ítem.

Ejemplo

"mandate": {
  "dni": "2222222222",
  "dv": "2",
  "code": "0"
}

Detalle de los campos
- dni
  
  Número de identificación del mandatario. Este campo es obligatorio y debe ser un string.
- dv
  
  Dígito de verificación del mandatario. Este campo es obligatorio y debe ser un string.
- code
  
  Código que indica el tipo de ingreso del mandatario. Este campo es obligatorio y debe ser un string.
  
  Código Significado
  0 B/S ingreso propio
  1 B/S Ingresos Recibidos para Terceros

Código	Significado
0	B/S ingreso propio
1	B/S Ingresos Recibidos para Terceros

`linea->extra_data`: NEW

Genera columnas dinámicas en el detalle del PDF. Los datos se muestran en la representación gráfica del documento pero no se envían a la DIAN. Este campo es opcional y debe ser un arreglo de objetos.

Columnas consistentes

El campo title debe ser idéntico en todas las líneas que comparten la misma columna. La plantilla lo usa como encabezado de columna único; si varía entre líneas, se generan columnas distintas.

📋 Campos disponibles

Campo	Tipo	Requerido	Descripción
`title`	string	Sí	Encabezado de la columna en el PDF
`value`	string	Sí	Valor de la celda en esa línea
`align`	string	No	`left`, `center`, `right`. Default: `left`
`position`	int	No	1–7. Indica después de qué columna base se inserta. Fuera de rango → comportamiento legacy

🗺️ Guía de Posicionamiento (PDF)

El valor de position indica después de qué columna base se inserta la columna dinámica:

`position`	Columna insertada después de...	Ejemplo visual
`1`	CÓDIGO	`CÓDIGO \| 👉 MI_CAMPO \| DETALLE \| CANT \| ...`
`2`	DETALLE	`CÓDIGO \| DETALLE \| 👉 MI_CAMPO \| CANT \| ...`
`3`	CANT	`... \| CANT \| 👉 MI_CAMPO \| U.M \| ...`
`4`	U.M	`... \| U.M \| 👉 MI_CAMPO \| PRECIO \| ...`
`5`	PRECIO	`... \| PRECIO \| 👉 MI_CAMPO \| DESCUENTO \| ...`
`6`	DESCUENTO (si aplica)	`... \| DESCUENTO \| 👉 MI_CAMPO \| RECARGO \| ...`
`7`	RECARGO (si aplica)	`... \| RECARGO \| 👉 MI_CAMPO \| IVA \| ...`
sin valor	(comportamiento legacy)	Después de recargos, antes de impuestos

Reglas

Rango válido: 1–7. Valores mayores a 7 se ignoran silenciosamente (comportamiento legacy).
Resolución de conflictos: Si múltiples líneas definen el mismo title con diferente position, la primera línea que define el título determina la posición para toda la tabla.
position es por columna (title), no por línea individual. Todas las líneas del documento comparten el mismo layout.

📝 Ejemplo JSON completo

"invoice_lines": [
  {
    "code": "PROD-001",
    "description": "Producto de ejemplo",
    "extra_data": [
      { "title": "LOTE", "value": "L-2026-001", "position": 2 },
      { "title": "FECHA VENCIMIENTO", "value": "2026-12-31", "align": "center" }
    ]
  }
]

Resultado visual en el PDF

CÓDIGO | DETALLE | LOTE | CANT | U.M | PRECIO | FECHA VENCIMIENTO | IVA | TOTAL
                (position=2)                    (sin position → legacy)

`lines->invoice_period`

Periodo de facturación de la línea del documento soporte. Este campo es obligatorio solo para los documentos soporte y debe ser un objeto.

Ejemplo

"invoice_period": {
    "start_date": "2022-06-28",
    "description_code": 1
  }

Descripción de los campos
- start_date
  Fecha de inicio. Este campo es obligatorio solo para los documentos soporte y debe ser un string.
- description_code
  Código de descripción. Este campo es obligatorio solo para los documentos soporte y debe ser un entero.

`lines->allowance_charges`

Grupo de campos para información relacionada con un cargo o un descuento en la línea. Este grupo se debe informar a nivel de ítem, si y solamente si el cargo o descuento afecta la base gravable del ítem. Si un cargo individual, general a la factura genera IVA, debe reportarse como ítem. Para el caso de los descuentos a nivel de ítem no es necesario codificarlos. Este campo es opcional y debe ser un arreglo de objetos.

Ejemplo

"allowance_charges": [
    {
        "amount": "10000",
        "base_amount": "725000",
        "charge_indicator": true,
        "allowance_charge_reason": "Motivo del cargo a la linea"
    },
    {
        "amount": "10000",
        "base_amount": "725000",
        "charge_indicator": false,
        "discount_id": 1,
        "allowance_charge_reason": "Motivo del descuento a la linea"
    }
]

Detalle de los campos
- amount
  Valor total del cargo o descuento. Este campo es obligatorio y debe ser un número flotante con máximo dos decimales encerrado entre "".
- base_amount
  Valor Base para calcular el descuento el cargo. Este campo es obligatorio y debe ser un número flotante con máximo dos decimales encerrado entre "".
- charge_indicator
  Indica que el elemento es un Cargo y no un descuento. Cargo es true, es un Débito aumenta el valor de la item. Descuento es false, un Crédito descuenta el valor del ítem El elemento solamente puede identificar una de las informaciones. Este campo es obligatorio cuando el cargo no es un descuento y debe ser un booleano.
- allowance_charge_reason
  Texto libre para informar de la razón del descuento. Este campo es obligatorio y debe ser un string.

`lines->tax_totals`

Grupo de campos para información relacionada con todos los impuestos de la línea. Este campo es obligatorio solo cuando la línea tiene impuestos y debe ser un arreglo de objetos.

La estructura del objeto varía según el tipo de tributo: porcentual (ej. IVA) o nominal/valor fijo por unidad (ej. Código 18, INC Bolsas - Código 22, etc.).

Ejemplo (Impuesto Porcentual — IVA, Código 01)

"tax_totals": [
    {
        "tax_id": "1",
        "tax_amount": 294.633000,
        "taxable_amount": 1550.700000,
        "percent": 19
    }
]

Ejemplo (Impuesto Nominal — Código 32)

Reglas DIAN para impuestos nominales

La DIAN valida matemáticamente que tax_amount = per_unit_amount × base_unit_measure. Los campos percent y taxable_amount deben enviarse con valor 0 para este tipo de tributo. La regla de validación es FAX07 (línea) / FAS07 (cabecera).

"tax_totals": [
    {
        "tax_id": "18",
        "tax_amount": 387.675000,
        "taxable_amount": 0,
        "percent": 0,
        "per_unit_amount": 387.675000,
        "base_unit_measure": 1,
        "quantity_units_id": 70
    }
]

Cálculo: 387.675 × 1 = 387.675 (debe ser matemáticamente exacto). El valor de quantity_units_id debe corresponder al código numérico de la unidad de medida en el catálogo DIAN.

Detalle de los campos
- tax_id
  ID del impuesto. Este campo es obligatorio y debe ser un string.
- tax_amount
  Monto o valor total del impuesto. Este campo es obligatorio y debe ser un número flotante con máximo dos decimales.
  - Para impuestos porcentuales: resultado de taxable_amount × percent / 100.
  - Para impuestos nominales: resultado exacto de per_unit_amount × base_unit_measure.
- taxable_amount
  Base gravable del impuesto. Este campo es obligatorio y debe ser un número flotante.
  - Para impuestos porcentuales: valor sobre el que se aplica el porcentaje.
  - Para impuestos nominales: debe enviarse como 0.
- percent
  Porcentaje del impuesto. Este campo es obligatorio y debe ser un número.
  - Para impuestos porcentuales: valor del porcentaje (ej. 19 para IVA del 19%).
  - Para impuestos nominales: debe enviarse como 0.
- per_unit_amount
  Valor monetario fijo del tributo por cada unidad de medida física. Obligatorio para impuestos nominales. Debe ser un número flotante con máximo dos decimales.
- base_unit_measure
  Cantidad de unidades físicas sujetas al impuesto. Obligatorio para impuestos nominales. Debe ser un número flotante.
- quantity_units_id
  Código numérico de la unidad de medida del catálogo DIAN para base_unit_measure. Obligatorio para impuestos nominales. Debe ser un número entero.

`tax_totals` 🔴

Arreglo que contiene la suma de todos los impuestos del documento, agrupados por tipo de impuesto. Este campo es obligatorio solo cuando el documento tiene impuestos.

La estructura del objeto dentro de este arreglo varía según el tipo de tributo: porcentual (ej. IVA) o nominal/valor fijo por unidad (ej. Código 18, INC Bolsas - Código 22, INCarbono, INCombustibles).

Ejemplo completo (Porcentual + Nominal)

Reglas DIAN para impuestos nominales

La DIAN valida matemáticamente que tax_amount = per_unit_amount × base_unit_measure. Los campos percent y taxable_amount deben enviarse con valor 0 para impuestos nominales.

Regla a nivel de línea: FAX07 (Factura) / DEAX07 (Doc. Equivalente).
Regla a nivel global: FAS07 (Factura) / DEAS07 (Doc. Equivalente).

"tax_totals": [
    {
        "tax_id": "1",
        "tax_amount": 294.633000,
        "taxable_amount": 1550.700000,
        "percent": 19
    },
    {
        "tax_id": "18",
        "tax_amount": 387.675000,
        "per_unit_amount": 387.675000,
        "base_unit_measure": 1,
        "quantity_units_id": 70,
        "taxable_amount": 0,
        "percent": 0
    }
]

Cálculo entrada nominal: 387.675 × 1 = 387.675. La multiplicación debe ser matemáticamente exacta y consistente con la suma de los valores de línea para no detonar la regla de descuadre general.

Detalle de los campos
- tax_id
  - ID del impuesto. Este campo es obligatorio y debe ser un string.
  - Este campo agrupa todos los impuestos que tengan el mismo ID.
- tax_amount
  - Monto o valor total del impuesto. Este campo es obligatorio y debe ser un número flotante con máximo dos decimales.
  - Este campo agrupa la suma del monto o valor total de todos los impuestos que tengan el mismo ID.
  - Para impuestos nominales: resultado exacto de per_unit_amount × base_unit_measure.
- taxable_amount
  - Base gravable del impuesto. Este campo es obligatorio y debe ser un número flotante con máximo dos decimales.
  - Para impuestos porcentuales: valor sobre el que se aplica el porcentaje.
  - Para impuestos de valor fijo por unidad (códigos 21, 22, 23, 24, 18 y similares): debe enviarse como 0.
- percent
  - Porcentaje del impuesto. Este campo es obligatorio y debe ser un número.
  - Para impuestos porcentuales (ej: IVA - Código 01): valor del porcentaje (ej. 19).
  - Para impuestos de valor fijo por unidad (códigos 21, 22, 23, 24, 18 y similares): debe enviarse como 0.
- quantity_units_id
  - Código numérico de la unidad de medida base del catálogo DIAN sobre la cual se aplica la tarifa fija del tributo.
  - Obligatorio para impuestos de valor fijo por unidad (códigos 21, 22, 23, 24, 18 y similares).
  - Debe ser un número entero (ej. 886 para NIU - Unidad en INC Bolsas; 821 para la unidad de medida en el código 18).
- per_unit_amount
  - Tarifa o valor monetario fijo del tributo por cada unidad de medida física. Obligatorio para impuestos nominales (códigos 21, 22, 23, 24, 18 y similares).
  - Debe ser un número flotante con máximo dos decimales (ej. 39.16 para código 18; 70.00 para INC Bolsas 2025).
- base_unit_measure
  - Cantidad de unidades físicas sujetas al impuesto. Obligatorio para impuestos nominales (códigos 21, 22, 23, 24, 18 y similares).
  - Para INC Bolsas su valor es generalmente 1; para otros nominales corresponde al total de unidades físicas del ítem (ej. 9.90 para código 18).
  - Debe ser un número flotante.

`additional_document_reference` 🟡

Arreglo de objetos utilizado para referenciar documentos adicionales. Es OBLIGATORIO para Facturas de Contingencia (Tipo 03) para relacionar el documento físico entregado. Para otros documentos, es opcional y sirve para referenciar documentos comerciales (múltiples órdenes, contratos, etc).

🧾 Campos de la referencia

Campo	Tipo	Requerido	Descripción
`number`	string	Sí	Prefijo y Número del documento referenciado (ej. `"PAPEL-001"`)
`date`	string	⚠️ Condicional	Fecha de emisión del documento. Obligatorio para Tipo 03. Formato `YYYY-MM-DD`
`uuid`	string	⚠️ Condicional	CUFE/CUDE del documento referenciado. Obligatorio para referencias electrónicas. (No aplica para papel)
`code`	string	Opcional	Código interno de la empresa (ej. `"TALONARIO"`, `"OC"`)
`scheme_name`	string	Opcional	Algoritmo del UUID (ej. `"CUFE-SHA384"`)

🚨 Uso en Factura de Contingencia (Tipo 03)

Cuando expide una factura física por contingencia, luego debe transmitirla con type_document_id = 9. En este caso, informe los datos del papel y no envíe CUFE.

"additional_document_reference": [
  {
    "number": "TALONARIO-123",
    "date": "2025-02-10",
    "code": "TALONARIO"
  }
]

🏢 Uso para Referencias Comerciales

Sirve para referenciar múltiples órdenes de compra, contratos u otros documentos electrónicos.

"additional_document_reference": [
  {
    "number": "OC-2025-001",
    "uuid": "0bd41b047f40dbca91ab0cdebdb89f6a41b57aa821ca92be68f05a58acbad48f04f66301e2df014965d588734c4ee567",
    "scheme_name": "CUFE-SHA384",
    "date": "2025-01-15",
    "code": "OC"
  }
]

`additional_data` 🟢 NEW

Información que quieres ver impresa en el PDF del documento y que no viaja a la DIAN: centro de costo, datos del afiliado, orden de servicio, medios de pago internos.

¿Por qué existe esto?

El modelo de factura electrónica cubre lo que exige la DIAN. Todo lo demás —lo que tu operación necesita ver en el documento— no tiene sitio en ese modelo. Este campo lo resuelve: envías los datos en el JSON y la plantilla Preprinted los imprime sin que haya que modificarla. Las plantillas Classic, Minimal y Modern no imprimen este bloque (ver Cómo llega al PDF).

Los tres ámbitos de datos adicionales

Ámbito	Clave en el JSON	Para qué
Documento	`additional_data`	Centro de costo, afiliado, orden de servicio
Cliente	`customer.extra_data`	Nº de socio, categoría, fecha de vinculación
Línea	`lines[].extra_data`	Lote, fecha de vencimiento, serial

Ninguno de los tres se envía a la DIAN.

📦 Con secciones — Estructura recomendada

Cada sección es un bloque con título; la plantilla la pinta como tal.

"additional_data": [
  {
    "section": "INFORMACIÓN DEL CENTRO DE COSTO",
    "fields": [
      { "title": "Nombre del Centro de Costo", "value": "Sede Norte" },
      { "title": "Dirección y Teléfono", "value": "Av. Siempre Viva 742 - 601 123 4567" },
      { "title": "Ciudad", "value": "Bogotá D.C." }
    ]
  },
  {
    "section": "INFORMACIÓN DEL USUARIO",
    "fields": [
      { "title": "Afiliado Dependiente/Particular", "value": "Juan Pérez Gómez" },
      { "title": "Identificación", "value": "1098765432" }
    ]
  }
]

📋 Lista plana — Sin secciones

Si solo necesitas un par de campos sueltos, omite las secciones:

"additional_data": [
  { "title": "Orden de servicio", "value": "OS-2026-0042" },
  { "title": "Observación", "value": "Entrega en portería" }
]

Se guardan como una sección sin título.

No mezcles secciones y campos sueltos

La validación revisa cada elemento por separado: los que traen fields (o items) son secciones y los demás son campos sueltos, así que un arreglo que mezcla las dos formas no se rechaza. El PDF, en cambio, decide la forma de todo el arreglo por el primer elemento:

Si el primer elemento no trae fields y trae un value no nulo, todo el arreglo se lee como lista plana y las secciones se descartan sin aviso.
En cualquier otro caso, todo se lee como secciones y los campos sueltos se descartan.

Por eso, en una lista plana el primer campo debe llevar value no nulo (vale ""). Si el primero no trae value o lo trae en null, no se imprime nada del bloque.

📐 Estructura de campos

Sección:

Campo	Tipo	Requerido	Descripción
`section`	string	No	Título del bloque (alias: `title`). Omitido o `null` para campos sueltos. Máx. 120
`order`	int	No	Orden del bloque. Por defecto, el de llegada
`fields`	array	Sí	Campos del bloque (alias: `items`). Es lo que identifica a un elemento como sección: sin `fields` el elemento se trata como un campo suelto. Un arreglo vacío se acepta y no imprime nada

Campo:

Campo	Tipo	Requerido	Por defecto	Descripción
`title`	string	Sí	—	Etiqueta (alias: `label`). No puede ir vacía. Máx. 60
`value`	string o number	No	vacío	Valor a imprimir. Debe ser un dato simple: un arreglo u objeto se rechaza. `null` u omitido se imprime vacío. Máx. 500
`type`	string	No	`TEXT`	`TEXT`, `NUMBER`, `DATE`, `CURRENCY` (alias: `value_type`; acepta minúsculas)
`align`	string	No	`LEFT`	`LEFT`, `CENTER`, `RIGHT` (alias: `alignment`; acepta minúsculas)
`order`	int	No	orden de llegada	Orden dentro de la sección

El campo type le dice a la plantilla cómo formatear el valor, sin deducirlo del contenido:

{ "title": "Anticipos", "value": "150000", "type": "CURRENCY", "align": "RIGHT" }

Con 2 decimales configurados, se imprime como $ 150.000,00 alineado a la derecha. Envía el valor en crudo (150000), no preformateado.

Cómo imprime cada type la plantilla Preprinted:

`type`	Se imprime
`CURRENCY`	El símbolo de la moneda del documento (por defecto `$`), un espacio y el número con punto de miles, coma decimal y los decimales de totales configurados en la empresa
`NUMBER`	El número con punto de miles y sin decimales
`DATE`	El valor tal cual: no se le aplica formato de fecha
`TEXT`	El valor tal cual

CURRENCY y NUMBER solo dan formato si value es numérico. Si no lo es, se imprime tal cual. align fija la alineación del valor dentro de su celda.

⚠️ Validación y límites

Las peticiones que excedan estos límites se rechazan con HTTP 422, indicando qué campo lo provocó.

Regla	Límite
Elementos de primer nivel del arreglo (secciones o, en una lista plana, campos)	10
Campos por sección	20
Longitud de `title`	60
Longitud de `value`	500
Título de sección	120

El límite de 10 cuenta los elementos de primer nivel de additional_data, antes de distinguir secciones de campos. Una lista plana admite por tanto como máximo 10 campos, no 20, y el exceso se rechaza con El campo additional data admite como máximo 10 secciones.

Se rechaza con HTTP 422 (en POST /invoice, /notes/credit, /notes/debit, /ds/document, /ds/adjustment-note, POST /auto-increment/* y PATCH /auto-increment/*/{uuid}):

Entrada	Mensaje
`additional_data` no es un arreglo	Llegan dos mensajes: `El campo additional_data debe ser un arreglo de secciones o de campos` y `El campo additional data debe ser un arreglo de secciones o de campos.`
Más de 10 elementos	`El campo additional data admite como máximo 10 secciones.`
Un elemento no es un objeto (por ejemplo, un texto suelto)	`El elemento 2 de additional data debe ser un objeto.`
El título de la sección (`section` o `title`) no es texto	`El título de la sección 0 debe ser texto.`
Título de sección de más de 120 caracteres	`El título de la sección 0 supera los 120 caracteres.`
`fields` no es un arreglo	`Los campos de la sección 0 deben ser un arreglo.`
Más de 20 campos en una sección	`La sección 0 admite como máximo 20 campos.`
Un campo de la sección no es un objeto	`El campo 1 de la sección 0 debe ser un objeto.`
Campo sin `title` o con `title` vacío	`El campo 0.1 requiere un título.`
`title` de más de 60 caracteres	`El título del campo 0.1 supera los 60 caracteres.`
`value` es un arreglo u objeto	`El valor del campo 0.1 debe ser un dato simple.`
`value` de más de 500 caracteres	`El valor del campo 0.1 supera los 500 caracteres.`
`type` distinto de `TEXT`, `NUMBER`, `DATE`, `CURRENCY`	`El tipo del campo 0.1 debe ser uno de: TEXT, NUMBER, DATE, CURRENCY.`
`align` distinto de `LEFT`, `CENTER`, `RIGHT`	`La alineación del campo 0.1 debe ser una de: LEFT, CENTER, RIGHT.`

En los mensajes, el número que acompaña a «elemento» o «sección» es su índice dentro de additional_data, y 0.1 es la ruta del campo: sección 0, campo 1 (en una lista plana es solo el índice del campo). Todos los mensajes llegan en errors.additional_data, y la validación del bloque se detiene en el primer error que encuentra. El error llega con el formato estándar de validación:

{
  "message": "El tipo del campo 0.1 debe ser uno de: TEXT, NUMBER, DATE, CURRENCY.",
  "errors": {
    "additional_data": [
      "El tipo del campo 0.1 debe ser uno de: TEXT, NUMBER, DATE, CURRENCY."
    ]
  }
}

Casos tolerados (el documento se emite igual):

Entrada	Comportamiento
`additional_data` ausente, `null` o `[]`	No se imprime ningún bloque
Sección con `fields` vacío	Se acepta y no imprime nada
Campo sin `value` o con `value: null`	Se imprime la etiqueta con valor vacío. Excepción: en una lista plana, si es el primer campo no se imprime nada del bloque (ver Lista plana)
Arreglo que mezcla secciones y campos sueltos	Se acepta, pero el PDF solo imprime una de las dos formas, según el primer elemento
`type` o `align` en minúsculas (ej. `"currency"`, `"right"`)	Se aceptan

En el envío masivo el payload de cada documento no pasa por esta validación: allí un type o align no reconocido cae al valor por defecto (TEXT / LEFT), un campo sin title se omite y lo que excede los límites se recorta (secciones y campos de más, textos largos) en lugar de rechazarse.

Se rechaza, no se trunca

Un dato cortado a la mitad en una factura impresa es peor que un error al emitir. Si un valor supera el límite, la petición falla para que puedas corregirla antes de que el documento llegue a la DIAN.

🖨️ Cómo llega al PDF — Plantilla Preprinted

Solo la plantilla Preprinted imprime additional_data

Las plantillas Classic, Minimal y Modern no leen el bloque. La API lo acepta y lo valida igual en POST /invoice, /notes/credit, /notes/debit, /ds/document, /ds/adjustment-note, POST /auto-increment/* y PATCH /auto-increment/*/{uuid}, pero con esas plantillas no aparece en el PDF. La plantilla de la empresa se elige en Plantillas de la empresa.

Con Preprinted, una sección nueva aparece en el PDF sin que nadie toque la plantilla. La plantilla toma los datos del propio documento, así que se imprimen desde la primera emisión.

Secciones con sitio fijo. Preprinted reconoce dos secciones por su título, sin distinguir mayúsculas, acentos ni espacios, y las coloca en un sitio fijo del formato:

El título de la sección contiene	Dónde se pinta	Etiquetas que se imprimen
"centro de costo" o "centro costo"	Recuadro superior izquierdo	El `title` de cada campo. Si envías menos de tres campos, los renglones que faltan se rotulan `Nombre del Centro de Costo`, `Dirección y Teléfono` y `Ciudad`
"del usuario" o "afiliado"	Bloque INFORMACIÓN DEL USUARIO	Fijas: `Afiliado Dependiente/Particular`, `Identificación` y `Descripción`. El `title` que envíes se ignora

Ambos bloques imprimen los campos por posición y solo los 3 primeros: del 4.º en adelante no se imprimen.
Solo se usa la primera sección que coincide. Las demás secciones cuyo título también coincide no se imprimen, porque se excluyen del recorrido general.

El resto de secciones se pinta en el orden en que llegan (o el que fijes con order), dentro del cuerpo del documento: después de INFORMACIÓN DEL CLIENTE y del bloque del usuario, y antes del documento de referencia (en las notas) y del detalle de líneas. Cada sección es una tabla con su título como franja (si la sección no tiene título, no lleva franja) y dos campos por renglón, con la forma Etiqueta: valor.

Campo Anticipos. Si un campo de additional_data se titula Anticipos (sin distinguir mayúsculas ni acentos), Preprinted muestra además su valor en la fila ANTICIPOS de los totales. Esa fila es informativa: el TOTAL A PAGAR sigue siendo el total del documento.

Ejemplo Mínimo Requerido

Este es un ejemplo con SOLO los campos obligatorios para generar una factura simple (tipo 1):

{
  "resolution_number": "18760000001",
  "prefix": "FEV",
  "document_number": 990000001,
  "operation_type_id": 1,
  "type_document_id": 1,
  "customer": {
    "country_id": "45",
    "city_id": "836",
    "identity_document_id": "1",
    "type_organization_id": 2,
    "tax_regime_id": 2,
    "tax_level_id": 5,
    "company_name": "NOMBRE DEL CLIENTE",
    "dni": "1234564",
    "email": "correo@cliente.com"
  },
  "payments": [
    {
      "payment_method_id": 1,
      "means_payment_id": 10,
      "value_paid": "141100.00"
    }
  ],
  "legal_monetary_totals": {
    "line_extension_amount": "131600.00",
    "tax_exclusive_amount": "131600.00",
    "tax_inclusive_amount": "141100.00",
    "payable_amount": "141100.00"
  },
  "lines": [
    {
      "invoiced_quantity": "1",
      "quantity_units_id": "1093",
      "line_extension_amount": "131600.00",
      "description": "Producto ejemplo",
      "price_amount": "131600.00"
    }
  ],
  "tax_totals": [
    {
      "tax_id": "01",
      "tax_amount": 9500,
      "taxable_amount": 131600,
      "percent": 19
    }
  ]
}

📊 Notas importantes sobre este ejemplo:

✅ Todos los campos 🔴 Obligatorios están presentes

✅ Campos 🟢 Opcionales se omitieron para simplicidad

✅ Puede extenderse con campos adicionales según necesidad

⚠️ Para contingencia (tipo 03), debe agregar additional_document_reference

⚠️ Para POS (tipo 9), debe agregar point_of_sale

🎯 Próximos Pasos

📄

Factura Simple
Ejemplo práctico paso a paso

🌎

Exportaciones
Facturas internacionales

🔌

Endpoints API
Referencia completa de endpoints

⚠️

Errores Comunes
Troubleshooting

📅 Última actualización: Febrero 2026 • 📖 Tipo: Referencia Técnica Completa • 🎯 Nivel: ⭐⭐⭐ Avanzado

🎯 Referencia Rápida de Tipos de Documento
✅ Compatibilidad de Campos por Tipo
🔧 Referencia de Campos
Ejemplo Mínimo Requerido
🎯 Próximos Pasos

🎯 Referencia Rápida de Tipos de Documento​

⚠️ IMPORTANTE: IDs del API vs Códigos DIAN

✅ Compatibilidad de Campos por Tipo​

🔧 Referencia de Campos​

resolution_number 🔴​

prefix 🟡​

date 🟢​

expiration_date 🟢​

time 🟢​

notes 🟢​

document_number 🔴​

uuid 🟢 NEW​

Ejemplo​

operation_type_id 🔴​

Ejemplo​

type_document_id 🔴​

Ejemplo​

graphic_representation 🟢​

Ejemplo​

send_email 🟢​

Ejemplo​

currency_id 🟢​

Ejemplo​

send_to_queue 🟢​

rounding 🟢​

attachments: NEW​

invoice_period 🟢​

Ejemplo​

Detalle de los campos​

start_date​

start_time​

end_date​

end_time​

deliveries: NEW​

delivery_terms 🟢​

Ejemplo​

Detalle de los campos​

delivery_id​

terms​

despatch_document_references 🟢​

Ejemplo​

Detalle de los campos​

number​

date​

receipt_document_references 🟢​

Ejemplo​

Detalle de los campos​

number​

date​

showroomInformation 🟢​

Ejemplo​

prepaid_payments 🟢​

Ejemplo​

Detalle de los campos​

id​

paid_amount​

received_date​

paid_date​

instruction_id​

payments 🔴​

Ejemplo​

Detalle de los campos​

payment_method_id​

means_payment_id​

value_paid​

payment_due_date​

duration_measure​

report_header: NEW​

due_diligence: NEW​

Ejemplo​

Tabla debida diligencia - Control cambiario​

document_signature: NEW​

Ejemplo​

Detalle de los campos​

cashier​

cashier_title​

seller​

seller_title​

payment_exchange_rate 🟡​

Ejemplo​

🎯 Referencia Rápida de Tipos de Documento

✅ Compatibilidad de Campos por Tipo

🔧 Referencia de Campos

`resolution_number` 🔴

`prefix` 🟡

`date` 🟢

`expiration_date` 🟢

`time` 🟢

`notes` 🟢

`document_number` 🔴

`uuid` 🟢 NEW

Ejemplo

`operation_type_id` 🔴

Ejemplo

`type_document_id` 🔴

Ejemplo

`graphic_representation` 🟢

Ejemplo

`send_email` 🟢

Ejemplo

`currency_id` 🟢

Ejemplo

`send_to_queue` 🟢

`rounding` 🟢

`attachments`: NEW

`invoice_period` 🟢

Ejemplo

Detalle de los campos

`start_date`

`start_time`

`end_date`

`end_time`

`deliveries`: NEW

`delivery_terms` 🟢

Ejemplo

Detalle de los campos

`delivery_id`

`terms`

`despatch_document_references` 🟢

Ejemplo

Detalle de los campos

`number`

`date`

`receipt_document_references` 🟢

Ejemplo

Detalle de los campos

`number`

`date`

`showroomInformation` 🟢

Ejemplo

`prepaid_payments` 🟢

Ejemplo

Detalle de los campos

`id`

`paid_amount`

`received_date`

`paid_date`

`instruction_id`

`payments` 🔴

Ejemplo

Detalle de los campos

`payment_method_id`

`means_payment_id`

`value_paid`

`payment_due_date`

`duration_measure`

`report_header`: NEW

`due_diligence`: NEW

Ejemplo

Tabla debida diligencia - Control cambiario

`document_signature`: NEW

Ejemplo

Detalle de los campos

`cashier`

`cashier_title`

`seller`

`seller_title`

`payment_exchange_rate` 🟡

Ejemplo

Detalle de los campos