Autenticación
API keys con esquema Bearer — prefijos por entorno, scopes y rotación.
Todas las requests a la API de Notta se autentican con un API key en el
header Authorization, usando el esquema Bearer:
No hay sesiones ni OAuth para la API: el key es la credencial. Trátalo como una contraseña — quien lo tenga puede emitir DTEs en nombre de tu organización.
Entornos: cert y producción
Cada key está vinculada a un entorno SII. El prefijo del key determina a qué entorno van tus emisiones:
| Prefijo | Entorno | Estado |
|---|---|---|
ntt_cert_… | Cert / sandbox (maullin.sii.cl) | Disponible desde el día 1, sin tarjeta |
ntt_prod_… | Producción (palena.sii.cl) | Requiere certificación SII como emisor electrónico |
Un key ntt_cert_ siempre va a maullin (sandbox, sin valor tributario).
Un key ntt_prod_ siempre va a palena (valor tributario real).
El entorno es fijo por key — no depende de la configuración de tu org.
Keys anteriores con prefijo rk_test_
Las keys creadas antes del rediseño de prefijos empiezan con rk_test_ y siguen
funcionando igual — apuntan a cert (maullin). No necesitas rotar tus keys
existentes por este cambio.
Obtener y rotar keys
- Crear: crea una key directo en el dashboard. El secreto se muestra una sola vez; guárdalo en tu gestor de secretos.
- Scopes: cada key se limita a scopes. Los de DTE son
dte:readydte:write(ydte:emit). Un request que requiere un scope que el key no tiene responde403 forbidden, con unhintque indica el scope faltante (p. ej.dte:write). - Rotar: genera un key nuevo, despliégalo, y recién después revoca el viejo. La revocación es inmediata.
Errores de autenticación
| Código | HTTP | Cuándo | next_action |
|---|---|---|---|
unauthorized | 401 | Falta el header Authorization: Bearer | send_bearer_token |
invalid_api_key | 401 | Key inválida (no matchea) | regenerate_api_key |
api_key_revoked | 401 | Key revocada | regenerate_api_key |
api_key_expired | 401 | Key expirada | regenerate_api_key |
forbidden | 403 | Key sin el scope requerido | use_api_key_with_required_scope |
El catálogo completo está en Errores.
Nunca publiques un key
No pongas un key en código cliente, repos ni logs. Si se filtra, revócalo de inmediato desde el dashboard.
Próximos pasos
- Tu primer DTE — usa tu key recién creada para emitir una Factura 33 en sandbox.
- Errores — catálogo completo con
next_actionpor código. - Rate limits — cuotas por key y cómo leer los headers de límite.
- Servidor MCP — conecta tu agente por API key o por OAuth sin instalar nada.
Última actualización