cadrumo.core.result_disposition module

Per-modelo result-disposition codes for the fichero “Tipo de declaración”.

The AEAT fichero-BOE “Tipo de declaración” field encodes the result disposition of an autoliquidación (a ingresar / a compensar / a devolver / negativa), NOT the amendment type (ordinary vs complementaria, which is a separate “Rectificativa” field). Hardcoding it to a constant "I" (ingreso) silently mis-files every credit, refund, and nil return as a payment owed.

Each modelo declares its own closed code set in its AEAT Diseño de Registros “Tipo de declaración” note. This module codifies those code sets and the result→code derivation per modelo, so feature code (the export header composer) emits a grounded, codified member instead of a hardcoded literal.

This module stops at the base sign-to-code mapping. The application resolver application.modelo.result_disposition_resolution.resolve_modelo_result_disposition() validates the full revision in its work-unit and registry context, then layers RefundElection and refund_disposition_available() for Modelo 303. Export and cross-period carry read that single resolved fact through result_disposition_is_refund().

Grounded verbatim from the bundled official diseños (_data/corpus/aeat_official/disenos_registro/modelo_*):

• M303: “C (solicitud de compensación) D (devolución) G (cuenta corriente-ingreso) I (ingreso) N (sin actividad/resultado cero) V (cuenta corriente-devolución) U (domiciliación) X (devolución por transferencia al extranjero)”.

• M130 / M131: “I (ingreso), U (domiciliación), G (ingreso a anotar en CCT), N (negativa) y B (resultado al deducir)”.

• M111 / M115 / M123: “I (ingreso), U (domiciliación), G (ingreso a anotar en CCT) y N (negativa)”.

• M200: “I (Ingreso), U (Domiciliación), N (Negativa/Resultado cero), D (Solicitud de devolución), R (Renuncia a la devolución), G/V/X (CCT / extranjero)”.

• M202: “I (ingreso), U (domiciliación), G (Ingreso en C.C.T.) y N (Negativa/Sin actividad/Resultado cero)”.

• M210: casilla 31 “Resultado de la autoliquidación”; positive is ingreso, zero is cuota cero, and negative is solicitud de devolución.

class ResultDisposition(*values)

Bases: StrEnum

AEAT fichero “Tipo de declaración” result-disposition codes (all modelos).

The member value is the single-character code the fichero expects. Not every modelo admits every code — the per-modelo derivation only selects codes that modelo’s diseño declares.

See also

RefundElection

Operator input that can request a Modelo 303 C credit be filed as D after the application resolver applies the refund gate.

result_disposition_is_refund()

Classifier for the refund dispositions that suppress compensación carry-forward.

COMPENSACION

Solicitud de compensación — an IVA credit carried forward, a compensar.

DEVOLUCION

Solicitud de devolución — refund requested.

CUENTA_CORRIENTE_INGRESO

Cuenta corriente tributaria — ingreso (operator payment-method election).

INGRESO

Ingreso — a positive result the taxpayer pays (a ingresar).

NEGATIVA

Negativa / sin actividad / resultado cero.

CUENTA_CORRIENTE_DEVOLUCION

Cuenta corriente tributaria — devolución.

DOMICILIACION

Domiciliación del ingreso en cuenta de cargo (payment-method election).

DEVOLUCION_TRANSFERENCIA_EXTRANJERO

Devolución por transferencia al extranjero.

RESULTADO_A_DEDUCIR

Resultado a deducir (pago fraccionado IRPF M130/M131 negative carry).

RENUNCIA_DEVOLUCION

Renuncia a la devolución (IS election).

result_disposition_is_refund(disposition)

Return whether disposition files the result as a refund (devolución).

A refund disposition (D / V / X) requests devolución rather than carry-forward, so a refunded Modelo 303 period must generate zero compensación carry-forward. The carried disposition (C, compensación) and every ingreso/negativa code return False. This is the single determined fact the export “Tipo de declaración” and the carry-forward derivation both read, so the fichero D and the cross-period carry cannot disagree.

Return type:

bool

Parameters:

disposition (ResultDisposition)

result_disposition_requires_bank_account(disposition)

Return whether disposition’s fichero must carry a bank account.

True for the three refund codes (AEAT pays into the account) and for U, domiciliación del ingreso (AEAT charges the account). Read by BOTH the header composer that emits the account block and the record guard that decides whether the account page reaches disk, because those two answering differently is how a filing acquires an account page with no account in it, or an account block with no page to carry it.

See also

result_disposition_is_refund()

The adjacent axis. Do not substitute one for the other: that one governs compensación carry-forward, this one governs whether the account is on the wire.

Return type:

bool

Parameters:

disposition (ResultDisposition)

result_disposition_casilla_ids(modelo)

Return the canonical result casilla.id values for modelo.

These are the only keys derive_result_disposition() accepts in its casilla_values mapping. A caller holding a full calculation revision must validate and filter the revision to this tuple first; passing unrelated result metadata raises CoreValidationError.

Return type:

tuple[TypeAliasType, ...] | None

Parameters:

modelo (str)

derive_result_disposition(modelo, casilla_values)

Derive the fichero result disposition for modelo from its computed result.

Sums the modelo’s final-result casilla(s) from casilla_values and maps the sign to the modelo’s diseño-grounded code. casilla_values must contain only the result casilla ids returned by result_disposition_casilla_ids(); callers with a full revision value map must first validate it against the selected registry revision, then filter to those ids.

• > 0 → ResultDisposition.INGRESO (I) for every modelo.

• < 0 → the modelo’s credit code (C for M303 IVA, B for M130/M131 IRPF pagos fraccionados; N for retenciones, which cannot go sub-zero in practice).

• == 0 (or the casilla absent) → the modelo’s zero code (N).

Returns the derived ResultDisposition, or None for a modelo without a codified spec, so the caller applies a documented fallback rather than a guessed disposition.

Return type:

ResultDisposition | None

Parameters:

• modelo (str)

• casilla_values (Mapping[CasillaId, Decimal])