# Notta

> El SII chileno como API. Facturación electrónica para humanos y agentes LLM.
> Emites por API REST; consultas y automatizas lecturas por MCP (y también emites, si la empresa lo habilita); o usas el dashboard web.

Notta emite, respalda y automatiza documentos tributarios chilenos (SII): factura
electrónica, factura exenta, nota de crédito, nota de débito y guía de despacho. La
boleta electrónica, la boleta exenta y la boleta de honorarios están en camino. La
herramienta de línea de comandos también. No reemplaza un ERP.

## Cuándo usar Notta (y cuándo no)

**Úsala para**: emitir documentos tributarios chilenos (factura 33, factura exenta 34, nota de crédito 61, nota de débito 56, guía de despacho 52 y, si la empresa tiene el tipo autorizado, exportación 110/112); consultar el estado de un documento ante el SII; leer las compras que llegan por la Casilla de Intercambio y el Registro de Compras y Ventas; acusar recibo o reclamar una factura de un proveedor.

**No la uses para**: contabilidad completa o ERP (Notta no reemplaza uno), remuneraciones, cobranza ni conciliación bancaria. La boleta electrónica (39/41), la boleta de honorarios y la herramienta de línea de comandos **todavía no están disponibles**: no intentes emitirlas ni instalarla.

**Lo que necesitas antes de la primera emisión**, y que un agente NO puede hacer solo: una persona crea la cuenta y la API key, sube el certificado digital `.p12` y su clave, y consigue folios (`POST /caf/request` los pide al SII, y ese trámite es irreversible).

**Reglas de operación**:

- Toda emisión exige una `Idempotency-Key` que pones tú. Repetir la MISMA clave es un reintento; una clave nueva es un documento nuevo y real ante el SII.
- La emisión es asíncrona: el `202` significa "encolado", no "aceptado". Ramifica por el bloque `estado` (`terminal`, `categoria`, `accion`), nunca por `sii_status === "EPR"`.
- No reintentes un `4xx` sin cambiar el pedido. Ante un `429` respeta `Retry-After`; las respuestas de los endpoints con freno traen `RateLimit`/`RateLimit-Remaining` para que te espacies antes de topar.
- Nunca uses una bandera de override legal (`override_cedida`, `override_plazo_anulacion`) por tu cuenta: eximen de la ley, no de un umbral, y las aprueba una persona.

## Documentación

### Primeros pasos

- [Tu primer DTE](/docs): De cero a una factura aceptada en maullin, el sandbox del SII, paso a paso.
- [Conceptos](/docs/concepts): El vocabulario mínimo del facturador chileno, con ejemplos reales de cada pieza.
- [Autenticación](/docs/authentication): API keys con esquema Bearer, prefijos por entorno, scopes y rotación.
- [Subir certificado](/docs/onboarding-cert): El .p12 de tu PSC queda cifrado con envelope encryption — paso a paso por dashboard y API.
- [Próximos pasos](/docs/next-steps): Producción, notas de crédito, webhooks y agentes. Las rutas típicas después del quickstart.

### Facturas

- [Factura afecta (33)](/docs/emit-factura-33): Campos, request por los 3 canales programáticos, response 202 y la tabla completa de estados SII, la referencia canónica de la familia de facturas.
- [Factura exenta (34)](/docs/factura-exenta-34): El delta sobre la factura afecta, items 100% exentos, IVA cero y el error 422 que te redirige a la 33 cuando mezclas afectos.

### Boletas

- [Boleta afecta (39)](/docs/boleta-39): En camino, pendiente de certificación ante el SII. Emisión B2C por el pipeline REST, receptor opcional, IVA incluido en el precio y batch de hasta 1.000 documentos.
- [Boleta exenta (41)](/docs/boleta-exenta-41): En camino, pendiente de certificación ante el SII. El delta sobre la boleta afecta, con items 100% exentos, IVA cero y todo el monto registrado como exento.
- [Boleta de honorarios (BHE)](/docs/bhe): En camino, pendiente de certificación ante el SII. Retención vigente del año, cálculo del líquido y anulación dentro del plazo legal de 3 meses.

### Notas de crédito y débito

- [Nota de crédito (61)](/docs/nota-credito-61): Anula o corrige una factura aceptada con los códigos de referencia correctos, dentro del plazo legal y sin chocar con el bloqueo de factura cedida.
- [Nota de débito (56)](/docs/nota-debito-56): Aumenta el monto de un documento emitido declarando la causal correcta. Las 3 razones válidas, sus combos de cod_ref y el bloqueo del Oficio SII 2011/2020.

### Operar

- [Pasa a producción](/docs/produccion): Requisitos, certificación ante el SII y el switch de maullin a palena. El camino completo para emitir con valor tributario.
- [RCV y F29](/docs/rcv-f29): Sincroniza el registro de compras y ventas del SII y obtén tu declaración mensual de IVA propuesta, lista para verificar antes de presentar.
- [Reclamo del receptor](/docs/reclamos): Cuando tu cliente reclama ante el SII un documento que le emitiste: en qué se diferencia del rechazo del SII, las 192 horas del plazo legal y por qué el reclamo no se puede revertir.
- [Webhooks](/docs/webhooks): Recibe por push cada cambio de estado SII de tus documentos, firmado con Notta-Signature y con reintentos durables.

### Referencia de la API

- [Referencia de la API](/docs/api-reference): Base URL, autenticación, status codes, convenciones de idempotencia y errores, y el índice completo de endpoints por recurso
- [API: DTEs](/docs/api/dtes): Emisión asíncrona de facturas (33/34), notas (56/61) y exportación (110/112), lectura de detalle, PDF, XML firmado y re-consulta de estado al SII
- [API: Boletas](/docs/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
- [API: BHE](/docs/api/bhe): En camino, pendiente de certificación ante el SII. Boleta de Honorarios Electrónica con retención de segunda categoría calculada por ley, listado con filtros por período y anulación dentro del plazo legal
- [API: Certificados](/docs/api/certificates): Subida, listado y eliminación del certificado digital .p12 con el que Notta firma tus DTE, cifrado con envelope encryption por organización
- [API: Folios (CAF)](/docs/api/caf): Carga, inventario y eliminación de los archivos CAF que autorizan tus rangos de folios por tipo de DTE, con alerta de folios bajos
- [Paginación](/docs/pagination): Parámetros de orden y límite, el envelope { data, next_cursor } y cómo iterar listados grandes sin sorpresas.
- [Límites de tasa](/docs/rate-limits): Shape del 429, dónde viene el tiempo de espera y el patrón de backoff que también cubre los errores transitorios del SII.
- [Catálogo de errores](/docs/errors): Referencia de los códigos que emite la API, con next_action accionable por código y request_id para correlacionar con soporte.
- [Versionado y estabilidad](/docs/versionado): Qué partes de /api/v1 puedes tratar como contrato y cómo te enteras cuando algo va a cambiar.

### Para agentes

- [Notta para agentes](/docs/agentes): Artefactos máquina-legibles, contrato de errores accionable y MCP, todo lo que un LLM necesita para operar facturación chilena con una API key.
- [Estados del DTE](/docs/estados-dte): Todos los estados de un DTE con su categoría, cuál es terminal y qué hacer con cada uno, más la cadencia real del seguimiento ante el SII.
- [Servidor MCP](/docs/mcp): Conecta tu agente LLM al servidor MCP remoto de Notta por HTTP, dos herramientas sobre un catálogo de 24 operaciones, con OAuth, techo por empresa y aprobación humana

### Herramientas

- [Referencia del CLI (en camino)](/docs/cli-reference): Los comandos, flags y formatos de salida previstos para el CLI, todavía no se puede instalar

## Herramientas para agentes

- **API REST**: base `https://app.notta.cl/api/v1`. Spec OpenAPI: [/openapi.json](/openapi.json) (también en [/docs/api/openapi.json](/docs/api/openapi.json)). Los permisos con nombre viven en `components.securitySchemes`: cada operación declara el scope que exige.
- **MCP server (remoto)**: endpoint `https://app.notta.cl/api/mcp`; tools `discover` y `execute` sobre un catálogo de 24 operaciones (autentica con OAuth, no con tu API key). Las tres que están detrás de un permiso de escritura viven en ese catálogo pero apagadas de fábrica: las habilita la empresa. Emitir sale directo bajo el umbral que fije; acusar o reclamar una compra ante el SII espera aprobación humana SIEMPRE, sin umbral, porque no se deshace; `refreshDteStatus` (destrabar un documento cuyo seguimiento ante el SII se detuvo) no pasa por umbral ni aprobación, no crea ni cambia nada, y comparte el permiso `dte:write` con la emisión. `execute({ operation, params, body })` la despacha; la `Idempotency-Key` la pone el llamante, y repetirla es lo único que separa un reintento de un segundo documento real.
- **CLI**: EN CAMINO, todavía no se puede usar: `@notta/cli` no está publicado en npm, así que `npm i -g @notta/cli` falla. No intentes instalarlo ni invocar el binario `notta`; usa la API REST o el MCP.

## Cómo se cierra el ciclo de una emisión

La emisión es **asíncrona**: `POST /api/v1/dtes` responde `202` con `sii_status: "queued"`, y el veredicto del SII llega minutos después. El `202` NO significa "aceptado".

Toda respuesta que trae `sii_status` trae también un bloque `estado` con ese mismo valor ya clasificado: `terminal` (¿hay veredicto del SII?), `categoria` (`en_proceso` · `aceptado` · `rechazado` · `requiere_accion` · `archivistico`) y `accion` (`esperar` · `reintentar_consulta` · `reemitir` · `contactar_soporte` · `accion_en_sii` · `ninguna`). Espera hasta `estado.terminal === true` y ramifica por `estado.categoria`, **nunca** cortes por `sii_status === "EPR"`, porque un rechazo también es final y ese bucle no termina. `estado.code` es un string, no un enum: un código que no reconozcas NO es terminal.

- Tabla completa de estados, cadencia del seguimiento y algoritmo de espera: [/docs/estados-dte](/docs/estados-dte)
- Push firmado en vez de preguntar: `POST /api/v1/webhooks` (scope `webhook:write`) registra una URL https a la que Notta hace POST con cada transición, con firma `Notta-Signature` y reintentos. Suscribirse a `dte.accepted` y `dte.rejected` entrega sólo el desenlace. NO está en el catálogo MCP a propósito: registrar un callback es del humano que integra. Detalle en [/docs/webhooks](/docs/webhooks)
- Transiciones de un documento (endpoint canónico de PULL, y el camino de recuperación si una entrega de webhook no llega): `GET /api/v1/dtes/{id}/events`, y `GET /api/v1/dtes?polled_since=` para ponerse al día en bloque
- Notta ya lleva cada documento a su estado final por su cuenta. `POST /api/v1/dtes/{id}/refresh-status` es una escotilla para un seguimiento que se murió, no el mecanismo de seguimiento: dos de sus tres respuestas `2xx` no hacen nada.

## Markdown para LLMs

- **Negociación de contenido**: cualquier página del sitio responde markdown si pides `Accept: text/markdown` sobre su URL canónica (mismo URL, `Vary: Accept`). Sirve para `/`, `/pricing`, `/docs/*` y el resto del sitio.
- Corpus completo en un archivo: [/llms-full.txt](/llms-full.txt)
- Cada página de la doc se sirve además como markdown agregando `.md` a su URL (ej. [/docs/emit-factura-33.md](/docs/emit-factura-33.md))
- Precios en markdown: [/pricing.md](/pricing.md)
- Una URL que no existe responde **404** con cuerpo markdown y punteros (nunca 200 con el shell del sitio).

## Descubrimiento para máquinas

- [/openapi.json](/openapi.json): spec OpenAPI 3.0 de la API REST (operaciones, esquemas, scopes)
- [/.well-known/api-catalog](/.well-known/api-catalog): catálogo de APIs en Linkset (RFC 9727)
- [/.well-known/mcp.json](/.well-known/mcp.json): manifiesto del servidor MCP remoto (tools + catálogo de operaciones)
- [/.well-known/oauth-protected-resource](/.well-known/oauth-protected-resource): metadata del recurso protegido con `scopes_supported` (RFC 9728)
- [/.well-known/oauth-authorization-server](/.well-known/oauth-authorization-server): endpoints OAuth 2.1 + PKCE del MCP (RFC 8414)
- [/sitemap.xml](/sitemap.xml): todas las URLs publicadas
- Errores de la API: SIEMPRE JSON, con `code`, `message`, `request_id` y, cuando aplica, `hint`, `next_action` y `docs_url`. Catálogo completo en [/docs/errors](/docs/errors).

## Confianza

- Seguridad (controles reales, subprocesadores, Ley 21.719): [/seguridad](/seguridad)
- Estado de los sistemas (API Notta + rieles SII): [/status](/status)

## Sitio

- [/](/): landing general de Notta
- [/pyme](/pyme): PyMEs de servicios
- [/partners](/partners): empresas que implementan Notta con sus clientes
- [/enterprise](/enterprise): equipos con volumen y compliance
- [/pricing](/pricing): planes