aeat.adapters.outbound.aeat.verify package

Read-only CSV verification against AEAT’s Sede electrónica.

The verify_csv() helper is opt-in: it only runs when the caller supplies or constructs a adapters.outbound.aeat.browser.DefaultBrowserSession. It is guarded by domain.calculations.registry.RemoteStateGuardPolicy and never mutates AEAT-side state. The contract is:

• open the Sede verification page,

• enter the CSV,

• read back the server response,

• return True iff AEAT confirms the document as valid.

The function degrades gracefully when a browser cannot be constructed and surfaces the underlying error to the caller via domain.justificante.JustificanteVerificationError.

Public surface: verify_csv() plus the Playwright protocol types (VerifyBrowserKeyboardLike, VerifyBrowserPageLike, VerifyBrowserContextLike, VerifyBrowserSessionLike, VerifyBrowserSessionFactory) that let the helper be unit-tested without spinning up a real browser.

See also

adapters.outbound.aeat.browser.default_browser_session_factory()

Production factory used by DEFAULT_BROWSER_SESSION_FACTORY.

adapters.outbound.aeat.browser.BrowserSession

Concrete browser session whose context/page surface these protocols mirror.

domain.calculations.registry.assert_remote_operation_allowed()

Guard used to allow only the reviewed read-only CSV verification URL and browser action token.

class VerifyBrowserKeyboardLike(*args, **kwargs)

Bases: Protocol

Subset of Playwright’s Keyboard API used by verify_csv().

The protocol keeps the fallback query path testable without importing a concrete Playwright Keyboard at runtime.

async type(value)

Type value into the focused element character by character.

Return type:

None

Parameters:

value (str)

async press(key)

Dispatch a key-press event for key (e.g. "Enter").

Return type:

None

Parameters:

key (str)

class VerifyBrowserPageLike(*args, **kwargs)

Bases: Protocol

Subset of Playwright’s Page API used by verify_csv().

The page surface is intentionally small: navigation to the reviewed Sede URL, CSV entry through a selector or keyboard fallback, and HTML content capture for the confirmation-token parse.

keyboard: VerifyBrowserKeyboardLike

async goto(url)

Navigate the page to url and return the primary response.

Return type:

object | None

Parameters:

url (str)

async fill(selector, value)

Clear and fill the element matched by selector with value.

Return type:

None

Parameters:

• selector (str)

• value (str)

async press(selector, key)

Focus the element matched by selector and press key.

Return type:

None

Parameters:

• selector (str)

• key (str)

async content()

Return the full HTML content of the page.

Return type:

str

class VerifyBrowserContextLike(*args, **kwargs)

Bases: Protocol

Subset of Playwright’s BrowserContext API used by verify_csv().

Context ownership depends on the caller: verify_csv() always closes the context it opens, while the surrounding session is closed only when the helper created it through DEFAULT_BROWSER_SESSION_FACTORY.

async new_page()

Open a new VerifyBrowserPageLike within this browser context.

Return type:

VerifyBrowserPageLike

async close()

Close the browser context and release its resources.

Return type:

None

class VerifyBrowserSessionLike(*args, **kwargs)

Bases: Protocol

Browser-session surface consumed by verify_csv().

The create_context signature mirrors adapters.outbound.aeat.browser.BrowserSession.create_context() so static checkers see no unsafe overlap between this protocol and the concrete browser sessions. verify_csv itself calls create_context() with no arguments; production and test sessions accept the same optional kwargs as the central adapters.outbound.aeat.browser.BrowserSession so the protocol stays structurally honest.

async create_context(*, provisioner=None, storage_state_path=None, storage_state=None)

Create and return a configured VerifyBrowserContextLike.

Return type:

VerifyBrowserContextLike

Parameters:

• provisioner (Any | None)

• storage_state_path (Any | None)

• storage_state (Any | None)

async close()

Close the browser session and release all underlying resources.

Return type:

None

VerifyBrowserSessionFactory

Callable that builds a self-owned VerifyBrowserSessionLike.

alias of Callable[[], Awaitable[VerifyBrowserSessionLike]]

async DEFAULT_BROWSER_SESSION_FACTORY(factory=None)

Module-level factory seam for the self-owned verify_csv() path.

Return type:

VerifyBrowserSessionLike

Parameters:

factory (Callable[[...], Awaitable[object]] | None)

async verify_csv(csv, *, browser=None, browser_session_factory=None)

Verify a justificante CSV against AEAT’s Sede electrónica.

The helper normalises the CSV, opens the reviewed public Sede verification URL under the read-only guard, submits the CSV, and parses the returned HTML for AEAT confirmation tokens. Passing browser borrows the session from the caller; omitting it builds a self-owned session through browser_session_factory or DEFAULT_BROWSER_SESSION_FACTORY and closes that session after the round-trip.

Parameters:

• csv (str) – The Código Seguro de Verificación as printed on the receipt.

• browser (VerifyBrowserSessionLike | None) – An already-constructed VerifyBrowserSessionLike. When None, one is built from the default settings/profile.

• browser_session_factory (Callable[[], Awaitable[VerifyBrowserSessionLike]] | None) – Optional no-argument factory for the self-owned path. Ignored when browser is supplied.

Return type:

bool

Returns:

True if AEAT confirms the CSV as valid; False if AEAT reports the document as unknown.

Raises:

JustificanteVerificationError – If the round-trip cannot be completed because browser construction, navigation, the guard, or parsing fails.