API: Boletas

En camino, pendiente de certificación ante el SII. Emisión de boletas electrónicas 39 y 41 por el pipeline REST, con detalle, XML firmado y lotes de hasta 1.000 documentos

En camino: las boletas 39 y 41 todavía no se emiten con Notta

La Boleta Electrónica afecta (39) y la Boleta Exenta (41) están pendientes de certificación ante el SII, así que hoy no puedes emitirlas con Notta. Esta referencia documenta el contrato con el que quedarán disponibles. Para lo que sí emites hoy (33, 34, 56, 61 y 52), usa API: DTEs.

El recurso /boletas emitirá 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). En la 39, Notta separa primero los ítems afectos de los exentos y deriva el desglose solo sobre la porción afecta: monto_neto = round(afecto / 1.19) e iva = afecto - monto_neto, mientras la porción exenta viaja entera en monto_exento. Dividir el total completo daría un desglose que cuadra en la suma y que el SII igual rechaza. En la 41 todo va a monto_exento.

Endpoints

`POST /boletas`

Emitirá una boleta 39 o 41: asignará folio del CAF correspondiente, firmará el timbre y encolará 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` (number, hasta 6 decimales), `precio_unitario` (number CLP bruto, hasta 6 decimales), `exento` (boolean), `monto_item` (int CLP bruto). En la boleta el precio y el monto son brutos (con IVA), a diferencia de la factura; el monto de línea sigue siendo entero.
`monto_neto` · `iva` · `monto_total`	int	no	Solo 39. El schema los acepta, pero Notta siempre los deriva de los `monto_item`: si los mandas, se ignoran.
`monto_exento` · `monto_total`	int	no	Solo 41 (enteros positivos). Mismo trato que la fila de arriba: se derivan de los ítems y un valor declarado se ignora.
`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": "66666666-6",
  "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": "66666666-6",
      "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": "66666666-6",
  "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