aeat.domain.calculations.registry._aeat_nif_iva_oracle module

AEAT NIF-IVA other-EU-countries verification oracle.

AEAT publishes a public verification servlet under the agenciatributaria.gob.es domain that confirms the validity of an EU IVA identifier issued by another member state. The form accepts the country code + IVA number, relays the query to the European Commission’s VIES service, and renders the response. The form is anonymous (no clave-móvil session, no NIF-history written for the calling autonomo) and creates no AEAT-side state under the autonomo’s account.

This adapter targets that AEAT-hosted form (www1.agenciatributaria.gob.es) so it stays inside the existing remote-state-guard host-pinning allow-list (matched by the agenciatributaria.gob.es suffix) and does not require a host-list expansion. Same verdict authority as direct EU VIES because AEAT delegates to VIES under the hood.

Concrete execution is supplied through a driver boundary. Without a driver the oracle still exposes planned operations and guard evaluation, but returns an unverifiable parity result instead of pretending that AEAT was checked.

class AeatNifIvaObservation(**data)[source]

Bases: _CheckerBaseModel

Observed NIF-IVA verdicts returned by an executable adapter.

Parameters:
values: dict[str, str]
raw_evidence_locator: str | None
class AeatNifIvaDriver(*args, **kwargs)[source]

Bases: Protocol

Execution boundary for AEAT NIF-IVA live or replay adapters.

property mode: Literal['live', 'replay']

Discriminate whether this driver drives a live AEAT query or a replay.

Returns:

"live" for a driver that hits the AEAT-hosted verification form over the network, or "replay" for one that decodes a previously captured response from disk. Callers use this to gate network-touching behaviour without inspecting the concrete type.

planned_operations(payload, *, expected)[source]

Describe the remote steps this driver would take, without running them.

Returns the ordered RemoteOperation plan the driver intends to run for the given query, so the oracle can surface and guard the plan before any network or filesystem access. A RemoteOperation is one recorded step in that plan (for example, a network request or a local file parse).

Parameters:

  • payload (bytes) – Raw bytes the driver consumes. For a replay driver this is a captured response; a live driver ignores it or treats it as request context.

  • expected (Mapping[str, object]) – Mapping from an EU IVA identifier (a VAT number issued by an EU member state) to the verdict expected for it. A verdict is the validity outcome, such as valid or invalid. The mapping is keyed by the identifier string.

Return type:

tuple[RemoteOperation, ...]

Returns:

The ordered tuple of planned RemoteOperation records.

collect_observation(payload, *, expected)[source]

Execute the driver and return the observed AEAT NIF-IVA verdicts.

A NIF-IVA is the Spanish tax identifier for VAT purposes; an observed verdict is the validity outcome (such as valid or invalid) the driver actually saw for each identifier.

Parameters:

  • payload (bytes) – Raw bytes the driver consumes. For a replay driver this is a captured response; a live driver treats it as transport input.

  • expected (Mapping[str, object]) – Mapping from an EU IVA identifier (a VAT number issued by an EU member state) to its expected verdict, supplied so a live driver knows which identifiers to query.

Return type:

AeatNifIvaObservation

Returns:

An AeatNifIvaObservation carrying the per-identifier verdicts the adapter actually saw, plus a locator pointing to the raw evidence (the stored response the verdicts were read from).

class AeatNifIvaReplayDriver[source]

Bases: object

Deterministic local replay driver for captured AEAT NIF-IVA outputs.

property mode: Literal['replay']

Identify this driver as a replay driver.

Returns:

The literal "replay". This driver never touches the network; it decodes a captured AEAT NIF-IVA response from a local payload, so its mode is fixed.

planned_operations(payload, *, expected)[source]

Report the single local-parse step a replay performs.

A replay does no remote work, so the plan is one RemoteOperation of kind local_workbook that parses the captured payload. A RemoteOperation` is one recorded step in a driver plan. Both arguments are accepted to match the shared AeatNifIvaDriver interface but are unused here.

Parameters:

  • payload (bytes) – The captured response bytes (ignored for planning).

  • expected (Mapping[str, object]) – Expected per-identifier verdicts, where a verdict is the validity outcome such as valid or invalid (ignored for planning).

Return type:

tuple[RemoteOperation, ...]

Returns:

A one-element tuple holding the local-parse RemoteOperation.

collect_observation(payload, *, expected)[source]

Decode the captured payload into observed NIF-IVA verdicts.

Parses payload as a replay JSON document and lifts its observed verdict map and raw-evidence locator into an AeatNifIvaObservation. A verdict is the validity outcome (such as valid or invalid) recorded for each identifier; the raw-evidence locator points back to the stored response.

Parameters:

  • payload (bytes) – The captured AEAT NIF-IVA response, as replay JSON bytes.

  • expected (Mapping[str, object]) – Accepted to match the shared driver interface but unused; a replay reports only what was recorded and never re-queries by expectation.

Return type:

AeatNifIvaObservation

Returns:

An AeatNifIvaObservation built from the decoded document.

class AeatNifIvaCheckerOracle(*, driver=None)[source]

Bases: BaseCheckerOracle[AeatNifIvaObservation]

Read-only AEAT-mediated EU IVA-identifier validator.

The adapter targets the public AEAT NIF-IVA verification page at sede.agenciatributaria.gob.es. The page proxies the query to the European Commission’s VIES service and renders the response inline. No authentication, no NIF-history, no server-side state under the autonomo’s account.

Parameters:

driver (AeatNifIvaDriver | None)

surface_label: str
property oracle_id: OracleId

Return the stable catalogue identifier for this oracle.

Returns:

The constant "aeat-nif-iva-checker". The live-parity catalogue keys oracles by this id, so it must stay stable across releases.

property surface_kind: Literal['file_validator', 'open_simulator', 'iva_id_check', 'pre_filing_validator', 'integration_test_service']

Classify the kind of AEAT surface this oracle verifies.

Returns:

The OracleSurfaceKind value "iva_id_check". It marks this oracle as a validator of EU IVA identifiers (a VAT number issued by another EU member state, which AEAT relays to the European Commission’s VIES service for checking) rather than a modelo filing surface. A modelo is an AEAT tax form; this oracle checks identifiers, not the casillas (the numbered boxes) on such a form.

planned_operations(payload, *, expected)[source]

Build the ordered remote plan for verifying the expected identifiers.

When a driver is bound, the plan is delegated to that driver. Otherwise the oracle emits its own default browser plan: GET the AEAT sede (the AEAT electronic-office website) landing page to acquire the session cookies the form servlet needs, GET the form servlet, open the form, issue one check per expected identifier in sorted order, then discard the anonymous (unauthenticated) session. Endpoint hosts are read from Settings.external_constants() so they stay inside the remote-state-guard host allowlist (the set of hosts the guard permits).

Parameters:

  • payload (bytes) – Raw bytes forwarded to a bound driver; unused by the default plan.

  • expected (Mapping[str, object]) – Mapping from an EU IVA identifier (a VAT number issued by an EU member state) to its expected verdict, where a verdict is the validity outcome such as valid or invalid. Must be non-empty.

Return type:

tuple[RemoteOperation, ...]

Returns:

The ordered tuple of planned RemoteOperation records, where each RemoteOperation is one recorded step in the plan.

Raises:

RegistryValidationError – If expected is empty, or if any identifier or verdict normalizes to blank.

register_default(catalogue, *, environment=OracleEnvironment.PRODUCTION)[source]

Register the AEAT NIF-IVA adapter under the requested environment.

Return type:

None

Parameters: