# Notas crédito

> Las operaciones de Notas crédito de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Fuente: https://platform.trevol.si/docs/api/credit-notes

Notas crédito electrónicas.

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 crédito

`POST /v1/credit_notes` · `createCreditNote`

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

**Respuestas**

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

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/credit_notes" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "DEV-2026-000045",
  "concept": "1",
  "description": "Devolución de una unidad por empaque dañado",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Café especial 500 g",
      "code": "CAF-500",
      "unit": "94",
      "quantity": "1",
      "unit_price": "32000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'
```

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

## Calcular una nota crédito sin emitirla

`POST /v1/credit_notes/preview` · `previewCreditNote`

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

**Respuestas**

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

`POST /v1/credit_notes/preview` (`previewCreditNote`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/credit_notes/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "DEV-2026-000045",
  "concept": "1",
  "description": "Devolución de una unidad por empaque dañado",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Café especial 500 g",
      "code": "CAF-500",
      "unit": "94",
      "quantity": "1",
      "unit_price": "32000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'
```

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

## Reenviar una pendiente o en error

`POST /v1/credit_notes/{id}/send` · `sendCreditNote`

**Respuestas**

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

`POST /v1/credit_notes/{id}/send` (`sendCreditNote`)

#### cURL

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

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

## Listar (nota crédito)

`GET /v1/credit_notes` · `listCreditNotes`

**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/credit_notes` (`listCreditNotes`)

#### cURL

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

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

## Una nota crédito

`GET /v1/credit_notes/{id}` · `retrieveCreditNote`

**Respuestas**

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

`GET /v1/credit_notes/{id}` (`retrieveCreditNote`)

#### cURL

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

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

## Archivo pdf

`GET /v1/credit_notes/{id}/pdf` · `downloadCreditNotePdf`

**Respuestas**

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

`GET /v1/credit_notes/{id}/pdf` (`downloadCreditNotePdf`)

#### cURL

```bash
curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_pdf.pdf
```

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

## Archivo xml

`GET /v1/credit_notes/{id}/xml` · `downloadCreditNoteXml`

**Respuestas**

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

`GET /v1/credit_notes/{id}/xml` (`downloadCreditNoteXml`)

#### cURL

```bash
curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_xml.xml
```

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

## Archivo zip

`GET /v1/credit_notes/{id}/zip` · `downloadCreditNoteZip`

**Respuestas**

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

`GET /v1/credit_notes/{id}/zip` (`downloadCreditNoteZip`)

#### cURL

```bash
curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_zip.zip
```

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

## Archivo dian_response

`GET /v1/credit_notes/{id}/dian_response` · `downloadCreditNoteDianResponse`

**Respuestas**

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

`GET /v1/credit_notes/{id}/dian_response` (`downloadCreditNoteDianResponse`)

#### cURL

```bash
curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_dian_response.xml
```

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

## Corregir una nota crédito rechazada (mismo número) y reenviarla

`PUT /v1/credit_notes/{id}` · `correctCreditNote`

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

**Respuestas**

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

`PUT /v1/credit_notes/{id}` (`correctCreditNote`)

#### cURL

```bash
curl -X PUT "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "DEV-2026-000045",
  "concept": "1",
  "description": "Devolución de una unidad por empaque dañado",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Café especial 500 g",
      "code": "CAF-500",
      "unit": "94",
      "quantity": "1",
      "unit_price": "32000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'
```

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