Permisos

Un agente tiene permisos del mismo catálogo que las personas del negocio: un nivel por módulo y unos permisos sensibles sueltos. No hay scopes: lo que la clave puede hacer lo deciden los permisos de su agente.

Nivel	Qué permite
Ninguno	Nada. La API responde 403
Ver	Listar, consultar, descargar PDF y XML, leer KPIs y reportes
Operar	Además, crear y emitir
Administrar	Además, anular, borrar y configurar. Nunca para un agente

La regla es simple: GET pide Ver; POST pide Operar, en el módulo del recurso. Emitir y enviar correos pasan además por la autonomía y los límites del agente.

Qué pide cada endpoint

Endpoint	Módulo · nivel	Además
GET /me, GET /establishments, GET /catalogs/{catalogo}	—	Cualquier clave válida
POST /invoices/issue	ventas.facturas · Operar	Idempotency-Key, autonomía invoice.issue, topes de emisión y un establecimiento de sus sucursales
GET /invoices, /invoices/{id}	ventas.facturas · Ver	Solo las de sus sucursales
GET /invoices/{id}/pdf, …/xml	ventas.facturas · Ver	Y datos.personales: el PDF y el XML llevan los datos del comprador
POST /invoices/{id}/retry	ventas.facturas · Operar	Autonomía invoice.issue
POST /invoices/{id}/send-email	ventas.facturas · Operar	Autonomía document.send_email y tope de correos
/credit-notes, /debit-notes	ventas.notas	Como las facturas, con document.issue
/waybills	ventas.guias	Ídem
/withholdings	compras.retenciones	Ídem
/purchase-settlements	compras.facturas	Ídem
GET /documents/{clave_acceso}	Ver en el módulo del tipo de comprobante	Se comprueba al encontrarlo; si es de otra sucursal, 404
GET /kpis	—	Solo lista lo que el agente puede leer
GET /kpis/summary, /kpis/sales, /kpis/daily	inicio.resumen · Ver
GET /kpis/receivables, /kpis/withholdings, /kpis/finance	analisis.finanzas · Ver
GET /kpis/purchases	compras.facturas · Ver
GET /kpis/inventory	inventario.stock · Ver
GET /kpis/recurring	ventas.suscripciones · Ver
GET /expenses	gastos · Ver
GET /purchase-invoices	compras.facturas · Ver
GET /contacts	contactos · Ver
GET /products	catalogo.productos · Ver
GET /quotes	ventas.cotizaciones · Ver
GET /reports/{trial-balance,income-statement,balance-sheet,cash-flow,equity-changes}	contabilidad.estados · Ver
GET /reports/{general-ledger,journal-book}	contabilidad.libros · Ver

Algunos bloques de un KPI dependen de otro módulo. Si el agente no lo tiene, el bloque llega vacío en vez de fallar la petición: en el resumen, la cartera y las retenciones necesitan analisis.finanzas y las compras compras.facturas. Ver KPIs.

Si le falta el permiso, la respuesta dice cuál:

{
  "error": {
    "code": "insufficient_permissions",
    "message": "El agente no tiene permiso para esta operación. Se lo da su responsable en Configuración → Equipo y sucursales → Agentes.",
    "details": { "modulo": "contabilidad.libros", "nivel": "view" },
    "request_id": "7b2e9c41-0d3a-4f8e-a6b5-1c9d2e4f7a80",
    "doc_url": "https://olympus.atharix.com/docs/empezar/errores#insufficient_permissions"
  }
}

Los módulos que no existen en el país del negocio no se pueden usar aunque estén concedidos: compras.retenciones es solo de Ecuador.

El techo de los agentes

Hay cosas que un agente no puede tener aunque quien lo crea sí las tenga. El editor las muestra deshabilitadas como «No disponible para agentes», y lo que el rol de partida da por encima se recorta solo.

Módulo o permiso	Máximo para un agente	Por qué
config.miembros, config.integraciones, config.plan, config.fiscal, config.aprobaciones	Ninguno	Un agente no gestiona personas, credenciales, el plan, la firma ni las reglas de aprobación
config.negocio	Ver	Puede leer los datos del negocio, no cambiarlos
contabilidad.libros, contabilidad.estados	Ver	Los asientos y los cierres los hace una persona
rrhh.empleados, rrhh.nomina	Ver	Datos personales de empleados. Ninguna plantilla los da
ari	Ver	Ari responde a un bot, no actúa por él
pos.venta, pos.terminales, restaurante.sala, restaurante.cocina, restaurante.ajustes	Ninguno	Exigen una persona y una caja o una sala
pos.sesiones, restaurante.carta, restaurante.reservas, restaurante.gestion	Ver	Solo consulta
Todos los demás módulos	Operar	Un agente no borra, no anula y no configura: eso es Administrar
datos.privacidad, auditoria.ver, contabilidad.periodos, inventario.ajustar	Nunca	Protección de datos (RGPD y LOPDP), auditoría, cierres de periodo y ajustes de inventario no se delegan en un bot

Además:

• Roles de partida: gerente, contador, vendedor, cajero, bodega o solo lectura. Nunca propietario, administrador ni los roles del restaurante.
• Nadie da lo que no tiene. Ni quien crea o edita el agente, ni su responsable, pueden tener menos que el agente. Si al responsable le bajan los permisos o sale del negocio, el agente queda suspendido en la revisión de cada noche.
• Descuentos: si le das ventas.descuento, el agente lleva siempre un tope de descuento; sin tope solo lo tiene el propietario.

Datos personales: datos.personales

Es un permiso sensible nuevo. Las personas lo tienen siempre, así que para ellas nada cambia. Un agente solo lo tiene si sus permisos lo activan expresamente, también si se creó desde un rol que a las personas se lo da. De las plantillas, solo Integración ERP lo trae activado.

Sin datos.personales:

• Toda respuesta de la API llega con los datos de contacto enmascarados, estén donde estén: comprobantes, KPIs, listados y reportes. Las únicas excepciones son GET /me y GET /establishments, que son datos del propio negocio.
• No puede descargar el PDF ni el XML de un comprobante, porque llevan esos datos en claro: 403 insufficient_permissions con details.permiso: "datos.personales".
• No puede buscar por correo, teléfono o identificación en /contacts, /purchase-invoices y /quotes: un buscar con @ o con 6 cifras o más responde lo mismo, 403 con details.permiso. Buscar por nombre sí puede, y en /products y /expenses la búsqueda no se bloquea.

Los campos se reconocen por su nombre, en español o en inglés:

Campo	Ejemplo	Enmascarado
Correo (email, correo, destinatarios, customer_email…)	facturas@andina.ec	f***@andina.ec
Teléfono (telefono, phone, mobile)	0991234567	*******567
Dirección (direccion, address)	Av. 6 de Diciembre N24-253	***********************253
Identificación (identificacion, tax_id, ruc, cedula, nif)	1792060346001	**********001

Los nombres y las razones sociales se ven completos. En los endpoints de datos, meta.datos_personales dice en cada respuesta si llegan "visibles" o "enmascarados".

Costos: costos.ver

Es el mismo permiso que en la web, con el mismo efecto. Sin él:

• /kpis/inventory llega sin valor del inventario, costo de ventas, rotación ni días de stock, y sin la lista de productos de más valor.
• /kpis/daily llega sin cogs ni profit por día.
• /products llega sin costos ni márgenes, igual que en la web.

Ninguna plantilla lo da.

Sucursales y ventas de otros

Las plantillas dan todas las sucursales y ventas.ver_ajenas (ver lo que crearon otros). En el editor puedes limitar el agente a algunas sucursales o quitarle ese permiso, como a cualquier miembro del equipo, y la API lo respeta igual que la web.

En los comprobantes (facturas, notas, retenciones, guías y liquidaciones):

• Los listados solo traen los de sus sucursales. Un comprobante de otra sucursal responde 404, también por clave de acceso (GET /documents/{clave_acceso}), igual que si no existiera.
• Sin ventas.ver_ajenas, en los módulos de ventas solo ve lo que creó él.
• Al emitir sin establecimiento, usa el establecimiento principal de sus sucursales. Si nombras uno que no es suyo: 403 branch_not_allowed, con el código en details.establecimiento.

En los datos (KPIs, listados y reportes):

• En los módulos que se acotan por sucursal (resumen, ventas, inventario, gastos, órdenes de compra…), los KPIs y los listados le llegan filtrados a las suyas. Si pide un KPI con sucursal de otra: 403 insufficient_permissions.
• Las cifras que no se pueden acotar llegan marcadas: scope: "business" si son de todo el negocio (caja, conciliación, runway, gastos, ingresos recurrentes) y hidden: true con hidden_reason: "branch_scope" si no se le pueden enseñar.
• analisis.finanzas y la contabilidad no se acotan por sucursal: con esos módulos, el agente ve las cifras de todo el negocio.

GET /establishments lista todos los establecimientos del negocio con su id, que es lo que espera el parámetro sucursal.

Lo siguiente

• Autonomía y límites: lo que hace solo y sus topes.
• Listados: el enmascarado en la práctica.