---
title: "API: DTEs"
description: Emisión asíncrona de facturas (33/34) y notas (56/61), lectura de detalle, PDF, XML firmado y re-consulta de estado al SII
url: https://notta.cl/docs/api/dtes
related:
  - https://notta.cl/docs/emit-factura-33
  - https://notta.cl/docs/api/boletas
  - https://notta.cl/docs/errors
  - https://notta.cl/docs/pagination
---

> Documentación de Notta en markdown. Índice completo: https://notta.cl/llms.txt — corpus entero: https://notta.cl/llms-full.txt

# "API: DTEs"

El recurso `/dtes` cubre los documentos que viajan por el pipeline SOAP del SII: Factura Electrónica (33), Factura Exenta (34), Nota de Débito (56) y Nota de Crédito (61). Las boletas (39/41) tienen pipeline REST propio — ver [API: Boletas](/docs/api/boletas).

Base URL: `https://app.notta.cl/api/v1`. Autenticación: `Authorization: Bearer ntt_cert_…` con scope `dte:read` para lecturas y `dte:write` para mutaciones — ver [Autenticación](/docs/authentication). Todo POST a este recurso exige además el header `X-Cert-Id` (UUID que devuelve [POST /certificates](/docs/api/certificates)) y `Idempotency-Key`.

La emisión es **asíncrona**: el POST responde `202` con `sii_status: "queued"` y el upload al SII corre en un workflow. Consulta `GET /dtes/:id` hasta ver un estado terminal (`EPR`, `RPR`, `RFR`, `RCT`).

## Endpoints

### `POST /dtes`

Emite un DTE: valida el input, asigna folio desde tu CAF, firma con tu certificado y encola el envío al SII.

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `tipo_dte` | int | sí | `33`, `34`, `56` o `61`. Las boletas 39/41 van por `POST /boletas` (aquí responden `dte.tipo_not_supported`). |
| `rut_emisor` | string | sí | RUT canónico `BODY-DV` sin puntos, p. ej. `76123456-0`. DV validado módulo 11. |
| `receptor.rut` | string | sí | RUT del receptor, p. ej. `11111111-1`. |
| `receptor.razon_social` | string | sí | Razón social (se recorta el whitespace; no puede quedar vacía). |
| `receptor.giro` · `direccion` · `comuna` | string | condicional | **Obligatorios para 33 y 34** (no vacíos): giro, dirección y comuna del receptor. En 56/61/39/41/52 son opcionales. |
| `forma_pago` | int | condicional | **Obligatorio para 33 y 34**: `1`=Contado, `2`=Crédito, `3`=Sin costo. No se exige en NC (61), ND (56), boletas (39/41) ni guías (52). |
| `fecha_emision` | string | sí | `YYYY-MM-DD`. |
| `items[]` | array | sí | 1 a 60 ítems. Cada uno: `nombre` (string), `cantidad` (int), `precio_unitario` (int CLP), `exento` (boolean), `monto_item` (int CLP — puede ser negativo en NC). |
| `references[]` | array | condicional | Obligatorias para 56 y 61; en 33/34 son opcionales y comerciales (orden de compra, contrato, HES). Ver tabla siguiente. |
| `nd_reason` | enum | 56: sí | `correccion_monto` · `reposicion_nc_anulada` · `interese_moratorio_contractual`. |
| `override_cedida` | boolean | no | Solo 61: confirma una NC sobre factura cedida (Corte Suprema 2025). |
| `monto_neto` · `monto_exento` · `iva` · `monto_total` | int | no | Si los mandas se valida coherencia aritmética contra los ítems; si no, Notta los calcula. |
| `certificate_id` | uuid | no | Certificado de firma; normalmente el mismo UUID que va en `X-Cert-Id`. |
| `sii_env` | enum | no | `cert` (default) o `prod`. |

Para 56/61, cada elemento de `references[]` lleva **todos** estos campos:

| Campo | Tipo | Descripción |
|---|---|---|
| `line_num` | int 1–40 | Número de línea de la referencia. |
| `tipo_doc_ref` | int | Tipo del documento referenciado (NC: solo 33 o 34; ND con `reposicion_nc_anulada`: 61). |
| `folio_ref` | int positivo | Folio del documento referenciado. |
| `fecha_ref` | string | `YYYY-MM-DD` del documento referenciado. |
| `cod_ref` | 1 \| 2 \| 3 | 1 anula, 2 corrige texto (exige montos en 0), 3 corrige montos. |
| `razon_ref` | string | Motivo (mínimo 1 carácter). |

> **Campos extra de 56 y 61:**
La Nota de Débito exige `nd_reason` con combos válidos de `cod_ref` (el motivo `interese_moratorio_legal` está bloqueado por el Oficio SII 2011/2020), y la Nota de Crédito aplica el plazo de 6 meses (Ley 21.398) y el bloqueo por factura cedida. El detalle completo está en [Nota de Débito 56](/docs/nota-debito-56) y [Nota de Crédito 61](/docs/nota-credito-61).

> **Requisitos de 33 y 34:**
La factura afecta (33) y la exenta (34) exigen el receptor completo — `receptor.giro`, `receptor.direccion` y `receptor.comuna` no pueden quedar vacíos — y `forma_pago` (`1`=Contado, `2`=Crédito, `3`=Sin costo). Este requisito es condicional al tipo: las notas (56/61), las boletas (39/41) y las guías (52) no lo exigen.

```bash
curl -X POST https://app.notta.cl/api/v1/dtes \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_dte": 33,
    "rut_emisor": "76123456-0",
    "receptor": { "rut": "11111111-1", "razon_social": "Cliente Ejemplo SpA", "giro": "Comercio", "direccion": "Av Siempre Viva 123", "comuna": "Santiago" },
    "forma_pago": 2,
    "fecha_emision": "2026-06-09",
    "items": [
      { "nombre": "Consultoría mayo", "cantidad": 5, "precio_unitario": 50000, "exento": false, "monto_item": 250000 }
    ]
  }'
```

Respuesta `202 Accepted`:

```json
{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "status": "queued",
  "folio": 1234,
  "tipo_dte": 33,
  "rut_emisor": "76123456-0",
  "rut_receptor": "11111111-1",
  "monto_neto": 250000,
  "monto_exento": 0,
  "iva": 47500,
  "monto_total": 297500,
  "sii_env": "cert",
  "sii_status": "queued",
  "fecha_emision": "2026-06-09",
  "links": {
    "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001",
    "pdf": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/pdf",
    "xml": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/xml",
    "events": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/events"
  }
}
```

`links.events` apunta a un endpoint aún no habilitado — para seguir el estado usa `links.self` o `refresh-status`.

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `idempotency_key_missing` | 400 | `send_idempotency_key_header` |
| `invalid_json` | 400 | `fix_json_body_and_retry` |
| `validation_failed` (incluye `issues[]` de Zod) | 400 | `fix_body_and_retry` |
| `cert_id_missing` | 400 | `send_cert_id_header` |
| `dte.tipo_not_supported` | 400 | `fix_tipo_dte_and_retry` |
| `unauthorized` · `invalid_api_key` · `api_key_revoked` · `api_key_expired` | 401 | `regenerate_api_key` |
| `billing.free_tier_exceeded` | 402 | `upgrade_plan` |
| `forbidden` (scope insuficiente) | 403 | `use_api_key_with_required_scope` |
| `caf_not_found` · `cert_not_found` | 404 | — |
| `idempotency_conflict` (mismo key, body distinto) | 409 | — |
| `caf_exhausted` · `caf_expired` · `cert_expired` · `emisor_rut_mismatch` | 422 | — |
| `dte.34.invalid_exenta` | 422 | `fix_tipo_dte_and_retry` |
| `dte.nota_credito.fuera_plazo` | 422 | `consult_lawyer_or_use_correction_path` |
| `nc.over_cedida.blocked` | 422 | `confirm_override_and_retry` |
| `dte.nota_debito.interese_moratorio_legal` | 422 | `consult_oficio_2011_2020` |
| `dte.nota_debito.invalid_reason` | 422 | `fix_reason_and_retry` |

### `GET /dtes`

Lista los DTEs de tu organización, los más recientes primero.

| Query param | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | int | no | 1–100, default 20. |
| `sort` | enum | no | `folio` · `monto_total` · `fecha_emision` · `sii_status` · `created_at`. |
| `dir` | enum | no | `asc` · `desc`. |

```bash
curl "https://app.notta.cl/api/v1/dtes?limit=50&sort=folio&dir=asc" \
  -H "Authorization: Bearer ntt_cert_..."
```

Respuesta `200 OK` (envelope de [paginación](/docs/pagination)):

```json
{
  "data": [
    {
      "id": "01977f2a-1b50-7000-8000-000000000001",
      "folio": 1234,
      "tipo_dte": 33,
      "rut_emisor": "76123456-0",
      "rut_receptor": "11111111-1",
      "monto_total": 297500,
      "sii_status": "EPR",
      "fecha_emision": "2026-06-09",
      "created_at": "2026-06-09T14:32:48.000Z",
      "links": { "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001" }
    }
  ],
  "next_cursor": null
}
```

Errores posibles: `401` (auth) y `403 forbidden` si el key no tiene `dte:read`.

### `GET /dtes/:id`

Devuelve el detalle de un DTE, incluyendo sus ítems por línea y el estado SII.

```bash
curl https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001 \
  -H "Authorization: Bearer ntt_cert_..."
```

Respuesta `200 OK`:

```json
{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "folio": 1234,
  "tipo_dte": 33,
  "rut_emisor": "76123456-0",
  "rut_receptor": "11111111-1",
  "razon_social_receptor": "Cliente Ejemplo SpA",
  "monto_neto": 250000,
  "monto_exento": 0,
  "iva": 47500,
  "monto_total": 297500,
  "sii_env": "cert",
  "sii_status": "EPR",
  "sii_glosa": null,
  "track_id": 998877665544,
  "fecha_emision": "2026-06-09",
  "created_at": "2026-06-09T14:32:48.000Z",
  "items": [
    {
      "position": 1,
      "nombre": "Consultoría mayo",
      "descripcion": null,
      "cantidad": 5,
      "precio_unitario": 50000,
      "monto_item": 250000,
      "exento": false
    }
  ],
  "links": {
    "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001",
    "pdf": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/pdf",
    "xml": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/xml",
    "events": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/events"
  }
}
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `not_found` | 404 | — |

### `GET /dtes/:id/pdf`

Descarga la representación impresa del DTE (formato SII con timbre PDF417), como `application/pdf`.

```bash
curl -o DTE-33-1234.pdf \
  https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/pdf \
  -H "Authorization: Bearer ntt_cert_..."
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `not_found` | 404 | — |
| `dte.pdf.not_signed` (todavía sin firmar; incluye `xml_url`) | 409 | `poll_self` |

### `GET /dtes/:id/xml`

Devuelve el XML firmado del DTE (`application/xml`), apto para verificación de firma y cesión.

```bash
curl https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/xml \
  -H "Authorization: Bearer ntt_cert_..."
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `not_found` | 404 | — |
| `dte.xml.not_yet_available` (workflow de firma en curso) | 404 | `poll_self` |

### `POST /dtes/:id/refresh-status`

Fuerza una re-consulta del estado del DTE al SII (útil tras una caída del SII); el poll corre en background y actualiza el documento.

```bash
curl -X POST https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/refresh-status \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `202 Accepted`:

```json
{ "id": "01977f2a-1b50-7000-8000-000000000001", "status": "refresh_enqueued" }
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `not_found` | 404 | — |
| `dte.refresh_status.no_track_id` (aún no subido al SII) | 409 | `wait_for_emit_workflow` |
| `dte.refresh_status.no_cert` (la org no tiene certificado activo) | 409 | — |

### `GET /dtes/muestras`

Flujo de certificación SII: arma un ZIP con un PDF por cada DTE firmado (33/34/56/61) de tu org para el lote de Muestras Impresas; `?source=set_pruebas` lo acota al set de pruebas.

```bash
curl -o muestras.zip "https://app.notta.cl/api/v1/dtes/muestras?source=set_pruebas" \
  -H "Authorization: Bearer ntt_cert_..."
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `dte.muestras.empty` | 422 | `emit_and_sign_dtes_first` |

### `POST /dtes/muestras/send`

Flujo de certificación SII: Notta arma y envía el correo de Muestras Impresas a `sii_dte_impresos@sii.cl` con los PDFs adjuntos.

```bash
curl -X POST https://app.notta.cl/api/v1/dtes/muestras/send \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200 OK`:

```json
{ "data": { "sent": 8, "sentAt": "2026-06-09T15:02:11.000Z" } }
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `dte.muestras.no_samples` | 422 | `emit_and_sign_dtes_first` |
| `dte.muestras.too_large` (lote supera 3MB del SII) | 422 | `paginate_into_multiple_emails` |
| `dte.muestras.send_not_configured` | 422 | `contact_support` |
| `dte.muestras.send_not_wired` | 501 | — |

## Próximos pasos

- **[Emitir Factura 33](/docs/emit-factura-33)** — la guía paso a paso del caso más común, con el mismo payload de esta referencia.
- [API: Boletas](/docs/api/boletas) — el pipeline REST para boletas 39/41, individual y en batch.
- [Catálogo de errores](/docs/errors) — todos los códigos con su `next_action` para manejo programático.
- [Paginación](/docs/pagination) — el envelope `{ data, next_cursor }` y los parámetros de orden.