Autenticar Cadrumo ante la AEAT¶

Autentica Cadrumo ante la Agencia Estatal de Administración Tributaria (AEAT) para que la orden aeat de Cadrumo pueda leer la información que tu identidad ante la AEAT autorice. La autenticación concede acceso de solo lectura. Nunca presenta una declaración, realiza un pago, acusa recibo de una notificación ni ejecuta acciones de escritura en representación.

Ejecuta aeat --help antes de continuar. Si falla, detente antes de configurar la autenticación y sigue la guía de resolución de problemas de la CLI. Si eso no restablece la orden, informa del fallo indicando la versión de Cadrumo y la salida con los datos sensibles ocultos.

Cuando tu identidad lo permita, la interfaz de línea de órdenes (CLI) puede leer declaraciones presentadas, expedientes, notificaciones y justificantes presentados. Para los datos de perfil del Modelo 036/censo, usa la guía de datos de perfil/censo. Cadrumo ya no obtiene estos datos en directo.

Antes de empezar¶

Necesitas:

un perfil activo. aeat config auth configure se niega con No hay un perfil activo hasta que crees uno. Inicia el asistente interactivo (un NIF, CIF, DNI o NIE es un identificador fiscal español); solicita la frase de contraseña del perfil y ofrece un código de recuperación opcional una vez que el perfil existe:
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 frase de contraseña de la clave maestra que protege tu almacén local; la herramienta te la pedirá.

Consultar los proveedores admitidos¶

Enumera los proveedores:

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 lista marca cada proveedor como disponible (disponible ahora) o reservado (no disponible aún) (reservado, todavía no disponible). Hay tres disponibles:

certificate: tu archivo de certificado digital (certificado digital).
clave_movil: Cl@ve móvil, confirmada en tu teléfono.
clave_permanente: Cl@ve Permanente, un acceso con DNI/NIE y contraseña.

Aparecen dos más, pero están reservados, así que todavía no puedes configurarlos:

clave_pin: Cl@ve PIN, un sistema de código de un solo uso de la AEAT. Reservado.
dnie_pkcs: el documento nacional de identidad (DNI electrónico). Reservado.

Configura uno de los proveedores disponibles.

Configurar un proveedor¶

Configura el proveedor que utilices:

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 para los proveedores que necesitan un archivo, como tu certificado digital. Mantén privados los archivos de credenciales y no los compartas.

Comprobar la preparación local¶

Comprueba qué está configurado:

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 quieres examinar un proveedor concreto, usa --provider con cualquiera de las dos órdenes.

Renovar el certificado antes de que caduque¶

Un certificado digital tiene una fecha de caducidad. La herramienta lee esa fecha del archivo del certificado y te avisa a medida que se acerca. Esto te ayuda a evitar una lectura en directo fallida por un certificado caducado.

Comprueba la validez restante:

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.

El informe te indica en qué situación está el certificado:

Más de 60 días restantes: el certificado es válido e informa de los días que quedan.
60 días o menos restantes: aparece un aviso: The certificate expires in N days. Plan the renewal. Inicia la renovación ahora.
14 días o menos restantes: el aviso es crítico. Renueva antes de tu próxima lectura en directo.
Ya caducado: The certificate expired N days ago. Renew it before authenticating. Se rechaza cualquier lectura en directo hasta que lo reemplaces.

Renueva el certificado ante el organismo que lo emitió, como la Fábrica Nacional de Moneda y Timbre (FNMT) o la AEAT. Esto ocurre fuera de la herramienta. Descarga a tu equipo el archivo del certificado renovado (.p12 o .pfx).

Apunta la herramienta al archivo renovado:

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 certificado renovado usa una contraseña nueva, rota la frase de contraseña almacenada para su fuente:

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 nueva caducidad:

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.

El informe muestra ahora la fecha de caducidad posterior del certificado renovado.

Gestionar varios certificados¶

Si actúas por cuenta de varias entidades, registra un certificado por entidad. No vuelvas a configurar aeat config auth configure --file cada vez que cambies.

Registra cada certificado con un nombre:

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

Enumera todos los certificados registrados:

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 quieras tener activo:

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 certificado registrado que ya no necesites:

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.

Comprobar la caducidad de todos los certificados registrados¶

Cada certificado registrado tiene tu propia fecha de caducidad. Comprueba todos los certificados registrados de una sola pasada, no solo el activo:

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.

El informe enumera cada certificado registrado con su estado:

ok: válido, con los días que quedan.
expiring: dentro de la ventana de renovación (60 días o menos de forma predeterminada, o 14 días o menos para la ventana crítica). Un aviso nombra el certificado.
expired: ya caducado. Un aviso nombra el certificado.

Renueva un certificado que esté por caducar o ya caducado ante el organismo que lo emitió y vuelve a registrarlo con su nombre existente:

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

Vuelve a ejecutar aeat config auth certificate check para confirmar la nueva fecha de caducidad.

Obtener o verificar una sesión en directo¶

Cuando estés listo para usar una orden de lectura en directo:

1Acquire or verify a live AEAT session.

aeat config auth login

aeat config auth login

Si necesitas volver a autenticarte a propósito, fuerza una autenticación nueva:

1Force a fresh authentication.

aeat config auth login --fresh

aeat config auth login --fresh

Si un inicio de sesión anterior se interrumpió y dejó bloqueado el paso de autenticación, usa --reset-lock. Ejecútalo cuando login indique que hay otro inicio de sesión en curso pero no lo haya.

Finalizar sesiones o restablecer la autenticación¶

Para finalizar la sesión local del proveedor de certificado sin eliminar su configuración:

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.

Para eliminar la configuración local, las sesiones, el bloqueo de obtención, los certificados registrados y los secretos de certificado almacenados de un proveedor:

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.

Para eliminar el estado de autenticación local de todos los proveedores configurados:

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.

Actuar por cuenta de otra persona (apoderado)¶

Si actúas como representante fiscal autorizado de otro contribuyente, registra localmente a quién representas y los ámbitos de apoderamiento pertinentes ante la AEAT. Un apoderado es un representante autorizado, como un gestor o un asesor.

El apoderamiento en sí se concede en la AEAT. La parte representada te autoriza a través de los propios procedimientos de apoderamiento de la AEAT. Las órdenes de esta sección registran esa concesión en tu perfil local para que las órdenes de lectura sepan de quién son los datos que leen. Nunca registran, amplían, revocan ni renuncian a un apoderamiento en la AEAT. Ninguna orden escribe el estado de representación en la AEAT.

Consultar los ámbitos admitidos¶

Enumera los códigos de ámbito que la herramienta admite:

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 ámbito es un área de apoderamiento de la AEAT. Algunos ejemplos:

RENT para los modelos 100 y 714.
IVA para los modelos 303 y 390.
PAGOSF para los modelos 130 y 131.
RETEN para los modelos de retenciones.
GENERALNT, CENSO, INFORM, NOTIFIC y EXPED para sus respectivas áreas de la autoridad.

Registrar a quién representas¶

Indica el identificador fiscal de la parte representada (NIF, CIF, DNI, NIE o NII) y los ámbitos que coincidan con la concesión en la 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.

Repite --scope para cada código. La CLI rechaza una lista separada por comas. Los códigos de ámbito van en mayúsculas. Usa --scope ALL para registrar de una vez todos los ámbitos del catálogo. La CLI rechaza los códigos desconocidos y enumera los códigos admitidos.

El perfil activo tiene como máximo una configuración de apoderado; volver a configurarla la reemplaza. El identificador representado se almacena cifrado.

Revisar o retirar la configuración¶

Muestra lo que hay registrado para el perfil activo:

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 es el verbo de verificación en directo, pero la vía de lectura en directo de la AEAT está sellada. Se niega con un mensaje de «live verification unavailable» y te remite de nuevo a status. Usa aeat config auth apoderado status para la lectura sin conexión de la configuración.

Elimina la configuración cuando termine la representación:

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.

Borrarla elimina solo el registro local. El apoderamiento en la AEAT no se ve afectado. Revócalo a través de los propios procedimientos de la AEAT.

Próximos pasos¶

Ejecuta aeat config auth test antes de cada tarea de lectura en directo. Sigue Renovar el certificado antes de que caduque cuando la orden informe de un aviso de caducidad.