Scopes y permisos

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 *, que no cubre los dos scopes privilegiados.
• 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 79 scopes simples más 3 macros. El consentimiento concede los datos de negocio de un NIF y nunca la administración de la cuenta: las claves, el equipo, la titularidad, los traspasos de NIF, la cartera de NIF y las cuentas que aprovisionas no tienen aquí ningún scope y necesitan una API key (consulta los scopes sin scope OAuth). Uno de los 79, payroll_exports.write, está en el catálogo pero la pantalla no lo ofrece, porque ninguna tool exige el scope al que se traduce.

Qué concede la pantalla según el nivel y el entorno

La pantalla no ofrece todos los scopes en todos los casos, y la confirmación lo comprueba de nuevo en el servidor:

• Nivel Ver. Si alcanzas la empresa con nivel Ver, solo se pueden conceder scopes de lectura: los que terminan en .read y el macro factuarea.read. Un intento de confirmar escritura responde 403 invalid_scope con read_only_restricted_scopes, que lista los scopes rechazados.
• Entorno Pruebas. El sandbox no ofrece algunos módulos: VeriFactu, el asistente de WhatsApp, el Vault de documentos, las integraciones de Stripe, GoCardless, Monei, Slack y Teams, los webhooks y las integraciones de tareas. Sus scopes no se conceden en Pruebas; la confirmación responde 403 con sandbox_restricted_scopes.
• Caducidad. La solicitud de consentimiento caduca a los 5 minutos de abrirse, y la pantalla dice cuántos minutos quedan.

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

Contactos

Catálogo — productos, tarifas, series, impuestos

Ventas — facturas, presupuestos, proformas, albaranes, documentos de control

Plantillas PDF

La biblioteca de plantillas PDF de la empresa: plantillas, marcas (identidades comerciales), activos privados y preferencias. Ambos scopes requieren el módulo de plan pdf_templates — consulta Gating por plan y módulo — y cubren las tools de Plantillas PDF. Ninguna macro factuarea.* los incluye, así que una app tiene que pedirlos de forma explícita. preview_pdf_template necesita además pdfs:read.

Compras

Facturas recurrentes

Cumplimiento e informes fiscales

Webhooks

Estos scopes cubren los webhook endpoints de un NIF. Las tools de webhooks de la cuenta reutilizan los mismos scopes detallados, pero el consentimiento nunca las alcanza: consulta las tools de cuenta que comparten scope con un NIF.

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 y employees.write se conceden en la pantalla de consentimiento, payroll_exports.write no se ofrece, y 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).

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.

Proyectos y tareas

Proyectos de tareas, tareas y su entorno. projects.* y tasks.* requieren el módulo de plan tasks — consulta Gating por plan y módulo—, mientras que users.read y notifications.* son transversales y no pertenecen a ningún módulo. projects.write y tasks.write son sensibles: una app puede crear, mover y comentar tareas e imputar tiempo en nombre del titular. users.read también es sensible: expone el directorio completo de la empresa, con los emails. Leer y escribir se conceden en la pantalla de consentimiento; borrar no — projects:delete y tasks:delete no tienen scope OAuth con punto y son solo API key (listados más abajo en los scopes detallados).

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.

El super-scope *

Una credencial que tiene * cubre todos los scopes excepto los dos privilegiados, accounts:read y accounts:write — las 686 tools del catálogo 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.

Una clave que solo tiene * no alcanza las diez tools de cuentas gestionadas: necesitan accounts:read o accounts:write en la clave, y que la cuenta tenga el privilegio.

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 recurso recurring_invoices:*.
• invoices.create_corrective se mapea a invoices:write (crear es una escritura).
• invoices.annul se mapea a invoices:void.
• Las acciones de ciclo de vida (*.convert, *.sign, *.pause, *.resume, *.generate_now, *.mark_paid, quotes.convert_to_invoice) se mapean al scope :transition del recurso.
• Cualquier scope de lectura sobre un documento también concede las utilidades de lectura transversales pdfs:read (descargar su PDF/recibo) y events:read (su registro de actividad).
• pdf_templates.read y pdf_templates.write se mapean a pdf_templates:read y pdf_templates:write. No conceden pdfs:read: las tools de artefactos PDF lo obtienen de un scope de lectura de documento, como en el punto anterior.
• verifactu.write y delivery_notes:gdpr_forget no tienen scope OAuth con punto — son inalcanzables vía OAuth por diseño.
• Los scopes de la cuenta — account:write, account:owner, members:*, invitations:*, nif_transfers:*, companies:* y los privilegiados accounts:* — tampoco tienen. profile.read es el único scope de cuenta que traduce el consentimiento, y da account:read.

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 *, salvo accounts:*). 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 first-party de la cuenta.

Estos scopes habilitan las tools de Pagos y pasarelas.

Un segundo grupo de scopes solo para API key gobierna lo que tiene la cuenta misma: sus claves, su equipo, su titularidad y sus traspasos de NIF. account:read es el único scope de cuenta que alcanza el consentimiento, mediante profile.read. No son privilegiados, así que el super-scope * sí los cubre. Los scopes members:*, invitations:* y nif_transfers:* requieren el módulo user_management: en un plan sin él no se pueden asignar a una clave (consulta Gating por plan y módulo).

Cómo funcionan los grants de un miembro en un NIF de otra cuenta está en acceso cedido.

Un tercer grupo gobierna la cartera de NIF de la cuenta. Cualquier cuenta, en cualquier plan, lista y consulta sus propios NIF, así que companies:* no tiene gating de módulo. Lo que el plan controla es añadir un NIF que paga la cuenta, y lo hace dentro de la operación, no en el scope: consulta NIF adicionales.

Un cuarto 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.

Un quinto 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.

Un quinto grupo son los scopes de borrado del módulo de tareas. Sus hermanos —projects.read|write y tasks.read|write— sí se conceden por OAuth (consulta los scopes de consentimiento de Proyectos y tareas más arriba), pero borrar un proyecto o una tarea se lleva consigo sus comentarios, adjuntos y tiempo imputado y no se puede deshacer desde la API, así que los dos quedan fuera del catálogo de consentimiento por diseño — la misma decisión que con automations:delete. Requieren el módulo de plan tasks.

Un último grupo cubre las demás tools de observabilidad first-party y los scopes que el catálogo cerrado reserva, ninguno de los cuales tiene scope punteado en OAuth:

Scopes privilegiados

Dos scopes son privilegiados: accounts:read y accounts:write. Permiten que una cuenta aprovisione, administre y cobre las cuentas de sus clientes, y las diez tools de cuentas gestionadas los necesitan. Se distinguen de todos los demás scopes:

• El super-scope * no los cubre. Lístalos en la clave, junto a * si quieres también el resto de la cuenta.
• Factuarea los concede, cuenta por cuenta. No puedes asignártelos: la API no tiene ninguna operación que conceda el privilegio, y crear una clave que los lista sin él responde 403 privileged_scope_required. GET /v1/me te dice si tu cuenta lo tiene, en account.is_provider y account.privileged_scopes.
• Se comprueban en cada llamada. La clave debe listar el scope, tu cuenta debe tener hoy el privilegio y la persona que emitió la clave debe seguir siendo titular o administrador de la cuenta. Si falla cualquiera de las tres, la respuesta es 403 privileged_scope_required, y las dos causas responden igual. Nada sale de una caché, así que un privilegio retirado detiene la misma clave en su siguiente llamada.
• El consentimiento nunca los concede y ningún módulo del plan los controla: el gate es el privilegio. Necesitan una API key.

La importación masiva necesita los mismos scopes y no tiene tool MCP: consulta lo que el servidor MCP no transporta.

Tools de cuenta que comparten scope con un NIF

Diez tools administran los webhook endpoints de la cuenta y dos leen su log de peticiones API. Reutilizan webhooks:read, webhooks:write, webhooks:delete y developers:read, los scopes que ya usan las tools de un NIF, así que el scope por sí solo no las distingue. Las distingue el canal:

OAuth no las alcanza aunque tenga el scope: tools/list no las anuncia a una conexión OAuth, y una llamada directa responde 403 forbidden_action. Las tools de webhooks de un NIF conservan sus scopes de consentimiento.

Con una API key, cada llamada comprueba primero que la cuenta de la credencial sea alcanzable (404 account_not_found), luego, en una tool que escribe, que la clave sea live (403 live_credential_required con una clave de pruebas) y, por último, que la persona que emitió la clave sea hoy titular o administrador de la cuenta y que el scope de la clave cubra todos los NIF reales de la cuenta (403 forbidden_action, la misma respuesta para las dos causas). El tramo del pagador de la cuenta también limita los endpoints: un tramo sin webhooks de cuenta responde 402 addon_required, y uno que ya está en su tope 422 account_webhook_endpoint_limit_reached. Webhooks de cuenta describe cada comprobación.

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. Varias 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. Los scopes de equipo y traspaso (members:*, invitations:*, nif_transfers:*) se mapean al módulo user_management, que incluyen los planes empresario y enterprise. Las tools de Proyectos y Tareas mapean projects:* y tasks:* al módulo tasks, que incluyen todos los planes; users:read y notifications:* no pertenecen a ningún módulo. Las tools de Plantillas PDF mapean pdf_templates:* al módulo pdf_templates, y las tools de FacturaE (FACe) requieren el módulo facturae. 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.

• Algunos scopes no tienen gating de módulo, a propósito. accounts:* los controla el privilegio de la cuenta, no el plan. companies:* deja que cualquier cuenta, en cualquier plan, liste y consulte sus propios NIF: el plan controla la compra de un NIF adicional dentro de la operación (NIF adicionales), no el scope, así que la cartera de NIF no depende de un módulo del plan. account:* son operaciones de la cuenta sobre sí misma y tampoco lo tienen.
• 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.