Notta para 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.

Esta página está escrita para ti, el agente. Notta trata al LLM como user-class de primera: los 3 canales programáticos (API, CLI, MCP) + el dashboard exponen el mismo flujo, y cada pieza de documentación existe también en formato máquina-legible. Si estás decidiendo por dónde empezar, lee /llms.txt y vuelve aquí.

Qué puedes hacer solo y qué requiere un humano

Con una API key activa operas la facturación completa por tu cuenta. Lo que no puedes hacer es crear esa credencial: la cuenta y la API key las crea un humano en el dashboard.

Acción	¿La haces solo?
Crear la cuenta y la API key	No — un humano la crea en app.notta.cl y te la pasa
Subir el certificado digital `.p12`	No — se sube con sesión humana en el dashboard, y el password lo custodia el humano
Emitir DTEs (33/34/39/41/56/61) y BHE	Sí — vía API, CLI o MCP
Consultar estado, PDF y XML de un DTE	Sí — `GET /dtes/:id`, `/pdf`, `/xml`
Sincronizar el RCV del SII	Sí — ver RCV y F29
Overrides de compliance (p. ej. NC sobre factura cedida)	Pide confirmación explícita al humano antes de usar `override_cedida`

Artefactos máquina-legibles

Todo el corpus está disponible sin scraping ni renderizado de HTML:

Artefacto	URL	Qué contiene
Índice del corpus	`https://notta.cl/llms.txt`	Mapa corto de la doc con links a cada pieza
Corpus completo	`https://notta.cl/llms-full.txt`	Toda la documentación en un solo archivo de texto
Página individual en Markdown	`https://notta.cl/docs/<slug>.md`	Cualquier página de docs, agregándole `.md` a la URL
Spec OpenAPI	`https://notta.cl/docs/api/openapi.json`	Schemas de request/response de `/api/v1`
Manifiesto MCP	`https://notta.cl/.well-known/mcp.json`	Descubrimiento del servidor MCP y sus tools

Conecta el MCP

El servidor MCP expone tools tipadas (notta_dte_emit, notta_dte_get, …) para clientes como Claude Desktop o Cursor. La configuración y el catálogo completo de tools están en MCP; el manifiesto de descubrimiento vive en /.well-known/mcp.json.

Disponibilidad

El package @notta/mcp está en proceso de publicación en npm — el install vía npx todavía no funciona. Mientras tanto el dashboard y la API cubren el flujo completo: cada tool MCP mapea 1:1 a un endpoint de /api/v1, así que con tu key y curl no pierdes ninguna capacidad.

El contrato de errores

Cada error trae un campo next_action enumerable: una instrucción accionable que puedes manejar por código sin parsear el message humano. Trata el catálogo de Errores como el contrato — message y hint pueden cambiar de redacción; code y next_action, no.

{
  "code": "caf.exhausted",
  "message": "CAF sin folios disponibles para tipo 33.",
  "hint": "Sube un CAF nuevo con más folios.",
  "next_action": "upload_more_folios",
  "request_id": "req_01957a910b50abcdef"
}

Ante un next_action que no reconoces, no improvises: reporta el error al humano junto con el request_id.

Prompt de arranque

Copia esto como system prompt (o primer mensaje) de un agente que va a operar Notta:

Eres un agente que opera facturación electrónica chilena vía Notta.

Contexto operativo:
- API base: https://app.notta.cl/api/v1
- Autenticación: header "Authorization: Bearer ntt_cert_..." (la key la provee el humano).
- Toda mutación (POST) lleva un header "Idempotency-Key" único (UUID).
- Todo POST de emisión a /dtes o /boletas lleva además el header "X-Cert-Id"
  con el id del certificado de la org (sin él: 400 cert_id_missing). No puedes
  consultarlo con la API key — /certificates y /caf hoy autentican con sesión
  del dashboard. Pídele al humano que confirme en el dashboard que hay
  certificado y CAF cargados, y que te pase el id del certificado.
- Documentación completa: https://notta.cl/llms-full.txt
- Ante un error, lee el campo next_action de la respuesta y actúa según esa enum.
  Si no la reconoces, escala al humano con el request_id.

Para factura 33/34 debes recolectar del receptor su giro, dirección y comuna
(además del RUT y la razón social), y la forma_pago (1=Contado, 2=Crédito,
3=Sin costo) — son obligatorios. Si te faltan, pídeselos al humano antes de emitir.

Primera tarea: emite una Factura Electrónica afecta (tipo_dte 33) del emisor
76123456-0 al receptor 11111111-1 (giro "Comercio", dirección "Av Siempre Viva
123", comuna "Santiago"), forma_pago 2 (Crédito), por 5 horas de consultoría a
50.000 CLP cada una, y reporta el folio asignado y el estado SII resultante.

Copia cualquier página como Markdown

Cada página de esta documentación tiene un botón Copiar como Markdown junto al título. Hace lo mismo que agregarle .md a la URL: te entrega la fuente limpia, sin chrome de navegación.

Próximos pasos

MCP — la configuración del servidor y el catálogo completo de tools tipadas.
Errores — el catálogo de code y next_action que vas a manejar por código.
Quickstart — el flujo cuenta → certificado → primer DTE, de punta a punta.
Referencia de la API — todos los endpoints de /api/v1 con sus shapes.