cadrumo.adapters.outbound.aeat.verify.contract module

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.factory.DefaultBrowserSession. It is guarded by domain.calculations.registry.remote_state_guard.RemoteStateGuardPolicy and never mutates AEAT-side state. The contract is:

• open the CSV-keyed Sede viewer,

• 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.errors.JustificanteVerificationError.

Public surface: verify_csv() plus the Playwright protocol types (VerifyBrowserPageLike, VerifyBrowserContextLike, VerifyBrowserSessionLike, and VerifyBrowserSessionFactory) shared by the concrete browser adapters.

See also

adapters.outbound.aeat.browser.factory.default_browser_session_factory()

Production factory used by DEFAULT_BROWSER_SESSION_FACTORY.

adapters.outbound.aeat.browser.session.BrowserSession

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

domain.calculations.registry.remote_state_guard.assert_remote_operation_allowed()

Guard used to allow only the reviewed read-only CSV verification URL.

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 CSV-keyed Sede URL and HTML content capture for exact result-URL and document-viewer validation.

property url: str

Return the page’s current absolute URL.

async goto(url)

Navigate the page to url and return the primary response.

Return type:

object | None

Parameters:

url (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.session.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.session.BrowserSession so the protocol stays structurally honest.

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

Create and return a configured VerifyBrowserContextLike.

Return type:

VerifyBrowserContextLike

Parameters:

• provisioner (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()

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

Return type:

VerifyBrowserSessionLike

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 AEAT’s reviewed CSV-keyed public viewer under the read-only guard, and parses the returned HTML for the exact CSV-bound document iframe. 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.