cadrumo.adapters.outbound.aeat.sede.nif_iva_check module

Read-only AEAT NIF-IVA / VIES proxy browser driver.

Drives the public AEAT-hosted form servlet that proxies non-Spanish EU IVA-identifier validity queries to the European Commission’s VIES service. The driver navigates from the sede gestiones page (which issues the session cookies the form servlet requires) to the form servlet itself, fills the country-code + IVA-number form per declared NIF, scrapes the rendered validity verdict, and returns one observation per declared NIF.

The contract is the sede adapter shape: an async collection coroutine plus a synchronous wrapper that a caller can drive. Browser-session lifecycle, guarded navigation, form interaction, response parsing, and error mapping are implemented here.

The driver is intentionally read-only: the form mutates no AEAT-side state under any NIF, requires no clave-móvil session, and writes nothing to the autonomo’s filing history. The remote-state guard host-pinning suffix (agenciatributaria.gob.es) covers both the sede entry subdomain and the www1 form-servlet subdomain.

assert_nif_iva_read_landing(landing_url)[source]

Refuse a landing that is neither the sede entry nor the form servlet.

The auth-gate detector above this rule names ONE known landing with a far better diagnostic, and keeps precedence for that reason. This rule is the complement: it refuses every landing nobody enumerated, which is the set an auth-gate detector cannot cover. It runs after each submit because the query click issues a browser form POST that reaches neither the first-party HTTP guard nor the forbidden-verb source scan.

Public so the driver’s proof exercises this exact rule rather than a mirrored copy that would keep agreeing with itself.

Parameters:

landing_url (str) – The URL AEAT actually served, read off the page.

Raises:

SedeNavigationError – When the landing is not a declared read page.

Return type:

None

class SedeNifIvaCheckObservation(**data)[source]

Bases: _SedeCheckerModel

One observation emitted per declared NIF after live navigation.

verdict is the AEAT/VIES-rendered validity for that NIF: valid, invalid, or unknown when the response is structurally unanswerable (network error mid-query, etc.).

Parameters:

data (Any)

nif: str
verdict: IdentityCheckVerdictValue
raw_evidence_locator: str | None
class NifIvaCheckResult(**data)[source]

Bases: _SedeCheckerModel

Aggregate live-driver result across all declared NIFs for one browser pass.

Each entry in observations corresponds to one NIF submitted to the AEAT-hosted VIES proxy form. An empty tuple signals that no NIFs were queried (caller-side guard: expected was empty before the driver ran).

Parameters:

data (Any)

observations: tuple[SedeNifIvaCheckObservation, ...]
class NifIvaCheckSedeDriver(*, settings=None)[source]

Bases: object

Live AEAT NIF-IVA driver backed by the central BrowserSession surface.

The driver follows the sequence the oracle’s planned_operations enumerates: GET sede entry, GET form servlet, open the form, per-NIF check, discard the session.

The driver follows the read-only public VIES proxy flow and converts the rendered AEAT response text into registry parity observations.

Parameters:

settings (Settings | None)

property mode: Literal[CheckerDriverMode.LIVE]

Driver execution mode — always "live" for this adapter.

planned_operations(payload, *, expected)[source]

Return the ordered list of remote operations this driver will perform.

The sequence is fixed: one HTTP GET to the sede (AEAT electronic office) gestiones entry page, one HTTP GET to the VIES proxy form servlet, one browser action to open the form, one check-nif-<NIF> browser action per NIF in expected (sorted alphabetically), and finally a discard-session action. The sequence is used by the remote-state guard pre-flight to validate that all planned operations are within the driver’s declared RemoteStateGuardPolicy.

Parameters:

  • payload (bytes) – Raw oracle payload bytes. Not read by this driver; the argument exists to satisfy the oracle driver protocol.

  • expected (Mapping[str, object]) – Mapping keyed by NIF (Spanish or EU IVA identifier) whose VIES validity is to be checked. At least one entry is required.

Return type:

tuple[RemoteOperation, ...]

Returns:

An immutable tuple of RemoteOperation records in execution order.

Raises:

RegistryValidationError – When expected is empty.

collect(payload, *, expected, timeout_ms=30000)[source]

Synchronous wrapper around collect_async() for oracle callers.

Runs the full browser-drive sequence inside asyncio.run and translates SedeError, SiteHealthError, and BrowserError into RegistryValidationError so the oracle protocol sees a single typed failure shape.

Parameters:

  • payload (bytes) – Raw oracle payload bytes. Not read; present for protocol compatibility.

  • expected (Mapping[str, object]) – Mapping keyed by NIF whose VIES validity is to be checked.

  • timeout_ms (int) – Per-operation Playwright timeout in milliseconds. Defaults to DEFAULT_NIF_IVA_TIMEOUT_MS.

Return type:

NifIvaCheckResult

Returns:

A NifIvaCheckResult with one observation per NIF.

Raises:

RegistryValidationError – On browser navigation, sede, or health failures.

collect_observation(payload, *, expected)[source]

Collect results and return the canonical checker observation.

Calls collect() and projects the observations into the canonical checker-observation shape the registry oracle expects: a values mapping of NIF -> verdict string and a single raw_evidence_locator (the first non-None URL from the observation set).

Parameters:

  • payload (bytes) – Raw oracle payload bytes. Not read; present for protocol compatibility.

  • expected (Mapping[str, object]) – Mapping keyed by NIF whose VIES validity is to be checked.

Return type:

CheckerObservation

Returns:

A CheckerObservation with the collected verdicts and evidence locator.

async collect_async(payload, *, expected, timeout_ms=30000)[source]

Async entry point that delegates to collect_nif_iva_check_observations().

Parameters:

  • payload (bytes) – Raw oracle payload bytes. Not read; present for protocol compatibility.

  • expected (Mapping[str, object]) – Mapping keyed by NIF whose VIES validity is to be checked.

  • timeout_ms (int) – Per-operation Playwright timeout in milliseconds. Defaults to DEFAULT_NIF_IVA_TIMEOUT_MS.

Return type:

NifIvaCheckResult

Returns:

A NifIvaCheckResult with one observation per NIF.

async collect_nif_iva_check_observations(payload, *, expected, settings=None, timeout_ms=30000, browser_session_factory=None)[source]

Open the NIF-IVA form, query each declared NIF, scrape verdicts into a NifIvaCheckResult.

The function navigates the AEAT sede gestiones entry, follows through to the form servlet (which the entry’s session cookies authorise), iterates the declared NIFs alphabetically, and returns one observation per NIF.

Return type:

NifIvaCheckResult

Parameters: