---
title: Referencia de la API
description: Base URL, autenticación, status codes, convenciones de idempotencia y errores, y el índice completo de endpoints por recurso
url: https://notta.cl/docs/api-reference
related:
  - https://notta.cl/docs/api/dtes
  - https://notta.cl/docs/authentication
  - https://notta.cl/docs/errors
  - https://notta.cl/docs/webhooks
  - https://notta.cl/docs/mcp
---

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

# Referencia de la API

La API REST de Notta es la base de los 3 canales programáticos (API, CLI, MCP) + el dashboard: todo lo que ves aquí es lo mismo que ejecutan los otros canales por debajo. Esta página resume el contrato común; cada recurso tiene su página con parámetros, ejemplos y errores endpoint por endpoint.

El spec OpenAPI completo se sirve en [`/docs/api/openapi.json`](/docs/api/openapi.json).

## Base URL y autenticación

Todos los endpoints viven bajo `https://app.notta.cl/api/v1`. La API se autentica con `Authorization: Bearer ntt_cert_...` (scopes `dte:read` / `dte:write`); los POST de emisión llevan además `Idempotency-Key`, y los de `/dtes` y `/boletas` el header `X-Cert-Id` — ver [Autenticación](/docs/authentication).

```bash
curl https://app.notta.cl/api/v1/dtes \
  -H "Authorization: Bearer ntt_cert_..."
```

Excepción: `/certificates` y `/caf` se autentican hoy con la sesión del dashboard (cookie de Supabase Auth), no con API key — el detalle está en sus páginas.

## Status codes

| HTTP | Significado en Notta |
|---|---|
| `200` | Lectura o acción síncrona exitosa (detalle, listado, anulación de BHE, borrado). |
| `201` | Recurso creado de forma síncrona (`POST /certificates`, `POST /caf`). |
| `202` | Emisión **aceptada y encolada**: el documento sale con `sii_status: "queued"` y el envío al SII corre asíncrono — haz polling con `links.self`. |
| `400` | Request malformado: JSON inválido, falta `Idempotency-Key` o `X-Cert-Id`, o `validation_failed` con `issues[]` de Zod. |
| `401` | Credencial ausente, inválida, revocada o expirada (`unauthorized`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`). |
| `402` | Cuota mensual del plan agotada (`billing.free_tier_exceeded`, con `usedThisMonth` y `limit` en `detail`). |
| `403` | El API key no tiene el scope que la operación requiere (`forbidden`). |
| `404` | Recurso inexistente o de otra organización (mismo 404 en ambos casos — no se filtra existencia cross-tenant). |
| `409` | Conflicto de estado: `idempotency_conflict`, PDF de un DTE sin firmar, CAF con DTEs aceptados por el SII. |
| `412` | `org.required` — los endpoints de sesión exigen una organización creada en el onboarding. |
| `422` | Regla de negocio o compliance: CAF agotado, certificado vencido, NC fuera de plazo (Ley 21.398), intereses moratorios legales bloqueados (Oficio 2011/2020). |
| `429` | Rate limit (`rate_limit` con `retryAfterSec`) — ver [Rate limits](/docs/rate-limits). |
| `5xx` | `500 internal_error` (nunca expone detalles internos), `502` pipeline o SII con respuesta inválida, `503` SII o dependencia no disponible (reintenta con backoff). |

## Convenciones

**Idempotencia.** Todo POST de emisión (`/dtes`, `/boletas`, `/bhe`) exige el header `Idempotency-Key` (genera un UUID por intento). Reintentar con el mismo key y el mismo body devuelve el documento ya creado; mismo key con body distinto responde `409 idempotency_conflict`. Los lotes de boletas usan `batch_idempotency_key` en el body.

**Paginación.** Los listados devuelven el envelope `{ data | boletas | bhes, next_cursor }` con `limit` (máx. 100) y, donde aplica, `sort`/`dir`. El cursoring incremental está en habilitación: programa iterando mientras `next_cursor` no sea `null` — ver [Paginación](/docs/pagination).

**Errores.** Shape uniforme `{ code, message, hint?, next_action?, detail?, request_id }`; los fallos de validación agregan `issues[]` (Zod). El campo `next_action` es enumerable para que un agente decida sin parsear el `message` — el catálogo completo está en [Errores](/docs/errors).

**Rate limits.** El `429` trae `retryAfterSec`; usa backoff exponencial con jitter, igual que para `503` del SII — ver [Rate limits](/docs/rate-limits). Hoy no hay un límite numérico publicado; el contrato `429` ya es estable.

## Índice de recursos

### [DTEs](/docs/api/dtes) — facturas y notas (pipeline SOAP)

| Método | Path | Descripción |
|---|---|---|
| `POST` | `/dtes` | Emitir factura 33/34 o nota 56/61 (asíncrono, `202`). |
| `GET` | `/dtes` | Listar DTEs con `limit`/`sort`/`dir`. |
| `GET` | `/dtes/:id` | Detalle con ítems, estado SII y `track_id`. |
| `GET` | `/dtes/:id/pdf` | Representación impresa (PDF con timbre PDF417). |
| `GET` | `/dtes/:id/xml` | XML firmado del DTE. |
| `POST` | `/dtes/:id/refresh-status` | Re-consultar el estado al SII (asíncrono, `202`). |
| `GET` | `/dtes/muestras` | ZIP de Muestras Impresas (flujo de certificación SII). |
| `POST` | `/dtes/muestras/send` | Enviar las muestras al SII por correo (flujo de certificación SII). |

### [Boletas](/docs/api/boletas) — boletas 39/41 (pipeline REST)

| Método | Path | Descripción |
|---|---|---|
| `POST` | `/boletas` | Emitir boleta 39 o 41 (asíncrono, `202`). |
| `GET` | `/boletas` | Listar boletas con `limit`. |
| `GET` | `/boletas/:id` | Detalle de una boleta. |
| `GET` | `/boletas/:id/xml` | XML firmado de la boleta. |
| `POST` | `/boletas/batch` | Iniciar un lote de hasta 1.000 boletas. |
| `GET` | `/boletas/batch/:id` | Estado del lote con contadores de progreso. |

### [BHE](/docs/api/bhe) — boletas de honorarios

| Método | Path | Descripción |
|---|---|---|
| `POST` | `/bhe` | Emitir BHE con retención calculada por ley (asíncrono, `202`). |
| `GET` | `/bhe` | Listar BHE con filtros por período, estado y anulación. |
| `GET` | `/bhe/:id` | Detalle de una BHE. |
| `POST` | `/bhe/:id/anular` | Anular dentro del plazo legal de 3 meses. |

### [Certificados](/docs/api/certificates) — firma digital

| Método | Path | Descripción |
|---|---|---|
| `POST` | `/certificates` | Subir un `.p12` (multipart); devuelve el id para `X-Cert-Id`. |
| `GET` | `/certificates` | Listar certificados vigentes. |
| `DELETE` | `/certificates/:id` | Eliminar (soft delete) un certificado. |

### [Folios (CAF)](/docs/api/caf) — rangos autorizados

| Método | Path | Descripción |
|---|---|---|
| `POST` | `/caf` | Subir un CAF XML (multipart); registra el rango de folios. |
| `GET` | `/caf` | Inventario de CAFs con folios restantes y alerta `low_folios`. |
| `DELETE` | `/caf/:id` | Eliminar un CAF sin DTEs aceptados por el SII. |

Sin documentar aún: `/rcof` (consumo diario de folios de boletas — RCOF).

## Próximos pasos

- **[API: DTEs](/docs/api/dtes)** — el recurso central: emite tu primera factura con un curl.
- [Autenticación](/docs/authentication) — API keys, scopes y entornos test/live.
- [Catálogo de errores](/docs/errors) — todos los códigos con su `next_action`.
- [Webhooks](/docs/webhooks) — el modelo de notificaciones push y su estado actual.
- [Servidor MCP](/docs/mcp) — la misma API, expuesta a tu agente por herramientas tipadas.