Scopes i permisos
El catàleg de scopes del consentiment OAuth, com es mapeja als scopes detallats que apliquen les tools, el super-scope i el gating per pla/mòdul.
Cada tool MCP declara el scope que una credencial ha de tenir per invocar-la. Els scopes funcionen de manera lleugerament diferent segons el canal:
- Les API keys es creen directament amb scopes detallats
(
resource:action, p. ex.invoices:read) — el mateix catàleg tancat que fa servir l'API REST. També pots concedir el super-scope*. - Els tokens OAuth reben scopes amb punt (
resource.action, p. ex.invoices.read) a la pantalla de consentiment. El servidor els tradueix als scopes detallats automàticament, de manera que tots dos canals apliquen el mateix conjunt al límit de la tool.
Catàleg de consentiment OAuth
Aquests són els scopes que un usuari pot concedir a una app de tercers a la pantalla de consentiment. Hi ha 56 scopes simples més 3 macros.
Scopes simples
Cadascun concedeix una capacitat. La columna Maps to mostra el scope detallat que apliquen les tools — la capa de consentiment tradueix els scopes OAuth amb punt a aquests automàticament. La columna Sensitive marca els scopes que la pantalla de consentiment destaca i no marca per defecte.
Perfil
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
profile.read | Llegir el teu nom, email i empresa activa. | account:read | no |
CRM — clients i proveïdors
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
clients.read | Llistar i llegir clients. | clients:read | no |
clients.write | Crear i actualitzar clients. | clients:write | no |
clients.delete | Eliminar clients. | clients:delete | ⚠ sí |
suppliers.read | Llistar i llegir proveïdors. | suppliers:read | no |
suppliers.write | Crear i actualitzar proveïdors. | suppliers:write | no |
suppliers.delete | Eliminar proveïdors. | suppliers:delete | ⚠ sí |
Catàleg — productes, sèries, impostos
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
products.read | Llistar i llegir el catàleg de productes. | products:read | no |
products.write | Crear i actualitzar productes. | products:write | no |
products.delete | Eliminar productes. | products:delete | ⚠ sí |
series.read | Llegir sèries de numeració. | series:read | no |
series.write | Crear i actualitzar sèries de numeració. | series:write | no |
taxes.read | Llegir tipus impositius i retencions. | taxes:read | no |
taxes.write | Crear i actualitzar tipus impositius. | taxes:write | no |
Vendes — factures, pressupostos, proformes, albarans
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
invoices.read | Llistar i llegir factures. | invoices:read | no |
invoices.write | Crear i actualitzar factures. | invoices:write | no |
invoices.send | Enviar factures per email. | invoices:send | no |
invoices.delete | Eliminar factures en esborrany. | invoices:delete | ⚠ sí |
invoices.annul | Anul·lar factures emeses. | invoices:void | ⚠ sí |
invoices.create_corrective | Emetre factures rectificatives. | invoices:write | no |
quotes.read | Llistar i llegir pressupostos. | quotes:read | no |
quotes.write | Crear i actualitzar pressupostos. | quotes:write | no |
quotes.send | Enviar pressupostos per email. | quotes:send | no |
quotes.delete | Eliminar pressupostos. | quotes:delete | ⚠ sí |
quotes.convert_to_invoice | Acceptar/rebutjar i convertir pressupostos en factures. | quotes:transition | no |
proformas.read | Llistar i llegir factures proforma. | proformas:read | no |
proformas.write | Crear i actualitzar proformes. | proformas:write | no |
proformas.send | Enviar proformes per email. | proformas:send | no |
proformas.delete | Eliminar proformes. | proformas:delete | ⚠ sí |
proformas.convert | Convertir proformes en factures. | proformas:transition | no |
delivery_notes.read | Llistar i llegir albarans. | delivery_notes:read | no |
delivery_notes.write | Crear, actualitzar i enviar albarans. | delivery_notes:write | no |
delivery_notes.send | Enviar albarans per email. | delivery_notes:write | no |
delivery_notes.delete | Eliminar albarans. | delivery_notes:delete | ⚠ sí |
delivery_notes.convert | Convertir albarans. | delivery_notes:transition | no |
delivery_notes.sign | Marcar com a lliurats / signar albarans. | delivery_notes:transition | ⚠ sí |
Compres
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
purchase_invoices.read | Llistar i llegir factures de compra. | purchase_invoices:read | no |
purchase_invoices.write | Crear i actualitzar factures de compra. | purchase_invoices:write | no |
purchase_invoices.mark_paid | Marcar factures de compra com a pagades. | purchase_invoices:transition | ⚠ sí |
purchase_invoices.delete | Eliminar factures de compra. | purchase_invoices:delete | ⚠ sí |
Els scopes de pagament són asimètrics entre vendes i compres. Registrar un
pagament en una factura de venda (register_invoice_payment) requereix
invoices:write — edita la factura. En canvi, registrar un pagament en una
factura de compra (register_purchase_invoice_payment) requereix
purchase_invoices:transition, perquè al costat de compra un pagament fa
avançar la factura pel seu cicle de vida (pendent → pagada) en lloc
d'editar-la.
Factures recurrents
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
recurring.read | Llistar i llegir plantilles recurrents. | recurring_invoices:read | no |
recurring.write | Crear i actualitzar plantilles recurrents. | recurring_invoices:write | no |
recurring.pause | Pausar plantilles recurrents. | recurring_invoices:transition | no |
recurring.resume | Reprendre plantilles recurrents. | recurring_invoices:transition | no |
recurring.generate_now | Emetre una factura recurrent manualment. | recurring_invoices:transition | ⚠ sí |
recurring.delete | Eliminar plantilles recurrents. | recurring_invoices:delete | ⚠ sí |
Compliment (VeriFactu)
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
verifactu.read | Llegir registres, esdeveniments, certificats i configuració de VeriFactu. | verifactu:read | no |
Webhooks
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
webhooks.read | Llistar webhook endpoints i lliuraments. | webhooks:read | no |
webhooks.write | Crear, actualitzar, rotar i fer ping de webhook endpoints. | webhooks:write | ⚠ sí |
webhooks.delete | Eliminar webhook endpoints. | webhooks:delete | ⚠ sí |
Macros
Paquets de conveniència que s'expandeixen a una llista de scopes simples en el moment d'emetre el token. El token persisteix els scopes expandits — les macros mai s'emmagatzemen.
| Macro | Concedeix | Sensitive |
|---|---|---|
factuarea.read | Accés de lectura complet a tot (sense escriptures). | no |
factuarea.write | Llegir-ho tot, a més de crear/actualitzar documents i enviar emails. | no |
factuarea.full | Llegir, escriure, enviar i accions destructives (eliminar, anul·lar, marcar com a pagada, signar). Exclou les escriptures de VeriFactu. | ⚠ sí |
El super-scope *
Una credencial que té * cobreix tots els scopes — les 232 tools en el cas d'una
API key. És l'equivalent a una clau de propietari. Reserva'l per a migracions puntuals
o automatitzacions de propietari totalment fiables; per a tota la resta, prefereix el
conjunt de scopes més reduït. El super-scope està disponible per a les API keys; el
consentiment OAuth concedeix scopes explícits (o macros), mai un * directe.
Com els scopes OAuth es converteixen en scopes detallats
Quan s'emet un token OAuth, els seus scopes amb punt es tradueixen un cop al catàleg detallat que apliquen les tools. Val la pena conèixer algunes reconciliacions:
recurring.*es mapeja al recursrecurring_invoices:*.invoices.create_correctivees mapeja ainvoices:write(crear és una escriptura).invoices.annules mapeja ainvoices:void.- Les accions de cicle de vida (
*.convert,*.sign,*.pause,*.resume,*.generate_now,*.mark_paid,quotes.convert_to_invoice) es mapegen al scope:transitiondel recurs. - Qualsevol scope de lectura sobre un document també concedeix les utilitats de
lectura transversals
pdfs:read(descarregar el seu PDF/rebut) ievents:read(el seu registre d'activitat). verifactu.writeidelivery_notes:gdpr_forgetno tenen scope OAuth amb punt — són inabastables via OAuth per disseny.facturae:read/facturae:writeencara no són al catàleg de consentiment OAuth — les tools de FacturaE (FACe) només són accessibles amb API key per ara.
Gating per pla i mòdul
Avui cap tool del MCP públic està limitada per mòdul: cada tool publicada és accessible
quan la credencial té el scope requerit — només s'aplica la comprovació de scope. Si en
el futur es publiqués una tool limitada per mòdul, el servidor l'ocultaria de
tools/list quan el pla de l'empresa no inclogui el mòdul i retornaria
module_not_in_plan (-32005) davant d'una crida directa.
- Els límits d'ús del pla (p. ex. quotes mensuals de documents) s'apliquen en el
moment de la crida i es manifesten com a
plan_limit_exceeded(-32004). Consulta Errors i límits de peticions.
Tota la superfície pública MCP també requereix que l'add-on d'API per a
desenvolupadors de l'empresa estigui actiu; en cas contrari, cada crida retorna
addon_not_active (-32007).
Catàleg de tools
Les 232 tools del MCP de Factuarea agrupades per domini, amb el scope que requereix cadascuna i la seva categoria de límit de peticions.
Errors i límits de peticions
Formes d'error JSON-RPC mapejades des del contracte v1, la taula completa de codis i throttling per token / per pla amb Retry-After.