# Documento equivalente

> Las operaciones de Documento equivalente de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Fuente: https://platform.trevol.si/docs/api/equivalent-documents

Documento equivalente electrónico (tiquete POS 20 y los tipos 25, 27, 30, 35, 40, 45, 50, 55 y 60) y su nota de ajuste (crédito 94 y débito 93). Se expiden como la factura: PDF, ZIP y correo.

Los ejemplos son peticiones con cURL. La llave va en `TREVOL_API_KEY`; los cuerpos de ejemplo son los de la especificación. Los errores comunes están en [Errores](/docs/errores).

## Emitir un documento equivalente

`POST /v1/equivalent_documents` · `createEquivalentDocument`

Genera un **documento equivalente electrónico**: el tiquete POS (20, por defecto) o cualquiera de los otros nueve tipos de la tabla 16.3 (`document_type`: 25 cine, 27 espectáculos, 30 juegos, 35 transporte, 40 peajes, 45 extracto, 50 tiquete aéreo, 55 bolsa de valores, 60 servicios públicos; cada uno con su información propia en `extension`). El POS lleva su caja en `pos.register` y, si la empresa tiene varias cajas, el prefijo de su resolución en `numbering.prefix`. Se expide como la factura: PDF, ZIP y correo después del 201 (espera `equivalent_document.delivered` o consulta `delivery.status`). La contingencia 07 (documento físico) se pide con `contingency`; la 08 (la DIAN no contestó) la decide Trevol y responde `202` con `status: contingency`. En habilitación, el set de pruebas por tipo es automático: mientras la DIAN lo valida responde `202 validating` en las dos versiones y reintentar no vuelve a mandarlo. Cómo se calcula el CUDE del POS depende del despliegue del servicio, no de la empresa.

**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | cabecera | texto | sí | Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días). |

**Cuerpo** ([EquivalentDocumentInput](/docs/api/objetos#EquivalentDocumentInput), obligatorio)

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

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 201 | El documento ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| 202 | Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| 402 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| 409 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| 422 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| 429 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| 503 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`POST /v1/equivalent_documents` (`createEquivalentDocument`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/equivalent_documents" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'
```

#### Respuesta 201

```json
{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=createEquivalentDocument&ejemplo=pos)

## Calcular un documento equivalente sin emitirlo

`POST /v1/equivalent_documents/preview` · `previewEquivalentDocument`

Valida y calcula los totales **sin** reservar un número ni enviar nada. No pide `Idempotency-Key`.

**Cuerpo** ([EquivalentDocumentInput](/docs/api/objetos#EquivalentDocumentInput), obligatorio)

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

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | Totales ([Preview](/docs/api/objetos#Preview)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`POST /v1/equivalent_documents/preview` (`previewEquivalentDocument`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/equivalent_documents/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'
```

[Probar en el Playground](https://platform.trevol.si/playground?op=previewEquivalentDocument&ejemplo=pos)

## Reenviar una pendiente o en error

`POST /v1/equivalent_documents/{id}/send` · `sendEquivalentDocument`

Vuelve a enviar un documento equivalente `pending` o `error`. En contingencia devuelve el documento (lo reenvía Trevol). Con el set de pruebas en curso (`validating`) solo consulta: no lo vuelve a mandar.

Sin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | El documento ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| 202 | Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| 409 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`POST /v1/equivalent_documents/{id}/send` (`sendEquivalentDocument`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/send" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

#### Respuesta 200

```json
{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=sendEquivalentDocument)

## Listar (documento equivalente)

`GET /v1/equivalent_documents` · `listEquivalentDocuments`

Paginación por cursor (`limit` hasta 100, `starting_after`) y filtros `status`, `external_id`, `created_from` y `created_to`. `status=error` trae también los que están en verificación (`processing`). Además, `document_type` filtra por tipo.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `limit` | consulta | entero |  |  |
| `starting_after` | consulta | texto |  |  |
| `status` | consulta | texto |  |  |
| `external_id` | consulta | texto |  |  |
| `created_from` | consulta | texto |  |  |
| `created_to` | consulta | texto |  |  |
| `document_type` | consulta | `20` \| `25` \| `27` \| `30` \| `35` \| `40` \| `45` \| `50` \| `55` \| `60` |  |  |

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | {object: list, data, has_more, next_cursor} (objeto) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/equivalent_documents` (`listEquivalentDocuments`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_documents?limit=100" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

[Probar en el Playground](https://platform.trevol.si/playground?op=listEquivalentDocuments)

## Un documento equivalente

`GET /v1/equivalent_documents/{id}` · `retrieveEquivalentDocument`

El documento equivalente tal como se emitió. `contingency` dice si salió en contingencia (07 u 08) y, en la 08, cuándo se mandó el respaldo POS.

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | El documento ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/equivalent_documents/{id}` (`retrieveEquivalentDocument`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

#### Respuesta 200

```json
{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=retrieveEquivalentDocument)

## Archivo pdf

`GET /v1/equivalent_documents/{id}/pdf` · `downloadEquivalentDocumentPdf`

La representación gráfica (`application/pdf`). Si todavía no se hizo, se genera en el momento.

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | pdf (archivo) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/equivalent_documents/{id}/pdf` (`downloadEquivalentDocumentPdf`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_pdf.pdf
```

[Probar en el Playground](https://platform.trevol.si/playground?op=downloadEquivalentDocumentPdf)

## Archivo xml

`GET /v1/equivalent_documents/{id}/xml` · `downloadEquivalentDocumentXml`

El XML firmado que se mandó a la DIAN (`application/xml`).

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | xml (archivo) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/equivalent_documents/{id}/xml` (`downloadEquivalentDocumentXml`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_xml.xml
```

[Probar en el Playground](https://platform.trevol.si/playground?op=downloadEquivalentDocumentXml)

## Archivo zip

`GET /v1/equivalent_documents/{id}/zip` · `downloadEquivalentDocumentZip`

El ZIP de entrega con el XML firmado y el PDF (`application/zip`).

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | zip (archivo) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/equivalent_documents/{id}/zip` (`downloadEquivalentDocumentZip`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_zip.zip
```

[Probar en el Playground](https://platform.trevol.si/playground?op=downloadEquivalentDocumentZip)

## Archivo dian_response

`GET /v1/equivalent_documents/{id}/dian_response` · `downloadEquivalentDocumentDianResponse`

El `ApplicationResponse` con que la DIAN contestó (`application/xml`).

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | dian_response (archivo) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/equivalent_documents/{id}/dian_response` (`downloadEquivalentDocumentDianResponse`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_dian_response.xml
```

[Probar en el Playground](https://platform.trevol.si/playground?op=downloadEquivalentDocumentDianResponse)

## Corregir un documento equivalente rechazado (mismo número) y reenviarlo

`PUT /v1/equivalent_documents/{id}` · `correctEquivalentDocument`

Corrige un documento equivalente rechazado con el **mismo número** y lo vuelve a enviar. Con el set de pruebas en curso responde `409 invalid_state`.

Solo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | cabecera | texto | sí | Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días). |

**Cuerpo** ([EquivalentDocumentInput](/docs/api/objetos#EquivalentDocumentInput), obligatorio)

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

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | El documento ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| 202 | Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. ([EquivalentDocument](/docs/api/objetos#EquivalentDocument)) |
| 409 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`PUT /v1/equivalent_documents/{id}` (`correctEquivalentDocument`)

#### cURL

```bash
curl -X PUT "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'
```

#### Respuesta 200

```json
{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=correctEquivalentDocument&ejemplo=pos)