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 62 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 |
Contactes
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
contacts.read | Llistar i consultar contactes canònics. | contacts:read | no |
contacts.write | Crear contactes i modificar identitat, rols i perfils. | contacts:write | no |
contacts.delete | Arxivar contactes i retirar rols sense referències. | contacts:delete | sí |
Catàleg — productes, tarifes, 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í |
price_lists.read | Llegir tarifes, ítems i preus efectius. | price_lists:read | no |
price_lists.write | Crear, actualitzar i eliminar tarifes i ítems. | price_lists:write | no |
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; duplicar des de source_purchase_invoice_id exigeix a més purchase_invoices:read. | 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 i informes fiscals
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
verifactu.read | Llegir registres, esdeveniments, certificats i configuració de VeriFactu. | verifactu:read | no |
facturae.read | Llegir XML FacturaE i enviaments a FACe. | facturae:read | no |
facturae.write | Enviar i cancel·lar presentacions a FACe. | facturae:write | sí |
tax_reports.read | Llegir previsualitzacions, historial, fitxers i estadístiques d'informes fiscals. | tax_reports:read | no |
tax_reports.write | Generar informes fiscals i llibres de revisió. | tax_reports:write | sí |
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í |
Automatitzacions
Regles d'automatització i el seu historial d'execucions. Tots els scopes
d'automatitzacions són sensibles: una regla pot enviar correus i disparar webhooks
en nom del titular, i l'historial d'execucions porta a dins els payloads de negoci
que van moure les seves accions (imports, destinataris, resultats). Tots tres
requereixen el mòdul de pla automations — consulta
Gating per pla i mòdul. Llegir i escriure regles i llegir
l'historial d'execucions es concedeixen a la pantalla de consentiment; esborrar una
regla no — automations:delete no té scope OAuth amb punt i és només API key
(llistat més avall als scopes detallats).
automations.read i automation_runs.read es concedeixen per separat a propòsit. El
primer cobreix el reglament: les regles, les seves versions segellades, el catàleg
d'activadors i accions, i l'assaig que diu què faria una regla sense arribar a fer-ho.
El segon cobreix el que les regles van fer de debò: cada execució, els seus passos, els
seus motius de descart tipificats i el payload congelat de l'activador que porta cada
execució. Una app pot llegir quines automatitzacions existeixen sense llegir les dades
de negoci que va tocar cada execució.
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
automations.read | Llistar i llegir les regles d'automatització, les seves versions, el catàleg d'activadors i accions, la quota mensual i l'assaig. | automations:read | sí |
automations.write | Crear, actualitzar, activar i pausar regles d'automatització, i rellançar execucions o passos solts. | automations:write | sí |
automation_runs.read | Llegir l'historial d'execucions de les teves automatitzacions, els seus passos i el seu resultat. | automation_runs:read | 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 457 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.
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 |
Un quart grup és el scope d'esborrat del motor d'automatitzacions. Els seus tres
germans —automations.read, automations.write i automation_runs.read— sí que es
concedeixen per OAuth (consulta els scopes de consentiment d'Automatitzacions més
amunt), però eliminar l'automatització d'altri és destructiu i no es pot desfer des de
l'API, així que queda fora del catàleg de consentiment per disseny — la mateixa decisió
que amb verifactu:write. Requereix el mòdul de pla automations.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
automations:delete | Eliminar regles d'automatització. La baixa és lògica i irreversible des de l'API: la regla deixa de disparar-se, mentre que les seves versions segellades i el seu historial d'execucions continuen sent auditables. | automations |
verifactu: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.
Un últim grup cobreix altres tools publicades de catàleg i observabilitat de primera part que encara no tenen scope puntejat a OAuth:
| Scope | Concedeix | Mòdul requerit |
|---|---|---|
taxes:delete | Eliminar un tipus impositiu quan no estigui en ús. | — |
developers:read | Inspeccionar el teu propi registre de peticions API. | — |
emails:read | Inspeccionar historial i estat d'emails enviats. | — |
integration_events:read | Inspeccionar esdeveniments de passarel·la i motius tipats de descart. | integration_stripe |
integration_events:write | Reprocessar esdeveniments de passarel·la aparcats. | integration_stripe |
gocardless_autoinvoicing:read | Reservat al catàleg tancat; cap tool publicada l'usa avui. | integration_gocardless |
gocardless_autoinvoicing:write | Reservat al catàleg tancat; cap tool publicada l'usa avui. | integration_gocardless |
monei_autoinvoicing:read | Reservat al catàleg tancat; cap tool publicada l'usa avui. | integration_monei |
monei_autoinvoicing:write | Reservat al catàleg tancat; cap tool publicada l'usa avui. | integration_monei |
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. Tres famílies a més estan
limitades per mòdul. Les tools de Tarifes mapegen
price_lists:* a products. Les tools de Pagaments i passarel·les
mapegen els seus scopes (stripe_autoinvoicing:*, payouts:read,
integration_events:*) 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. Les
tools d'Automatitzacions mapegen els seus scopes
(automations:*, automation_runs:read) al mòdul automations. 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).
Permisos de botigues
La gestió de botigues fa servir stores:read i stores:write; els scopes del proveïdor són woocommerce_store:read, woocommerce_store:write, shopify_store:read i shopify_store:write. Les proves de connexió requereixen el scope d’escriptura del proveïdor. Aquests scopes s’assignen a API keys i queden fora del consentiment OAuth. Consulta la taula d’operacions de botigues.