---
title: "API: Boletas"
description: Emisión de boletas electrónicas 39 y 41 por el pipeline REST del SII, con detalle, XML firmado y lotes de hasta 1.000 documentos
url: https://notta.cl/docs/api/boletas
related:
  - https://notta.cl/docs/boleta-39
  - https://notta.cl/docs/boleta-exenta-41
  - https://notta.cl/docs/api/dtes
  - https://notta.cl/docs/rate-limits
---

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

# "API: Boletas"

El recurso `/boletas` emite Boleta Electrónica afecta (39) y Boleta Exenta (41). Las boletas viajan por el pipeline REST del SII (`bolcoreinternetui`), separado del SOAP de facturas — por eso viven en su propio recurso y no en [`/dtes`](/docs/api/dtes).

Base URL: `https://app.notta.cl/api/v1`. La autenticación es la misma del recurso DTEs: `Authorization: Bearer ntt_cert_…` con scope `dte:read`/`dte:write`, header `X-Cert-Id` en todo POST e `Idempotency-Key` en la emisión individual — ver [Autenticación](/docs/authentication).

En boletas los `monto_item` son **brutos** (IVA incluido): para la 39, Notta deriva `monto_neto = round(total / 1.19)` e `iva = total - neto`; en la 41 todo va a `monto_exento`.

## Endpoints

### `POST /boletas`

Emite una boleta 39 o 41: asigna folio del CAF correspondiente, firma el timbre y encola el upload REST al SII.

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `tipo_dte` | int | sí | `39` (afecta) o `41` (exenta — rechaza ítems afectos). |
| `rut_emisor` | string | sí | RUT canónico `BODY-DV`, p. ej. `76123456-0`. |
| `rut_receptor` | string | no | Opcional — la venta anónima es el default. |
| `razon_social_receptor` | string | no | Opcional, acompaña a `rut_receptor`. |
| `fecha_emision` | string | sí | `YYYY-MM-DD`. |
| `items[]` | array | sí | 1 a 60 ítems: `nombre`, `cantidad` (int), `precio_unitario` (int CLP bruto), `exento` (boolean), `monto_item` (int CLP bruto). |
| `monto_neto` · `iva` · `monto_total` | int | no | Solo 39; si faltan, Notta los deriva del total bruto. |
| `monto_exento` · `monto_total` | int | no | Solo 41 (enteros positivos). |
| `certificate_id` | uuid | no | Certificado de firma; normalmente el mismo UUID de `X-Cert-Id`. |
| `sii_env` | enum | no | `cert` (default) o `prod`. |

```bash
curl -X POST https://app.notta.cl/api/v1/boletas \
  -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": 39,
    "rut_emisor": "76123456-0",
    "fecha_emision": "2026-06-09",
    "items": [
      { "nombre": "Café americano", "cantidad": 2, "precio_unitario": 1500, "exento": false, "monto_item": 3000 }
    ]
  }'
```

Respuesta `202 Accepted`:

```json
{
  "id": "01977f3b-2c60-7000-8000-000000000002",
  "tipo_dte": 39,
  "folio": 88,
  "status": "queued",
  "sii_status": "queued",
  "rut_emisor": "76123456-0",
  "rut_receptor": null,
  "monto_neto": 2521,
  "monto_exento": 0,
  "iva": 479,
  "monto_total": 3000,
  "fecha_emision": "2026-06-09",
  "sii_env": "cert",
  "links": {
    "self": "/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002",
    "xml": "/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002/xml"
  }
}
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `idempotency_key_missing` | 400 | — |
| `invalid_json` | 400 | — |
| `validation_failed` (incluye `issues[]` de Zod) | 400 | — |
| `cert_id_missing` | 400 | `send_cert_id_header` |
| `unauthorized` · `invalid_api_key` · `api_key_revoked` · `api_key_expired` | 401 | `regenerate_api_key` |
| `billing.free_tier_exceeded` | 402 | `upgrade_plan` |
| `forbidden` | 403 | `use_api_key_with_required_scope` |
| `caf_not_found` · `cert_not_found` | 404 | — |
| `idempotency_conflict` | 409 | — |
| `dte.41.afecto_not_allowed` | 422 | `fix_tipo_dte_and_retry` |
| `caf_exhausted` · `caf_expired` · `cert_expired` | 422 | — |

### `GET /boletas`

Lista las boletas (39/41) de tu organización, las más recientes primero.

| Query param | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | int | no | 1–100, default 20. |

```bash
curl "https://app.notta.cl/api/v1/boletas?limit=50" \
  -H "Authorization: Bearer ntt_cert_..."
```

Respuesta `200 OK`:

```json
{
  "boletas": [
    {
      "id": "01977f3b-2c60-7000-8000-000000000002",
      "tipo_dte": 39,
      "folio": 88,
      "rut_emisor": "76123456-0",
      "rut_receptor": null,
      "monto_total": 3000,
      "sii_status": "EPR",
      "fecha_emision": "2026-06-09",
      "created_at": "2026-06-09T16:01:12.000Z",
      "links": { "self": "/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002" }
    }
  ],
  "next_cursor": null
}
```

A diferencia de `GET /dtes`, el array viene bajo la clave `boletas` (no `data`) y todavía no soporta `sort`/`dir`.

### `GET /boletas/:id`

Devuelve el detalle de una boleta con montos desglosados, estado SII y `track_id`.

```bash
curl https://app.notta.cl/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002 \
  -H "Authorization: Bearer ntt_cert_..."
```

Respuesta `200 OK`:

```json
{
  "id": "01977f3b-2c60-7000-8000-000000000002",
  "tipo_dte": 39,
  "folio": 88,
  "rut_emisor": "76123456-0",
  "rut_receptor": null,
  "monto_neto": 2521,
  "monto_exento": 0,
  "iva": 479,
  "monto_total": 3000,
  "sii_status": "EPR",
  "sii_glosa": null,
  "track_id": 12345678,
  "fecha_emision": "2026-06-09",
  "sii_env": "cert",
  "created_at": "2026-06-09T16:01:12.000Z",
  "links": {
    "self": "/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002",
    "xml": "/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002/xml"
  }
}
```

Errores posibles:

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

### `GET /boletas/:id/xml`

Devuelve el XML firmado de la boleta (`application/xml`).

```bash
curl https://app.notta.cl/api/v1/boletas/01977f3b-2c60-7000-8000-000000000002/xml \
  -H "Authorization: Bearer ntt_cert_..."
```

Errores posibles:

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

### `POST /boletas/batch`

Inicia un lote de hasta 1.000 boletas; cada una se encola individualmente y el avance se consulta con `GET /boletas/batch/:id`.

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `batch_idempotency_key` | string | sí | 1–128 caracteres. Mismo key + mismo body → replay del mismo `batchId`; mismo key + body distinto → `409`. |
| `boletas[]` | array | sí | 1 a 1.000 boletas con el mismo shape del `POST /boletas` individual (39 o 41, mezclables). |

La idempotencia del batch va en el **body** (`batch_idempotency_key`), no en el header; cada boleta interna se deduplica por `(batch, posición)`.

```bash
curl -X POST https://app.notta.cl/api/v1/boletas/batch \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_idempotency_key": "cierre-caja-2026-06-09",
    "boletas": [
      {
        "tipo_dte": 39,
        "rut_emisor": "76123456-0",
        "fecha_emision": "2026-06-09",
        "items": [
          { "nombre": "Café americano", "cantidad": 1, "precio_unitario": 1500, "exento": false, "monto_item": 1500 }
        ]
      }
    ]
  }'
```

Respuesta `202 Accepted`:

```json
{ "batchId": "01977f4c-3d70-7000-8000-000000000003", "queued": 1 }
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `invalid_json` | 400 | — |
| `validation_error` (incluye `errors[]` con `path` + `message`) | 422 | — |
| `boleta.batch.exceeds_max` | 422 | `split_batch` |
| `boleta.batch.idempotency_conflict` | 409 | `poll_existing_or_change_key` |

### `GET /boletas/batch/:id`

Devuelve el estado del lote con los contadores de progreso por boleta.

```bash
curl https://app.notta.cl/api/v1/boletas/batch/01977f4c-3d70-7000-8000-000000000003 \
  -H "Authorization: Bearer ntt_cert_..."
```

Respuesta `200 OK`:

```json
{
  "batchId": "01977f4c-3d70-7000-8000-000000000003",
  "status": "processing",
  "total": 1,
  "queued": 0,
  "sending": 1,
  "done": 0,
  "failed": 0,
  "createdAt": "2026-06-09T16:05:00.000Z",
  "completedAt": null
}
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `boleta.batch.not_found` | 404 | `verify_batch_id` |

## Próximos pasos

- **[Boleta 39](/docs/boleta-39)** — la guía de emisión de boleta afecta con el detalle del pipeline REST.
- [Boleta Exenta 41](/docs/boleta-exenta-41) — cuándo corresponde la exenta y sus restricciones.
- [API: DTEs](/docs/api/dtes) — facturas y notas por el pipeline SOAP.
- [Rate limits](/docs/rate-limits) — backoff recomendado para volúmenes altos de boletas.