Notta Docs

Tu primer DTE

De cero a una factura aceptada en maullin, el sandbox del SII, paso a paso.

Notta emite DTEs chilenos (Documentos Tributarios Electrónicos) por los 2 canales programáticos (API, MCP) + el dashboard. Esta guía te lleva de cero a una Factura 33 aceptada en el sandbox del SII.

Antes de empezar

Necesitas dos cosas: una cuenta y una API key.

  1. Crea tu cuenta en app.notta.cl/signup.
  2. Crea tu API key directo en el dashboard.

1. Sube tu certificado

Tu certificado digital .p12 lo emite tu PSC (Acepta, eCertChile, etc). Con él Notta firma cada DTE en tu nombre. Súbelo en app.notta.cl/app/certificates: drag-and-drop del .p12, password, y listo. El dashboard es el camino más cómodo porque la contraseña del .p12 no debería viajar en un script, pero POST /api/v1/certificates también acepta Authorization: Bearer con una key de scope certificates:write.

Al subirlo, anota el id del certificado que muestra el dashboard (un UUID, p. ej. 01957a91-0b50-7000-8000-cccc00000001): lo vas a usar como header X-Cert-Id al emitir en el paso 3.

El .p12 se cifra con envelope encryption (DEK por org, KEK en Supabase Vault) antes de guardarse, y el password va dentro de ese mismo blob cifrado, nunca en claro. El detalle está en Subir certificado.

2. Carga folios (CAF)

El CAF es el archivo XML con el rango de folios que el SII te autoriza por tipo de DTE. Sin un CAF vigente la emisión falla con caf_not_found.

Tienes dos caminos, y los dos sirven con API key:

  • Pídelos por API: POST /api/v1/caf/request con {"tipo": 33} hace el timbraje contra el SII por ti y guarda el CAF. Necesitas una key con scope caf:write. Ojo: el grant es irreversible, el SII no devuelve folios.
  • Sube el XML que ya tienes: lo descargas del timbraje electrónico del SII (en maullin para el entorno cert) y lo subes tal cual, sin editar, con POST /api/v1/caf o desde app.notta.cl/app/caf.

En cualquiera de los dos vas a ver el rango autorizado (folio_desde/folio_hasta) y los folios restantes. El contrato completo está en API: Folios (CAF).

Qué es un CAF por dentro y cómo se administra: Conceptos → CAF.

3. Emite tu primera factura

Tipo 33 es la Factura Electrónica afecta a IVA, el caso más común. Elige tu canal:

curl -X POST https://app.notta.cl/api/v1/dtes \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01957a91-0b50-7000-8000-cccc00000001" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_dte": 33,
    "rut_emisor": "76123456-0",
    "receptor": {
      "rut": "11111111-1",
      "razon_social": "Cliente Ejemplo SpA",
      "giro": "Comercio",
      "direccion": "Av Siempre Viva 123",
      "comuna": "Santiago"
    },
    "forma_pago": 2,
    "fecha_emision": "2026-06-09",
    "items": [
      {
        "nombre": "Consultoría mayo",
        "cantidad": 5,
        "precio_unitario": 50000,
        "exento": false,
        "monto_item": 250000
      }
    ],
    "sii_env": "cert"
  }'

El X-Cert-Id es el id del certificado que anotaste en el paso 1: sin él, el endpoint responde 400 cert_id_missing.

Salida esperada (202 Accepted):

{
  "id": "01957a91-0b50-7000-8000-000000000001",
  "status": "queued",
  "folio": 1,
  "tipo_dte": 33,
  "rut_emisor": "76123456-0",
  "rut_receptor": "11111111-1",
  "monto_neto": 250000,
  "monto_exento": 0,
  "iva": 47500,
  "monto_total": 297500,
  "sii_env": "cert",
  "sii_status": "queued",
  "fecha_emision": "2026-06-09",
  "links": {
    "self": "/api/v1/dtes/01957a91-0b50-7000-8000-000000000001",
    "pdf": "/api/v1/dtes/01957a91-0b50-7000-8000-000000000001/pdf",
    "xml": "/api/v1/dtes/01957a91-0b50-7000-8000-000000000001/xml",
    "events": "/api/v1/dtes/01957a91-0b50-7000-8000-000000000001/events"
  }
}

links.events es el feed de transiciones del documento: GET /api/v1/dtes/{id}/events devuelve la historia completa de estados en orden cronológico, con la glosa del SII. Es el camino recomendado para seguir la emisión, ver Referencia API de DTEs.

Por MCP se consulta, y se emite con permiso

El servidor MCP de Notta te sirve para consultar los DTEs ya emitidos desde tu agente. La emisión también está en su catálogo, pero apagada de fábrica: la habilita tu empresa y, sobre el umbral que fije, cada documento espera la aprobación de una persona. Empieza por aquí (POST /api/v1/dtes con tu API key, el request del tab de curl) y enciende el MCP cuando quieras que tu agente facture.

Criterio de éxito: consulta GET /api/v1/dtes/{id} hasta que estado.terminal sea true. Si estado.categoria es aceptado, abre el PDF en links.pdf y cerraste el loop completo: certificado → folios → emisión → documento aceptado. Si es rechazado, el folio se quemó y estado.accion te dice qué hacer. No cortes por sii_status === "EPR": un rechazo también es final, y ese bucle no terminaría nunca. La tabla de estados está en Estados del DTE.

¿Eres un agente? Copia este prompt

Para delegar el setup completo a un agente LLM, pásale esto tal cual:

Configura Notta para mí:
1. Lee https://notta.cl/llms.txt para entender la API.
2. Pídeme una API key ntt_cert_ de https://app.notta.cl/app/api-keys#crear, con
   los scopes dte:write y caf:write.
3. Comprueba con esa key que haya un certificado .p12 y folios tipo 33:
   GET /api/v1/certificates (guarda el id, lo vas a mandar como header
   X-Cert-Id) y GET /api/v1/caf. Si faltan folios, pídelos con
   POST /api/v1/caf/request y body {"tipo": 33}. Avísame antes, porque el SII
   otorga folios reales y no los devuelve. El .p12 sí lo subo yo desde
   https://app.notta.cl/app/certificates (necesita su contraseña).
4. Emite una Factura 33 de prueba con POST https://app.notta.cl/api/v1/dtes
   (sii_env "cert", headers Idempotency-Key único por intento y X-Cert-Id con
   el id del certificado).
5. La emisión es asíncrona. Si puedo exponer una URL https pública, prefiere el
   push: pídeme una key con scope webhook:write y registra un webhook con
   POST https://app.notta.cl/api/v1/webhooks, body {"url": "<mi URL>",
   "events": ["dte.accepted", "dte.rejected"]}. Guarda el secret que devuelve,
   que no se puede recuperar. Esa suscripción trae solo el desenlace: si a los
   15 minutos no llegó ninguna entrega, consulta igual
   GET https://app.notta.cl/api/v1/dtes/{id}, porque un documento que queda en
   requiere_accion no dispara dte.accepted ni dte.rejected. Si no puedo exponer
   una URL, consulta
   GET https://app.notta.cl/api/v1/dtes/{id} cada 5 segundos hasta que
   estado.terminal sea true, con un tope de 15 minutos. En los dos casos: NO
   cortes por sii_status == "EPR", porque un rechazo también es final y ese
   bucle no terminaría nunca. Un código que no reconozcas NO es terminal.
6. Ramifica por estado.categoria:
   - "aceptado" o "archivistico": entrégame la URL del PDF (links.pdf).
   - "rechazado": el folio se quemó. Muéstrame sii_glosa y estado.accion, y
     NO emitas otro documento sin que yo lo apruebe.
   - "requiere_accion": muéstrame estado.descripcion y detente.

¿Prefieres CLI? — en camino

@notta/cli todavía no está publicado en npm, así que ninguno de los comandos de abajo funciona por ahora. Quedan aquí para que sepas qué esperar: cuando se publique, lo instalas y autenticas así.

npm install -g @notta/cli
notta auth login
# Paste your API key: ntt_cert_...

El key queda guardado en ~/.config/notta/credentials (chmod 600). Los comandos completos están en CLI Reference.

Próximos pasos

  • Emitir Factura 33: la guía completa del tipo 33 (campos, montos, referencias comerciales y errores típicos).
  • Producción: postulación, certificación SII y el switch a palena para emitir con valor tributario.
  • Conceptos: DTE, CAF, certificado y entornos del SII en una página.
  • Errores: catálogo completo con next_action por código.
  • Agentes: llms.txt, manifiesto MCP y patrones para integrar tu agente.

Última actualización

Siguiente

Conceptos

En esta página