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 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.
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.
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. |
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.
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.
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. |
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 — 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 — 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 — 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) — 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 — 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 — el modelo de notificaciones push y su estado actual.
- Servidor MCP — la misma API, expuesta a tu agente por herramientas tipadas.
Última actualización