API: Boletas

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

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.

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.

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

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:

{
  "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.

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

Respuesta 200 OK:

{
  "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.

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

Respuesta 200 OK:

{
  "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).

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

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:

{ "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.

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

Respuesta 200 OK:

{
  "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 — la guía de emisión de boleta afecta con el detalle del pipeline REST.
Boleta Exenta 41 — cuándo corresponde la exenta y sus restricciones.
API: DTEs — facturas y notas por el pipeline SOAP.
Rate limits — backoff recomendado para volúmenes altos de boletas.

API: Boletas

En esta página