Autonomía y límites

Los permisos dicen qué puede tocar un agente. La autonomía y los límites dicen qué hace solo y cuánto al día. Un bot se equivoca a la velocidad de una máquina, y un comprobante autorizado por el SRI no se puede borrar: por eso lo fiscal nace pidiendo a una persona.

Niveles de riesgo

Cada operación tiene un nivel. Cuanto más alto, más controles:

Nivel	Qué es	En la API hoy	Controles
N0	Metadatos	GET /me, /establishments, /catalogs/…	Clave válida
N1	Lectura operativa	Consultar comprobantes y productos	Módulo · Ver
N2	Lectura sensible	KPIs, contactos, compras, gastos, reportes contables	Módulo · Ver, datos personales enmascarados y tope de registros al día
N3	Escritura interna y reversible	Contactos, borradores, cotizaciones, gastos (aún sin endpoint)	Módulo · Operar
N4	Efecto externo o fiscal	Emitir comprobantes, enviarlos por correo	Módulo · Operar, Idempotency-Key al emitir, autonomía y topes
N5	Mueve dinero	Cobros y pagos a proveedores (aún sin endpoint)	Módulo · Operar y aprobación por defecto. Solo el propietario lo pasa a automático

Lo que un agente no puede hacer nunca (gestionar personas, claves, el plan, la firma, anular, borrar, cerrar periodos) no tiene endpoint y, aunque lo tuviera, el techo lo impide.

Autonomía: qué hace solo

Cada tipo de acción tiene un modo:

Modo	Qué pasa
Automático (auto)	El agente lo hace, dentro de sus topes
Con aprobación (approval)	Necesita a una persona. Ver abajo qué significa hoy
Prohibido (forbidden)	No lo hace nunca

Acción	Qué cubre hoy	Nivel	Por defecto
invoice.issue	POST /invoices/issue y POST /invoices/{id}/retry	N4	Con aprobación
document.issue	Emitir y reintentar notas, retenciones, guías y liquidaciones	N4	Con aprobación
document.send_email	POST …/send-email de cualquier comprobante	N4	Con aprobación
invoice.payment	Registrar cobros (aún sin endpoint)	N5	Con aprobación
purchase.payment	Pagar a proveedores (aún sin endpoint)	N5	Con aprobación
contact.write	Crear y editar contactos (aún sin endpoint)	N3	Automático
draft.write	Borradores y cotizaciones (aún sin endpoint)	N3	Automático
expense.create	Gastos y compras (aún sin endpoint)	N3	Automático

Las plantillas cambian algunos valores de partida: Cobranza envía correos en automático, e Integración ERP emite y envía correos en automático. Ver Crear un agente.

Quién cambia la autonomía: quien administra las integraciones (config.integraciones · Administrar). Pasar a automático una acción N5 lo hace solo el propietario, y no se puede mientras la puntuación de seguridad del agente esté en banda baja.

Tu bot puede leer su autonomía y sus topes en GET /me → agente.autonomia y agente.limites.

«Con aprobación», hoy

La bandeja de aprobación para agentes todavía no existe. Mientras tanto, una acción en modo «con aprobación» no se ejecuta y la API responde:

{
  "error": {
    "code": "agent_action_requires_approval",
    "message": "Esta acción necesita la aprobación de una persona y este agente no la tiene en automático.",
    "details": { "accion": "invoice.issue", "modo": "approval" },
    "request_id": "e41a07c2-5b9d-4e1f-8c3a-2d6f9b0e7a15",
    "doc_url": "https://olympus.atharix.com/docs/empezar/errores#agent_action_requires_approval"
  }
}

No se crea nada: el control va antes de construir el comprobante. Tiene su propio código, distinto de agent_action_forbidden, para que tu bot sepa que la acción no está vedada sino que le toca a una persona. Lo correcto es avisar a alguien del negocio para que la haga desde Olympus, o pedir al responsable que la pase a automático con topes.

No lo reintentes en bucle

Un 403 cuenta para la pausa automática: más de 20 en 10 minutos pausan al agente. Ver Seguridad.

Límites del día

Límite	Qué limita	Por defecto	Cuándo se comprueba
max_document_amount	Importe de un comprobante	Sin tope	Al emitir, con el comprobante ya calculado
max_daily_amount	Importe emitido en el día	Sin tope	Al emitir: lo emitido hoy más este comprobante
max_daily_documents	Comprobantes emitidos en el día	200 (500 en Integración ERP)	Antes de emitir o reintentar
max_daily_emails	Correos enviados en el día	200 (100 en Cobranza)	Antes de enviar: los de hoy más todos los destinatarios de la petición
max_daily_rows_read	Registros leídos en el día por KPIs, listados y reportes	20 000	Antes de cada lectura
ari_daily_queries	Preguntas a Ari en el día	200	Reservado para Ari para bots

• Importes en la moneda del negocio: el total del comprobante por su tipo de cambio, redondeado al centavo. Un comprobante sin importe, como una guía de remisión, solo cuenta como documento.
• Si el importe se pasa, el comprobante se descarta y no se emite.
• Los registros leídos se cuentan después de responder: en un listado, las filas; en un KPI o un reporte, los elementos de sus listas. Un listado nunca devuelve más filas de las que le quedan al agente: la página llega recortada y recortadas_por_tope dice cuántas faltan. Un KPI o un reporte grande sí puede pasar el tope; la lectura siguiente se rechaza.
• El día es el día natural en la hora de Ecuador (UTC−5), también para negocios de España: los contadores vuelven a cero a las 00:00 de Guayaquil, que son las 06:00 de Madrid en invierno y las 07:00 en verano.

Al pasar un tope, 429:

{
  "error": {
    "code": "agent_limit_exceeded",
    "message": "El agente alcanzó su límite «Importe máximo al día». Lo cambia su responsable en Configuración → Equipo y sucursales → Agentes.",
    "details": { "limite": "max_daily_amount", "permitido": 3000.0, "actual": 2760.0, "este_documento": 345.0 },
    "request_id": "0c9f3b6e-2a71-4d58-b9e4-6f1a8c2d5e37",
    "doc_url": "https://olympus.atharix.com/docs/empezar/errores#agent_limit_exceeded"
  }
}

details.limite dice qué tope, permitido cuánto es y actual lo que lleva hoy. En max_daily_amount, además, este_documento (aquí, 2760 + 345 = 3105 pasa de 3000); en max_daily_emails, esta_peticion, con los destinatarios de la petición.

No es lo mismo que rate_limited

rate_limited es el límite de peticiones por minuto y trae Retry-After: espera unos segundos y sigue. agent_limit_exceeded es un tope del día y no trae Retry-After: reintentar no sirve hasta el día siguiente o hasta que el responsable suba el tope.

Límite de peticiones por minuto

Es el de siempre (600 lecturas y 120 escrituras por minuto), con una diferencia: en un agente se cuenta por agente, no por clave. Todas sus claves comparten el cupo, así que tener más claves no multiplica lo que puede pedir. Si pones un límite propio en una clave, vale para lecturas y escrituras. Ver Límites y paginación.

Idempotencia

Un agente reintenta a menudo, y un modelo de IA más. Por eso, al emitir (POST /invoices/issue y POST /{credit-notes,debit-notes,withholdings,waybills,purchase-settlements}/issue), Idempotency-Key es obligatoria para un agente. Sin ella: 400 idempotency_key_required, y no se emite nada. La única excepción son los agentes de tipo Integración que nacen de convertir una clave de integración anterior, que siguen como antes.

Usa también referencia_externa en el payload. Ver Idempotencia.

Dos detalles de agente:

• Un 403 de autonomía o un 429 de topes no se guardan como respuesta: cuando el responsable cambie la autonomía o suba el tope, puedes reintentar con la misma Idempotency-Key.
• Las Idempotency-Key se recuerdan por clave, no por agente. Si rotas la clave a mitad de un reintento, la nueva no conoce las anteriores: referencia_externa es lo que te protege entonces.

Lo siguiente

• Seguridad: la puntuación, la pausa automática y los interruptores.
• Errores: todos los códigos de agente.