# Objetos

> Todos los objetos de la API de Trevol con sus campos, tipos y cuáles son obligatorios.

Fuente: https://platform.trevol.si/docs/api/objetos

Cada objeto de la API, con sus campos. Los campos obligatorios llevan «sí». Los tipos enlazan a su objeto.

### Acquirer

El adquiriente como lo tiene la DIAN (y su correo, si lo conoce).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `acquirer` |  |  |
| `document_type` | texto |  |  |
| `document_number` | texto |  |  |
| `found` | booleano |  |  |
| `name` | texto (puede ser null) |  |  |
| `email` | texto (puede ser null) |  |  |

### AirCollection

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | texto | sí |  |
| `data` | lista de [InteroperabilityData](/docs/api/objetos#InteroperabilityData) | sí | Máximo 50. |

### AirExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `group` | texto |  |  |
| `collections` | lista de [AirCollection](/docs/api/objetos#AirCollection) | sí | Máximo 50. |
| `passengers` | lista de [AirCollection](/docs/api/objetos#AirCollection) | sí | Máximo 50. |

### AllowanceCharge

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | `discount` \| `charge` | sí |  |
| `code` | texto |  | Código (texto). |
| `reason` | texto |  |  |
| `percent` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `amount` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `base` | decimal |  | Número o texto decimal con punto («150000.50»). |

### AlternativeCurrency

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Una tercera moneda (ni la de la factura ni COP). |
| `exchange_rate` | decimal | sí | Unidades de esa moneda por 1 unidad de la moneda de la factura. |
| `rate_date` | fecha (AAAA-MM-DD) | sí |  |

### Balance

El saldo prepago de Trevol. Es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (`shared: true`) y cualquier llave de cualquiera de ellas, de lectura o de escritura, `test` o `live`, ve el mismo. Solo lo que se emite en producción (llaves `live`) lo consume; la habilitación (`test`) no cobra. `available` es lo que se puede gastar (en pesos); `held`, lo apartado por documentos que la DIAN todavía valida; `overdraft`, cuánto puede bajar `available` de cero al apartar un documento; `low_threshold`, el umbral del aviso de saldo bajo (el 20 % de la última recarga; `null` sin recargas). `level`: `empty` con `available` ≤ 0, `low` por debajo de `low_threshold`, si no `ok`. Con `available` por debajo del precio de un documento, emitir en producción responde 402 `insufficient_balance`. El evento `balance.low` avisa por webhook.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `balance` | sí |  |
| `currency` | `COP` | sí |  |
| `available` | entero | sí | Lo que se puede gastar, en pesos (puede ser negativo). |
| `held` | entero | sí | Apartado por documentos que la DIAN todavía valida. |
| `overdraft` | entero | sí | Cuánto puede bajar `available` de cero al apartar un documento. |
| `low_threshold` | entero (puede ser null) | sí | El umbral del aviso de saldo bajo; null sin recargas. |
| `level` | `ok` \| `low` \| `empty` | sí |  |
| `updated_at` | fecha y hora (puede ser null) | sí | Cuándo cambió el saldo por última vez; null si nunca tuvo. |
| `shared` | `true` | sí | Siempre true: el saldo es de la cuenta y lo comparten todas sus empresas. |

### BalanceEventData

`balance.low` (solo producción): el saldo de la cuenta quedó bajo o se agotó. Lleva solo el nivel: el saldo es de la cuenta y lo comparten todas sus empresas.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `balance` |  |  |
| `level` | `low` \| `depleted` |  |  |

### BalanceTransaction

Un movimiento del saldo de la cuenta (un documento es una sola fila).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto | sí | Úsalo en `starting_after` para pedir la página siguiente. |
| `object` | `balance_transaction` | sí |  |
| `type` | `document` \| `top_up` \| `bonus` \| `adjustment` \| `top_up_reversal` \| `license_fee` \| `expiration` \| `other` | sí |  |
| `status` | `charged` \| `pending` \| `released` \| `completed` | sí | De un documento: pending, charged o released. Lo demás: completed. |
| `amount` | entero | sí | Lo que hizo con el disponible, en pesos y con signo (released: 0). |
| `available_after` | entero (puede ser null) | sí | El disponible justo después. |
| `description` | texto | sí | En español, como en la app. |
| `document` | objeto (puede ser null) | sí | Solo en `type: document`. |
| `company` | objeto (puede ser null) | sí | La empresa de la cuenta que emitió el documento. |
| `reference` | texto (puede ser null) |  | La referencia TRV-REC-… de una recarga o de su reverso. |
| `created_at` | fecha y hora | sí |  |

### Carrier

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `document_type` | texto |  | Tipo de documento del transportador (tabla 13.2.1). |
| `document_number` | texto |  | Sin DV ni puntos; el DV lo calcula Trevol. |
| `name` | texto |  |  |
| `tax_responsibilities` | lista de texto |  | Tabla 13.2.6.1 (O-13, O-15, O-23, O-47, R-99-PN). Máximo 20. |
| `email` | texto |  |  |
| `phone` | texto |  |  |
| `address` | [ForeignAddress](/docs/api/objetos#ForeignAddress) |  |  |

### CertificateEventData

`certificate.expiring` (los dos ambientes): el certificado de firma vence en 30, 15, 7 y 1 día.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `certificate` |  |  |
| `expires_on` | fecha (AAAA-MM-DD) |  |  |
| `days_left` | entero |  |  |

### CinemaExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `address` | texto | sí |  |
| `cinema_room` | texto |  |  |
| `screenings` | lista de [CinemaScreening](/docs/api/objetos#CinemaScreening) | sí | Máximo 50. |

### CinemaScreening

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `room` | texto | sí |  |
| `seats` | texto | sí |  |
| `screening` | texto | sí |  |
| `location` | texto |  |  |
| `date` | fecha (AAAA-MM-DD) |  |  |
| `time` | texto |  |  |

### Company

La empresa de la llave, su ambiente y sus numeraciones activas.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `company` |  |  |
| `id` | texto |  |  |
| `nit` | texto (puede ser null) |  |  |
| `check_digit` | entero (puede ser null) |  |  |
| `name` | texto (puede ser null) |  | La razón social. |
| `trade_name` | texto (puede ser null) |  |  |
| `status` | `enabled` \| `not_enabled` |  |  |
| `environment` | `test` \| `live` \| `null` (puede ser null) |  |  |
| `numbering` | lista de objeto |  | Las numeraciones (resoluciones) activas del ambiente de la llave. |
| `key` | objeto |  | La llave con que se llamó. |
| `capabilities` | objeto libre |  | Lo que ESTA llave puede emitir ahora (documento soporte, equivalente, nómina, eventos RADIAN). Informativo: si una lectura falla, esa clave no aparece. |

### Consumption

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `subtotal` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `discounts` | lista de [ConsumptionAdjustment](/docs/api/objetos#ConsumptionAdjustment) |  | Máximo 50. |
| `charges` | lista de [ConsumptionAdjustment](/docs/api/objetos#ConsumptionAdjustment) |  | Máximo 50. |
| `meter` | [Meter](/docs/api/objetos#Meter) |  |  |

### ConsumptionAdjustment

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `reason` | texto | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### Contingency

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `physical_document` | [PhysicalDocument](/docs/api/objetos#PhysicalDocument) |  |  |

### Currency

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Moneda (tabla 13.3.3, ISO 4217), distinta de COP. |
| `exchange_rate` | decimal | sí | TRM o tasa pactada: pesos por 1 unidad de la moneda (hasta 6 decimales). |
| `rate_date` | fecha (AAAA-MM-DD) | sí | El día de la tasa; no puede ser posterior a la factura. |
| `alternative` | [SupportCurrency](/docs/api/objetos#SupportCurrency) |  |  |

### Customer

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `final_consumer` | booleano |  |  |
| `document_type` | texto |  | Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA… |
| `document_number` | texto |  | Sin DV ni puntos; el DV lo calcula Trevol. |
| `check_digit` | entero |  | Opcional: si viene, tiene que ser el DV del NIT. |
| `name` | texto |  |  |
| `person_type` | `legal` \| `natural` |  | Por defecto se deduce del NIT. |
| `email` | texto |  |  |
| `phone` | texto |  |  |
| `address` | texto |  |  |
| `city` | texto |  |  |
| `municipality_code` | texto |  | Código DANE del municipio (5 dígitos). |
| `department_code` | texto |  |  |
| `tax_responsibilities` | lista de texto |  | Tabla 13.2.6.1 (O-13, O-15, O-23, O-47, R-99-PN). Máximo 20. |
| `tax_scheme` | texto |  | TaxScheme del adquiriente: 01, 04, ZA o ZZ (por defecto ZZ). |
| `country` | texto |  | País del cliente (tabla 13.4.1, ISO 3166-1 alfa-2). Distinto de "CO": cliente en el exterior, sin `municipality_code`; con `city`, `region` y `postal_code`. Solo en facturas. |
| `region` | texto |  | Departamento, estado o provincia del cliente en el exterior. Solo en facturas. |
| `region_code` | texto |  | Código de la región del cliente en el exterior (máximo 6). Solo en facturas. |
| `postal_code` | texto |  | Código postal del cliente en el exterior (máximo 10). Solo en facturas. |

### DeletedObject

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto | sí |  |
| `object` | texto | sí |  |
| `deleted` | `true` | sí |  |

### Delivery

Con la versión 2026-10-22, el PDF, el ZIP y el correo se hacen en segundo plano después del 201: casi siempre llegan `pending` y se completan en segundos (GET o el evento `….delivered`). Si pides …/pdf o …/zip antes, se generan al momento. Con la 2026-10-21 se hacen antes del 201, como en la fase 1.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `status` | `pending` \| `completed` \| `null` (puede ser null) |  | null si el documento no está `accepted`; `completed` con PDF, ZIP y un correo en estado final (sent, skipped, failed, bounced o complained). |
| `pdf` | booleano |  |  |
| `zip` | booleano |  |  |
| `xml` | booleano |  |  |
| `email` | objeto (puede ser null) |  |  |

### DeliveryTerms

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `incoterm` | texto |  |  |
| `conditions` | texto |  |  |

### Document

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | inv_… \| cn_… \| dn_… |
| `object` | `invoice` \| `credit_note` \| `debit_note` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `contingency` \| `processing` |  | `processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `cufe` | texto (puede ser null) |  |  |
| `cude` | texto (puede ser null) |  |  |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `customer` | [Customer](/docs/api/objetos#Customer) |  |  |
| `items` | lista de [Item](/docs/api/objetos#Item) |  |  |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `invoice` | [InvoiceReference](/docs/api/objetos#InvoiceReference) |  |  |
| `document_type` | texto |  | Tipo de factura (tabla 13.1.3): 01 venta, 02 exportación. |
| `operation_type` | texto |  | Tipo de operación (tabla 13.1.5.1). |
| `currency` | [Currency](/docs/api/objetos#Currency) |  |  |
| `cop_totals` | booleano |  |  |
| `delivery_terms` | [DeliveryTerms](/docs/api/objetos#DeliveryTerms) |  |  |
| `shipment` | [Shipment](/docs/api/objetos#Shipment) |  |  |
| `due_diligence` | texto |  | Debida diligencia (tabla 18.3). |
| `interoperability` | [Interoperability](/docs/api/objetos#Interoperability) |  |  |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente. |
| `dian` | objeto |  |  |
| `delivery` | [Delivery](/docs/api/objetos#Delivery) |  |  |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |

### DocumentEventData

Resumen de un documento. Pide el documento completo con GET /v1/{invoices|credit_notes|debit_notes}/{id}.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `invoice` \| `credit_note` \| `debit_note` | sí |  |
| `id` | texto | sí | inv_… \| cn_… \| dn_… (el mismo de la respuesta de la API). |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `contingency` | sí | Nunca `processing`: ese estado solo existe en las respuestas de la API. |
| `environment` | `test` \| `live` | sí |  |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  | Tu identificador, solo en los documentos creados por la API. |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `cufe` | texto (puede ser null) |  | En las facturas. |
| `cude` | texto (puede ser null) |  | En las notas crédito y débito. |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `total` | texto (puede ser null) |  | Texto decimal con dos decimales. |
| `invoice` | objeto (puede ser null) |  | En las notas: la factura de Trevol que corrigen. |
| `dian` | objeto | sí |  |
| `delivery` | objeto | sí |  |
| `error` | objeto |  | Solo en `….error`. El texto es fijo por código: nunca el mensaje de la DIAN. |

### DocumentReference

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  |  |
| `date` | fecha (AAAA-MM-DD) |  |  |

### EquivalentAdjustmentItem

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `description` | texto | sí |  |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `unit_price` | decimal | sí | Precio unitario SIN impuestos. |
| `taxes` | lista de [ItemTax](/docs/api/objetos#ItemTax) |  | Impuestos de la línea: {code, rate} porcentual, {code: "01", excluded: true} o nominal {code, unit_amount, unit?, quantity?}. Máximo 12. |
| `discounts` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Máximo 10. |
| `charges` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Máximo 10. |
| `free_of_charge` | [FreeOfCharge](/docs/api/objetos#FreeOfCharge) |  |  |
| `standard_code` | [StandardCode](/docs/api/objetos#StandardCode) |  |  |
| `brand` | texto |  |  |
| `model` | texto |  |  |
| `income` | `own` \| `collected` \| `third_party` |  | Mandatos (tabla 16.16): "own" (por defecto), "collected" o "third_party". |
| `mandator` | [ItemMandator](/docs/api/objetos#ItemMandator) |  |  |

### EquivalentDocument

Un documento equivalente electrónico (tiquete POS 20 y los demás tipos de la tabla 16.3). Se expide como la factura: archivos `pdf`, `xml`, `zip` y `dian_response`.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | pos_… (todos los tipos de documento equivalente) |
| `object` | `equivalent_document` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `contingency` \| `processing` \| `validating` |  | `processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. `validating`: el set de pruebas de la DIAN (habilitación) recibió el documento y todavía lo valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía). |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `cude` | texto (puede ser null) |  | El código único del documento (CUDE, 96 hex). |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `customer` | [Customer](/docs/api/objetos#Customer) |  |  |
| `items` | lista de [EquivalentItem](/docs/api/objetos#EquivalentItem) |  |  |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `document_type` | `20` \| `25` \| `27` \| `30` \| `35` \| `40` \| `45` \| `50` \| `55` \| `60` |  | Tipo de documento equivalente (tabla 16.3). |
| `operation_type` | texto |  | Tipo de operación (CustomizationID, tabla 16.4.1). |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente. |
| `dian` | objeto |  |  |
| `delivery` | [Delivery](/docs/api/objetos#Delivery) |  |  |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |
| `notes` | lista de texto |  |  |
| `period` | [Period](/docs/api/objetos#Period) |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  |  |
| `prepayments` | lista de [Prepayment](/docs/api/objetos#Prepayment) |  |  |
| `rounding` | booleano o decimal |  |  |
| `withholdings` | lista de [Withholding](/docs/api/objetos#Withholding) |  |  |
| `pos` | [Pos](/docs/api/objetos#Pos) |  |  |
| `extension` | [Extension](/docs/api/objetos#Extension) |  |  |
| `origin_note` | [OriginNote](/docs/api/objetos#OriginNote) |  |  |
| `contingency` | objeto (puede ser null) |  |  |

### EquivalentDocumentAdjustment

Una nota de ajuste de un documento equivalente (crédito 94 o débito 93). Se expide como la factura: archivos `pdf`, `xml`, `zip` y `dian_response`.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | posa_… |
| `object` | `equivalent_document_adjustment` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `contingency` \| `processing` \| `validating` |  | `processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. `validating`: el set de pruebas de la DIAN (habilitación) recibió el documento y todavía lo valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía). |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `cude` | texto (puede ser null) |  | El código único del documento (CUDE, 96 hex). |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `customer` | [Customer](/docs/api/objetos#Customer) |  |  |
| `items` | lista de [EquivalentAdjustmentItem](/docs/api/objetos#EquivalentAdjustmentItem) |  |  |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente. |
| `dian` | objeto |  |  |
| `delivery` | [Delivery](/docs/api/objetos#Delivery) |  |  |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |
| `notes` | lista de texto |  |  |
| `period` | [Period](/docs/api/objetos#Period) |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  |  |
| `prepayments` | lista de [Prepayment](/docs/api/objetos#Prepayment) |  |  |
| `rounding` | booleano o decimal |  |  |
| `note_type` | `credit` \| `debit` |  |  |
| `concept` | texto |  | Concepto de la nota (tabla 16.6): 1 a 5. |
| `description` | texto |  |  |
| `equivalent_document` | [EquivalentDocumentReference](/docs/api/objetos#EquivalentDocumentReference) |  |  |

### EquivalentDocumentAdjustmentInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. |
| `customer` | [Customer](/docs/api/objetos#Customer) |  | Opcional con `equivalent_document.id`: se toma el adquirente del documento (si viene, tiene que ser el mismo). |
| `items` | lista de [EquivalentAdjustmentItem](/docs/api/objetos#EquivalentAdjustmentItem) | sí | Las líneas (1 a 500). Máximo 500. |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `period` | [Period](/docs/api/objetos#Period) |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  | Descuentos y recargos globales (no tocan las bases). Máximo 20. |
| `prepayments` | lista de [Prepayment](/docs/api/objetos#Prepayment) |  | Anticipos (informativos: no restan del total). Máximo 20. |
| `rounding` | booleano o decimal |  | true = redondeo al peso; o un valor entre -2.00 y 2.00. |
| `note_type` | `credit` \| `debit` | sí | "credit" (nota de ajuste crédito, 94) o "debit" (débito, 93). |
| `concept` | texto | sí | Concepto de la nota (tabla 16.6): "1" devolución parcial, "2" anulación del documento (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros. |
| `description` | texto |  | Opcional (20 a 5000 caracteres). Sin ella, Trevol pone el texto de la tabla (el EXACTO en la nota débito: NADBF04). |
| `equivalent_document` | [EquivalentDocumentReference](/docs/api/objetos#EquivalentDocumentReference) | sí | El documento que ajusta: {"id": "pos_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cude, issue_date, document_type, total?} si es de otra plataforma (`total` hace falta para anularlo). |

### EquivalentDocumentEventData

Resumen de un documento equivalente electrónico o de su nota de ajuste (nunca datos del comprador ni líneas). Pide el documento completo con GET /v1/{equivalent_documents|equivalent_document_adjustments}/{id}.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `contingency` | sí | Nunca `processing`: ese estado solo existe en las respuestas de la API. |
| `environment` | `test` \| `live` | sí |  |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  | Tu identificador, solo en los documentos creados por la API. |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `total` | texto (puede ser null) |  | Texto decimal con dos decimales. |
| `dian` | objeto | sí |  |
| `error` | objeto |  | Solo en `….error`. El texto es fijo por código: nunca el mensaje de la DIAN. |
| `object` | `equivalent_document` \| `equivalent_document_adjustment` | sí |  |
| `id` | texto | sí | pos_… \| posa_… |
| `cude` | texto (puede ser null) |  | Código único del documento. |
| `document_type` | texto |  | El tipo de documento equivalente (20 POS, 25, 27, 30…). Solo en `equivalent_document`. |
| `equivalent_document` | objeto |  | En la nota de ajuste: el documento equivalente que ajusta. |
| `delivery` | objeto | sí |  |

### EquivalentDocumentInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. |
| `customer` | [Customer](/docs/api/objetos#Customer) |  | El adquirente. Para consumidor final: {"final_consumer": true}. La relación de juegos (30) no lleva `customer`: el adquirente es la DIAN. |
| `items` | lista de [EquivalentItem](/docs/api/objetos#EquivalentItem) | sí | Las líneas (1 a 500). Retenciones solo como autorretenciones del emisor (`self_withholding: true`). Máximo 500. |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `period` | [Period](/docs/api/objetos#Period) |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  | Descuentos y recargos globales (no tocan las bases). Máximo 20. |
| `prepayments` | lista de [Prepayment](/docs/api/objetos#Prepayment) |  | Anticipos (informativos: no restan del total). Máximo 20. |
| `withholdings` | lista de [Withholding](/docs/api/objetos#Withholding) |  | Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10. |
| `rounding` | booleano o decimal |  | true = redondeo al peso; o un valor entre -2.00 y 2.00. |
| `document_type` | texto |  | Tipo de documento equivalente (tabla 16.3): "20" tiquete POS (por defecto), "25" boleta de cine, "27" espectáculos públicos, "30" juegos localizados y no localizados (se acepta "32"), "35" transporte de pasajeros, "40" peajes, "45" extracto, "50" tiquete aéreo, "55" bolsa de valores o "60" servicios públicos. |
| `operation_type` | texto |  | Tipo de operación (CustomizationID, tabla 16.4.1) del tipo de documento. Por defecto, el primero del tipo ("10" en el POS). |
| `pos` | [Pos](/docs/api/objetos#Pos) |  | Obligatorio en el tiquete POS (20) y prohibido en los demás: la caja que expide el tiquete y, opcional, los beneficios del comprador. |
| `extension` | [Extension](/docs/api/objetos#Extension) |  | La información propia del tipo, con UNA clave, la de su `document_type`: `cinema` (25), `show` (27), `games` (30), `transport` (35), `air` (50), `stock_exchange` (55) o `public_services` (60). Prohibida en el POS (20), peajes (40) y extracto (45). |
| `prefix` | texto |  | Solo en los tipos sin resolución (todos menos el POS): el prefijo del consecutivo propio (1 a 4 letras o dígitos). Por defecto, el del tipo (DEC, DEEP, DEJL, DETT, DEP, EXT, DETA, DEBV, SPD). |
| `origin_note` | [OriginNote](/docs/api/objetos#OriginNote) |  | La nota de ajuste que dio origen a este documento (opcional). |
| `contingency` | [Contingency](/docs/api/objetos#Contingency) |  | Solo la contingencia 07 (el emisor transcribe un documento físico): `physical_document` con number, date y type. La 08 (la DIAN no contestó) no se pide: la decide Trevol y el documento responde `202` con `status: contingency`. |
| `numbering` | [Numbering](/docs/api/objetos#Numbering) |  | Solo en el POS: el prefijo de la resolución POS que numera (una empresa con varias cajas o establecimientos tiene varias). Sin él, la más nueva vigente. Si no existe, `numbering_unavailable` (`no_resolution`). |

### EquivalentDocumentReference

Uno de: objeto, objeto.

### EquivalentItem

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `description` | texto | sí |  |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `unit_price` | decimal | sí | Precio unitario SIN impuestos. |
| `taxes` | lista de [ItemTax](/docs/api/objetos#ItemTax) |  | Impuestos de la línea: {code, rate} porcentual, {code: "01", excluded: true} o nominal {code, unit_amount, unit?, quantity?}. Máximo 12. |
| `discounts` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Máximo 10. |
| `charges` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Máximo 10. |
| `withholdings` | lista de [ItemWithholding](/docs/api/objetos#ItemWithholding) |  | Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10. |
| `free_of_charge` | [FreeOfCharge](/docs/api/objetos#FreeOfCharge) |  |  |
| `standard_code` | [StandardCode](/docs/api/objetos#StandardCode) |  |  |
| `brand` | texto |  |  |
| `model` | texto |  |  |
| `income` | `own` \| `collected` \| `third_party` |  | Mandatos (tabla 16.16): "own" (por defecto), "collected" (ingreso recaudado para terceros) o "third_party" (facturado para terceros); los dos últimos con `mandator`. En 272 y 274 la línea del mandante va con "collected". |
| `mandator` | [ItemMandator](/docs/api/objetos#ItemMandator) |  | El mandante de un ingreso para terceros (con NIT en 272 y 274). |

### Event

Exactamente lo que se manda al endpoint (los bytes firmados) y lo que devuelve GET /v1/events. El mismo `id` (también en la cabecera `webhook-id`) llega en cada reintento y en un reenvío manual: úsalo para no procesar dos veces el mismo evento.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto | sí |  |
| `object` | `event` | sí |  |
| `type` | `invoice.accepted` \| `invoice.rejected` \| `invoice.error` \| `invoice.delivered` \| `invoice.email_bounced` \| `invoice.email_failed` \| `credit_note.accepted` \| `credit_note.rejected` \| `credit_note.error` \| `credit_note.delivered` \| `credit_note.email_bounced` \| `credit_note.email_failed` \| `debit_note.accepted` \| `debit_note.rejected` \| `debit_note.error` \| `debit_note.delivered` \| `debit_note.email_bounced` \| `debit_note.email_failed` \| `balance.low` \| `numbering.low` \| `numbering.expiring` \| `certificate.expiring` \| `support_document.accepted` \| `support_document.rejected` \| `support_document.error` \| `support_document_adjustment.accepted` \| `support_document_adjustment.rejected` \| `support_document_adjustment.error` \| `equivalent_document.accepted` \| `equivalent_document.rejected` \| `equivalent_document.error` \| `equivalent_document.delivered` \| `equivalent_document.email_bounced` \| `equivalent_document.email_failed` \| `equivalent_document_adjustment.accepted` \| `equivalent_document_adjustment.rejected` \| `equivalent_document_adjustment.error` \| `equivalent_document_adjustment.delivered` \| `equivalent_document_adjustment.email_bounced` \| `equivalent_document_adjustment.email_failed` \| `payroll.accepted` \| `payroll.rejected` \| `payroll.error` \| `payroll_adjustment.accepted` \| `payroll_adjustment.rejected` \| `payroll_adjustment.error` \| `radian_event.accepted` \| `radian_event.rejected` \| `radian_event.error` \| `webhook.test` | sí |  |
| `timestamp` | fecha y hora | sí | UTC. |
| `environment` | `test` \| `live` | sí |  |
| `api_version` | texto | sí | La versión vigente más nueva de la API; el resumen del documento no cambia con la versión de la llave. |
| `data` | uno de: [DocumentEventData](/docs/api/objetos#DocumentEventData), [SupportDocumentEventData](/docs/api/objetos#SupportDocumentEventData), [EquivalentDocumentEventData](/docs/api/objetos#EquivalentDocumentEventData), [PayrollEventData](/docs/api/objetos#PayrollEventData), [RadianEventData](/docs/api/objetos#RadianEventData), [BalanceEventData](/docs/api/objetos#BalanceEventData), [NumberingLowEventData](/docs/api/objetos#NumberingLowEventData), [NumberingExpiringEventData](/docs/api/objetos#NumberingExpiringEventData), [CertificateEventData](/docs/api/objetos#CertificateEventData), [TestEventData](/docs/api/objetos#TestEventData) | sí |  |

### EventClaim

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `note` | texto |  |  |

### Extension

La información propia del tipo de documento equivalente: UNA clave, la de su `document_type` (cinema 25, show 27, games 30, transport 35, air 50, stock_exchange 55, public_services 60).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `cinema` | [CinemaExtension](/docs/api/objetos#CinemaExtension) |  |  |
| `show` | [ShowExtension](/docs/api/objetos#ShowExtension) |  |  |
| `games` | [GamesExtension](/docs/api/objetos#GamesExtension) |  |  |
| `transport` | [TransportExtension](/docs/api/objetos#TransportExtension) |  |  |
| `air` | [AirExtension](/docs/api/objetos#AirExtension) |  |  |
| `stock_exchange` | [StockExchangeExtension](/docs/api/objetos#StockExchangeExtension) |  |  |
| `public_services` | [PublicServicesExtension](/docs/api/objetos#PublicServicesExtension) |  |  |

### ForeignAddress

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `country` | texto |  | País (tabla 13.4.1). Sin `country`: Colombia. |
| `city` | texto |  | Obligatoria fuera de Colombia. |
| `region` | texto |  |  |
| `region_code` | texto |  |  |
| `postal_code` | texto |  |  |
| `municipality_code` | texto |  | Solo en Colombia (DANE, 5 dígitos). |
| `street` | texto |  | Calle y número. |

### FreeOfCharge

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `reference_price` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `price_type` | texto |  |  |

### Game

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | texto | sí |  |
| `total` | entero | sí |  |

### GameCredit

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `serial` | texto | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### GamesExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `venue` | [GamesVenue](/docs/api/objetos#GamesVenue) | sí |  |
| `games` | lista de [Game](/docs/api/objetos#Game) | sí | Máximo 2. |
| `credits` | lista de [GameCredit](/docs/api/objetos#GameCredit) |  | Máximo 500. |

### GamesVenue

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `address` | texto | sí |  |
| `deposit` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### Interoperability

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `group` | texto | sí |  |
| `collections` | lista de [AirCollection](/docs/api/objetos#AirCollection) | sí | Máximo 10. |

### InteroperabilityCollection

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | texto | sí |  |
| `data` | lista de [InteroperabilityData](/docs/api/objetos#InteroperabilityData) | sí | Máximo 50. |

### InteroperabilityData

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | texto | sí |  |
| `value` | texto |  |  |

### InvoiceInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. |
| `customer` | [Customer](/docs/api/objetos#Customer) |  |  |
| `items` | lista de [Item](/docs/api/objetos#Item) | sí | Las líneas (1 a 500). Máximo 500. |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `period` | [Period](/docs/api/objetos#Period) |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  | Descuentos y recargos globales (no tocan las bases). Máximo 20. |
| `prepayments` | lista de [Prepayment](/docs/api/objetos#Prepayment) |  | Anticipos (informativos: no restan del total). Máximo 20. |
| `withholdings` | lista de [Withholding](/docs/api/objetos#Withholding) |  | Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10. |
| `rounding` | booleano o decimal |  | true = redondeo al peso; o un valor entre -2.00 y 2.00. |
| `document_type` | texto |  | Tipo de factura (tabla 13.1.3): "01" venta (por defecto) o "02" exportación. La contingencia (03/04) todavía no está disponible en la API. |
| `operation_type` | texto |  | Tipo de operación (tabla 13.1.5.1): "10" estándar (por defecto), "09" AIU, "11" mandatos, "12" transporte de carga, "14" notarios, "15" compra o "16" venta de divisas, o "SS-CUFE" (sector salud, con `interoperability`). |
| `currency` | [Currency](/docs/api/objetos#Currency) |  | Moneda extranjera: los valores del pedido van en ESA moneda; la factura y el CUFE van en pesos (× la tasa). Sin `currency`, la factura es en pesos. |
| `cop_totals` | booleano |  | Con `currency`: informa la moneda y la tasa en la interoperabilidad («Exportación» / «Factura de Venta»). |
| `delivery_terms` | [DeliveryTerms](/docs/api/objetos#DeliveryTerms) |  | Condiciones de entrega de la exportación (tabla 13.3.7: INCOTERM). |
| `shipment` | [Shipment](/docs/api/objetos#Shipment) |  | El envío físico de la mercancía (fecha, dirección y transportador). No se llama `delivery`: esa clave de la respuesta es el estado de los archivos y del correo. |
| `due_diligence` | texto |  | Debida diligencia (tabla 18.3: "01"–"04"). Obligatoria en la compra y venta de divisas (15/16) y prohibida en los demás tipos de operación. |
| `interoperability` | [Interoperability](/docs/api/objetos#Interoperability) |  | Grupo de interoperabilidad (Suplemento H). Obligatorio con `operation_type` "SS-CUFE". |

### InvoiceReference

Uno de: objeto, objeto.

### Item

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `description` | texto | sí |  |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `unit_price` | decimal | sí | Precio unitario SIN impuestos. |
| `taxes` | lista de [ItemTax](/docs/api/objetos#ItemTax) |  | Impuestos de la línea: {code, rate} porcentual, {code: "01", excluded: true} o nominal {code, unit_amount, unit?, quantity?}. Máximo 12. |
| `discounts` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Máximo 10. |
| `charges` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Máximo 10. |
| `withholdings` | lista de [ItemWithholding](/docs/api/objetos#ItemWithholding) |  | Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10. |
| `free_of_charge` | [FreeOfCharge](/docs/api/objetos#FreeOfCharge) |  |  |
| `standard_code` | [StandardCode](/docs/api/objetos#StandardCode) |  |  |
| `brand` | texto |  |  |
| `model` | texto |  |  |
| `aiu` | texto |  | AIU (solo con `operation_type` "09"): "A" administración, "I" imprevistos, "U" utilidad. Solo en facturas. |
| `aiu_contract` | texto |  | El objeto del contrato AIU: solo en la línea A, y obligatorio en ella. Solo en facturas. |
| `income` | `own` \| `third_party` |  | Mandatos (11): "own" (por defecto) o "third_party" (con `mandator`). Solo en facturas. |
| `mandator` | [ItemMandator](/docs/api/objetos#ItemMandator) |  | El mandante de un ingreso para terceros. Solo en facturas. |
| `consignment` | [ItemConsignment](/docs/api/objetos#ItemConsignment) |  | La remesa del RNDC (transporte de carga, 12). Solo en facturas. |
| `notary` | [ItemNotary](/docs/api/objetos#ItemNotary) |  | Matrícula inmobiliaria y valor comercial (notarios, 14). Solo en facturas. |
| `properties` | lista de [ItemProperty](/docs/api/objetos#ItemProperty) |  | Propiedades libres de la línea (hasta 20; no en el transporte de carga). Solo en facturas. Máximo 20. |

### ItemAllowance

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `reason` | texto |  |  |
| `percent` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `amount` | decimal |  | Número o texto decimal con punto («150000.50»). |

### ItemConsignment

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `rndc_filing` | texto | sí | Número de radicación de la remesa en el RNDC (1 a 100 000 millones). |
| `number` | texto | sí | Consecutivo interno de la remesa (alfanumérico, hasta 15 caracteres). |
| `freight` | decimal | sí | Pesos, sin decimales (la ley los fija en pesos: no se convierte). |
| `quantity` | decimal | sí | Cantidad transportada, sin decimales. |
| `unit` | texto | sí | "KGM" kilogramos o "GLL" galones. |

### ItemMandator

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `document_type` | texto | sí | Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA… |
| `document_number` | texto | sí | Sin DV ni puntos; el DV lo calcula Trevol. |
| `name` | texto | sí |  |

### ItemNotary

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `property_registration` | texto | sí |  |
| `commercial_value` | decimal | sí | Pesos: no se convierte. |

### ItemProperty

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | texto | sí |  |
| `value` | texto | sí |  |
| `quantity` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6); solo con `quantity` (por defecto 94). |

### ItemTax

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Código (texto). |
| `rate` | decimal |  | Tarifa en % (ICA y ReteICA: por mil). |
| `excluded` | booleano |  |  |
| `unit_amount` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `volume_cc` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `name` | texto |  |  |

### ItemWithholding

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Código (texto). |
| `rate` | decimal | sí | Tarifa en % (ICA y ReteICA: por mil). |
| `self_withholding` | booleano |  |  |

### Meter

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `number` | texto | sí |  |
| `previous_date` | fecha (AAAA-MM-DD) |  |  |
| `previous_reading` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `current_date` | fecha (AAAA-MM-DD) |  |  |
| `current_reading` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `method` | texto |  |  |
| `days` | entero |  |  |

### NoteInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. |
| `customer` | [Customer](/docs/api/objetos#Customer) |  |  |
| `items` | lista de [Item](/docs/api/objetos#Item) | sí | Las líneas (1 a 500). Máximo 500. |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `period` | [Period](/docs/api/objetos#Period) |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  | Descuentos y recargos globales (no tocan las bases). Máximo 20. |
| `prepayments` | lista de [Prepayment](/docs/api/objetos#Prepayment) |  | Anticipos (informativos: no restan del total). Máximo 20. |
| `withholdings` | lista de [Withholding](/docs/api/objetos#Withholding) |  | Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10. |
| `rounding` | booleano o decimal |  | true = redondeo al peso; o un valor entre -2.00 y 2.00. |
| `concept` | texto | sí | Concepto de corrección: NC 1–6, ND 1–4. |
| `description` | texto |  |  |
| `invoice` | [InvoiceReference](/docs/api/objetos#InvoiceReference) |  |  |

### Numbering

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `prefix` | texto | sí | Prefijo de la resolución POS o de documento soporte que numera (el de `GET /v1/company` → `capabilities.equivalent_documents.pos_numbering` o `capabilities.support_documents.numbering`). |

### NumberingExpiringEventData

`numbering.expiring` (solo producción): la resolución vence en 30 y en 7 días.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `numbering` |  |  |
| `document` | `invoice` \| `support_document` \| `equivalent_document` |  | De qué documento es la numeración (la fase 3 avisa también del documento soporte y del POS). |
| `prefix` | texto (puede ser null) |  |  |
| `resolution_number` | texto |  |  |
| `valid_to` | fecha (AAAA-MM-DD) |  |  |
| `days_left` | entero |  |  |

### NumberingLowEventData

`numbering.low` (solo producción): a la resolución le quedan pocos números (10 % del rango, y otra vez con 10 números).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `numbering` |  |  |
| `document` | `invoice` \| `support_document` \| `equivalent_document` |  | De qué documento es la numeración (la fase 3 avisa también del documento soporte y del POS). |
| `prefix` | texto (puede ser null) |  |  |
| `resolution_number` | texto |  |  |
| `remaining` | entero |  |  |
| `to` | entero |  |  |

### OriginNote

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `number` | texto | sí |  |
| `cude` | texto | sí | El CUDE de la nota de ajuste (96 hex). |
| `issue_date` | fecha (AAAA-MM-DD) | sí |  |

### Payment

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `form` | `cash` \| `credit` | sí | cash (contado) \| credit (crédito: con due_date o term_days). |
| `term_days` | entero |  |  |
| `due_date` | fecha (AAAA-MM-DD) |  |  |
| `methods` | lista de [PaymentMethod](/docs/api/objetos#PaymentMethod) |  | Medios de pago (tabla 13.3.4.2): 10 efectivo, 42 consignación, 47 transferencia… Máximo 5. |

### PaymentMethod

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Código (texto). |
| `reference` | texto |  |  |

### Payroll

Una nómina electrónica individual (102). Archivos `xml`, `zip` y `dian_response`.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | pr_… |
| `object` | `payroll` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `validating` \| `accepted` \| `rejected` \| `error` \| `processing` |  | `validating`: el set de pruebas de la DIAN (habilitación) recibió la nómina y todavía la valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía). `processing`: solo en la versión 2026-10-22, la DIAN no contestó y Trevol sigue resolviendo el documento. |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` |  |  |
| `cune` | texto (puede ser null) |  | El código único de la nómina (CUNE, 96 hex). |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `submission` | `sync` \| `test_set` \| `null` (puede ser null) |  | `sync`: SendNominaSync; `test_set`: el set de pruebas de habilitación. |
| `period` | [PayrollPeriod](/docs/api/objetos#PayrollPeriod) |  |  |
| `pay_period` | texto |  |  |
| `currency` | texto |  |  |
| `exchange_rate` | decimal |  | Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP. |
| `novelty` | [PayrollNovelty](/docs/api/objetos#PayrollNovelty) |  |  |
| `notes` | lista de texto |  | Máximo 20. |
| `employee` | [PayrollEmployee](/docs/api/objetos#PayrollEmployee) |  |  |
| `payment` | [PayrollPayment](/docs/api/objetos#PayrollPayment) |  |  |
| `payment_dates` | lista de fecha (AAAA-MM-DD) |  | Máximo 31. |
| `earnings` | [PayrollEarnings](/docs/api/objetos#PayrollEarnings) |  |  |
| `deductions` | [PayrollDeductions](/docs/api/objetos#PayrollDeductions) |  |  |
| `rounding` | decimal |  | Redondeo hasta 2.00; no suma a los totales. |
| `generation_place` | [PayrollPlace](/docs/api/objetos#PayrollPlace) |  |  |
| `employer` | [PayrollEmployer](/docs/api/objetos#PayrollEmployer) |  |  |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales. Null en un ajuste Eliminar. |
| `dian` | objeto |  |  |
| `files` | objeto |  | Qué archivos hay (…/xml, …/zip, …/dian_response). No hay PDF. |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |

### PayrollAdjustment

Una nota de ajuste de nómina electrónica (103: Reemplazar o Eliminar). Archivos `xml`, `zip` y `dian_response`.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | pra_… |
| `object` | `payroll_adjustment` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `validating` \| `accepted` \| `rejected` \| `error` \| `processing` |  | `validating`: el set de pruebas de la DIAN (habilitación) recibió la nómina y todavía la valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía). `processing`: solo en la versión 2026-10-22, la DIAN no contestó y Trevol sigue resolviendo el documento. |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` |  |  |
| `cune` | texto (puede ser null) |  | El código único de la nómina (CUNE, 96 hex). |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `submission` | `sync` \| `test_set` \| `null` (puede ser null) |  | `sync`: SendNominaSync; `test_set`: el set de pruebas de habilitación. |
| `type` | `replace` \| `delete` \| `null` (puede ser null) |  |  |
| `predecessor` | [PayrollReference](/docs/api/objetos#PayrollReference) (puede ser null) |  |  |
| `period` | [PayrollPeriod](/docs/api/objetos#PayrollPeriod) |  |  |
| `pay_period` | texto |  |  |
| `currency` | texto |  |  |
| `exchange_rate` | decimal |  | Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP. |
| `notes` | lista de texto |  | Máximo 20. |
| `employee` | [PayrollEmployee](/docs/api/objetos#PayrollEmployee) |  |  |
| `payment` | [PayrollPayment](/docs/api/objetos#PayrollPayment) |  |  |
| `payment_dates` | lista de fecha (AAAA-MM-DD) |  | Máximo 31. |
| `earnings` | [PayrollEarnings](/docs/api/objetos#PayrollEarnings) |  |  |
| `deductions` | [PayrollDeductions](/docs/api/objetos#PayrollDeductions) |  |  |
| `rounding` | decimal |  | Redondeo hasta 2.00; no suma a los totales. |
| `generation_place` | [PayrollPlace](/docs/api/objetos#PayrollPlace) |  |  |
| `employer` | [PayrollEmployer](/docs/api/objetos#PayrollEmployer) |  |  |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales. Null en un ajuste Eliminar. |
| `dian` | objeto |  |  |
| `files` | objeto |  | Qué archivos hay (…/xml, …/zip, …/dian_response). No hay PDF. |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |

### PayrollAdjustmentInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos). |
| `type` | `replace` \| `delete` | sí | "replace" (Reemplazar: el ajuste lleva todos los datos de la nómina menos `novelty`) o "delete" (Eliminar: solo `predecessor`, `notes`, `generation_place` y `employer`). |
| `predecessor` | [PayrollReference](/docs/api/objetos#PayrollReference) | sí | El documento que se ajusta: {"id": "pr_…"} (una nómina de Trevol) o {"id": "pra_…"} (otro ajuste, el último de la cadena), o sus datos {number, cune, issue_date}. |
| `period` | [PayrollPeriod](/docs/api/objetos#PayrollPeriod) |  |  |
| `pay_period` | texto |  |  |
| `currency` | texto |  |  |
| `exchange_rate` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `notes` | lista de texto |  | Máximo 20. |
| `employee` | [PayrollEmployee](/docs/api/objetos#PayrollEmployee) |  |  |
| `payment` | [PayrollPayment](/docs/api/objetos#PayrollPayment) |  |  |
| `payment_dates` | lista de fecha (AAAA-MM-DD) |  | Máximo 31. |
| `earnings` | [PayrollEarnings](/docs/api/objetos#PayrollEarnings) |  |  |
| `deductions` | [PayrollDeductions](/docs/api/objetos#PayrollDeductions) |  |  |
| `rounding` | decimal |  | true = redondeo al peso; o un valor entre -2.00 y 2.00. |
| `generation_place` | [PayrollPlace](/docs/api/objetos#PayrollPlace) |  |  |
| `employer` | [PayrollEmployer](/docs/api/objetos#PayrollEmployer) |  |  |

### PayrollBasic

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `days` | entero | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollCompensatedVacation

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `days` | entero | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollCompensation

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `ordinary` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `extraordinary` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollDeductions

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `health` | [PayrollPercentAmount](/docs/api/objetos#PayrollPercentAmount) | sí | Salud (obligatoria). |
| `pension` | [PayrollPercentAmount](/docs/api/objetos#PayrollPercentAmount) | sí | Pensión (obligatoria). |
| `solidarity_fund` | [PayrollSolidarityFund](/docs/api/objetos#PayrollSolidarityFund) |  |  |
| `unions` | lista de [PayrollPercentAmount](/docs/api/objetos#PayrollPercentAmount) |  | Máximo 100. |
| `sanctions` | lista de [PayrollSanction](/docs/api/objetos#PayrollSanction) |  | Máximo 100. |
| `payroll_loans` | lista de [PayrollLoan](/docs/api/objetos#PayrollLoan) |  | Máximo 100. |
| `third_party_payments` | lista de decimal |  | Máximo 100. |
| `advances` | lista de decimal |  | Máximo 100. |
| `other` | lista de decimal |  | Máximo 100. |
| `voluntary_pension` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `withholding_tax` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `afc` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `cooperative` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `tax_garnishment` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `complementary_plan` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `education` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `refund` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `debt` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollDisability

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `start` | fecha (AAAA-MM-DD) |  |  |
| `end` | fecha (AAAA-MM-DD) |  |  |
| `days` | entero | sí |  |
| `type` | texto | sí | Tabla 5.5.6: "1" común, "2" profesional, "3" laboral. |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollEarnings

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `basic` | [PayrollBasic](/docs/api/objetos#PayrollBasic) | sí | El sueldo básico (obligatorio). |
| `transport` | lista de [PayrollTransport](/docs/api/objetos#PayrollTransport) |  | Máximo 100. |
| `overtime` | lista de [PayrollOvertime](/docs/api/objetos#PayrollOvertime) |  | Máximo 500. |
| `vacation` | [PayrollVacation](/docs/api/objetos#PayrollVacation) |  |  |
| `service_bonus` | [PayrollServiceBonus](/docs/api/objetos#PayrollServiceBonus) |  |  |
| `severance` | [PayrollSeverance](/docs/api/objetos#PayrollSeverance) |  |  |
| `disabilities` | lista de [PayrollDisability](/docs/api/objetos#PayrollDisability) |  | Máximo 100. |
| `leaves` | [PayrollLeaves](/docs/api/objetos#PayrollLeaves) |  |  |
| `bonuses` | lista de [PayrollSalaryAmounts](/docs/api/objetos#PayrollSalaryAmounts) |  | Máximo 100. |
| `allowances` | lista de [PayrollSalaryAmounts](/docs/api/objetos#PayrollSalaryAmounts) |  | Máximo 100. |
| `strikes` | lista de [PayrollUnpaidPeriod](/docs/api/objetos#PayrollUnpaidPeriod) |  | Máximo 100. |
| `other_concepts` | lista de [PayrollOtherConcept](/docs/api/objetos#PayrollOtherConcept) |  | Máximo 100. |
| `compensations` | lista de [PayrollCompensation](/docs/api/objetos#PayrollCompensation) |  | Máximo 100. |
| `epctv_bonuses` | lista de [PayrollEpctvBonus](/docs/api/objetos#PayrollEpctvBonus) |  | Máximo 100. |
| `commissions` | lista de decimal |  | Máximo 100. |
| `third_party_payments` | lista de decimal |  | Máximo 100. |
| `advances` | lista de decimal |  | Máximo 100. |
| `endowment` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `sustenance_support` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `telework` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `retirement_bonus` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `indemnity` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `refund` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollEmployee

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | texto | sí | Tipo de trabajador (tabla 5.5.3). |
| `subtype` | texto |  |  |
| `high_risk_pension` | booleano |  |  |
| `document_type` | texto | sí | Tipo de documento del trabajador (tabla 5.2.1). |
| `document_number` | texto | sí | Solo dígitos, sin puntos ni comas ni espacios. |
| `first_surname` | texto | sí |  |
| `second_surname` | texto | sí | Obligatorio (NIE047): la DIAN lo exige aunque la base no. |
| `first_name` | texto | sí |  |
| `other_names` | texto |  |  |
| `workplace` | [PayrollWorkplace](/docs/api/objetos#PayrollWorkplace) | sí |  |
| `integral_salary` | booleano |  |  |
| `contract_type` | texto | sí | Tipo de contrato (tabla 5.5.2). |
| `salary` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `code` | texto |  | El código interno del empleado (filtra las listas con `employee_code`; no es un dato de identificación). |

### PayrollEmployer

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `first_surname` | texto | sí |  |
| `second_surname` | texto | sí |  |
| `first_name` | texto | sí |  |
| `other_names` | texto |  |  |

### PayrollEpctvBonus

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `salary_payment` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `non_salary_payment` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `food_salary` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `food_non_salary` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollEventData

Resumen de una nómina electrónica (102) o de su nota de ajuste (103): SIN el trabajador (ni su documento, nombre o salario) y SIN montos. Pide el documento completo con GET /v1/{payrolls|payroll_adjustments}/{id}.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `payroll` \| `payroll_adjustment` | sí |  |
| `id` | texto | sí | pr_… \| pra_… |
| `status` | `pending` \| `sending` \| `validating` \| `accepted` \| `rejected` \| `error` | sí |  |
| `environment` | `test` \| `live` | sí |  |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` |  |  |
| `cune` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `type` | `replace` \| `delete` \| `null` (puede ser null) |  | Solo en la nota de ajuste. |
| `predecessor` | objeto (puede ser null) |  |  |
| `submission` | `sync` \| `test_set` \| `null` (puede ser null) |  |  |
| `dian` | objeto | sí |  |
| `error` | objeto |  | Solo en `….error`. Texto fijo por código. |

### PayrollInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos). |
| `period` | [PayrollPeriod](/docs/api/objetos#PayrollPeriod) | sí | El periodo que se liquida y el tiempo laborado (`time_worked` se calcula si no se manda: años de 360 días y meses de 30). |
| `pay_period` | texto | sí | Periodo de nómina (tabla 5.5.1): "1" semanal, "2" decenal, "3" catorcenal, "4" quincenal, "5" mensual, "6" otro. |
| `currency` | texto |  | Moneda (ISO 4217). Por defecto COP; con otra va `exchange_rate`. |
| `exchange_rate` | decimal |  | Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP. |
| `novelty` | [PayrollNovelty](/docs/api/objetos#PayrollNovelty) |  | El CUNE del documento con la novedad contractual, si la hay. Solo en la nómina. |
| `notes` | lista de texto |  | Máximo 20. |
| `employee` | [PayrollEmployee](/docs/api/objetos#PayrollEmployee) | sí | El trabajador. Sus datos solo salen en las respuestas a esta llave (la del empleador): nunca en webhooks, en el registro de peticiones ni en lo que se guarda de la idempotencia. |
| `payment` | [PayrollPayment](/docs/api/objetos#PayrollPayment) | sí |  |
| `payment_dates` | lista de fecha (AAAA-MM-DD) | sí | Las fechas de pago (1 a 31). Máximo 31. |
| `earnings` | [PayrollEarnings](/docs/api/objetos#PayrollEarnings) | sí |  |
| `deductions` | [PayrollDeductions](/docs/api/objetos#PayrollDeductions) | sí |  |
| `rounding` | decimal |  | Redondeo hasta 2.00; no suma a los totales. |
| `generation_place` | [PayrollPlace](/docs/api/objetos#PayrollPlace) |  | Dónde se generó el documento. Por defecto, el municipio de la empresa. |
| `employer` | [PayrollEmployer](/docs/api/objetos#PayrollEmployer) |  | Solo si la empresa es persona natural: sus apellidos y nombres (si la razón social no se separa bien en «apellido1 apellido2 nombre1»). |

### PayrollLeaves

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `maternity_paternity` | lista de [PayrollPaidPeriod](/docs/api/objetos#PayrollPaidPeriod) |  | Máximo 100. |
| `paid` | lista de [PayrollPaidPeriod](/docs/api/objetos#PayrollPaidPeriod) |  | Máximo 100. |
| `unpaid` | lista de [PayrollUnpaidPeriod](/docs/api/objetos#PayrollUnpaidPeriod) |  | Máximo 100. |

### PayrollLoan

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `description` | texto | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollNovelty

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `cune` | texto | sí |  |

### PayrollOtherConcept

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `description` | texto | sí |  |
| `salary` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `non_salary` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollOvertime

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | texto | sí | Tabla 5.5.5: HED, HEN, HRN, HEDDF, HRDDF, HENDF, HRNDF. El porcentaje sale de la tabla. |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `start` | texto |  | AAAA-MM-DDTHH:MM:SS (NIE074). |
| `end` | texto |  | AAAA-MM-DDTHH:MM:SS (NIE074). |
| `percent` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollPaidPeriod

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `start` | fecha (AAAA-MM-DD) |  |  |
| `end` | fecha (AAAA-MM-DD) |  |  |
| `days` | entero | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollPayment

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `form` | texto |  | Forma de pago (tabla 5.3.3.1); por defecto "1" (contado). |
| `method` | texto | sí | Medio de pago (tabla 5.3.3.2). |
| `bank` | texto |  |  |
| `account_type` | texto |  |  |
| `account_number` | texto |  |  |

### PayrollPercentAmount

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `percent` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollPeriod

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `hire_date` | fecha (AAAA-MM-DD) | sí |  |
| `start` | fecha (AAAA-MM-DD) | sí |  |
| `end` | fecha (AAAA-MM-DD) | sí |  |
| `termination_date` | fecha (AAAA-MM-DD) |  |  |
| `time_worked` | entero |  |  |

### PayrollPlace

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `country` | texto |  |  |
| `department_code` | texto |  |  |
| `municipality_code` | texto |  | Código DANE del municipio (5 dígitos). |

### PayrollReference

Uno de: objeto, objeto.

### PayrollSalaryAmounts

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `salary` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `non_salary` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollSanction

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `public` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `private` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollServiceBonus

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `days` | entero | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `non_salary_amount` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollSeverance

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `percent` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `interest` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### PayrollSolidarityFund

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `percent` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `amount` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `subsistence_percent` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `subsistence_amount` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollTransport

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `allowance` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `salary_per_diem` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `non_salary_per_diem` | decimal |  | Número o texto decimal con punto («150000.50»). |

### PayrollUnpaidPeriod

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `start` | fecha (AAAA-MM-DD) |  |  |
| `end` | fecha (AAAA-MM-DD) |  |  |
| `days` | entero | sí |  |

### PayrollVacation

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `regular` | lista de [PayrollPaidPeriod](/docs/api/objetos#PayrollPaidPeriod) |  | Máximo 100. |
| `compensated` | lista de [PayrollCompensatedVacation](/docs/api/objetos#PayrollCompensatedVacation) |  | Máximo 100. |

### PayrollWorkplace

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `country` | texto |  |  |
| `department_code` | texto |  |  |
| `municipality_code` | texto |  | Código DANE del municipio (5 dígitos). |
| `address` | texto |  |  |

### Period

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `start` | fecha (AAAA-MM-DD) |  |  |
| `end` | fecha (AAAA-MM-DD) |  |  |

### PhysicalDocument

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `number` | texto |  |  |
| `date` | fecha (AAAA-MM-DD) |  |  |
| `type` | texto |  | Codificación propia del tipo del documento físico (hasta 10 caracteres). Por defecto, FISICO. |

### Pos

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `register` | [PosRegister](/docs/api/objetos#PosRegister) | sí |  |
| `buyer` | [PosBuyer](/docs/api/objetos#PosBuyer) |  |  |

### PosBuyer

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Por defecto, el documento del adquirente. |
| `name` | texto |  | Por defecto, el nombre del adquirente. |
| `points` | decimal |  | Puntos del comprador. Por defecto, 0. |

### PosRegister

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `plate` | texto | sí | Placa de inventario de la caja (DEPD26). |
| `location` | texto | sí | Ubicación de la caja (DEPD28). |
| `cashier` | texto | sí | Nombre del cajero o vendedor (DEPD30). |
| `type` | texto | sí | Tipo de caja (DEPD32). |
| `sale_code` | texto |  | Código de la venta. Por defecto, el número del documento (DEPD34). |

### Prepayment

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto | sí |  |
| `amount` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `received_date` | fecha (AAAA-MM-DD) | sí |  |
| `paid_date` | fecha (AAAA-MM-DD) |  |  |
| `instructions` | texto |  |  |

### Preview

El resultado de calcular sin emitir: el documento que se emitiría, con sus totales. No gasta numeración, saldo ni le manda nada a la DIAN. Lleva además los campos del pedido normalizados (cambian de un tipo de documento a otro).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `preview` |  |  |
| `document` | texto |  | El `object` del documento que se emitiría (`invoice`, `credit_note`, `payroll`…). |
| `environment` | `test` \| `live` \| `null` (puede ser null) |  |  |
| `totals` | objeto libre |  | Los totales calculados: la misma forma que `totals` del documento (en nómina, devengados, deducciones y total del comprobante). |

### Problem

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | texto | sí |  |
| `title` | texto | sí |  |
| `status` | entero | sí |  |
| `code` | `authentication_required` \| `certificate_problem` \| `company_not_enabled` \| `dian_rejected` \| `dian_unavailable` \| `duplicate_document` \| `external_id_in_use` \| `file_unavailable` \| `idempotency_key_required` \| `idempotency_key_reused` \| `insufficient_balance` \| `internal_error` \| `invalid_api_key` \| `invalid_json` \| `invalid_request` \| `invalid_state` \| `method_not_allowed` \| `not_found` \| `numbering_unavailable` \| `permission_denied` \| `previous_event_pending` \| `rate_limited` \| `request_in_progress` \| `tacit_acceptance_not_due` \| `top_up_above_maximum` \| `top_up_below_minimum` \| `top_ups_unavailable` \| `unsupported_version` \| `validation_error` \| `webhook_limit_reached` | sí |  |
| `detail` | texto |  |  |
| `retryable` | booleano | sí |  |
| `retry_after` | entero |  |  |
| `request_id` | texto |  |  |
| `errors` | lista de objeto |  |  |
| `document` | [Document](/docs/api/objetos#Document) |  |  |
| `existing_id` | texto |  | En `external_id_in_use` y `duplicate_document`: el id (con el prefijo de su clase) del recurso que ya existe. |
| `reason` | `missing_legal_representative` \| `missing_pin` \| `missing_software` \| `missing_technical_key` \| `no_resolution` \| `payroll_not_enabled` \| `prefix_in_use` \| `resolution_exhausted` \| `resolution_expired` \| `resolution_not_yet_valid` |  | En `company_not_enabled` (`missing_legal_representative`, `missing_pin`, `missing_software`, `payroll_not_enabled`) y en `numbering_unavailable` (`missing_technical_key`, `no_resolution`, `prefix_in_use`, `resolution_exhausted`, `resolution_expired`, `resolution_not_yet_valid`): por qué. |
| `previous` | texto |  | En `previous_event_pending`: el evento que la DIAN todavía no muestra. |
| `minimum_cop` | entero (puede ser null) |  | En `top_up_below_minimum`: la recarga mínima, en pesos. |
| `maximum_cop` | entero (puede ser null) |  | En `top_up_above_maximum`: la recarga máxima, en pesos. |
| `limit` | texto |  | En `rate_limited`: qué límite se pasó. |
| `available_from` | fecha (AAAA-MM-DD) (puede ser null) |  | En `tacit_acceptance_not_due`: desde cuándo procede la aceptación tácita. `null` si la DIAN todavía no muestra el recibo del bien (032) de la compradora: consulta de nuevo en unos minutos con `GET /v1/invoices/{id}/tacit_acceptance`. |
| `rules` | lista de objeto libre |  | En `tacit_acceptance_not_due`: las reglas (LGC…) que la DIAN aplicaría; las locales llevan `local: true`. |

### PublicServicesExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `service` | texto | sí |  |
| `company` | texto | sí |  |
| `reason` | texto |  |  |
| `contract` | texto | sí |  |
| `use` | texto | sí |  |
| `stratum` | texto | sí |  |
| `payment_due_date` | fecha (AAAA-MM-DD) |  |  |
| `payment_reference` | texto |  |  |
| `due_date` | fecha (AAAA-MM-DD) |  |  |
| `period` | fecha (AAAA-MM-DD) |  |  |
| `cycle_days` | entero |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `consumptions` | lista de [Consumption](/docs/api/objetos#Consumption) | sí | Máximo 50. |
| `third_parties` | lista de [ThirdPartyCharge](/docs/api/objetos#ThirdPartyCharge) |  | Máximo 20. |

### RadianEvent

Un evento RADIAN 030–034 sobre una factura. Solo archivo `xml`. Un rechazo es final.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  |  |
| `object` | `radian_event` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `validating` \| `accepted` \| `rejected` \| `error` \| `processing` |  | `validating`: la DIAN respondió 98 («en proceso de validación»); no es un error, responde 202 en las dos versiones y Trevol solo consulta (el 98 significa «no reenvíes»). `processing`: solo en la 2026-10-22, un envío en duda o el evento anterior que aún no aparece: Trevol lo sigue resolviendo. `error` incluye el envío en duda de la 2026-10-21. |
| `event_code` | `030` \| `031` \| `032` \| `033` \| `034` |  |  |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` |  |  |
| `cude` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `invoice` | objeto |  | 030–033: la factura recibida (con el emisor). 034: {id, cufe, number} de la factura propia; sin `id` si no se emitió con Trevol (la trajo la sincronización con la DIAN). |
| `claim` | [EventClaim](/docs/api/objetos#EventClaim) (puede ser null) |  |  |
| `software` | `own` \| `dian_free` |  |  |
| `provider` | `dian` \| `company` |  |  |
| `dian` | objeto |  |  |
| `already_registered` | booleano |  | true: GetStatusEvent ya mostraba el CUDE de ESTE evento (un envío en duda que sí llegó); se cerró `accepted` sin reenviar. |
| `already_registered_elsewhere` | booleano |  | true: la DIAN rechazó con LGC01, la factura ya tiene ese evento (quizá de otro software); no hace falta enviarlo. |
| `tacit` | booleano |  | 033 rechazada con DC24c: la factura ya quedó aceptada tácitamente. |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |

### RadianEventData

Resumen de un evento RADIAN (030–034): sin nombres ni NIT del emisor de la factura. Pide el evento completo con GET /v1/radian_events/{id}.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `radian_event` | sí |  |
| `id` | texto | sí |  |
| `status` | `pending` \| `sending` \| `validating` \| `accepted` \| `rejected` \| `error` | sí |  |
| `environment` | `test` \| `live` | sí |  |
| `event_code` | `030` \| `031` \| `032` \| `033` \| `034` | sí |  |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` |  |  |
| `cude` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `invoice` | objeto |  |  |
| `dian` | objeto | sí |  |
| `error` | objeto |  | Solo en `….error`. Texto fijo por código. |

### RadianEventInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En los eventos es único entre los eventos (aparte de las facturas y las nóminas). |
| `event_code` | texto | sí | "030" acuse de recibo, "031" reclamo, "032" recibo del bien o servicio, "033" aceptación expresa (las cuatro sobre una factura RECIBIDA) o "034" aceptación tácita (sobre una factura PROPIA a crédito). Los 035 a 051 necesitan un participante RADIAN y no están disponibles. |
| `invoice` | [ReceivedInvoice](/docs/api/objetos#ReceivedInvoice) |  | 030–033: la factura RECIBIDA sobre la que va el evento (CUFE, número y quién la emitió). 034: la factura PROPIA por su CUFE, `{cufe, number?}` (solo esos dos), en lugar de `invoice_id`: sirve también para las facturas que no se emitieron con Trevol (las trae la sincronización con la DIAN). Si el CUFE es de una factura de Trevol, es lo mismo que mandar su `invoice_id`. |
| `invoice_id` | texto |  | 034: el id (`inv_…`) de una factura de Trevol: propia, validada, a crédito y que no sea de consumidor final. Va aparte de `invoice` para que cada esquema sea plano en los SDK. Para una factura que no se emitió con Trevol, usa `invoice: {cufe}` (exactamente uno de los dos). |
| `claim` | [EventClaim](/docs/api/objetos#EventClaim) |  | Solo en el reclamo (031) y obligatorio en él: {code: "01" a "04", note?}. |
| `software` | `own` \| `dian_free` |  | 030–033: `own` (el Software Propio de la empresa, por defecto) o `dian_free` (el software gratuito de la DIAN). El 034 se firma con el Software Propio. |
| `provider` | `dian` \| `company` |  | 030–033: quién es el proveedor tecnológico: `dian` (por defecto con `dian_free`) o `company` (por defecto con `own`). |

### ReceivedInvoice

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `cufe` | texto |  | El CUFE de la factura (96 caracteres hexadecimales). |
| `number` | texto |  | El número de la factura, con su prefijo. En el 034 es opcional: si viene, tiene que ser el de la factura de ese CUFE. |
| `type` | texto |  | Tipo de documento de la factura ("01" a "04"; por defecto "01"). No va en el 034. |
| `issuer` | [ReceivedInvoiceIssuer](/docs/api/objetos#ReceivedInvoiceIssuer) |  |  |
| `acquirer_document_type` | texto |  | El tipo de documento con que el emisor identificó a la empresa en la factura ("31" NIT o "13" cédula). Por defecto, el de la empresa (si no, la regla AAH09). |

### ReceivedInvoiceIssuer

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `nit` | texto |  |  |
| `check_digit` | entero |  | Opcional: si viene, tiene que ser el DV del NIT. |
| `document_type` | texto |  | Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA… |
| `name` | texto |  | Se guarda (va en el XML) pero no sale en los webhooks. |

### References

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `purchase_order` | [DocumentReference](/docs/api/objetos#DocumentReference) |  |  |
| `despatches` | lista de [DocumentReference](/docs/api/objetos#DocumentReference) |  | Máximo 20. |
| `receipts` | lista de [DocumentReference](/docs/api/objetos#DocumentReference) |  | Máximo 20. |

### RequestLog

Una petición de la API (sin cuerpo, consulta, IP ni llave). Se guardan 30 días y son las de la empresa y el ambiente de la llave.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `request` | sí |  |
| `id` | texto | sí | El `Request-Id` de la respuesta: compártelo si pides ayuda. |
| `method` | `GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE` | sí |  |
| `path` | texto | sí | La plantilla de la ruta, no la ruta real: /v1/invoices/{id}/pdf |
| `status` | entero | sí | El estado HTTP que se respondió. |
| `code` | texto (puede ser null) |  | El `code` del error (validation_error…); null si salió bien. |
| `duration_ms` | entero | sí | Lo que tardó Trevol en responder, en milisegundos. |
| `key_id` | texto (puede ser null) |  | La llave que hizo la petición (key_…, la de GET /v1/company); null si ya se borró. |
| `document_id` | texto (puede ser null) |  | El documento (inv_…, cn_…, dn_…) sobre el que se actuó, si lo hay. |
| `idempotent_replayed` | booleano |  | Se respondió con el resultado guardado de una Idempotency-Key repetida. |
| `api_version` | `2026-10-21` \| `2026-10-22` \| `null` (puede ser null) |  |  |
| `created_at` | fecha y hora | sí |  |

### Seller

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `resident` | booleano |  | Residente fiscal en Colombia. Por defecto, `country` es CO. |
| `person_type` | `legal` \| `natural` |  | Por defecto se deduce del NIT. |
| `document_type` | texto | sí | Residente: solo "31" (NIT). No residente: 21, 22, 31, 41, 42, 47 o 50 (tabla 16.2.1). |
| `document_number` | texto | sí | Sin dígito de verificación; Trevol calcula el DV del NIT. |
| `check_digit` | entero |  | Opcional: si viene, tiene que ser el DV del NIT. |
| `name` | texto | sí |  |
| `address` | texto |  |  |
| `tax_scheme` | texto |  | "ZZ" (no aplica, por defecto) o "01" (IVA). |
| `tax_responsibilities` | lista de texto |  | O-13, O-15, O-23, O-47, O-48, O-49 o R-99-PN (por defecto R-99-PN). Máximo 20. |
| `country` | texto |  | ISO 3166-1 alfa-2 (tabla 16.4.1). Por defecto CO. |
| `municipality_code` | texto |  | Solo vendedor residente: código DANE del municipio. |
| `department_code` | texto |  |  |
| `postal_code` | texto |  | Residente: de la tabla 16.4.4, del mismo departamento. No residente: libre, hasta 10 caracteres. |
| `city` | texto |  | Obligatoria si no es residente. |
| `region` | texto |  | Solo vendedor no residente. |

### Shipment

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `date` | fecha (AAAA-MM-DD) |  |  |
| `address` | [ForeignAddress](/docs/api/objetos#ForeignAddress) |  |  |
| `carrier` | [Carrier](/docs/api/objetos#Carrier) |  |  |

### ShowEvent

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | texto | sí |  |
| `locality` | texto | sí |  |
| `pulep` | texto |  |  |
| `sale_type` | texto |  |  |
| `sale_phase` | texto |  |  |
| `category` | texto |  |  |
| `municipality_code` | texto |  | Código DANE del municipio (5 dígitos). |
| `venue` | texto |  |  |
| `date` | fecha (AAAA-MM-DD) |  |  |
| `time` | texto |  |  |

### ShowExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `producer` | [ShowProducer](/docs/api/objetos#ShowProducer) | sí |  |
| `event` | [ShowEvent](/docs/api/objetos#ShowEvent) | sí |  |

### ShowProducer

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | texto | sí |  |
| `nit` | texto | sí |  |
| `lep` | texto |  |  |

### StandardCode

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `scheme` | texto |  |  |
| `value` | texto |  |  |

### StockExchangeExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `trade_number` | texto | sí |  |
| `settlement_date` | fecha (AAAA-MM-DD) | sí |  |
| `nominal_quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `prices` | [StockExchangePrices](/docs/api/objetos#StockExchangePrices) | sí |  |
| `yields` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `value` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `commission_percent` | decimal | sí | Número o texto decimal con punto («150000.50»). |

### StockExchangePrices

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `registration` | texto |  |  |
| `total_assignment` | texto |  |  |

### SupportAdjustmentItem

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `description` | texto | sí |  |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `unit_price` | decimal | sí | Precio unitario SIN impuestos. |
| `taxes` | lista de [SupportItemTax](/docs/api/objetos#SupportItemTax) |  | Solo IVA: {code: "01", rate: 0 \| 5 \| 19} o {code: "01", excluded: true}. Máximo 12. |
| `discounts` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Descuentos de la línea, sin código; la razón va de 10 a 5000 caracteres (NSBE04). Máximo 10. |
| `charges` | lista de [SupportItemCharge](/docs/api/objetos#SupportItemCharge) |  | Máximo 10. |
| `standard_code` | [StandardCode](/docs/api/objetos#StandardCode) |  |  |

### SupportAdjustmentReference

Uno de: objeto, objeto.

### SupportCurrency

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Moneda del documento (ISO 4217); los valores del pedido van en ESA moneda. |
| `exchange_rate` | decimal | sí | Pesos por 1 unidad de la moneda. |
| `rate_date` | fecha (AAAA-MM-DD) | sí |  |

### SupportDocument

Un documento soporte en adquisiciones a no obligados a facturar (Invoice 05). Se genera, no se expide: archivos `xml` y `dian_response`.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | sd_… |
| `object` | `support_document` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `processing` |  | `processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `items` | lista de [SupportItem](/docs/api/objetos#SupportItem) |  |  |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `currency` | [SupportCurrency](/docs/api/objetos#SupportCurrency) |  |  |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente. |
| `dian` | objeto |  |  |
| `delivery` | objeto |  | El documento soporte se genera, no se expide: no hay PDF, ZIP ni correo. Solo hay XML y la respuesta de la DIAN. |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |
| `cuds` | texto (puede ser null) |  | El código único del documento (CUDS, 96 hex). |
| `seller` | [Seller](/docs/api/objetos#Seller) |  |  |
| `notes` | lista de texto |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  |  |
| `transmission` | `per_operation` \| `weekly` |  |  |
| `adjustment_note` | [SupportAdjustmentReference](/docs/api/objetos#SupportAdjustmentReference) (puede ser null) |  |  |

### SupportDocumentAdjustment

Una nota de ajuste de un documento soporte (CreditNote 95). Se genera, no se expide: archivos `xml` y `dian_response`.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto |  | sda_… |
| `object` | `support_document_adjustment` |  |  |
| `environment` | `test` \| `live` |  |  |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `processing` |  | `processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  |  |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `qr` | texto (puede ser null) |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `items` | lista de [SupportAdjustmentItem](/docs/api/objetos#SupportAdjustmentItem) |  |  |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `currency` | [SupportCurrency](/docs/api/objetos#SupportCurrency) |  |  |
| `totals` | objeto (puede ser null) |  | Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente. |
| `dian` | objeto |  |  |
| `delivery` | objeto |  | El documento soporte se genera, no se expide: no hay PDF, ZIP ni correo. Solo hay XML y la respuesta de la DIAN. |
| `created_at` | fecha y hora |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |
| `cuds` | texto (puede ser null) |  | El código único del documento (CUDS, 96 hex). |
| `seller` | [Seller](/docs/api/objetos#Seller) |  |  |
| `notes` | lista de texto |  |  |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  |  |
| `concept` | texto |  | Concepto de la nota (tabla 16.2.4): 1 a 5. |
| `description` | texto |  |  |
| `support_document` | [SupportDocumentReference](/docs/api/objetos#SupportDocumentReference) |  |  |

### SupportDocumentAdjustmentInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. |
| `seller` | [Seller](/docs/api/objetos#Seller) |  | Opcional con `support_document.id`: se toma el vendedor del documento soporte (si viene, tiene que ser el mismo). |
| `items` | lista de [SupportAdjustmentItem](/docs/api/objetos#SupportAdjustmentItem) | sí | Las líneas de la nota (1 a 500): sin retenciones ni fecha de compra. Máximo 500. |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  | Descuentos y recargos globales (no tocan las bases). Máximo 20. |
| `currency` | [SupportCurrency](/docs/api/objetos#SupportCurrency) |  |  |
| `concept` | texto | sí | Concepto de la nota de ajuste (tabla 16.2.4): "1" devolución parcial, "2" anulación del documento soporte (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros. |
| `description` | texto | sí | Qué se corrige y por qué (de 20 a 5000 caracteres, NSBF04). |
| `support_document` | [SupportDocumentReference](/docs/api/objetos#SupportDocumentReference) | sí | El documento soporte que ajusta: {"id": "sd_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cuds, issue_date, total?} si es de otra plataforma (`total` hace falta para anularlo). |

### SupportDocumentEventData

Resumen de un documento soporte o de su nota de ajuste (nunca datos del proveedor ni líneas). Pide el documento completo con GET /v1/{support_documents|support_document_adjustments}/{id}.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `status` | `pending` \| `sending` \| `accepted` \| `rejected` \| `error` \| `contingency` | sí | Nunca `processing`: ese estado solo existe en las respuestas de la API. |
| `environment` | `test` \| `live` | sí |  |
| `number` | texto (puede ser null) |  |  |
| `prefix` | texto (puede ser null) |  |  |
| `external_id` | texto (puede ser null) |  | Tu identificador, solo en los documentos creados por la API. |
| `origin` | `api` \| `app` \| `contapyme` |  |  |
| `issued_at` | fecha y hora (puede ser null) |  |  |
| `total` | texto (puede ser null) |  | Texto decimal con dos decimales. |
| `dian` | objeto | sí |  |
| `error` | objeto |  | Solo en `….error`. El texto es fijo por código: nunca el mensaje de la DIAN. |
| `object` | `support_document` \| `support_document_adjustment` | sí |  |
| `id` | texto | sí | sd_… \| sda_… |
| `cuds` | texto (puede ser null) |  | Código único del documento soporte. |
| `support_document` | objeto |  | En la nota de ajuste: el documento soporte que ajusta. |
| `delivery` | null |  | El documento soporte no se expide al vendedor: no hay PDF ni correo. |

### SupportDocumentInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `external_id` | texto |  | Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. |
| `seller` | [Seller](/docs/api/objetos#Seller) | sí | Quien vende y no está obligado a facturar (el SNO). La empresa de la llave es la compradora: sus datos salen de la empresa. No hay `customer`. |
| `items` | lista de [SupportItem](/docs/api/objetos#SupportItem) | sí | Las líneas (1 a 500). Retenciones solo por línea (`withholdings`: 05 ReteIVA, 06 ReteRenta); las del documento no se publican. Máximo 500. |
| `payment` | [Payment](/docs/api/objetos#Payment) |  |  |
| `notes` | lista de texto |  | Máximo 10. |
| `references` | [References](/docs/api/objetos#References) |  |  |
| `allowance_charges` | lista de [AllowanceCharge](/docs/api/objetos#AllowanceCharge) |  | Descuentos y recargos globales (no tocan las bases). Máximo 20. |
| `currency` | [SupportCurrency](/docs/api/objetos#SupportCurrency) |  |  |
| `transmission` | `per_operation` \| `weekly` |  | `per_operation` (por defecto, un documento por compra) o `weekly` (acumulado semanal con un mismo vendedor: cada línea lleva su `purchase_date`). |
| `adjustment_note` | [SupportAdjustmentReference](/docs/api/objetos#SupportAdjustmentReference) |  | La nota de ajuste que originó este documento (opcional): {"id": "sda_…"} o {number, cuds, issue_date}. |
| `numbering` | [Numbering](/docs/api/objetos#Numbering) |  | Opcional: el prefijo de la resolución de documento soporte que numera (una empresa con varios rangos). Sin él, la más nueva vigente. Si no existe, `numbering_unavailable` (`no_resolution`). |

### SupportDocumentReference

Uno de: objeto, objeto.

### SupportItem

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto |  | Código (texto). |
| `description` | texto | sí |  |
| `unit` | texto |  | Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad). |
| `quantity` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `unit_price` | decimal | sí | Precio unitario SIN impuestos. |
| `taxes` | lista de [SupportItemTax](/docs/api/objetos#SupportItemTax) |  | Solo IVA: {code: "01", rate: 0 \| 5 \| 19} o {code: "01", excluded: true}. Máximo 12. |
| `discounts` | lista de [ItemAllowance](/docs/api/objetos#ItemAllowance) |  | Descuentos de la línea, sin código; la razón va de 10 a 5000 caracteres (DSBE04). Máximo 10. |
| `charges` | lista de [SupportItemCharge](/docs/api/objetos#SupportItemCharge) |  | Máximo 10. |
| `withholdings` | lista de [SupportItemWithholding](/docs/api/objetos#SupportItemWithholding) |  | Las practica la empresa al vendedor: 05 ReteIVA (15 o 100 %) o 06 ReteRenta. No restan del total a pagar. Máximo 10. |
| `standard_code` | [StandardCode](/docs/api/objetos#StandardCode) |  |  |
| `purchase_date` | fecha (AAAA-MM-DD) |  | Fecha de la compra. Obligatoria en el acumulado semanal (entre 6 días antes de hoy y hoy); por operación no se informa. |

### SupportItemCharge

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `reason` | texto |  |  |
| `percent` | decimal |  | Número o texto decimal con punto («150000.50»). |
| `amount` | decimal |  | Número o texto decimal con punto («150000.50»). |

### SupportItemTax

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Código (texto). |
| `rate` | decimal |  | Tarifa en % (ICA y ReteICA: por mil). |
| `excluded` | booleano |  |  |

### SupportItemWithholding

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Código (texto). |
| `rate` | decimal | sí | Tarifa en % (ICA y ReteICA: por mil). |

### TacitAcceptance

¿Procede ya la aceptación tácita (034) sobre una factura propia? Solo lectura: consulta GetStatusEvent con el certificado de la empresa y no envía nada. Límite propio: 30 por minuto por llave (las dos consultas, juntas).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `tacit_acceptance` |  |  |
| `invoice_id` | texto |  | Solo si la factura es de Trevol. |
| `cufe` | texto |  | El CUFE de la factura. |
| `number` | texto |  | El número de la factura. |
| `allowed` | booleano |  |  |
| `available_from` | fecha (AAAA-MM-DD) (puede ser null) |  | Desde cuándo procede (3 días hábiles después del recibo del bien, 032). |
| `rules` | lista de objeto |  | Las reglas (LGC…) que impiden el 034 ahora; llevan `local: true`. |

### TestEventData

`webhook.test`: lo manda «Probar» (app) o POST …/test, solo a ese endpoint.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `test` |  |  |
| `message` | texto |  |  |

### ThirdPartyCharge

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `service` | texto | sí |  |
| `company` | [ThirdPartyCompany](/docs/api/objetos#ThirdPartyCompany) | sí |  |
| `reason` | texto |  |  |
| `contract` | texto |  |  |
| `period` | texto |  |  |
| `note` | texto |  |  |
| `total` | decimal | sí | Número o texto decimal con punto («150000.50»). |
| `charges` | lista de [ConsumptionAdjustment](/docs/api/objetos#ConsumptionAdjustment) |  | Máximo 50. |

### ThirdPartyCompany

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `nit` | texto | sí |  |
| `name` | texto | sí |  |

### TopUp

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `top_up` | sí |  |
| `reference` | texto | sí |  |
| `amount_cop` | entero | sí |  |
| `status` | `prepared` | sí |  |
| `wompi` | objeto | sí | Lo que necesita el widget de Wompi (WidgetCheckout). |

### TopUpBuyer

El comprador de la factura de la recarga. Sin él, la empresa de la llave.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `document_type` | `13` \| `31` \| `22` \| `41` | sí | 13 cédula, 31 NIT, 22 cédula de extranjería, 41 pasaporte (lo que acepta la facturación de la recarga). |
| `document_number` | texto | sí | Sin DV ni puntos (con 13 y 31, solo dígitos). |
| `check_digit` | texto o entero |  | Con NIT, obligatorio: el DV del NIT. No va con los demás. |
| `person_type` | `legal` \| `natural` | sí | legal (persona jurídica, solo con NIT) o natural. |
| `name` | texto | sí | Razón social o, para una persona natural, nombres y apellidos (al menos dos palabras). |
| `email` | texto | sí | A dónde llega la factura de la recarga. |
| `phone` | texto |  |  |
| `address` | texto |  |  |
| `municipality_code` | texto |  | Código DANE del municipio (5 dígitos). |

### TopUpInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount_cop` | entero | sí | En pesos, entre la recarga mínima y la máxima. |
| `buyer` | [TopUpBuyer](/docs/api/objetos#TopUpBuyer) |  |  |

### TransportExtension

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `mode` | texto | sí |  |
| `vehicle_id` | texto | sí |  |
| `vehicle` | texto | sí |  |
| `origin` | texto | sí |  |
| `destination` | texto | sí |  |

### WebhookDelivery

Un evento hacia un endpoint, con sus reintentos (8 automáticos en unas 32 horas; 3 si es manual).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto | sí |  |
| `object` | `webhook_delivery` | sí |  |
| `endpoint_id` | texto | sí |  |
| `event_id` | texto | sí |  |
| `event_type` | texto (puede ser null) |  |  |
| `status` | `pending` \| `sending` \| `succeeded` \| `failed` \| `canceled` | sí |  |
| `attempts` | entero | sí |  |
| `manual` | booleano |  |  |
| `next_attempt_at` | fecha y hora (puede ser null) |  |  |
| `last_attempt` | objeto (puede ser null) |  |  |
| `created_at` | fecha y hora (puede ser null) |  |  |
| `succeeded_at` | fecha y hora (puede ser null) |  |  |

### WebhookEndpoint

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | texto | sí |  |
| `object` | `webhook_endpoint` | sí |  |
| `environment` | `test` \| `live` | sí |  |
| `url` | texto | sí | La URL completa solo la ven las llaves de escritura; las de lectura ven el esquema y el host (el camino va enmascarado: a veces es un secreto). |
| `description` | texto (puede ser null) |  |  |
| `events` | lista de `*` \| `invoice.accepted` \| `invoice.rejected` \| `invoice.error` \| `invoice.delivered` \| `invoice.email_bounced` \| `invoice.email_failed` \| `credit_note.accepted` \| `credit_note.rejected` \| `credit_note.error` \| `credit_note.delivered` \| `credit_note.email_bounced` \| `credit_note.email_failed` \| `debit_note.accepted` \| `debit_note.rejected` \| `debit_note.error` \| `debit_note.delivered` \| `debit_note.email_bounced` \| `debit_note.email_failed` \| `balance.low` \| `numbering.low` \| `numbering.expiring` \| `certificate.expiring` \| `support_document.accepted` \| `support_document.rejected` \| `support_document.error` \| `support_document_adjustment.accepted` \| `support_document_adjustment.rejected` \| `support_document_adjustment.error` \| `equivalent_document.accepted` \| `equivalent_document.rejected` \| `equivalent_document.error` \| `equivalent_document.delivered` \| `equivalent_document.email_bounced` \| `equivalent_document.email_failed` \| `equivalent_document_adjustment.accepted` \| `equivalent_document_adjustment.rejected` \| `equivalent_document_adjustment.error` \| `equivalent_document_adjustment.delivered` \| `equivalent_document_adjustment.email_bounced` \| `equivalent_document_adjustment.email_failed` \| `payroll.accepted` \| `payroll.rejected` \| `payroll.error` \| `payroll_adjustment.accepted` \| `payroll_adjustment.rejected` \| `payroll_adjustment.error` \| `radian_event.accepted` \| `radian_event.rejected` \| `radian_event.error` | sí | Eventos del catálogo (49 tipos, hasta 60 en la lista), o ["*"] para todos (no se mezcla). `balance.low`, `numbering.low` y `numbering.expiring` solo existen en producción (llaves live). `webhook.test` no se suscribe. Máximo 60. |
| `catalog_version` | `1` \| `2` |  | Qué catálogo recibe con `["*"]`: `1` = el de la fase 2 (facturas, notas, saldo, numeración y certificado); `2` = también documento soporte, documento equivalente, nómina y eventos RADIAN. Los endpoints creados antes de la fase 3 quedan en 1 hasta que guardes de nuevo su lista de eventos (PATCH `events`); los nuevos nacen en 2. Una lista explícita siempre recibe lo que pide. |
| `status` | `enabled` \| `paused` \| `disabled` | sí | `paused`: lo pausaste tú. `disabled`: lo desactivó Trevol por fallos sostenidos (10 seguidos durante 5 días); se reactiva con PATCH status=enabled. |
| `disabled_reason` | `sustained_failures` \| `null` (puede ser null) |  |  |
| `secret_rotated_at` | fecha y hora (puede ser null) |  |  |
| `created_at` | fecha y hora (puede ser null) |  |  |
| `updated_at` | fecha y hora (puede ser null) |  |  |
| `secret` | texto |  | SOLO al crear o rotar, una única vez: guárdalo. Verifica cada entrega con él (Standard Webhooks). |

### WebhookEndpointInput

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `url` | texto | sí | https:// con un nombre de dominio (no una IP), sin usuario ni clave, puerto 443 o 1024–65535. En cada intento se resuelve el nombre y se rechaza toda dirección privada o local. |
| `description` | texto (puede ser null) |  |  |
| `events` | lista de `*` \| `invoice.accepted` \| `invoice.rejected` \| `invoice.error` \| `invoice.delivered` \| `invoice.email_bounced` \| `invoice.email_failed` \| `credit_note.accepted` \| `credit_note.rejected` \| `credit_note.error` \| `credit_note.delivered` \| `credit_note.email_bounced` \| `credit_note.email_failed` \| `debit_note.accepted` \| `debit_note.rejected` \| `debit_note.error` \| `debit_note.delivered` \| `debit_note.email_bounced` \| `debit_note.email_failed` \| `balance.low` \| `numbering.low` \| `numbering.expiring` \| `certificate.expiring` \| `support_document.accepted` \| `support_document.rejected` \| `support_document.error` \| `support_document_adjustment.accepted` \| `support_document_adjustment.rejected` \| `support_document_adjustment.error` \| `equivalent_document.accepted` \| `equivalent_document.rejected` \| `equivalent_document.error` \| `equivalent_document.delivered` \| `equivalent_document.email_bounced` \| `equivalent_document.email_failed` \| `equivalent_document_adjustment.accepted` \| `equivalent_document_adjustment.rejected` \| `equivalent_document_adjustment.error` \| `equivalent_document_adjustment.delivered` \| `equivalent_document_adjustment.email_bounced` \| `equivalent_document_adjustment.email_failed` \| `payroll.accepted` \| `payroll.rejected` \| `payroll.error` \| `payroll_adjustment.accepted` \| `payroll_adjustment.rejected` \| `payroll_adjustment.error` \| `radian_event.accepted` \| `radian_event.rejected` \| `radian_event.error` | sí | Eventos del catálogo (49 tipos, hasta 60 en la lista), o ["*"] para todos (no se mezcla). `balance.low`, `numbering.low` y `numbering.expiring` solo existen en producción (llaves live). `webhook.test` no se suscribe. Máximo 60. |

### WebhookEndpointUpdate

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `url` | texto |  | https:// con un nombre de dominio (no una IP), sin usuario ni clave, puerto 443 o 1024–65535. En cada intento se resuelve el nombre y se rechaza toda dirección privada o local. |
| `description` | texto (puede ser null) |  |  |
| `events` | lista de `*` \| `invoice.accepted` \| `invoice.rejected` \| `invoice.error` \| `invoice.delivered` \| `invoice.email_bounced` \| `invoice.email_failed` \| `credit_note.accepted` \| `credit_note.rejected` \| `credit_note.error` \| `credit_note.delivered` \| `credit_note.email_bounced` \| `credit_note.email_failed` \| `debit_note.accepted` \| `debit_note.rejected` \| `debit_note.error` \| `debit_note.delivered` \| `debit_note.email_bounced` \| `debit_note.email_failed` \| `balance.low` \| `numbering.low` \| `numbering.expiring` \| `certificate.expiring` \| `support_document.accepted` \| `support_document.rejected` \| `support_document.error` \| `support_document_adjustment.accepted` \| `support_document_adjustment.rejected` \| `support_document_adjustment.error` \| `equivalent_document.accepted` \| `equivalent_document.rejected` \| `equivalent_document.error` \| `equivalent_document.delivered` \| `equivalent_document.email_bounced` \| `equivalent_document.email_failed` \| `equivalent_document_adjustment.accepted` \| `equivalent_document_adjustment.rejected` \| `equivalent_document_adjustment.error` \| `equivalent_document_adjustment.delivered` \| `equivalent_document_adjustment.email_bounced` \| `equivalent_document_adjustment.email_failed` \| `payroll.accepted` \| `payroll.rejected` \| `payroll.error` \| `payroll_adjustment.accepted` \| `payroll_adjustment.rejected` \| `payroll_adjustment.error` \| `radian_event.accepted` \| `radian_event.rejected` \| `radian_event.error` |  | Eventos del catálogo (49 tipos, hasta 60 en la lista), o ["*"] para todos (no se mezcla). `balance.low`, `numbering.low` y `numbering.expiring` solo existen en producción (llaves live). `webhook.test` no se suscribe. Máximo 60. |
| `status` | `enabled` \| `paused` |  | enabled reactiva (también uno desactivado por Trevol) y pone en cero el contador de fallos. |

### Withholding

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | texto | sí | Código (texto). |
| `rate` | decimal | sí | Tarifa en % (ICA y ReteICA: por mil). |
| `self_withholding` | booleano |  |  |
| `base` | decimal |  | Número o texto decimal con punto («150000.50»). |