Scopes y permisos
El catálogo de scopes del consentimiento OAuth, cómo se mapea a los scopes detallados que aplican las tools, el super-scope y el gating por plan/módulo.
Cada tool MCP declara el scope que una credencial debe tener para invocarla. Los scopes funcionan de forma ligeramente distinta según el canal:
- Las API keys se crean directamente con scopes detallados
(
resource:action, p. ej.invoices:read) — el mismo catálogo cerrado que usa la API REST. También puedes conceder el super-scope*. - Los tokens OAuth reciben scopes con punto (
resource.action, p. ej.invoices.read) en la pantalla de consentimiento. El servidor los traduce a los scopes detallados automáticamente, de modo que ambos canales aplican el mismo conjunto en el límite de la tool.
Catálogo de consentimiento OAuth
Estos son los scopes que un usuario puede conceder a una app de terceros en la pantalla de consentimiento. Hay 62 scopes simples más 3 macros.
Scopes simples
Cada uno concede una capacidad. La columna Maps to muestra el scope detallado que aplican las tools — la capa de consentimiento traduce los scopes OAuth con punto a estos automáticamente. La columna Sensitive marca los scopes que la pantalla de consentimiento destaca y no marca por defecto.
Perfil
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
profile.read | Leer tu nombre, email y empresa activa. | account:read | no |
Contactos
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
contacts.read | Listar y consultar contactos canónicos. | contacts:read | no |
contacts.write | Crear contactos y modificar identidad, roles y perfiles. | contacts:write | no |
contacts.delete | Archivar contactos y retirar roles sin referencias. | contacts:delete | sí |
Catálogo — productos, tarifas, series, impuestos
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
products.read | Listar y leer el catálogo de productos. | products:read | no |
products.write | Crear y actualizar productos. | products:write | no |
products.delete | Eliminar productos. | products:delete | sí |
price_lists.read | Leer tarifas, ítems y precios efectivos. | price_lists:read | no |
price_lists.write | Crear, actualizar y eliminar tarifas e ítems. | price_lists:write | no |
series.read | Leer series de numeración. | series:read | no |
series.write | Crear y actualizar series de numeración. | series:write | no |
taxes.read | Leer tipos impositivos y retenciones. | taxes:read | no |
taxes.write | Crear y actualizar tipos impositivos. | taxes:write | no |
Ventas — facturas, presupuestos, proformas, albaranes
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
invoices.read | Listar y leer facturas. | invoices:read | no |
invoices.write | Crear y actualizar facturas. | invoices:write | no |
invoices.send | Enviar facturas por email. | invoices:send | no |
invoices.delete | Eliminar facturas en borrador. | invoices:delete | sí |
invoices.annul | Anular facturas emitidas. | invoices:void | sí |
invoices.create_corrective | Emitir facturas rectificativas. | invoices:write | no |
quotes.read | Listar y leer presupuestos. | quotes:read | no |
quotes.write | Crear y actualizar presupuestos. | quotes:write | no |
quotes.send | Enviar presupuestos por email. | quotes:send | no |
quotes.delete | Eliminar presupuestos. | quotes:delete | sí |
quotes.convert_to_invoice | Aceptar/rechazar y convertir presupuestos en facturas. | quotes:transition | no |
proformas.read | Listar y leer facturas proforma. | proformas:read | no |
proformas.write | Crear y actualizar proformas. | proformas:write | no |
proformas.send | Enviar proformas por email. | proformas:send | no |
proformas.delete | Eliminar proformas. | proformas:delete | sí |
proformas.convert | Convertir proformas en facturas. | proformas:transition | no |
delivery_notes.read | Listar y leer albaranes. | delivery_notes:read | no |
delivery_notes.write | Crear, actualizar y enviar albaranes. | delivery_notes:write | no |
delivery_notes.send | Enviar albaranes por email. | delivery_notes:write | no |
delivery_notes.delete | Eliminar albaranes. | delivery_notes:delete | sí |
delivery_notes.convert | Convertir albaranes. | delivery_notes:transition | no |
delivery_notes.sign | Marcar como entregados / firmar albaranes. | delivery_notes:transition | sí |
Compras
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
purchase_invoices.read | Listar y leer facturas de compra. | purchase_invoices:read | no |
purchase_invoices.write | Crear y actualizar facturas de compra; duplicar desde source_purchase_invoice_id exige además purchase_invoices:read. | purchase_invoices:write | no |
purchase_invoices.mark_paid | Marcar facturas de compra como pagadas. | purchase_invoices:transition | sí |
purchase_invoices.delete | Eliminar facturas de compra. | purchase_invoices:delete | sí |
Los scopes de pago son asimétricos entre ventas y compras. Registrar un
pago en una factura de venta (register_invoice_payment) requiere
invoices:write — edita la factura. En cambio, registrar un pago en una
factura de compra (register_purchase_invoice_payment) requiere
purchase_invoices:transition, porque en el lado de compra un pago hace
avanzar la factura por su ciclo de vida (pendiente → pagada) en vez de
editarla.
Facturas recurrentes
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
recurring.read | Listar y leer plantillas recurrentes. | recurring_invoices:read | no |
recurring.write | Crear y actualizar plantillas recurrentes. | recurring_invoices:write | no |
recurring.pause | Pausar plantillas recurrentes. | recurring_invoices:transition | no |
recurring.resume | Reanudar plantillas recurrentes. | recurring_invoices:transition | no |
recurring.generate_now | Emitir una factura recurrente manualmente. | recurring_invoices:transition | sí |
recurring.delete | Eliminar plantillas recurrentes. | recurring_invoices:delete | sí |
Cumplimiento e informes fiscales
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
verifactu.read | Leer registros, eventos, certificados y configuración de VeriFactu. | verifactu:read | no |
facturae.read | Descargar XML FacturaE y leer envíos a FACe. | facturae:read | no |
facturae.write | Enviar facturas a FACe y solicitar anulaciones. | facturae:write | sí |
tax_reports.read | Leer histórico, previews, ficheros, estadísticas y actividad fiscal. | tax_reports:read | no |
tax_reports.write | Generar informes fiscales y libros de revisión. | tax_reports:write | sí |
Webhooks
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
webhooks.read | Listar webhook endpoints y entregas. | webhooks:read | no |
webhooks.write | Crear, actualizar, rotar y hacer ping de webhook endpoints. | webhooks:write | sí |
webhooks.delete | Eliminar webhook endpoints. | webhooks:delete | sí |
Personal — control horario
Datos de empleados, fichajes, ausencias, horarios de trabajo, presencia, festivos
y exportaciones de nómina. Todos los scopes de personal son sensibles (PII de
empleado y datos de cumplimiento) y requieren el módulo de plan control_horario
— consulta Gating por plan y módulo. Las lecturas,
employees.write y la generación de exportaciones de nómina se conceden en la
pantalla de consentimiento; las acciones privilegiadas de escritura y transición no
tienen scope OAuth con punto y son solo API key (listadas más abajo en los scopes
detallados).
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
employees.read | Listar y leer empleados. | employees:read | sí |
employees.write | Crear y actualizar empleados. | employees:write | sí |
time_entries.read | Leer fichajes, saldos y hojas de horas mensuales. | time_entries:read | sí |
absences.read | Listar y leer ausencias, políticas y solicitudes. | absences:read | sí |
work_schedules.read | Leer horarios de trabajo y sus asignaciones. | work_schedules:read | sí |
presence.read | Leer la presencia en vivo y diaria. | presence:read | sí |
holidays.read | Leer el calendario de festivos de la empresa. | holidays:read | sí |
payroll_exports.read | Leer las exportaciones de nómina generadas. | payroll_exports:read | sí |
payroll_exports.write | Generar exportaciones de nómina. | payroll_exports:write | sí |
Automatizaciones
Reglas de automatización y su historial de ejecuciones. Todos los scopes de
automatizaciones son sensibles: una regla puede enviar correos y disparar webhooks
en nombre del titular, y el historial de ejecuciones lleva dentro los payloads de
negocio que movieron sus acciones (importes, destinatarios, resultados). Los tres
requieren el módulo de plan automations — consulta
Gating por plan y módulo. Leer y escribir reglas y leer el
historial de ejecuciones se conceden en la pantalla de consentimiento; borrar una
regla no — automations:delete no tiene scope OAuth con punto y es solo API key
(listado más abajo en los scopes detallados).
automations.read y automation_runs.read se conceden por separado a propósito. El
primero cubre el reglamento: las reglas, sus versiones selladas, el catálogo de
disparadores y acciones, y el ensayo que dice qué haría una regla sin llegar a hacerlo.
El segundo cubre lo que las reglas hicieron de verdad: cada ejecución, sus pasos, sus
motivos de descarte tipificados y el payload congelado del disparador que lleva cada
ejecución. Una app puede leer qué automatizaciones existen sin leer los datos de
negocio que tocó cada ejecución.
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
automations.read | Listar y leer las reglas de automatización, sus versiones, el catálogo de disparadores y acciones, la cuota mensual y el ensayo. | automations:read | sí |
automations.write | Crear, actualizar, activar y pausar reglas de automatización, y relanzar ejecuciones o pasos sueltos. | automations:write | sí |
automation_runs.read | Leer el historial de ejecuciones de tus automatizaciones, sus pasos y su resultado. | automation_runs:read | sí |
Macros
Paquetes de conveniencia que se expanden a una lista de scopes simples en el momento de emitir el token. El token persiste los scopes expandidos — las macros nunca se almacenan.
| Macro | Concede | Sensitive |
|---|---|---|
factuarea.read | Acceso de lectura completo a todo (sin escrituras). | no |
factuarea.write | Leer todo, además de crear/actualizar documentos y enviar emails. | no |
factuarea.full | Leer, escribir, enviar y acciones destructivas (eliminar, anular, marcar como pagada, firmar). Excluye las escrituras de VeriFactu. | sí |
El super-scope *
Una credencial que tiene * cubre todos los scopes — las 457 tools en el caso de
una API key. Es el equivalente a una clave de propietario. Resérvalo para migraciones
puntuales o automatizaciones de propietario totalmente confiables; para todo lo demás,
prefiere el conjunto de scopes más reducido. El super-scope está disponible para las API
keys; el consentimiento OAuth concede scopes explícitos (o macros), nunca un * directo.
Cómo los scopes OAuth se convierten en scopes detallados
Cuando se emite un token OAuth, sus scopes con punto se traducen una vez al catálogo detallado que aplican las tools. Conviene conocer algunas reconciliaciones:
recurring.*se mapea al recursorecurring_invoices:*.invoices.create_correctivese mapea ainvoices:write(crear es una escritura).invoices.annulse mapea ainvoices:void.- Las acciones de ciclo de vida (
*.convert,*.sign,*.pause,*.resume,*.generate_now,*.mark_paid,quotes.convert_to_invoice) se mapean al scope:transitiondel recurso. - Cualquier scope de lectura sobre un documento también concede las utilidades de
lectura transversales
pdfs:read(descargar su PDF/recibo) yevents:read(su registro de actividad). verifactu.writeydelivery_notes:gdpr_forgetno tienen scope OAuth con punto — son inalcanzables vía OAuth por diseño.
Scopes detallados sin scope OAuth (solo API key)
Algunos scopes detallados viven en el catálogo cerrado recurso:accion que usan las
API keys, pero no tienen equivalente OAuth con punto — nunca se conceden a través de
una pantalla de consentimiento de terceros y solo son accesibles con API key.
Concédelos directamente en la key (o vía el super-scope *). Algunos están gateados por
un módulo de integración —entonces la empresa de la key debe tener el plan
correspondiente (consulta Gating por plan y módulo)—; el resto
son scopes de cuenta propia y de gestoría.
| Scope | Concede | Gating de módulo |
|---|---|---|
stripe_autoinvoicing:read | Leer el estado de la integración Stripe Connect, la configuración de auto-facturación y las cuentas conectadas, y listar cobros/rectificativas auto-facturados. | integration_stripe |
stripe_autoinvoicing:write | Activar/desactivar la auto-facturación de cobros Stripe, fijar la serie auto-emitida y editar/desconectar cuentas conectadas. | integration_stripe |
payouts:read | Leer los payouts de Stripe ingeridos y su estado de conciliación bancaria. | integration_stripe |
Estos scopes habilitan las tools de Pagos y pasarelas.
Un segundo grupo de scopes solo para API key gobierna la gestión de cuenta
propia y de gestoría — tus propias credenciales y, para asesorías, las
empresas hijas que gestionas y sus API keys. companies:* requiere el módulo del
plan de gestoría; el resto no tienen gating de módulo.
| Scope | Concede | Gating de módulo |
|---|---|---|
account:write | Gestionar tus propias API keys (crear, rotar, revocar) y actualizar la personalización de la cuenta. | — |
companies:read | Listar y leer las empresas gestionadas (sub-cuentas hijas). | gestoria |
companies:write | Crear, actualizar, activar y desactivar empresas gestionadas. | gestoria |
companies:delete | Archivar empresas gestionadas. | gestoria |
api_keys:read | Listar y leer las API keys de las empresas gestionadas. | — |
api_keys:write | Crear, rotar y revocar las API keys de las empresas gestionadas. | — |
api_keys:delete | Eliminar permanentemente las API keys de las empresas gestionadas. | — |
Un tercer grupo cubre las acciones de escritura y transición de personal
(control horario). Sus lecturas se conceden por OAuth (consulta los scopes de
consentimiento de Personal más arriba), pero estos scopes privilegiados no tienen
equivalente OAuth con punto — son solo API key, el espejo de verifactu:write.
Todos requieren el módulo de plan control_horario.
| Scope | Concede | Gating de módulo |
|---|---|---|
employees:delete | Eliminar empleados de forma permanente. | control_horario |
time_entries:write | Fichar entrada/salida, registrar entradas manuales, gestionar correcciones de fichaje y el cierre mensual del registro. | control_horario |
absences:write | Crear y gestionar tipos, políticas y solicitudes de ausencia. | control_horario |
absences:transition | Aprobar, rechazar y cancelar solicitudes de ausencia. | control_horario |
work_schedules:write | Crear, actualizar, asignar y archivar horarios de trabajo. | control_horario |
Un cuarto grupo es el scope de borrado del motor de automatizaciones. Sus tres
hermanos —automations.read, automations.write y automation_runs.read— sí se
conceden por OAuth (consulta los scopes de consentimiento de Automatizaciones más
arriba), pero eliminar la automatización de otro es destructivo y no se puede deshacer
desde la API, así que queda fuera del catálogo de consentimiento por diseño — la misma
decisión que con verifactu:write. Requiere el módulo de plan automations.
| Scope | Concede | Gating de módulo |
|---|---|---|
automations:delete | Eliminar reglas de automatización. La baja es lógica e irreversible desde la API: la regla deja de dispararse, mientras que sus versiones selladas y su historial de ejecuciones siguen siendo auditables. | automations |
verifactu:write y delivery_notes:gdpr_forget también son scopes detallados
solo para API key
(descritos arriba) — se aplican en la frontera de la tool como cualquier otro
scope, pero no tienen contraparte en el consentimiento OAuth.
Un último grupo cubre las demás tools publicadas de catálogo y observabilidad de primera parte que no tienen scope punteado en OAuth:
| Scope | Concede | Módulo requerido |
|---|---|---|
taxes:delete | Eliminar un tipo impositivo cuando no esté en uso. | — |
developers:read | Inspeccionar tu propio log de peticiones API. | — |
emails:read | Inspeccionar historial y estado de emails enviados. | — |
integration_events:read | Inspeccionar eventos de pasarela y motivos tipados de descarte. | integration_stripe |
integration_events:write | Reprocesar eventos de pasarela aparcados. | integration_stripe |
gocardless_autoinvoicing:read | Reservado en el catálogo cerrado; ninguna tool publicada lo usa hoy. | integration_gocardless |
gocardless_autoinvoicing:write | Reservado en el catálogo cerrado; ninguna tool publicada lo usa hoy. | integration_gocardless |
monei_autoinvoicing:read | Reservado en el catálogo cerrado; ninguna tool publicada lo usa hoy. | integration_monei |
monei_autoinvoicing:write | Reservado en el catálogo cerrado; ninguna tool publicada lo usa hoy. | integration_monei |
Gating por plan y módulo
La mayoría de las tools publicadas solo aplican una comprobación de scope: son
accesibles en cuanto la credencial tiene el scope requerido. Tres familias además están
limitadas por módulo. Las tools de Tarifas mapean
price_lists:* a products. Las tools de Pagos y pasarelas
mapean sus scopes (stripe_autoinvoicing:*, payouts:read,
integration_events:*) al módulo integration_stripe.
Las tools de personal (Empleados, Asientos de empleado, Horarios de trabajo, Control
horario, Ausencias, Presencia, Festivos) mapean sus scopes (employees:*,
time_entries:*, absences:*, work_schedules:*, presence:read, holidays:read,
payroll_exports:*) al módulo control_horario. Las
tools de Automatizaciones mapean sus scopes (automations:*,
automation_runs:read) al módulo automations. Cuando el plan de la empresa no incluye
el módulo, el servidor oculta esas tools de tools/list y devuelve module_not_in_plan
(-32005) ante una llamada directa.
- Los límites de uso del plan (p. ej. cuotas mensuales de documentos) se aplican en
el momento de la llamada y se manifiestan como
plan_limit_exceeded(-32004). Consulta Errores y límites de peticiones.
Toda la superficie pública MCP también requiere que la empresa tenga un
plan de Factuarea activo — el acceso a la API está incluido en todos los
planes; de lo contrario, cada llamada devuelve addon_not_active (-32007).
Permisos de tiendas
La gestión de tiendas usa stores:read y stores:write; los scopes del proveedor son woocommerce_store:read, woocommerce_store:write, shopify_store:read y shopify_store:write. Las pruebas de conexión requieren el scope de escritura del proveedor. Estos scopes se asignan a API keys y quedan fuera del consentimiento OAuth. Consulta la tabla de operaciones de tiendas.