cadrumo.application.filing.producer_snapshot module

Typed, immutable filing producer inputs.

This module owns the filing-instance facts that export consumers need before they translate them into a revision-specific registry vocabulary. It does not own export keys, layout offsets, or rendered record fragments.

Core types: TaxpayerProfile.

exception FilingProducerSnapshotError(message=None, *, context=None, translated_message=None)

Bases: CadrumoError

Raised when filing facts cannot form a complete producer snapshot.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

assert_m303_regularisation_result_matches_bienes_register(*, bienes_register, regularisation_result, parameters)

Refuse a result that is not the register’s exact annual projection.

The result rows carry the definitive prorrata facts used to produce them, so replay the canonical domain projection from those facts and compare the complete immutable result. This admits no result-row omission, foreign register, substituted contribution, or invented pending state.

The result also carries the registry declaration its figures came from, and that is checked against parameters FIRST and by identity rather than by replay. A result produced under a different revision would otherwise be silently re-derived under this one and compared against itself, so the provenance check is what stops the replay from confirming the wrong law.

Return type:

None

Parameters:

• bienes_register (BienesInversionIvaRegister)

• regularisation_result (RegistroRegularizacionResult)

• parameters (BienesInversionRegularizacionParameters)

class PresenterIdentity(**data)

Bases: BaseModel

Identity of the presenter for this filing instance.

Presenter identity is deliberately separate from taxpayer identity. A caller must supply it; no taxpayer-to-presenter fallback exists here.

Parameters:

data (Any)

tax_id: SubjectTaxId

full_name: _NonBlankName

class TaxpayerIdentityFacts(**data)

Bases: BaseModel

Explicit taxpayer name facts for one filing instance.

The four fields model distinct official producer meanings. They are not interchangeable aliases: a revision requiring one of them must receive that exact fact, and an absent fact remains absent.

Parameters:

data (Any)

legal_name: _NonBlankName | None

given_name: _NonBlankName | None

surnames: _NonBlankName | None

full_name: _NonBlankName | None

class DeclarationContactFacts(**data)

Bases: BaseModel

The “persona con quien relacionarse” AEAT asks for on an informativa.

Distinct from both TaxpayerIdentityFacts and PresenterIdentity: AEAT reserves this pair for whoever it should contact ABOUT the declaration, which under a gestor is routinely neither the taxpayer nor the transmitting presenter. Filling it from either would name the wrong person on a live filing, which is why it is its own fact.

Both halves are optional and absent stays absent – AEAT’s global rule for the informativa header is that an alphanumeric field with no content is written to blancos, so an unsupplied contact is a legal filing rather than a defect.

Parameters:

• phone (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=200, pattern=None, ascii_only=None)] | None)

• full_name (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=200, pattern=None, ascii_only=None)] | None)

• secondary_phone (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=200, pattern=None, ascii_only=None)] | None)

• email (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=200, pattern=None, ascii_only=None)] | None)

phone: _NonBlankName | None

full_name: _NonBlankName | None

secondary_phone: _NonBlankName | None

AEAT reserves a second telephone and an e-mail beside the pair above on the informativa header – modelo 210 cites both. They were absent here, so the layout’s fields resolved to nothing and rendered blank.

email: _NonBlankName | None

class Modelo111ProfileFacts(**data)

Bases: BaseModel

Stable Modelo 111 profile facts consumed by a filing producer.

Parameters:

data (Any)

colegio_concertado: bool | None

class Modelo222ProfileFacts(**data)

Bases: BaseModel

Fiscal-group identity and régimen facts a Modelo 222 filing declares.

Modelo 222 is the pago fraccionado of a grupo fiscal, so the group’s own identity is not optional context – it is what the return is about. AEAT’s design prescribes a format for the número de grupo (Nota 8: ----/-- estatal, ---/--A foral), which is a rule about content, not about an empty field.

Before this type existed the twenty-three m222.* producer keys were declared in the vocabulary and resolved by nothing, so every one of them rendered blank on a non-required field and the return emitted with its group number and its entidad dominante empty.

Every field below is optional EXCEPT the group identity, because AEAT’s own design leaves the régimen marks blank when they do not apply, and a mark that does not apply is genuinely absent rather than unknown. The group number and the dominante are not in that category.

Parameters:

data (Any)

numero_grupo: _GrupoNumber

entidad_dominante_identificacion: str

entidad_dominante_razon_social: str

representante_o_dominante: str | None

“1” representante (entidad no dominante), “2” dominante incluida en el grupo fiscal.

normativa_territorio_foral: str | None

entidad_dominante_pais_territorio_foral: _ForalTerritory | None

fecha_inicio_periodo_impositivo: str | None

cnae_actividad_principal: _CnaeCode | None

regimen_entidades_navieras_tonelaje: str | None

regimen_reducida_dimension: str | None

cifra_negocios_grupo_doce_meses: str | None

cooperativa_fiscalmente_protegida: str | None

regimen_entidades_capital_riesgo: str | None

circunstancia_concurrente: str | None

cifra_negocios_periodo_anterior_tramo: str | None

multiples_tipos_impositivos: str | None

tipo_gravamen_impuesto_sociedades: str | None

importe_neto_cifra_negocios_tramo: str | None

modalidad_liquidacion: str | None

comunicacion_datos_adicionales: str | None

numero_referencia_sociedades: str | None

comunicacion_variacion_composicion_grupo: str | None

numero_referencia_sociedades_variacion: str | None

class Modelo353ProfileFacts(**data)

Bases: BaseModel

Grupo de entidades IVA identity and régimen marks a Modelo 353 filing declares.

Modelo 353 is the autoliquidación agregada of the régimen especial del grupo de entidades (LIVA art. 163 sexies), so the group’s number is what the return is about rather than optional colour.

Before this type existed the five m353.* producer keys were declared in the vocabulary and resolved by nothing, so the número de grupo and the two marks rendered from whatever the field’s required flag allowed.

numero_grupo is required here. The two régimen marks are required too, and that is a departure from the Modelo 222 shape for a grounded reason: AEAT’s design gives them 1 -Sí, 2 -No and the published layout marks both required = true, so there is no blank state to represent – a filer who is not inscrito declares "2", not nothing. sin_actividad and grupo_normativa_foral are the genuinely optional ones: the design reads X o blanco.

Parameters:

data (Any)

numero_grupo: _M353GrupoNumber

Identificación. Nº Grupo – design offset 109, length 10.

regimen_especial_avanzado_elected: _SiNoMark

“1” sí, “2” no.

Type:

Tipo régimen especial aplicable, art. 163 sexies.cinco

regimen_especial_inscrito_redeme: _SiNoMark

“1” sí, “2” no.

Type:

Inscrito en el Registro de devolución mensual (art. 30 RIVA)

sin_actividad: _XOrBlankMark | None

“X o blanco” in the design; absent means the group had activity.

grupo_normativa_foral: _XOrBlankMark | None

“X o blanco” in the design; absent means the group is not sometido a normativa foral.

class Modelo296PerceptorRow(**data)

Bases: BaseModel

One Modelo 296 perceptor: the payee, the renta and the retencion practicada.

The Tipo 2 record is emitted once per payee, so this row is the unit AEAT repeats. Members are M296PerceptorField’s values verbatim and are generated from that enum, which keeps the projection reference and the row that answers it in lock-step: a field the reference can name is a field this row has.

Every member is optional and rendered as text. The record design’s own per-field width, padding, justification and data type are what shape the bytes, and they live in the published layout; duplicating them as constraints here would be a second copy of the design that is free to disagree with it.

These rows are NOT yet fed from the withholding substrate. The values already exist in the registry as Withholding296Observation – perceptor tax id, legal name, naturaleza, clave, subclave, base and retencion among them – and the snapshot assembler should project them from there rather than take them as operator entry. Until it does, a caller that populates these by hand can state a figure the ledger disagrees with.

Parameters:

data (Any)

apellidos_y_nombre_razon_social_o_deno: str | None

base_retenciones_e_ingresos_a_cuenta: str | None

ciudad: str | None

clave: str | None

clave_de_mercado: str | None

codigo: str | None

codigo_bic_del_perceptor_mediador: str | None

codigo_cuenta_valores: str | None

codigo_emisor: str | None

codigo_lei_del_perceptor: str | None

codigo_pais: str | None

decimal: str | None

decimal_numerico_parte_decimal: str | None

decimal_numerico_parte_decimal_2: str | None

decimal_numerico_parte_decimal_3: str | None

declarante: str | None

direccion_del_perceptor: str | None

ejercicio: str | None

ejercicio_devengo: str | None

entero: str | None

entero_numerico_parte_entera: str | None

entero_numerico_parte_entera_2: str | None

entero_numerico_parte_entera_3: str | None

f_j: str | None

fecha_de_devengo: str | None

fecha_de_inicio_del_prestamo: str | None

fecha_de_nacimiento: str | None

fecha_de_vencimiento_del_prestamo: str | None

identificador_de_registro_o_numero_de: str | None

ingresos_a_cuenta_repercutidos: str | None

naturaleza: str | None

nif_del_declarante: str | None

nif_del_pagador_anterior: str | None

nif_del_perceptor: str | None

nif_del_representante_legal: str | None

nif_en_el_pais_de_residencia_fiscal: str | None

pais_o_territorio_de_residencia_fiscal: str | None

parte_decimal_del_importe_de_las_reten: str | None

parte_entera_del_importe_de_las_retenc: str | None

pendiente: str | None

perceptor_mediador: str | None

procedimiento_especial_de_retenciones: str | None

subclave: str | None

tipo_codigo: str | None

class Modelo296PerceptorInteresesRow(**data)

Bases: BaseModel

One Modelo 296 perceptor of the intereses hoja.

Members are M296PerceptorInteresesField’s values verbatim and are generated from that enum, so a field the projection reference can name is a field this row has. Every member is optional and rendered as text: the per-field width, padding, justification and data type belong to the published layout, and a second copy of them here would be free to disagree with the design.

Parameters:

data (Any)

apellidos_y_nombre_razon_social_o_deno: str | None

ejercicio: str | None

f_j: str | None

identificador_de_registro_o_numero_de: str | None

nif_del_declarante: str | None

nif_del_perceptor: str | None

nif_del_representante_legal: str | None

retenciones_e_ingresos_a_cuenta_ingres: str | None

class Modelo296AnexoPagoRow(**data)

Bases: BaseModel

One Modelo 296 pago a contribuyente.

Members are M296AnexoPagoField’s values verbatim and are generated from that enum, so a field the projection reference can name is a field this row has. Every member is optional and rendered as text: the per-field width, padding, justification and data type belong to the published layout, and a second copy of them here would be free to disagree with the design.

Parameters:

data (Any)

apellidos_y_nombre_razon_social_o_deno: str | None

apellidos_y_nombre_razon_social_o_deno_2: str | None

ciudad: str | None

clave_de_personalidad_del_contribuyent: str | None

codigo_isin: str | None

codigo_lei_del_contribuyente: str | None

codigo_pais: str | None

direccion_del_contribuyente: str | None

ejercicio: str | None

f_j: str | None

fecha_de_devengo: str | None

fecha_de_nacimiento_del_contribuyente: str | None

identificador_de_registro_o_numero_de: str | None

importe_del_pago_al_contribuyente: str | None

nif_del_contribuyente: str | None

nif_del_declarante: str | None

nif_del_perceptor: str | None

nif_del_representante_legal: str | None

nif_en_el_pais_de_residencia_fiscal_de: str | None

numero_de_justificante_del_modelo_210: str | None

pais_o_territorio_de_residencia_fiscal: str | None

porcentaje_de_retencion: str | None

retenciones: str | None

class Modelo296AnexoCertificadoRow(**data)

Bases: BaseModel

One Modelo 296 certificado de pago.

Members are M296AnexoCertificadoField’s values verbatim and are generated from that enum, so a field the projection reference can name is a field this row has. Every member is optional and rendered as text: the per-field width, padding, justification and data type belong to the published layout, and a second copy of them here would be free to disagree with the design.

Parameters:

data (Any)

apellidos_y_nombre_razon_social_o_deno: str | None

apellidos_y_nombre_razon_social_o_deno_2: str | None

codigo_cuenta_valores_del_certificado: str | None

codigo_isin_del_certificado: str | None

codigo_lei_del_titular_registral: str | None

decimal: str | None

decimal_2: str | None

decimal_3: str | None

ejercicio: str | None

entero: str | None

entero_2: str | None

entero_3: str | None

f_j: str | None

fecha_de_pago: str | None

fecha_de_presentacion_del_modelo_210: str | None

identificador_de_registro_o_numero_de: str | None

nif_del_declarante: str | None

nif_del_perceptor: str | None

nif_del_representante_legal: str | None

numero_de_justificante_del_modelo_210: str | None

parte_decimal_del_numero_de_titulos: str | None

parte_decimal_del_numero_de_titulos_2: str | None

parte_entera_del_numero_de_titulos: str | None

parte_entera_del_numero_de_titulos_2: str | None

titular_registral_de_la_cuenta_de_valo: str | None

class Modelo296ProfileFacts(**data)

Bases: BaseModel

Declarant identity the Modelo 296 tipo-1 record declares.

Modelo 296 is the IRNR annual summary of retenciones e ingresos a cuenta on rentas obtained by non-residents without permanent establishment (TRLIRNR art. 24, Orden EHA/3290/2008 art. 6). Its first record identifies who is declaring, for which ejercicio, and how many perceptores the file carries.

All twelve m296.dec.* keys were declared in the vocabulary and produced by nothing, so every one of them rendered blank: the ejercicio at offset 5, the declarante NIF at offset 9 and the razon social at offset 18 among them. A 296 emitted that way names nobody.

Field names are the AEAT key tails verbatim, including two the source design truncated: apellidos_y_nombre is persona con quien relacionarse (design ordinal 7, the 49-byte contact block AEAT splits into a 9-byte telefono and a 40-byte name), and n is N.I.F. DEL REPRESENTANTE LEGAL. (design ordinal 16, offset 391) – the slug stopped at the first period in the label. Renaming either would change a published layout, so the name stays and the meaning is recorded here.

ejercicio restates a year the draft already knows. The structurally better home is a draft field carrying ExportDraftAttribute.FILING_YEAR, which cannot disagree with the draft; that is a layout change and is not made here. Until it is, a snapshot builder must populate this from the draft’s own filing year rather than from an independently entered value.

Parameters:

data (Any)

ejercicio: _FourDigitYear

Ejercicio – design offset 5, length 4, four-digit year.

nif_del_declarante: _NonBlankName

NIF del declarante – design offset 9, length 9.

apellidos_y_nombre_o_razon_social_del: _NonBlankName

Apellidos y nombre o razon social del declarante – design offset 18, length 40.

tipo_de_soporte: _M296SupportType | None

Tipo de soporte – design offset 58, length 1, alfabetico.

telefono: _DigitString9 | None

Persona con quien relacionarse, telefono – design offset 59, length 9.

apellidos_y_nombre: _NonBlankName | None

Persona con quien relacionarse, apellidos y nombre – design offset 68, length 40.

numero_identificativo_de_la_declaracio: _AeatReceiptNumber | None

Numero identificativo de la declaracion – design offset 108, length 13.

declaracion_complementaria_o_sustituti: _M296AmendmentMark | None

Declaracion complementaria o sustitutiva – design offset 121, length 2.

numero_identificativo_de_la_declaracio_2: _AeatReceiptNumber | None

Numero identificativo de la declaracion anterior – design offset 123, length 13.

numero_total_de_perceptores: _DigitString9 | None

Numero total de perceptores – design offset 136, length 9.

An operator-supplied count that the perceptor rows themselves determine. It is optional here deliberately: once the perceptor record repeats its rows, the count is derived from them, and a value stated here that disagrees with the rows is a defect rather than a fact.

n: _NonBlankName | None

N.I.F. del representante legal – design offset 391, length 9. See the class note on why the key tail is n.

sello_electronico: str | None

Sello electronico – design offset 488, length 13.

perceptor_rows: tuple[Modelo296PerceptorRow, ...]

One entry per payee. Empty emits no perceptor record at all, which is what AEAT expects of a declaration with nothing to report; whether that absence is admissible is the record’s own required flag, checked by the renderer.

perceptor_intereses_rows: tuple[Modelo296PerceptorInteresesRow, ...]

One entry per perceptor of the intereses hoja. Empty emits no row of this record at all.

anexo_pago_rows: tuple[Modelo296AnexoPagoRow, ...]

One entry per pago a contribuyente. Empty emits no row of this record at all.

anexo_certificado_rows: tuple[Modelo296AnexoCertificadoRow, ...]

One entry per certificado de pago. Empty emits no row of this record at all.

class Modelo210ContribuyenteFactSet(**data)

Bases: BaseModel

Modelo 210 contribuyente facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

birth_city: str | None

birth_country_code: str | None

birth_date: str | None

foreign_address_city: str | None

foreign_address_complement: str | None

foreign_address_country_code: str | None

foreign_address_email: str | None

foreign_address_fax: str | None

foreign_address_mobile_phone: str | None

foreign_address_phone: str | None

foreign_address_postal_code: str | None

foreign_address_region: str | None

foreign_address_street: str | None

foreign_tax_id: str | None

full_name: str | None

person_type: str | None

tax_id: str | None

tax_residence_country_code: str | None

class Modelo210DeclaracionFactSet(**data)

Bases: BaseModel

Modelo 210 declaracion facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

tipo: str | None

class Modelo210DeclaranteFactSet(**data)

Bases: BaseModel

Modelo 210 declarante facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

capacity_contribuyente: str | None

capacity_depositario: str | None

capacity_gestor: str | None

capacity_pagador: str | None

capacity_representante: str | None

capacity_retenedor: str | None

full_name: str | None

tax_id: str | None

class Modelo210DevengoFactSet(**data)

Bases: BaseModel

Modelo 210 devengo facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

agrupacion: str | None

fecha_devengo: str | None

class Modelo210DevolucionFactSet(**data)

Bases: BaseModel

Modelo 210 devolucion facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

cuenta_resto_banco: str | None

cuenta_resto_ciudad: str | None

cuenta_resto_codigo_pais: str | None

cuenta_resto_direccion_banco: str | None

cuenta_resto_numero_cuenta: str | None

cuenta_resto_swift_bic: str | None

cuenta_sepa_iban: str | None

cuenta_sepa_swift_bic: str | None

cuenta_titular_full_name: str | None

cuenta_titular_tax_id: str | None

renuncia_a_favor_del_tesoro: str | None

class Modelo210GananciaInmobiliariaFactSet(**data)

Bases: BaseModel

Modelo 210 ganancia inmobiliaria facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

conyuge_full_name: str | None

conyuge_tax_id: str | None

cuota_participacion_contribuyente: str | None

cuota_participacion_conyuge: str | None

fecha_adquisicion: str | None

fecha_mejora: str | None

justificante_modelo_211: str | None

titularidad: str | None

class Modelo210IngresoFactSet(**data)

Bases: BaseModel

Modelo 210 ingreso facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

cuenta_resto_banco: str | None

cuenta_resto_ciudad: str | None

cuenta_resto_codigo_pais: str | None

cuenta_resto_direccion_banco: str | None

cuenta_resto_numero_cuenta: str | None

cuenta_resto_swift_bic: str | None

cuenta_sepa_iban: str | None

cuenta_sepa_swift_bic: str | None

cuenta_titular_full_name: str | None

cuenta_titular_tax_id: str | None

forma_pago: str | None

class Modelo210InmuebleFactSet(**data)

Bases: BaseModel

Modelo 210 inmueble facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

referencia_catastral: str | None

situacion_bloque: str | None

situacion_calificador_numero: str | None

situacion_codigo_ine_municipio: str | None

situacion_codigo_postal: str | None

situacion_codigo_provincia: str | None

situacion_datos_complementarios: str | None

situacion_escalera: str | None

situacion_localidad: str | None

situacion_nombre_via: str | None

situacion_numero_casa: str | None

situacion_planta: str | None

situacion_portal: str | None

situacion_puerta: str | None

situacion_tipo_numeracion: str | None

situacion_tipo_via: str | None

class Modelo210PagadorFactSet(**data)

Bases: BaseModel

Modelo 210 pagador facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

full_name: str | None

person_type: str | None

tax_id: str | None

class Modelo210RentaFactSet(**data)

Bases: BaseModel

Modelo 210 renta facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

clave_divisa: str | None

class Modelo210RepresentanteFactSet(**data)

Bases: BaseModel

Modelo 210 representante facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

appointment_kind: str | None

domicilio_bloque: str | None

domicilio_calificador_numero: str | None

domicilio_codigo_ine_municipio: str | None

domicilio_codigo_postal: str | None

domicilio_codigo_provincia: str | None

domicilio_datos_complementarios: str | None

domicilio_escalera: str | None

domicilio_localidad: str | None

domicilio_nombre_via: str | None

domicilio_numero_casa: str | None

domicilio_planta: str | None

domicilio_portal: str | None

domicilio_puerta: str | None

domicilio_tipo_numeracion: str | None

domicilio_tipo_via: str | None

fax: str | None

full_name: str | None

mobile_phone: str | None

person_type: str | None

phone: str | None

tax_id: str | None

class Modelo210SinIngresoNiDevolucionFactSet(**data)

Bases: BaseModel

Modelo 210 sin ingreso ni devolucion facts, flat members named from the AEAT component vocabulary.

Parameters:

data (Any)

cuota_cero: str | None

class Modelo210ProfileFacts(**data)

Bases: BaseModel

The party, property and settlement facts modelo 210’s export layout cites.

Modelo 210 is the non-resident income tax return. Its layout cites 102 irnr.* producer keys across twelve scopes; every one of them resolved to nothing, so the contribuyente, the representante, the inmueble and the refund account all rendered blank on a filed return.

Each scope declares its own flat members rather than sharing one address or account model. AEAT reuses one address grammar but not one address shape: modelo 210 identifies the municipio by INE code where modelo 360 writes its name, so a shared type would assert two shapes are interchangeable when they are not.

Every field is optional and absent stays absent: AEAT writes an alphanumeric header field with no content to blancos, so an unsupplied scope is a legal filing rather than a defect. Which scopes a given filing must carry is the caller’s decision, not this type’s.

Parameters:

data (Any)

contribuyente: Modelo210ContribuyenteFactSet | None

declaracion: Modelo210DeclaracionFactSet | None

declarante: Modelo210DeclaranteFactSet | None

devengo: Modelo210DevengoFactSet | None

devolucion: Modelo210DevolucionFactSet | None

ganancia_inmobiliaria: Modelo210GananciaInmobiliariaFactSet | None

ingreso: Modelo210IngresoFactSet | None

inmueble: Modelo210InmuebleFactSet | None

pagador: Modelo210PagadorFactSet | None

renta: Modelo210RentaFactSet | None

representante: Modelo210RepresentanteFactSet | None

sin_ingreso_ni_devolucion: Modelo210SinIngresoNiDevolucionFactSet | None

class GeneralFilingProfileFacts(**data)

Bases: BaseModel

Explicit absence of modelo-specific producer facts for a layout.

Parameters:

data (Any)

class Modelo202ActivityFacts(**data)

Bases: BaseModel

One repeatable M202 activity fact, without claiming primacy.

Parameters:

data (Any)

cnae: _CnaeCode

class M202UnsupportedProducerId(*values)

Bases: StrEnum

M202 producer facts that are not yet admitted to the typed substrate.

PRINCIPAL_CNAE

OFFICIAL_OFFSET_122

OFFICIAL_OFFSET_123

OFFICIAL_OFFSET_124

OFFICIAL_OFFSET_125

OFFICIAL_OFFSET_126

OFFICIAL_OFFSET_127

OFFICIAL_OFFSET_128

OFFICIAL_OFFSET_129

OFFICIAL_OFFSET_130

OFFICIAL_OFFSET_131

OFFICIAL_OFFSET_132

OFFICIAL_OFFSET_147

class Modelo202ProducerProfile(**data)

Bases: BaseModel

M202 producer view referencing the canonical taxpayer profile owner.

The régimen marks and the principal CNAE below are what modelo 202’s export layout cites as header producers. Before they existed the eighteen m202.* keys were declared in the vocabulary and resolved by nothing, so each one rendered blank on a filed pago fraccionado.

principal_cnae is DECLARED, never inferred from activities: Modelo202ActivityFacts is documented as “one repeatable M202 activity fact, without claiming primacy”, so picking the first or the largest would invent a primacy the substrate deliberately does not carry. AEAT asks which activity is principal, so the operator answers it.

Every mark is optional and absent stays absent – AEAT leaves a régimen mark blank when the régimen does not apply, and a mark that does not apply is genuinely absent rather than unknown.

Parameters:

data (Any)

taxpayer_profile: TaxpayerProfile

activities: tuple[Modelo202ActivityFacts, ...]

principal_cnae: _CnaeCode | None

regimen_ley_49_2002_sin_fines_lucrativos: str | None

regimen_ley_11_2009_socimi: str | None

regimen_entidades_navieras_tonelaje: str | None

regimen_articulo_101_lis_reducida_dimension: str | None

regimen_entidad_capital_riesgo: str | None

cifra_negocios_doce_meses_umbral: str | None

cifra_negocios_periodo_anterior_bajo_umbral: str | None

cooperativa_o_multiples_tipos: str | None

cooperativa_fiscalmente_protegida: str | None

multiples_tipos_impositivos: str | None

tipo_gravamen_impuesto_sociedades: str | None

importe_neto_cifra_negocios_tramo: str | None

marca_instrumental: str | None

discriminante_declaracion_negativa: str | None

normativa_territorio_foral: str | None

comunicacion_datos_adicionales: str | None

numero_referencia_sociedades: str | None

property unsupported_producer_ids: tuple[M202UnsupportedProducerId, ...]

Return the exact immutable M202 producer-gap inventory.

class FilingElectionFacts(**data)

Bases: BaseModel

Immutable operator elections and their resolved result disposition.

Parameters:

data (Any)

result_disposition: ResultDisposition

payment: PaymentElection

refund: RefundElection

prior_domiciliation: PriorDomiciliationElection

class M303FilingFacts(**data)

Bases: BaseModel

DP30301 facts owned by one immutable Modelo 303 filing instance.

Parameters:

data (Any)

joint_return_elected: bool

annual_volume_nonzero: bool

insolvency: M303InsolvencyFilingFact | None

exonerado_390: M303Exonerado390FilingEvidence

regimen_simplificado: M303RegimenSimplificadoFilingEvidence

regimen_simplificado_result: M303RegimenSimplificadoCalculationResult

period: Period

supplier_regime: M303SupplierRegimeArrival

prorrata_transition: M303ProrrataTransitionArrival

prorrata_register: ProrrataRegister

differentiated_contributions: tuple[IvaDifferentiatedDeductionContribution, ...]

bienes_register: BienesInversionIvaRegister

regularisation_result: RegistroRegularizacionResult

bienes_parameters: BienesInversionRegularizacionParameters

The registry-resolved figures the regularisation result was produced under. Carried on the facts rather than resolved here because this model holds no revision, and because the oracle’s independence depends on comparing the result’s own provenance against a bundle supplied from outside it.

resolve_m303_filing_facts(*, evidence, supplier_regime, prorrata_transition, prorrata_register, differentiated_contributions, bienes_register, regularisation_result, bienes_parameters)

Project persisted M303 evidence together with canonical arrival facts.

Return type:

M303FilingFacts

Parameters:

• evidence (FilingInstanceEvidence)

• supplier_regime (M303SupplierRegimeArrival)

• prorrata_transition (M303ProrrataTransitionArrival)

• prorrata_register (ProrrataRegister)

• differentiated_contributions (tuple[IvaDifferentiatedDeductionContribution, ...])

• bienes_register (BienesInversionIvaRegister)

• regularisation_result (RegistroRegularizacionResult)

• bienes_parameters (BienesInversionRegularizacionParameters)

class AmendmentEvidence(**data)

Bases: BaseModel

Typed evidence for an amendment of an AEAT-accepted filing.

Parameters:

data (Any)

kind: CalculationRevisionAmendmentKind

m303_rectificativa_motive: M303RectificativaMotive | None

original_aeat_receipt: _AeatReceiptNumber

property is_complementaria: bool

True when this evidence records a complementaria amendment.

property is_sustitutiva: bool

True when this evidence records a sustitutiva amendment.

property is_rectificativa: bool

True when this evidence records a rectificativa amendment.

class RefundAccountSelection(**data)

Bases: BaseModel

Secure account selected for a refund disposition.

Parameters:

data (Any)

role: Literal['refund']

account: RefundAccount

class ChargeAccountSelection(**data)

Bases: BaseModel

Secure account selected for a direct-debit disposition.

Parameters:

data (Any)

role: Literal['charge']

account: ChargeAccount

class FilingProducerSnapshot(**data)

Bases: BaseModel

Complete immutable filing facts before registry-specific translation.

Parameters:

data (Any)

modelo: Modelo

taxpayer_tax_id: SubjectTaxId

taxpayer_identity: TaxpayerIdentityFacts

presenter: PresenterIdentity

declaration_contact: DeclarationContactFacts

every existing caller predates this fact and none of them can supply it, so demanding it would refuse filings that are legal without it. An absent contact renders as blancos, which is what AEAT’s own header rule prescribes.

Type:

Defaulted rather than required

model_profile: FilingModelProfileFacts

elections: FilingElectionFacts

amendment_evidence: AmendmentEvidence | None

selected_account: SelectedFilingAccount | None

m303_filing_facts: M303FilingFacts | None

m390_filing_facts: _M390FilingFacts | None

build_filing_producer_snapshot(*, modelo, taxpayer_tax_id, taxpayer_identity, presenter, model_profile, elections, amendment_evidence, refund_account, charge_account, m303_filing_facts, declaration_contact=None, nota_three_refund_account=False)

Build a snapshot retaining only the account selected by disposition.

declaration_contact is optional so every caller that predates the informativa contact fact keeps working unchanged; an absent contact renders as blancos, which is what AEAT’s own header rule prescribes.

Return type:

FilingProducerSnapshot

Parameters:

• modelo (Modelo)

• taxpayer_tax_id (SubjectTaxId)

• taxpayer_identity (TaxpayerIdentityFacts)

• presenter (PresenterIdentity)

• model_profile (FilingModelProfileFacts)

• elections (FilingElectionFacts)

• amendment_evidence (AmendmentEvidence | None)

• refund_account (RefundAccount | None)

• charge_account (ChargeAccount | None)

• m303_filing_facts (M303FilingFacts | None)

• declaration_contact (DeclarationContactFacts | None)

• nota_three_refund_account (bool)