Opción 1: el servidor MCP
El servidor MCP de Tupana está enhttps://mcp.tupana.ai/mcp (Streamable HTTP, OAuth 2.1 con PKCE y registro dinámico de clientes). No necesitas API key ni client ID: el usuario inicia sesión con su cuenta Tupana y el asistente solo ve las empresas a las que esa persona pertenece.
Para la lista vigente, pídele al asistente que llame a
list_capabilities.
Opción 2: tool calling sobre la API REST
Si el agente vive en tu producto, defínele herramientas que llamen a la API de Tupana desde tu backend. La guía Tool calling sobre la API trae las definiciones listas para copiar (JSON Schema) y el ciclo completo de confirmación.Patrones recomendados
Confirmación humana antes de emitir
Confirmación humana antes de emitir
Emitir un DTE al SII es irreversible: una factura mal emitida solo se corrige con una nota de crédito. Separa siempre preparar de emitir: el agente arma el documento y muestra un resumen (receptor, RUT, ítems, neto, IVA, total); la emisión ocurre solo cuando una persona confirma. El servidor MCP ya lo hace así: sin confirmación explícita, el documento queda como borrador.
Claves de idempotencia en cada emisión
Claves de idempotencia en cada emisión
Los modelos reintentan. Manda
Idempotency-Key en POST /v2/documents/batch/, derivada de algo estable (tu id de pedido, por ejemplo pedido-1001), no un valor aleatorio por intento. Si el agente repite la llamada, Tupana devuelve el lote original sin volver a emitir.Lotes asíncronos y webhooks, no esperas activas
Lotes asíncronos y webhooks, no esperas activas
La emisión se procesa en segundo plano. En vez de que el agente consulte en un ciclo, recibe el resultado por webhook (
document.issued, document.rejected, document.issue_failed) y retoma la conversación con ese evento.API keys con el mínimo de permisos
API keys con el mínimo de permisos
Las API keys tienen permisos por alcance (por ejemplo
document:access para leer documentos y document:create para emitir). Un agente que solo consulta no necesita emitir. Usa una key por agente o por entorno, guárdala en tu backend y nunca la pongas en el prompt ni en el navegador.Sandbox primero
Sandbox primero
Las keys nuevas nacen en sandbox: la emisión se simula, el folio es
SANDBOX-{n} y nada llega al SII. Corre tus evaluaciones del agente en sandbox y pasa a producción solo cuando el flujo completo funcione.Datos del contribuyente desde el RUT, no desde el modelo
Datos del contribuyente desde el RUT, no desde el modelo
No dejes que el modelo invente razón social, giro o dirección. Pídelos a la API (Buscar entidad por RUT) y usa
X-Use-Defaults: true para que Tupana complete lo que falte con la configuración de la empresa.Prompts de ejemplo
Con el servidor MCP conectado, prueba:- “Factura a 76.123.456-7 un servicio de consultoría por $850.000 neto. Muéstrame el borrador antes de emitir.”
- “¿Qué facturas de clientes vencieron este mes y cuánto suman? Ordénalas por monto.”
- “Reenvíale a Constructora Vega la factura 1234 con el PDF.”
- “Concilia los movimientos del banco de la última semana y muéstrame los que no tienen una factura que calce.”
- “Anula la factura 5678 con una nota de crédito total; antes muéstrame el detalle.”
- “Arma un gráfico de ventas mensuales de este año comparado con el anterior.”
Ejemplos de código
En el repositorio tupana-ai/tupana-examples hay un agente de ejemplo que emite, cobra y concilia con Tupana. Para el cliente de la API en Node.js o Python, ver SDKs.Para LLMs
Si tu agente necesita leer la documentación completa, apúntalo a:/llms.txt: resumen, cuándo usar Tupana e índice de páginas./llms-full.txt: todas las guías y la referencia completa de la API v2 en Markdown./api-reference/openapi-v2.json: la especificación OpenAPI.