Scopes i permisos
El catàleg de scopes del consentiment OAuth, com es mapeja als scopes detallats que apliquen les tools, els scopes de compte i privilegiats, 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*, que no cobreix els dos scopes privilegiats. - 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 79 scopes simples més 3 macros. El
consentiment concedeix les dades de negoci d'un NIF i mai l'administració del
compte: les claus, l'equip, la titularitat, els traspassos de NIF, la cartera de NIF i
els comptes que aprovisiones no tenen aquí cap scope i necessiten una API key (consulta
els scopes sense scope OAuth). Un dels 79, payroll_exports.write, és al catàleg però la pantalla no l'ofereix, perquè
cap tool exigeix el scope al qual es tradueix.
Què concedeix la pantalla segons el nivell i l'entorn
La pantalla no ofereix tots els scopes en tots els casos, i la confirmació ho comprova de nou al servidor:
- Nivell Veure. Si abastes l'empresa amb nivell Veure, només es poden concedir scopes de lectura: els que acaben en
.readi el macrofactuarea.read. Un intent de confirmar escriptura respon403 invalid_scopeambread_only_restricted_scopes, que llista els scopes rebutjats. - Entorn Proves. El sandbox no ofereix alguns mòduls: VeriFactu, l'assistent de WhatsApp, el Vault de documents, les integracions de Stripe, GoCardless, Monei, Slack i Teams, els webhooks i les integracions de tasques. Els seus scopes no es concedeixen a Proves; la confirmació respon
403ambsandbox_restricted_scopes. - Caducitat. La sol·licitud de consentiment caduca als 5 minuts d'obrir-se, i la pantalla diu quants minuts queden.
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 |
taxes.delete | Eliminar els teus propis tipus impositius. | taxes:delete | sí |
Vendes — factures, pressupostos, proformes, albarans, documents de control
| 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í |
transport_documents.read | Llistar i llegir documents de control (DeCA), el seu registre d'emissió i el seu codi QR; concedeix a més pdfs:read per al PDF de cada versió. | transport_documents:read | no |
transport_documents.write | Crear i editar esborranys de documents de control i enviar-los per email al transportista. | transport_documents:write | no |
transport_documents.delete | Eliminar documents de control en esborrany. Un d'emès no s'elimina mai. | transport_documents:delete | sí |
transport_documents.transition | Emetre, modificar, tancar, reobrir, anul·lar i marcar com a substituïts documents de control. Emetre, modificar, anul·lar i substituir no es desfan. | transport_documents:transition | sí |
Plantilles PDF
La biblioteca de plantilles PDF de l'empresa: plantilles, marques (identitats comercials), actius privats i preferències. Tots dos scopes requereixen el mòdul de pla pdf_templates — consulta Gating per pla i mòdul — i cobreixen les tools de Plantilles PDF. Cap macro factuarea.* els inclou, així que una app els ha de demanar de manera explícita. preview_pdf_template necessita a més pdfs:read.
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
pdf_templates.read | Llegir la biblioteca de plantilles PDF, les seves revisions, marques i les preferències de l'emissor. | pdf_templates:read | no |
pdf_templates.write | Gestionar plantilles PDF, revisions, marques, actius privats i les preferències de l'emissor. | pdf_templates:write | no |
Compres
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
purchase_invoices.read | Llistar i llegir despeses. | purchase_invoices:read | no |
purchase_invoices.write | Crear i actualitzar despeses; duplicar des de source_purchase_invoice_id exigeix a més purchase_invoices:read. | purchase_invoices:write | no |
purchase_invoices.mark_paid | Marcar despeses com a pagades. | purchase_invoices:transition | sí |
purchase_invoices.delete | Eliminar despeses. | purchase_invoices:delete | sí |
Els scopes de pagament són asimètrics entre vendes i compres. Registrar un
pagament en una factura (register_invoice_payment) requereix
invoices:write — edita la factura. En canvi, registrar un pagament en una
despesa (register_purchase_invoice_payment) requereix
purchase_invoices:transition, perquè al costat de compra un pagament fa
avançar la despesa 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í |
Aquests scopes cobreixen els webhook endpoints d'un NIF. Les tools de webhooks del compte reutilitzen els mateixos scopes detallats, però el consentiment mai les abasta: consulta les tools de compte que comparteixen scope amb un NIF.
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 i employees.write es
concedeixen a la pantalla de consentiment, payroll_exports.write no s'ofereix, i 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 | No s'ofereix: les exportacions de nòmina són de només lectura i cap tool exigeix payroll_exports:write. | 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í |
Projectes i tasques
Projectes de tasques, tasques i el seu entorn. projects.* i tasks.* requereixen
el mòdul de pla tasks — consulta Gating per pla i mòdul—,
mentre que users.read i notifications.* són transversals i no pertanyen a cap
mòdul. projects.write i tasks.write són sensibles: una app pot crear,
moure i comentar tasques i imputar temps en nom del titular. users.read també és sensible:
exposa el directori complet de l'empresa, amb els emails. Llegir i
escriure es concedeixen a la pantalla de consentiment; esborrar no —
projects:delete i tasks:delete no tenen scope OAuth amb punt i són només API key
(llistats més avall als scopes detallats).
| Scope | Concedeix | Maps to | Sensitive |
|---|---|---|---|
projects.read | Llistar i llegir projectes, les seves columnes, camps personalitzats, temps imputat i exportació. | projects:read | no |
projects.write | Crear i actualitzar projectes: columnes, camps personalitzats, arxivat i importació de tasques. | projects:write | sí |
tasks.read | Cercar i llegir tasques, comentaris, activitat, relacions, vincles, adjunts, temps imputat, etiquetes i l'agenda. | tasks:read | no |
tasks.write | Crear i actualitzar tasques: estat, assignació, comentaris, etiquetes, adjunts i temps imputat en nom teu. | tasks:write | sí |
users.read | Llegir els membres de la teva empresa (nom i email) per assignar-los tasques, i el teu propi usuari. | users:read | sí |
notifications.read | Llegir les notificacions de la teva safata. | notifications:read | no |
notifications.write | Marcar com a llegides les notificacions de la teva safata. | notifications:write | no |
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 excepte els dos
privilegiats, accounts:read i accounts:write — les
668 tools del catàleg 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.
Una clau que només té * no abasta les deu
tools de comptes gestionats: necessiten accounts:read o
accounts:write a la clau, i que el compte tingui el privilegi.
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). pdf_templates.readipdf_templates.writees mapegen apdf_templates:readipdf_templates:write. No concedeixenpdfs:read: les tools d'artefactes PDF l'obtenen d'un scope de lectura de document, com al punt anterior.verifactu.writeidelivery_notes:gdpr_forgetno tenen scope OAuth amb punt — són inabastables via OAuth per disseny.- Els scopes del compte —
account:write,account:owner,members:*,invitations:*,nif_transfers:*,companies:*i els privilegiatsaccounts:*— tampoc no en tenen.profile.readés l'únic scope de compte que tradueix el consentiment, i donaaccount:read.
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 *, tret d'accounts:*). 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 first-party del compte.
| 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 el que té el compte mateix:
les seves claus, el seu equip, la seva titularitat i els seus traspassos de NIF.
account:read és l'únic scope de compte que abasta el consentiment, mitjançant
profile.read. No són privilegiats, així que el super-scope * sí que els cobreix. Els
scopes members:*, invitations:* i nif_transfers:* requereixen el mòdul
user_management: en un pla sense ell no es poden assignar a una clau (consulta
Gating per pla i mòdul).
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
account:write | Crear, rotar i revocar les API keys del compte, canviar els NIF que abasta una clau i actualitzar la personalització del compte. | — |
account:owner | Transferir la titularitat del compte a una altra persona de l'equip. | — |
members:read | Llegir els membres del compte, els seus grants (permisos per NIF) en cada NIF i les seves restriccions de mòdul. | user_management |
members:write | Afegir, canviar el rol i donar de baixa membres, fixar i retirar els seus grants en un NIF —també en un que un altre compte cedeix al teu— i canviar les seves restriccions de mòdul. | user_management |
invitations:read | Llistar i consultar les invitacions del compte. | user_management |
invitations:write | Enviar, reenviar i revocar invitacions. | user_management |
nif_transfers:read | Llistar els traspassos de NIF que va emetre el compte. | user_management |
nif_transfers:write | Emetre, acceptar i revocar un traspàs de NIF. | user_management |
Com funcionen els grants d'un membre en un NIF d'un altre compte és a accés cedit.
Un tercer grup governa la cartera de NIF del compte. Qualsevol compte, en qualsevol
pla, llista i consulta els seus propis NIF, així que companies:* no té gating de mòdul.
El que el pla controla és afegir un NIF que paga el compte, i ho fa dins de l'operació, no
al scope: consulta NIF addicionals.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
companies:read | Llistar i consultar els NIF del compte, les seves estadístiques, el seu estat de creació i la seva aptitud per emetre, la vista prèvia del càrrec d'un NIF addicional i el resum consolidat de compliment de jornada. | — |
companies:write | Donar d'alta, editar, activar i desactivar NIF del compte, i verificar la creació d'un. | — |
companies:delete | Arxivar un NIF del compte. | — |
Un quart 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 cinquè 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 |
Un cinquè grup són els scopes d'esborrat del mòdul de tasques. Els seus germans
—projects.read|write i tasks.read|write— sí es concedeixen per OAuth (consulta els
scopes de consentiment de Projectes i tasques més amunt), però esborrar un projecte o
una tasca s'endú els seus comentaris, adjunts i temps imputat i no es pot desfer des
de l'API, així que tots dos queden fora del catàleg de consentiment per disseny — la
mateixa decisió que amb automations:delete. Requereixen el mòdul de pla tasks.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
projects:delete | Esborrar de manera permanent projectes, columnes de tauler i definicions de camps personalitzats. | tasks |
tasks:delete | Esborrar de manera permanent tasques, comentaris, adjunts, imputacions de temps i etiquetes. | tasks |
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 les altres tools d'observabilitat first-party i els scopes que el catàleg tancat reserva, cap dels quals té scope puntejat a OAuth:
| Scope | Concedeix | Mòdul requerit |
|---|---|---|
api_keys:read | Reservat al catàleg tancat; cap tool publicada l'usa. Les API keys del compte es gestionen amb account:read i account:write. | — |
api_keys:write | Reservat al catàleg tancat; cap tool publicada l'usa. Les API keys del compte es gestionen amb account:read i account:write. | — |
api_keys:delete | Reservat al catàleg tancat; cap tool publicada l'usa. Les API keys del compte es gestionen amb account:read i account:write. | — |
developers:read | Inspeccionar el registre de peticions API d'un NIF i del compte. | — |
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 |
Scopes privilegiats
Dos scopes són privilegiats: accounts:read i accounts:write. Permeten que un
compte aprovisioni, administri i cobri els comptes dels seus clients, i les deu
tools de comptes gestionats els necessiten. Es distingeixen
de tots els altres scopes:
- El super-scope
*no els cobreix. Llista'ls a la clau, al costat de*si també vols la resta del compte. - Factuarea els concedeix, compte per compte. No te'ls pots assignar: l'API no té cap
operació que concedeixi el privilegi, i crear una clau que els llista sense ell respon
403 privileged_scope_required.GET /v1/meet diu si el teu compte el té, aaccount.is_provideriaccount.privileged_scopes. - Es comproven a cada crida. La clau ha de llistar el scope, el teu compte ha de tenir
avui el privilegi i la persona que va emetre la clau ha de continuar sent titular o
administrador del compte. Si falla qualsevol de les tres, la resposta és
403 privileged_scope_required, i les dues causes responen igual. Res no surt d'una memòria cau, així que un privilegi retirat atura la mateixa clau a la crida següent. - El consentiment mai no els concedeix i cap mòdul del pla els controla: el gate és el privilegi. Necessiten una API key.
| Scope | Concedeix | Gating de mòdul |
|---|---|---|
accounts:read | Llistar i consultar els comptes gestionats del teu compte, llegir el seu consum d'aprovisionament i la vista prèvia d'un canvi de pla, i descarregar la plantilla d'una importació massiva. | — |
accounts:write | Aprovisionar un compte gestionat, canviar-ne el pla i el nivell, reemetre'n el val, acabar-ne la gestió, i previsualitzar i aplicar una importació massiva. | — |
La importació massiva necessita els mateixos scopes i no té tool MCP: consulta el que el servidor MCP no transporta.
Tools de compte que comparteixen scope amb un NIF
Deu tools administren els webhook endpoints del compte i dues llegeixen el seu registre de
peticions API. Reutilitzen webhooks:read, webhooks:write, webhooks:delete i
developers:read, els scopes que ja fan servir les tools d'un NIF, així que el scope per si
sol no les distingeix. Les distingeix el canal:
| Scope | Tools del compte | Canal |
|---|---|---|
webhooks:read | list_account_webhooks, get_account_webhook, list_account_webhook_deliveries, get_account_webhook_delivery | Només API key |
webhooks:write | create_account_webhook, update_account_webhook, rotate_account_webhook_secret, test_account_webhook, retry_account_webhook_delivery | Només API key |
webhooks:delete | delete_account_webhook | Només API key |
developers:read | list_account_request_logs, get_account_request_log | Només API key |
OAuth no les abasta encara que tingui el scope: tools/list no les anuncia a una connexió
OAuth, i una crida directa respon 403 forbidden_action. Les tools de webhooks d'un NIF
conserven els seus scopes de consentiment.
Amb una API key, cada crida comprova primer que el compte de la credencial sigui abastable
(404 account_not_found), després, en una tool que escriu, que la clau sigui live
(403 live_credential_required amb una clau de proves) i, finalment, que la persona que va
emetre la clau sigui avui titular o administrador del compte i que el scope de la clau cobreixi
tots els NIF reals del compte (403 forbidden_action, la mateixa resposta per a les dues
causes). El tram del pagador del compte també limita els endpoints: un tram sense webhooks de
compte respon 402 addon_required, i un que ja és al seu topall
422 account_webhook_endpoint_limit_reached.
Webhooks de compte descriu cada comprovació.
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. Diverses 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. Els scopes d'equip i
traspàs (members:*, invitations:*, nif_transfers:*) es mapegen al mòdul
user_management, que inclouen els plans empresario i enterprise. Les
tools de Projectes i Tasques mapegen projects:* i tasks:* al
mòdul tasks, que inclouen tots els plans; users:read i notifications:* no
pertanyen a cap mòdul. Les tools de Plantilles PDF mapegen pdf_templates:* al mòdul pdf_templates, i les tools de FacturaE (FACe) requereixen el mòdul facturae. 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.
- Alguns scopes no tenen gating de mòdul, a propòsit.
accounts:*els controla el privilegi del compte, no el pla.companies:*deixa que qualsevol compte, en qualsevol pla, llisti i consulti els seus propis NIF: el pla controla la compra d'un NIF addicional dins de l'operació (NIF addicionals), no el scope, així que la cartera de NIF no depèn d'un mòdul del pla.account:*són operacions del compte sobre ell mateix i tampoc no en tenen. - 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.