Referencia de la API
Base URL, autenticación, status codes, convenciones de idempotencia y errores, y el índice completo de endpoints por recurso
La API REST de Notta es la base de los 2 canales programáticos (API, 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.
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.
/certificates y /caf aceptan las dos credenciales (Bearer o cookie de sesión del dashboard) y usan scopes propios: certificates:read / certificates:write y caf:write: 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. Entérate del desenlace con un webhook, o pollea links.self / links.events. |
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. |
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. GET /dtes ya pagina por cursor: pasas el next_cursor en ?cursor= sin cambiar sort/dir. El resto de los listados responde next_cursor: null mientras se les habilita, así que el mismo bucle, iterar mientras no sea null, sirve para todos. Ver Paginación.
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.
X-Request-Id. Toda respuesta lo lleva, incluidos los 200 y los cuerpos que no son JSON (XML, PDF, ZIP). Es el identificador con el que soporte encuentra tu request exacto: guárdalo también cuando la respuesta fue exitosa.
Rate limits. El 429 trae retryAfterSec; usa backoff exponencial con jitter, igual que para 503 del SII, ver Rate limits. Hoy no hay un límite numérico publicado; el contrato 429 ya es estable.
Índice de recursos
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. |
GET | /dtes/:id/events | Feed cronológico de transiciones de estado con la glosa del SII: el camino de seguimiento. |
POST | /dtes/:id/refresh-status | Escotilla para revivir un poll muerto; responde 202 si encola, 200 si no había nada que hacer. |
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 — boletas 39/41 (pipeline REST) · en camino
Pendientes de certificación ante el SII: estos endpoints no están disponibles todavía y responden 404. La tabla documenta el contrato con el que quedarán expuestos.
| 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 — boletas de honorarios · en camino
Mismo estado que las boletas: pendiente de certificación, hoy responde 404.
| 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 — 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. |
POST | /certificates/:id/activate | Fijar cuál certificado firma por defecto (rotación sin tocar tu código). |
DELETE | /certificates/:id | Eliminar (soft delete) un certificado. |
Folios (CAF) — rangos autorizados
| Método | Path | Descripción |
|---|---|---|
POST | /caf/request | Pedirle folios al SII (timbraje on-demand). ⚠️ El grant es irreversible. |
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. |
Webhooks: push firmado de cambios de estado
| Método | Path | Descripción |
|---|---|---|
POST | /webhooks | Registrar una URL https de callback (Idempotency-Key obligatorio). El secret de firma sale solo aquí. |
GET | /webhooks | Listar las suscripciones del ambiente de la key, sin el secret. |
POST | /webhooks/:id/rotate-secret | Rotar el signing secret; el anterior deja de firmar de inmediato. |
POST | /webhooks/:id/test | Encolar una entrega de prueba contra tu URL (202). |
DELETE | /webhooks/:id | Borrar la suscripción y su registro de entregas (204). |
Este índice no es la API completa. /rcv (Registro de Compras y Ventas) se documenta en RCV y F29 y /recepcion en Reclamos. Sin documentar aún: /rcof (consumo diario de folios de boletas, RCOF). El contrato exhaustivo, con schemas y códigos de respuesta, es el spec OpenAPI del principio de esta página.
Próximos pasos
- API: DTEs, el recurso central: emite tu primera factura con un curl.
- Autenticación: API keys, scopes y entornos test/live.
- Catálogo de errores: todos los códigos con su
next_action. - Webhooks: push firmado a tu URL con cada cambio de estado, con reintentos.
- Servidor MCP: la misma API, expuesta a tu agente por herramientas tipadas.
Última actualización