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 56 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 |
CRM — clientes y proveedores
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
clients.read | Listar y leer clientes. | clients:read | no |
clients.write | Crear y actualizar clientes. | clients:write | no |
clients.delete | Eliminar clientes. | clients:delete | ⚠ sí |
suppliers.read | Listar y leer proveedores. | suppliers:read | no |
suppliers.write | Crear y actualizar proveedores. | suppliers:write | no |
suppliers.delete | Eliminar proveedores. | suppliers:delete | ⚠ sí |
Catálogo — productos, 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í |
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. | 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 (VeriFactu)
| Scope | Concede | Maps to | Sensitive |
|---|---|---|---|
verifactu.read | Leer registros, eventos, certificados y configuración de VeriFactu. | verifactu:read | no |
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í |
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 232 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.facturae:read/facturae:writeaún no están en el catálogo de consentimiento OAuth — las tools de FacturaE (FACe) solo son accesibles con API key por ahora.
Gating por plan y módulo
Hoy ninguna tool del MCP público está limitada por módulo: cada tool publicada es
accesible en cuanto la credencial tiene el scope requerido — solo aplica la
comprobación de scope. Si en el futuro se publicara una tool limitada por módulo, el
servidor la ocultaría de tools/list cuando el plan de la empresa no incluya el módulo
y devolvería 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 el add-on de API para
desarrolladores de la empresa esté activo; de lo contrario, cada llamada devuelve
addon_not_active (-32007).
Catálogo de tools
Las 232 tools del MCP de Factuarea agrupadas por dominio, con el scope que requiere cada una y su categoría de límite de peticiones.
Errores y límites de peticiones
Formas de error JSON-RPC mapeadas desde el contrato v1, la tabla completa de códigos y throttling por token / por plan con Retry-After.