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 59 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í |
Personal — control horari
Dades d'empleats, fitxatges, absències, horaris de treball, presència, festius i
exportacions de nòmina. Tots els scopes de personal són sensibles (PII d'empleat
i dades de compliment) i requereixen el mòdul de pla control_horario — consulta
Gating per pla i mòdul. Les lectures, employees.write i la
generació d'exportacions de nòmina es concedeixen a la pantalla de consentiment; les
accions privilegiades d'escriptura i transició no tenen scope OAuth amb punt i són
només API key (llistades més avall als scopes detallats).
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
employees.read | Llistar i llegir empleats. | employees:read | ⚠ sí |
employees.write | Crear i actualitzar empleats. | employees:write | ⚠ sí |
time_entries.read | Llegir fitxatges, saldos i fulls d'hores mensuals. | time_entries:read | ⚠ sí |
absences.read | Llistar i llegir absències, polítiques i sol·licituds. | absences:read | ⚠ sí |
work_schedules.read | Llegir horaris de treball i les seves assignacions. | work_schedules:read | ⚠ sí |
presence.read | Llegir la presència en viu i diària. | presence:read | ⚠ sí |
holidays.read | Llegir el calendari de festius de l'empresa. | holidays:read | ⚠ sí |
payroll_exports.read | Llegir les exportacions de nòmina generades. | payroll_exports:read | ⚠ sí |
payroll_exports.write | Generar exportacions de nòmina. | payroll_exports:write | ⚠ 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 391 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.
Scopes detallats sense scope OAuth (només API key)
Alguns scopes detallats viuen al catàleg tancat recurs:accio que fan servir les API
keys, però no tenen equivalent OAuth amb punt — mai es concedeixen a través d'una
pantalla de consentiment de tercers i només són accessibles amb API key. Concedeix-los
directament a la key (o via el super-scope *). Alguns estan gateats per un mòdul
d'integració —llavors l'empresa de la key ha de tenir el pla corresponent (consulta
Gating per pla i mòdul)—; la resta són scopes de compte propi
i de gestoria.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
stripe_autoinvoicing:read | Llegir l'estat de la integració Stripe Connect, la configuració d'auto-facturació i els comptes connectats, i llistar cobraments/rectificatives auto-facturats. | integration_stripe |
stripe_autoinvoicing:write | Activar/desactivar l'auto-facturació de cobraments Stripe, fixar la sèrie auto-emesa i editar/desconnectar comptes connectats. | integration_stripe |
payouts:read | Llegir els payouts de Stripe ingerits i el seu estat de conciliació bancària. | integration_stripe |
Aquests scopes habiliten les tools de Pagaments i passarel·les.
Un segon grup de scopes només per a API key governa la gestió de compte propi
i de gestoria — les teves pròpies credencials i, per a gestories, les empreses
filles que gestiones i les seves API keys. companies:* requereix el mòdul del pla
de gestoria; la resta no tenen gating de mòdul.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
account:write | Gestionar les teves pròpies API keys (crear, rotar, revocar) i actualitzar la personalització del compte. | — |
companies:read | Llistar i llegir les empreses gestionades (subcomptes fills). | gestoria |
companies:write | Crear, actualitzar, activar i desactivar empreses gestionades. | gestoria |
companies:delete | Arxivar empreses gestionades. | gestoria |
api_keys:read | Llistar i llegir les API keys de les empreses gestionades. | — |
api_keys:write | Crear, rotar i revocar les API keys de les empreses gestionades. | — |
api_keys:delete | Eliminar permanentment les API keys de les empreses gestionades. | — |
Un tercer grup cobreix les accions d'escriptura i transició de personal
(control horari). Les seves lectures es concedeixen per OAuth (consulta els scopes
de consentiment de Personal més amunt), però aquests scopes privilegiats no tenen
equivalent OAuth amb punt — són només API key, el mirall de verifactu:write.
Tots requereixen el mòdul de pla control_horario.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
employees:delete | Eliminar empleats de manera permanent. | control_horario |
time_entries:write | Fitxar entrada/sortida, registrar entrades manuals, gestionar correccions de fitxatge i el tancament mensual del registre. | control_horario |
absences:write | Crear i gestionar tipus, polítiques i sol·licituds d'absència. | control_horario |
absences:transition | Aprovar, rebutjar i cancel·lar sol·licituds d'absència. | control_horario |
work_schedules:write | Crear, actualitzar, assignar i arxivar horaris de treball. | control_horario |
verifactu:write, facturae:read, facturae:write i
delivery_notes:gdpr_forget també són scopes detallats només per a API key
(descrits a dalt) — s'apliquen a la frontera de la tool com qualsevol altre
scope, però no tenen contrapart al consentiment OAuth.
Gating per pla i mòdul
La majoria de les tools publicades només apliquen una comprovació de scope: són
accessibles quan la credencial té el scope requerit. Dues famílies a més estan
limitades per mòdul. Les tools de Pagaments i passarel·les
mapegen els seus scopes (stripe_autoinvoicing:*, payouts:read) al mòdul
integration_stripe. Les tools de personal (Empleats, Places d'empleat, Horaris de
treball, Control horari, Absències, Presència, Festius) mapegen els seus scopes
(employees:*, time_entries:*, absences:*, work_schedules:*, presence:read,
holidays:read, payroll_exports:*) al mòdul control_horario. Quan el pla de
l'empresa no inclou el mòdul, el servidor oculta aquestes tools de tools/list i
retorna 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'empresa tingui un
pla de Factuarea actiu — l'accés a l'API està inclòs en tots els plans;
en cas contrari, cada crida retorna addon_not_active (-32007).