Autentica Cadrumo amb l’AEAT¶

Autentica Cadrumo amb l’Agència Tributària d’Espanya, l’Agencia Estatal de Administración Tributaria (AEAT), perquè l’ordre aeat de Cadrumo pugui llegir la informació que la teva identitat davant l’AEAT autoritzi. L’autenticació només ofereix accés de només lectura. Mai no presenta una declaració, ni fa un pagament, ni acusa recepció d’una notificació, ni duu a terme accions d’escriptura com a representant.

Executa aeat --help abans de continuar. Si falla, atura’t abans de configurar l’autenticació i segueixes la guia de resolució de problemes de la CLI. Si això no restableix l’ordre, comuniques la fallada amb la versió de Cadrumo i la sortida amb les dades sensibles ocultades.

Quan la teva identitat hi tingui accés, la interfície de línia d’ordres (CLI) pot llegir declaracions presentades, expedients, notificacions i justificants presentats. Per a les dades censals del perfil (Model 036/Cens), usa la guia de dades del perfil/Cens. Cadrumo ja no recupera aquestes dades en directe.

Abans de començar¶

Necessita:

un perfil actiu. aeat config auth configure es nega amb No hay un perfil activo fins que en creeu un. Inicieu l’assistent interactiu (un NIF, CIF, DNI o NIE és un identificador fiscal espanyol); demana la frase de contrasenya del perfil i ofereix un codi de recuperació opcional un cop el perfil existeix:
1Start the interactive profile wizard, which prompts for the passphrase.
aeat config profile create me
aeat config profile create me
2Confirm a profile is active before configuring AEAT authentication.
aeat --format json config profile list
aeat --format json config profile list
```
{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.profile.list",
  "notices": [],
  "result": {
    "active_profile": "docs-sequence-sandbox",
    "profiles": [
      {
        "active": true,
        "bucket_id": "<bucket-id>",
        "name": "docs-sequence-sandbox"
      }
    ]
  },
  "schema_version": "2",
  "status": "success"
}
```
Review interactive profile creation and confirm a profile is active.
la contrasenya de la clau mestra que protegeix el teu magatzem local; l’eina te la demana.

Consulta els proveïdors admesos¶

Llista els proveïdors:

1List the supported authentication providers and their availability.

aeat --format json config auth providers

aeat --format json config auth providers

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.providers",
  "notices": [],
  "result": {
    "providers": [
      {
        "description": "auth.catalogue.certificate_description",
        "id": "certificate",
        "label": "auth.catalogue.certificate_label"
      },
      {
        "description": "auth.catalogue.clave_movil_description",
        "id": "clave_movil",
        "label": "auth.catalogue.clave_movil_label"
      },
      {
        "description": "auth.catalogue.clave_permanente_description",
        "id": "clave_permanente",
        "label": "auth.catalogue.clave_permanente_label"
      }
    ]
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool lists the supported authentication providers.

La llista marca cada proveïdor com a disponible (disponible ara) o reservado (no disponible aún) (reservat, encara no disponible). N’hi ha tres de disponibles:

certificate: el fitxer del teu certificat digital (certificado digital).
clave_movil: Cl@ve basat en el mòbil, confirmat al telèfon.
clave_permanente: Cl@ve Permanente, un accés amb DNI/NIE i contrasenya.

N’hi ha dos més a la llista, però reservats, de manera que encara no els pots configurar:

clave_pin: Cl@ve PIN, un sistema de codi d’un sol ús de l’AEAT. Reservat.
dnie_pkcs: el document nacional d’identitat (DNI electrónico). Reservat.

Configura un dels proveïdors disponibles.

Configura un proveïdor¶

Configura el proveïdor que utilitzes:

1Configure a provider that needs a file, such as your digital certificate.

aeat config auth configure --provider certificate --file ./certificate.p12

aeat config auth configure --provider certificate --file ./certificate.p12

Usa --file per als proveïdors que necessiten un fitxer, com ara el teu certificat digital. Mantén privats els fitxers de credencials i no els comparteixis.

Comprova la preparació local¶

Comprova què hi ha configurat:

1Show what authentication is configured.

aeat config auth status

aeat config auth status

Authentication is not configured yet.
provider	
configured	False
authenticated	False
available	False
active_profile	docs-sequence-sandbox
active_profile_status	ready
active_profile_registered	True
active_profile_record_present	True
backend_configured	False
backend_available	False
certificate_path	
health_severity	
health_summary

2Probe the stored credentials locally, without contacting AEAT.

aeat --format json config auth test

aeat --format json config auth test

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.test",
  "notices": [],
  "result": {
    "active_profile": "docs-sequence-sandbox",
    "active_profile_precondition_action": null,
    "active_profile_record_present": true,
    "active_profile_registered": true,
    "active_profile_status": "ready",
    "authenticated": false,
    "available": false,
    "backend_available": false,
    "backend_configured": false,
    "certificate_path": "",
    "configured": false,
    "health_severity": "",
    "health_summary": "",
    "persisted_session_expired": null,
    "persisted_session_present": false,
    "persisted_session_state": "no_provider",
    "probe_result": "no_provider",
    "probe_summary": "No auth provider is configured; nothing to probe locally.",
    "provider": ""
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool reports what is configured and probes it locally.

Si vols inspeccionar un proveïdor concret, uses --provider amb qualsevol de les dues ordres.

Renova el certificat abans que caduqui¶

Un certificat digital té una data de caducitat. L’eina llegeix aquesta data del fitxer del certificat i t’avisa a mesura que s’acosta. Això t’ajuda a evitar una lectura en directe fallida per un certificat caducat.

Comprova la validesa restant:

1Read the certificate's remaining validity from the local probe.

aeat --format json config auth test

aeat --format json config auth test

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.test",
  "notices": [],
  "result": {
    "active_profile": "docs-sequence-sandbox",
    "active_profile_precondition_action": null,
    "active_profile_record_present": true,
    "active_profile_registered": true,
    "active_profile_status": "ready",
    "authenticated": false,
    "available": false,
    "backend_available": false,
    "backend_configured": false,
    "certificate_path": "",
    "configured": false,
    "health_severity": "",
    "health_summary": "",
    "persisted_session_expired": null,
    "persisted_session_present": false,
    "persisted_session_state": "no_provider",
    "probe_result": "no_provider",
    "probe_summary": "No auth provider is configured; nothing to probe locally.",
    "provider": ""
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the local probe reports the certificate's remaining validity.

L’informe et diu en quin estat es troba el certificat:

Més de 60 dies restants: el certificat és vàlid i informa dels dies que queden.
60 dies o menys restants: apareix un avís: The certificate expires in N days. Plan the renewal. Comença la renovació ara.
14 dies o menys restants: l’avís és crític. Renova’l abans de la propera lectura en directe.
Ja caducat: The certificate expired N days ago. Renew it before authenticating. Es rebutja una lectura en directe fins que el substitueixes.

Renova el certificat amb l’organisme que el va emetre, com ara la Fábrica Nacional de Moneda y Timbre (FNMT) o l’AEAT. Això passa fora de l’eina. Descarrega el fitxer del certificat renovat (.p12 o .pfx) a la teva màquina.

Apunta l’eina cap al fitxer renovat:

1Point the tool at the renewed certificate file.

aeat config auth configure --provider certificate --file ./renewed-certificate.p12

aeat config auth configure --provider certificate --file ./renewed-certificate.p12

Si el certificat renovat utilitza una contrasenya nova, canvies la contrasenya emmagatzemada per a la seva font:

1Rotate the stored passphrase for the certificate source.

aeat config auth certificate secret set --name personal

aeat config auth certificate secret set --name personal

Confirma la nova data de caducitat:

1Read the renewed certificate's expiry from the local probe.

aeat --format json config auth test

aeat --format json config auth test

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.test",
  "notices": [],
  "result": {
    "active_profile": "docs-sequence-sandbox",
    "active_profile_precondition_action": null,
    "active_profile_record_present": true,
    "active_profile_registered": true,
    "active_profile_status": "ready",
    "authenticated": false,
    "available": false,
    "backend_available": false,
    "backend_configured": false,
    "certificate_path": "",
    "configured": false,
    "health_severity": "",
    "health_summary": "",
    "persisted_session_expired": null,
    "persisted_session_present": false,
    "persisted_session_state": "no_provider",
    "probe_result": "no_provider",
    "probe_summary": "No auth provider is configured; nothing to probe locally.",
    "provider": ""
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the local probe reports the renewed certificate's later expiry.

Ara l’informe mostra la data de caducitat posterior del certificat renovat.

Gestiona diversos certificats¶

Si actues per a diverses entitats, registres un certificat per entitat. No tornis a executar aeat config auth configure --file cada vegada que en canvies.

Registra cada certificat sota un nom:

1Register a certificate under a name.

aeat config auth certificate register --name personal --file ./personal.p12

aeat config auth certificate register --name personal --file ./personal.p12

2Register another certificate with a friendly name.

aeat config auth certificate register --name apoderado-acme --file ./acme.p12 \
  --friendly-name ACME SL

aeat config auth certificate register --name apoderado-acme --file ./acme.p12 `
  --friendly-name ACME SL

Llista tots els certificats registrats:

1List every registered certificate.

aeat --format json config auth certificate list

aeat --format json config auth certificate list

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.certificate.list",
  "notices": [],
  "result": {
    "active_source": "",
    "sources": []
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool lists the registered certificates.

Selecciona el que vols activar:

1Select the registered certificate you want active.

aeat config auth certificate select --name apoderado-acme

aeat config auth certificate select --name apoderado-acme

Elimina un certificat registrat que ja no necessites:

1Remove a registered certificate you no longer need.

aeat --format json config auth certificate remove --name personal

aeat --format json config auth certificate remove --name personal

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.certificate.remove",
  "notices": [],
  "result": {
    "active": false,
    "certificate_path": "",
    "name": "personal",
    "removed": false
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool removes a registered certificate by name.

Comprova la caducitat de cada certificat registrat¶

Cada certificat registrat té la seva pròpia data de caducitat. Comprova tots els certificats registrats en una sola passada, no només l’actiu:

1Check every registered certificate's expiry.

aeat --format json config auth certificate check

aeat --format json config auth certificate check

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.certificate.check",
  "notices": [],
  "result": {
    "entries": [],
    "has_warnings": false
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool checks every registered certificate's expiry in one pass.

L’informe llista cada certificat registrat amb el seu estat:

ok: vàlid, amb els dies que queden.
expiring: dins de la finestra de renovació (60 dies o menys per defecte, o 14 dies o menys per a la finestra crítica). Un avís anomena el certificat.
expired: ja caducat. Un avís anomena el certificat.

Renova un certificat que caduca o que ja ha caducat amb l’organisme que el va emetre i, tot seguit, torna’l a registrar amb el seu nom existent:

1Re-register a renewed certificate under its existing name.

aeat config auth certificate register --name apoderado-acme --file ./renewed-acme.p12

aeat config auth certificate register --name apoderado-acme --file ./renewed-acme.p12

Torna a executar aeat config auth certificate check per confirmar la nova data de caducitat.

Obtén o verifica una sessió en directe¶

Quan estiguis a punt per utilitzar una ordre de lectura en directe:

1Acquire or verify a live AEAT session.

aeat config auth login

aeat config auth login

Si necessites tornar a autenticar-te intencionadament, forces una autenticació nova:

1Force a fresh authentication.

aeat config auth login --fresh

aeat config auth login --fresh

Si un inici de sessió anterior es va interrompre i va deixar encallat el pas d’autenticació, uses --reset-lock. Executa-ho quan login informi que hi ha un altre inici de sessió en curs però de fet no n’hi ha cap.

Finalitza sessions o restableix l’autenticació¶

Per finalitzar la sessió local del proveïdor de certificat sense eliminar-ne la configuració:

1End the certificate provider's local sessions without removing its configuration.

aeat --format json config auth logout --provider certificate

aeat --format json config auth logout --provider certificate

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.logout",
  "notices": [],
  "result": {
    "bucket_id": "<bucket-id>",
    "cleared_session_state": false,
    "providers": [
      "certificate"
    ],
    "removed_sessions": 0
  },
  "schema_version": "2",
  "status": "success"
}

Confirm logout ends the local session while preserving the provider configuration.

Per eliminar la configuració local d’un proveïdor, les sessions, el bloqueig d’obtenció, els certificats registrats i els secrets de certificat emmagatzemats:

1Remove the certificate provider's local configuration and custody state.

aeat --format json config auth reset --provider certificate --yes

aeat --format json config auth reset --provider certificate --yes

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.reset",
  "notices": [],
  "result": {
    "bucket_id": "<bucket-id>",
    "cleared_locks": 0,
    "cleared_provider_configuration": true,
    "providers": [
      "certificate"
    ],
    "removed_certificate_secrets": 0,
    "removed_certificate_sources": 0,
    "removed_sessions": 0
  },
  "schema_version": "2",
  "status": "success"
}

Confirm reset removes the selected provider's local authentication state.

Per eliminar l’estat d’autenticació local de cada proveïdor configurat:

1Remove local authentication state for every configured provider.

aeat --format json config auth reset --all --yes

aeat --format json config auth reset --all --yes

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.reset",
  "notices": [],
  "result": {
    "bucket_id": "<bucket-id>",
    "cleared_locks": 0,
    "cleared_provider_configuration": true,
    "providers": [
      "certificate",
      "clave_movil",
      "clave_permanente"
    ],
    "removed_certificate_secrets": 0,
    "removed_certificate_sources": 0,
    "removed_sessions": 0
  },
  "schema_version": "2",
  "status": "success"
}

Confirm reset removes local authentication state for all configured providers.

Actua en nom d’una altra persona (apoderado)¶

Si actues com a representant fiscal autoritzat d’un altre contribuent, registres localment qui representes i els àmbits d’apoderamiento de l’AEAT corresponents. Un apoderado és un representant autoritzat, com ara un gestor o assessor.

L’apoderamiento en si es concedeix a l’AEAT. La part representada t’autoritza mitjançant els procediments d’apoderamiento de la mateixa AEAT. Les ordres d’aquesta secció registren aquesta concessió al teu perfil local perquè les ordres de lectura sàpiguen de qui llegeixen les dades. Mai no registren, amplien, revoquen ni renuncien a un apoderamiento a l’AEAT. Cap ordre no escriu l’estat de representació a l’AEAT.

Consulta els àmbits admesos¶

Llista els codis d’àmbit que accepta l’eina:

1List the scope codes the tool accepts.

aeat --format json config auth apoderado scopes list

aeat --format json config auth apoderado scopes list

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.apoderado.scopes.list",
  "notices": [],
  "result": {
    "catalogue_version": "2026.05.bootstrap",
    "scopes": [
      {
        "code": "CENSO",
        "modelo_codes": [
          "036",
          "037"
        ],
        "name_en": "Censo declarations (registration, modification, deregistration)",
        "name_es": "Censo (modelo 036, 037)"
      },
      {
        "code": "EXPED",
        "modelo_codes": [],
        "name_en": "Filing records and queries",
        "name_es": "Expedientes y consultas"
      },
      {
        "code": "GENERALNT",
        "modelo_codes": [],
        "name_en": "General tax procedures",
        "name_es": "Trámites tributarios (general)"
      },
      {
        "code": "INFORM",
        "modelo_codes": [
          "347",
          "349",
          "720"
        ],
        "name_en": "Informational declarations",
        "name_es": "Declaraciones informativas (modelo 347, 349, 720)"
      },
      {
        "code": "IVA",
        "modelo_codes": [
          "303",
          "390"
        ],
        "name_en": "IVA periodic and annual returns",
        "name_es": "IVA (modelo 303, 390)"
      },
      {
        "code": "NOTIFIC",
        "modelo_codes": [],
        "name_en": "Electronic notifications (DEHú)",
        "name_es": "Notificaciones electrónicas DEHú"
      },
      {
        "code": "PAGOSF",
        "modelo_codes": [
          "130",
          "131"
        ],
        "name_en": "Quarterly self-employed instalments",
        "name_es": "Pagos fraccionados (modelo 130, 131)"
      },
      {
        "code": "RENT",
        "modelo_codes": [
          "100",
          "714"
        ],
        "name_en": "Income tax and wealth declaration",
        "name_es": "Renta y patrimonio (modelo 100, 714)"
      },
      {
        "code": "RETEN",
        "modelo_codes": [
          "111",
          "115",
          "123",
          "180",
          "190",
          "193"
        ],
        "name_en": "Withholding tax declarations",
        "name_es": "Retenciones (modelo 111, 115, 123, 180, 190, 193)"
      }
    ]
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool lists the accepted apoderamiento scope codes.

Cada àmbit és una àrea d’apoderamiento de l’AEAT. Alguns exemples són:

RENT per als models 100 i 714.
IVA per als models 303 i 390.
PAGOSF per als models 130 i 131.
RETEN per als models de retencions.
GENERALNT, CENSO, INFORM, NOTIFIC i EXPED per a les seves àrees d’autoritat respectives.

Registra qui representa¶

Indica l’identificador fiscal de la part representada (NIF, CIF, DNI, NIE o NII) i els àmbits que corresponen a la concessió a l’AEAT:

1Record who you represent and the scopes that match the grant at AEAT.

aeat --format json config auth apoderado configure --represented-nif 11111111H --scope \
  IVA --scope PAGOSF

aeat --format json config auth apoderado configure --represented-nif 11111111H --scope `
  IVA --scope PAGOSF

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.apoderado.configure",
  "notices": [],
  "result": {
    "bucket_id": "<bucket-id>",
    "catalogue_version": "2026.05.bootstrap",
    "configured_at": "2026-04-01T09:00:00+00:00",
    "granted_scopes": [
      "IVA",
      "PAGOSF"
    ],
    "notes": "",
    "represented_nif": "sha256:33982da1"
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool records the represented party and scopes locally.

Repeteix --scope per a cada codi. La CLI rebutja una llista separada per comes. Els codis d’àmbit van en majúscules. Usa --scope ALL per registrar tots els àmbits del catàleg alhora. La CLI rebutja els codis desconeguts i llista els codis admesos.

El perfil actiu conté com a màxim una configuració d’apoderado; si el tornes a configurar, el substitueixes. L’identificador representat s’emmagatzema xifrat.

Revisa o retira la configuració¶

Mostra què hi ha registrat per al perfil actiu:

1Show the apoderado configuration recorded for the active profile.

aeat --format json config auth apoderado status

aeat --format json config auth apoderado status

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.apoderado.status",
  "notices": [],
  "result": {
    "bucket_id": "<bucket-id>",
    "catalogue_version": "2026.05.bootstrap",
    "configured": true,
    "configured_at": "2026-04-01T09:00:00+00:00",
    "granted_scopes": [
      "IVA",
      "PAGOSF"
    ],
    "represented_nif": "sha256:33982da1"
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool shows the apoderado configuration recorded locally.

aeat config auth apoderado check és el verb de verificació en directe, però la via de lectura en directe de l’AEAT està segellada. Es nega amb un missatge de «verificació en directe no disponible» i et remet de nou a status. Usa aeat config auth apoderado status per a la lectura de la configuració fora de línia.

Elimina la configuració quan finalitzi la representació:

1Remove the local apoderado record when the representation ends.

aeat --format json config auth apoderado clear

aeat --format json config auth apoderado clear

{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.auth.apoderado.clear",
  "notices": [],
  "result": {
    "bucket_id": "<bucket-id>",
    "cleared": true
  },
  "schema_version": "2",
  "status": "success"
}

Confirm the tool removes the local apoderado record.

En esborrar-la només s’elimina el registre local. L’apoderamiento a l’AEAT no es veu afectat. Revoca’l mitjançant els procediments de la mateixa AEAT.

Passos següents¶

Executa aeat config auth test abans de cada tasca de lectura en directe. Segueix Renova el certificat abans que caduqui quan l’ordre informi d’un avís de caducitat.