# Notas de ajuste del documento equivalente

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

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

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 una nota de ajuste del documento equivalente

`POST /v1/equivalent_document_adjustments` · `createEquivalentDocumentAdjustment`

Genera la **nota de ajuste de un documento equivalente**: crédito (94) o débito (93) según `note_type`. El documento que ajusta es de Trevol (`equivalent_document.id`) o de otra plataforma. `concept` 1 a 5 (el 2 anula y lleva exactamente los valores del documento). Sin `customer` toma el del documento; en juegos el adquirente es la DIAN. Se expide como el documento: PDF, ZIP y correo.

**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** ([EquivalentDocumentAdjustmentInput](/docs/api/objetos#EquivalentDocumentAdjustmentInput), 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) |  | 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). |

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 201 | El documento ([EquivalentDocumentAdjustment](/docs/api/objetos#EquivalentDocumentAdjustment)) |
| 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`. ([EquivalentDocumentAdjustment](/docs/api/objetos#EquivalentDocumentAdjustment)) |
| 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_document_adjustments` (`createEquivalentDocumentAdjustment`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/equivalent_document_adjustments" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'
```

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

## Calcular una nota de ajuste del documento equivalente sin emitirla

`POST /v1/equivalent_document_adjustments/preview` · `previewEquivalentDocumentAdjustment`

Valida y calcula la nota de ajuste **sin** reservar un número ni enviar nada.

**Cuerpo** ([EquivalentDocumentAdjustmentInput](/docs/api/objetos#EquivalentDocumentAdjustmentInput), 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) |  | 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). |

**Respuestas**

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

`POST /v1/equivalent_document_adjustments/preview` (`previewEquivalentDocumentAdjustment`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/equivalent_document_adjustments/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'
```

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

## Reenviar una pendiente o en error

`POST /v1/equivalent_document_adjustments/{id}/send` · `sendEquivalentDocumentAdjustment`

Vuelve a enviar una nota de ajuste `pending` o `error`.

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 ([EquivalentDocumentAdjustment](/docs/api/objetos#EquivalentDocumentAdjustment)) |
| 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`. ([EquivalentDocumentAdjustment](/docs/api/objetos#EquivalentDocumentAdjustment)) |
| 409 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`POST /v1/equivalent_document_adjustments/{id}/send` (`sendEquivalentDocumentAdjustment`)

#### cURL

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

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

## Listar (nota de ajuste del documento equivalente)

`GET /v1/equivalent_document_adjustments` · `listEquivalentDocumentAdjustments`

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

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

**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_document_adjustments` (`listEquivalentDocumentAdjustments`)

#### cURL

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

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

## Una nota de ajuste del documento equivalente

`GET /v1/equivalent_document_adjustments/{id}` · `retrieveEquivalentDocumentAdjustment`

La nota de ajuste del documento equivalente, con `equivalent_document` (el documento que ajusta).

**Respuestas**

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

`GET /v1/equivalent_document_adjustments/{id}` (`retrieveEquivalentDocumentAdjustment`)

#### cURL

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

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

## Archivo pdf

`GET /v1/equivalent_document_adjustments/{id}/pdf` · `downloadEquivalentDocumentAdjustmentPdf`

La representación gráfica (`application/pdf`).

**Respuestas**

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

`GET /v1/equivalent_document_adjustments/{id}/pdf` (`downloadEquivalentDocumentAdjustmentPdf`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_pdf.pdf
```

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

## Archivo xml

`GET /v1/equivalent_document_adjustments/{id}/xml` · `downloadEquivalentDocumentAdjustmentXml`

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_document_adjustments/{id}/xml` (`downloadEquivalentDocumentAdjustmentXml`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_xml.xml
```

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

## Archivo zip

`GET /v1/equivalent_document_adjustments/{id}/zip` · `downloadEquivalentDocumentAdjustmentZip`

El ZIP de entrega (`application/zip`).

**Respuestas**

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

`GET /v1/equivalent_document_adjustments/{id}/zip` (`downloadEquivalentDocumentAdjustmentZip`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_zip.zip
```

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

## Archivo dian_response

`GET /v1/equivalent_document_adjustments/{id}/dian_response` · `downloadEquivalentDocumentAdjustmentDianResponse`

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_document_adjustments/{id}/dian_response` (`downloadEquivalentDocumentAdjustmentDianResponse`)

#### cURL

```bash
curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_dian_response.xml
```

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

## Corregir una nota de ajuste del documento equivalente rechazada (mismo número) y reenviarla

`PUT /v1/equivalent_document_adjustments/{id}` · `correctEquivalentDocumentAdjustment`

Corrige una nota de ajuste rechazada con el **mismo número** y la vuelve a enviar.

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** ([EquivalentDocumentAdjustmentInput](/docs/api/objetos#EquivalentDocumentAdjustmentInput), 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) |  | 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). |

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | El documento ([EquivalentDocumentAdjustment](/docs/api/objetos#EquivalentDocumentAdjustment)) |
| 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`. ([EquivalentDocumentAdjustment](/docs/api/objetos#EquivalentDocumentAdjustment)) |
| 409 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`PUT /v1/equivalent_document_adjustments/{id}` (`correctEquivalentDocumentAdjustment`)

#### cURL

```bash
curl -X PUT "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'
```

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