Introducción

Un agente es un miembro del equipo que es un bot. Tiene un rol y unos permisos del mismo catálogo que las personas del negocio, se gestiona desde la misma pantalla (Configuración → Equipo → Agentes) y entra en la API con sus propias claves dlt_.

Sirve para que un sistema automático —tu ERP, un flujo de n8n, un asistente de IA que has construido— lea los datos del negocio (KPIs, listados, reportes contables) y emita comprobantes dentro de lo que el negocio le deje hacer solo.

Lo que tiene un agente

Pieza	Qué es
Responsable	Una persona del negocio que responde por él. Un agente nunca puede más que su responsable.
Permisos	Un rol de partida y ajustes por módulo, del mismo catálogo que el equipo humano, con un techo: hay cosas que un agente no puede tener nunca. Ver Permisos.
Sucursales	Todas, o solo las que le asignes.
Autonomía	Qué hace solo, qué necesita a una persona y qué tiene prohibido, por tipo de acción.
Límites	Topes diarios: comprobantes, importes, correos, registros leídos. Ver Autonomía y límites.
Claves	Una o varias claves dlt_, con caducidad (90 días por defecto) y lista de IPs.
Puntuación de seguridad	De 0 a 100, según lo que puede hacer y cómo están sus claves. Ver Seguridad.
Estado	Activo, pausado, suspendido o revocado.

Lo que hace queda firmado por él: los comprobantes que emite llevan al agente como autor y el historial de cambios lo muestra como tal, no como «API».

Cómo se decide si una petición pasa

Cada petición con la clave de un agente recorre estos controles, en este orden. En cuanto uno falla, la API responde con su código y no sigue:

1. La clave es válida. Existe, no está revocada, ni caducada, ni desactivada. Si no: 401 invalid_api_key, api_key_revoked, api_key_expired o api_key_disabled.

2. La IP está permitida por la lista de IPs de la clave, si la tiene. Si no: 403 ip_not_allowed.

3. Los agentes están encendidos en Olympus. Es el interruptor de la plataforma. Si no: 503 agents_disabled.

4. El agente puede trabajar. No está revocado (401 agent_revoked), ni suspendido (403 agent_suspended), el negocio no ha pausado a todos sus agentes (403 agents_paused) y él no está pausado (403 agent_paused).

5. Sigue siendo miembro del negocio. Si no: 403 agent_without_access.

6. Tiene el módulo al nivel que pide la operación: Ver para leer (GET), Operar para escribir (POST); para descargar un PDF o un XML, además, datos.personales. Si no: 403 insufficient_permissions, con lo que falta.

7. No ha pasado su límite de peticiones por minuto, que comparten todas sus claves. Si no: 429 rate_limited.

8. Al emitir, envía Idempotency-Key. Si no: 400 idempotency_key_required.

9. Su autonomía le deja hacer la acción (emitir, enviar correos). Si está prohibida: 403 agent_action_forbidden; si necesita a una persona: 403 agent_action_requires_approval.

10. No ha pasado sus topes del día: comprobantes, importe por documento o por día, correos, registros leídos. Si no: 429 agent_limit_exceeded.

Los pasos 8 a 10 solo aplican a lo que emite, tiene autonomía o tiene tope (emitir, reintentar, enviar correos y leer datos). Una consulta de una factura termina en el paso 7.

Además, el agente solo ve y emite lo de sus sucursales: un comprobante de otra responde 404, y emitir desde un establecimiento que no es suyo, 403 branch_not_allowed. Ver Permisos.

No reintentes un 403

Un 403 no se arregla reintentando: falta un permiso, la acción está vedada o el agente está parado. Además, más de 20 rechazos 403 en 10 minutos pausan al agente automáticamente. Ver Seguridad.

Claves de integración y claves de agente

Las dos son claves dlt_ y se envían igual (X-API-Key). Lo que cambia es de quién son y qué las gobierna:

	Clave de integración	Clave de agente
Dónde se crea	Configuración → Integraciones	Configuración → Equipo → Agentes
Qué decide lo que puede	Sus scopes (invoices:write…)	Los permisos del agente, su autonomía y sus límites
Quién figura como autor	Nadie: la clave	El agente
Límite de peticiones	Por clave	Por agente: todas sus claves comparten el cupo
Idempotency-Key al emitir	Recomendada	Obligatoria
Datos de contacto (correo, teléfono, dirección, identificación)	En claro	Enmascarados, salvo que tenga datos.personales
Sucursales	Todas	Las suyas
Caducidad	Opcional	90 días por defecto, como mucho un año
KPIs, listados y reportes	No (403 agent_required)	Sí, según sus permisos
Pausa automática y puntuación	No	Sí
Error si le falta un permiso	insufficient_scope	insufficient_permissions

Las claves de integración siguen funcionando igual; no tienes que cambiar nada. Si quieres pasar una integración a agente, ver Migrar desde claves.

Endpoints solo para agentes

Estos endpoints responden 403 agent_required a una clave de integración:

Endpoint	Qué devuelve
GET /kpis	Catálogo de KPIs que el agente puede pedir, con su definición
GET /kpis/{summary,sales,receivables,withholdings,purchases,finance,inventory,daily,recurring}	Las cifras. Ver KPIs
GET /expenses, /purchase-invoices, /contacts, /products, /quotes	Listados. Ver Listados
GET /reports/{nombre}	Siete reportes contables. Ver Reportes contables

El resto de la API —emitir y consultar facturas y los demás comprobantes, GET /me, establecimientos y catálogos— funciona con los dos tipos de clave.

Próximamente: aprobaciones de agentes en la bandeja, acciones de escritura (borradores, cotizaciones, cobros), Ari para bots, webhooks y servidor MCP.

Lo siguiente

• Crear un agente: plantillas, responsable, permisos y su primera clave.
• Permisos: qué módulo pide cada endpoint y qué no se le puede dar nunca a un agente.
• Seguridad: la guía para quien construye el bot.