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, clients: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.
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) | clients.delete, invoices.delete, products.delete, taxes.delete, webhook_endpoints.delete… | <resource>:delete |
| Esborrats massius | invoices.bulk_delete, clients.bulk_delete, products.bulk_delete, suppliers.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 |
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.