Scopes i irreversibilitat
Com llegir el scope requerit i la irreversibilitat de cada endpoint des de l'especificació OpenAPI — les extensions x-required-scope i x-irreversible — i el catàleg d'operacions irreversibles.
Cada endpoint públic declara dues peces de metadata de seguretat a
l'especificació OpenAPI: el scope exacte que enforça i si l'operació es pot
desfer. Els clients (el CLI, els agents, el teu propi tooling) les
llegeixen per fallar aviat — bloquejar una crida quan la key no té el scope,
confirmar abans d'una acció irreversible — en lloc de descobrir el problema per
un 403 o una mutació irrecuperable.
Llegir-ho des de l'especificació
Cada operació a l'especificació OpenAPI porta dues extensions personalitzades:
{
"operationId": "public-api.v1.invoices.delete",
"x-required-scope": "invoices:delete",
"x-irreversible": true
}x-required-scope— l'únic scoperesource:actionque l'API key ha de tenir per cridar l'operació. Present a totes les operacions.x-irreversible—truenomés a les operacions que no es poden desfer. Absent (tractat com afalse) a tota la resta.
Són extensions de proveïdor x-*, així que un visor OpenAPI genèric pot no
renderitzar-les — però qualsevol client que parsegi l'especificació (com el
CLI) les llegeix directament. Genera un client des de l'especificació i heretes
totes dues.
Scopes
Els scopes són resource:action (p. ex. invoices:read, contacts:delete) — el
mateix catàleg tancat que fan servir la REST API i les API keys. Una petició la
key de la qual no té el scope retorna 403 amb code: insufficient_scope.
Demana només els scopes que la teva integració necessita.
Una operació exigeix un segon scope a més de x-required-scope quan un camp
amplia el que llegeix: POST /v1/purchase_invoices amb
source_purchase_invoice_id necessita també purchase_invoices:read, perquè
copia les línies d'un altre document. Consulta
Línies de compra mesurades.
Les operacions de control horari porten els seus propis scopes — employees:*,
time_entries:*, work_schedules:*, absences:*, presence:read,
holidays:read i payroll_exports:read — tots darrere el mòdul
control_horario. Consulta Control horari.
Les automatitzacions fan el mateix amb automations:read, automations:write,
automations:delete i automation_runs:read, darrere el mòdul automations.
Consulta Automatitzacions.
El catàleg complet — cada scope, què concedeix, i els sensibles — és a
Scopes i permisos. Un scope no sempre es deriva del nom del
recurs: alguns endpoints enforcen un scope diferent del que endevinaries (les
descàrregues de PDF enforcen pdfs:read, els mètodes de pagament enforcen
invoices:read, les transicions d'estat enforcen un scope :transition, les
accions de VeriFactu enforcen verifactu:*). Llegeix sempre x-required-scope
en lloc d'inferir-lo.
Una API key pot tenir el super-scope *, que satisfà qualsevol
x-required-scope. Consulta Autenticació.
Operacions irreversibles
Una operació marcada x-irreversible: true no té desfer: esborra dades, emet
un registre fiscal, transiciona un document a un estat terminal, o rota un
secret. El CLI demana una confirmació
tipada abans d'executar-ne una; el teu propi tooling hauria de protegir-les
igual.
Aquestes són les categories que porten x-irreversible: true:
| Categoria | Exemples | Scope |
|---|---|---|
| Esborrats (individuals) | invoices.delete, products.delete, taxes.delete, webhook_endpoints.delete… | <resource>:delete |
| Eliminacions de subrecursos de catàleg | products.presentations.delete, products.variants.delete, products.supplier-offers.delete, price-lists.delete, price-lists.items.delete, price-lists.items.purge_retired | products:write / price_lists:write |
| Esborrats massius | invoices.bulk_delete, products.bulk_delete… | <resource>:delete |
| Emissió / numeració fiscal | invoices.send, invoices.mark_sent, invoices.assign_real_number, invoices.corrective, invoices.substitute_simplified | invoices:send / invoices:write |
| Void / anul·lació | invoices.void, invoices.annul | invoices:void |
| Conversions terminals | quotes.convert, proformas.convert, delivery_notes.convert | <resource>:transition |
| Cancel·lar / signar | delivery_notes.cancel, delivery_notes.sign, recurring_invoices.cancel, recurring_invoices.generate | <resource>:transition / :write |
| VeriFactu (AEAT) | invoices.verifactu_create, verifactu.records.subsanar, verifactu.settings.update, verifactu.certificates.revoke | verifactu:write |
| Secret / certificat | webhook_endpoints.rotate_secret, verifactu.certificates.revoke | webhooks:write / verifactu:write |
| Oblit GDPR | delivery_notes.signature_audits.forget | delivery_notes:gdpr_forget |
| Enviament FacturaE (B2G) | invoices.face_submissions.submit, face_submissions.cancel | facturae:write |
| Segellat del tancament mensual | monthly_time_record_closes.seal | time_entries:write |
| Rellançament (reexecució) | automations.runs.replay, automations.runs.steps.replay, integrations.events.replay | automations:write / integration_events:write |
Aquesta llista és el resum llegible. La font de veritat llegible per màquina
és x-irreversible a l'especificació — un client que la llegeix es manté
correcte encara que el catàleg creixi.
Ajuntant-ho tot
Un client segur fa dues comprovacions abans d'una mutació:
- Scope-check — té la key el
x-required-scope? Si no, atura't en local (sense gastar un round trip). El CLI surt amb4; consulta scope-check. - Confirmació d'irreversibilitat — és
x-irreversibletrue? Si ho és, confirma abans de cridar. El CLI requereix--confirm <id>; consulta operacions irreversibles.
Els SDKs oficials i el CLI fan totes dues per tu. Si generes el teu propi client des de l'especificació, cabla aquestes dues comprovacions tu mateix des de les extensions.
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.