fiscalapi 4.0.418__tar.gz → 4.0.439__tar.gz

{fiscalapi-4.0.418/fiscalapi.egg-info → fiscalapi-4.0.439}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.418
+Version: 4.0.439
 Summary: Genera facturas CFDI válidas ante el SAT consumiendo el API de https://www.fiscalapi.com
 Home-page: https://www.fiscalapi.com
 Author: Fiscalapi
@@ -87,13 +87,14 @@ Dynamic: summary
 - **Búsqueda de información** en catálogos del SAT con filtros avanzados
 - **Acceso y búsqueda** en catálogos completos
 
-## 🎫 Gestión de Timbres y Créditos de Validación
+## 🎫 Gestión de Timbres, Créditos de Validación y Créditos de Ticket
 - **Gestión de folios fiscales**: compra timbres a FiscalAPI y transfiere/retira a las personas de tu organización según tus reglas de negocio
 - **Listar transacciones** del ledger con paginación
 - **Consultar transacciones** por ID
 - **Transferir timbres** entre personas
 - **Retirar timbres** de una persona
 - **Transferir y retirar créditos de validación SAT** con `credit_type=CreditType.VALIDATION`
+- **Transferir y retirar créditos de ticket** con `credit_type=CreditType.TICKET`; su saldo se lee en `balances` de la persona
 
 ## 🛡️ Validaciones SAT
 - **Estructura del XML** contra el Anexo 20 y los complementos declarados
@@ -180,7 +181,7 @@ from fiscalapi import TaxFile
 # Subir certificado (CER)
 certificado_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
     file_type=0,  # 0 para certificado, 1 para llave privada
     password="12345678a"    
@@ -189,7 +190,7 @@ certificado_csd = TaxFile(
 # Subir llave privada (KEY)
 clave_privada_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
     file_type=1,
     password="12345678a"
@@ -437,6 +438,25 @@ params = StampTransactionParams(
 api_response = client.stamps.transfer_stamps(params)
 ```
 
+Los créditos de ticket se transfieren igual, con `credit_type=CreditType.TICKET`, y su saldo se lee en `balances` de la persona (un tipo ausente tiene saldo 0):
+
+```python
+from fiscalapi import CreditType, StampTransactionParams
+
+params = StampTransactionParams(
+    from_person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
+    to_person_id="96b46762-d246-4a67-a562-510a25dbafa9",
+    amount=100,
+    comments="Asignación de créditos de ticket",
+    credit_type=CreditType.TICKET
+)
+
+api_response = client.stamps.transfer_stamps(params)
+
+person = client.people.get_by_id("96b46762-d246-4a67-a562-510a25dbafa9").data
+ticket_balance = next((b.available for b in person.balances or [] if b.credit_type == CreditType.TICKET), 0)
+```
+
 ### 10. Factura de Comercio Exterior
 
 El complemento se envía en `Invoice.complement.comercio_exterior`. Puede combinarse con carta porte en el mismo comprobante.
@@ -566,7 +586,7 @@ if api_response.succeeded:
     print(api_response.data.base64_file)     # PDF firmado en base64
 ```
 
-Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado en `manifest_status_id`.
+Tras una firma exitosa, todas las personas del tenant con el RFC del certificado quedan con `manifest_status_id` en `Signed`; `client.people.get_by_id(...)` lo refleja.
 
 ## 📋 Operaciones Principales
 
@@ -576,17 +596,20 @@ Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado e
   Alta y administración de personas, gestión de certificados (CSD).
 - **Productos y Servicios**
   Administración de catálogos de productos, búsqueda en catálogos SAT.
-- **Timbres y créditos de validación**
-  Listar transacciones, transferir y retirar timbres o créditos de validación entre personas.
+- **Timbres, créditos de validación y créditos de ticket**
+  Listar transacciones, transferir y retirar timbres, créditos de validación o créditos de ticket entre personas.
 - **Validaciones SAT**
   Validar estructura, certificado, sellos, estatus en el SAT y listas negras 69-B de un CFDI o un RFC.
 - **Carta manifiesto**
   Firmar la carta manifiesto de una persona con su e.firma (FIEL) y obtener el PDF resultante.
+- **Tickets (Auto CFDI)**
+  Ingerir ventas pagadas del punto de venta con Idempotency-Key opcional, consultarlas con filtros, reimprimir su código y cancelarlas.
 
 ## 📂 Más Ejemplos
 
 - [Gestión de Timbres](examples/ejemplos-timbres.py)
 - [Validaciones SAT](examples/ejemplos-validaciones-sat.py)
+- [Tickets de Auto CFDI](examples/ejemplos-tickets.py)
 - [Complementos de Pago](examples/ejemplos-facturas-de-complemento-pago.py)
 - [Facturas de Nómina](examples/ejemplos-facturas-de-nomina.py)
 - [Impuestos Locales (Por Valores)](examples/ejemplos-factura-impuestos-locales-valores.py)

{fiscalapi-4.0.418 → fiscalapi-4.0.439}/README.md

@@ -50,13 +50,14 @@
 - **Búsqueda de información** en catálogos del SAT con filtros avanzados
 - **Acceso y búsqueda** en catálogos completos
 
-## 🎫 Gestión de Timbres y Créditos de Validación
+## 🎫 Gestión de Timbres, Créditos de Validación y Créditos de Ticket
 - **Gestión de folios fiscales**: compra timbres a FiscalAPI y transfiere/retira a las personas de tu organización según tus reglas de negocio
 - **Listar transacciones** del ledger con paginación
 - **Consultar transacciones** por ID
 - **Transferir timbres** entre personas
 - **Retirar timbres** de una persona
 - **Transferir y retirar créditos de validación SAT** con `credit_type=CreditType.VALIDATION`
+- **Transferir y retirar créditos de ticket** con `credit_type=CreditType.TICKET`; su saldo se lee en `balances` de la persona
 
 ## 🛡️ Validaciones SAT
 - **Estructura del XML** contra el Anexo 20 y los complementos declarados
@@ -143,7 +144,7 @@ from fiscalapi import TaxFile
 # Subir certificado (CER)
 certificado_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
     file_type=0,  # 0 para certificado, 1 para llave privada
     password="12345678a"    
@@ -152,7 +153,7 @@ certificado_csd = TaxFile(
 # Subir llave privada (KEY)
 clave_privada_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
     file_type=1,
     password="12345678a"
@@ -400,6 +401,25 @@ params = StampTransactionParams(
 api_response = client.stamps.transfer_stamps(params)
 ```
 
+Los créditos de ticket se transfieren igual, con `credit_type=CreditType.TICKET`, y su saldo se lee en `balances` de la persona (un tipo ausente tiene saldo 0):
+
+```python
+from fiscalapi import CreditType, StampTransactionParams
+
+params = StampTransactionParams(
+    from_person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
+    to_person_id="96b46762-d246-4a67-a562-510a25dbafa9",
+    amount=100,
+    comments="Asignación de créditos de ticket",
+    credit_type=CreditType.TICKET
+)
+
+api_response = client.stamps.transfer_stamps(params)
+
+person = client.people.get_by_id("96b46762-d246-4a67-a562-510a25dbafa9").data
+ticket_balance = next((b.available for b in person.balances or [] if b.credit_type == CreditType.TICKET), 0)
+```
+
 ### 10. Factura de Comercio Exterior
 
 El complemento se envía en `Invoice.complement.comercio_exterior`. Puede combinarse con carta porte en el mismo comprobante.
@@ -529,7 +549,7 @@ if api_response.succeeded:
     print(api_response.data.base64_file)     # PDF firmado en base64
 ```
 
-Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado en `manifest_status_id`.
+Tras una firma exitosa, todas las personas del tenant con el RFC del certificado quedan con `manifest_status_id` en `Signed`; `client.people.get_by_id(...)` lo refleja.
 
 ## 📋 Operaciones Principales
 
@@ -539,17 +559,20 @@ Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado e
   Alta y administración de personas, gestión de certificados (CSD).
 - **Productos y Servicios**
   Administración de catálogos de productos, búsqueda en catálogos SAT.
-- **Timbres y créditos de validación**
-  Listar transacciones, transferir y retirar timbres o créditos de validación entre personas.
+- **Timbres, créditos de validación y créditos de ticket**
+  Listar transacciones, transferir y retirar timbres, créditos de validación o créditos de ticket entre personas.
 - **Validaciones SAT**
   Validar estructura, certificado, sellos, estatus en el SAT y listas negras 69-B de un CFDI o un RFC.
 - **Carta manifiesto**
   Firmar la carta manifiesto de una persona con su e.firma (FIEL) y obtener el PDF resultante.
+- **Tickets (Auto CFDI)**
+  Ingerir ventas pagadas del punto de venta con Idempotency-Key opcional, consultarlas con filtros, reimprimir su código y cancelarlas.
 
 ## 📂 Más Ejemplos
 
 - [Gestión de Timbres](examples/ejemplos-timbres.py)
 - [Validaciones SAT](examples/ejemplos-validaciones-sat.py)
+- [Tickets de Auto CFDI](examples/ejemplos-tickets.py)
 - [Complementos de Pago](examples/ejemplos-facturas-de-complemento-pago.py)
 - [Facturas de Nómina](examples/ejemplos-facturas-de-nomina.py)
 - [Impuestos Locales (Por Valores)](examples/ejemplos-factura-impuestos-locales-valores.py)

{fiscalapi-4.0.418 → fiscalapi-4.0.439}/fiscalapi/__init__.py

@@ -75,6 +75,20 @@ from .models.sat_validation_models import (
     SatValidationStatus,
     SatValidationResult,
 )
+# Modelos de tickets (Auto CFDI)
+from .models.ticket_models import (
+    TicketStatus,
+    TicketEventType,
+    TicketActorType,
+    TicketIssuer,
+    TicketItemTax,
+    TicketItem,
+    TicketEvent,
+    Ticket,
+    TicketIngestionResult,
+    TicketCodeResult,
+    TicketListFilters,
+)
 
 # Modelos de dominio
 from .models.fiscalapi_models import (
@@ -82,6 +96,7 @@ from .models.fiscalapi_models import (
     ProductTax,
     Product,
     # Person models
+    CreditBalance,
     Person,
     EmployeeData,
     EmployerData,
@@ -174,6 +189,7 @@ from .services.tax_file_service import TaxFileService
 from .services.sat_validation_service import SatValidationService
 from .services.stamp_service import StampService
 from .services.manifest_service import ManifestService
+from .services.ticket_service import TicketService
 
 # Cliente principal
 from .services.fiscalapi_client import FiscalApiClient
@@ -190,6 +206,7 @@ __all__ = [
     "ProductTax",
     "Product",
     # Person models
+    "CreditBalance",
     "Person",
     "EmployeeData",
     "EmployerData",
@@ -309,6 +326,18 @@ __all__ = [
     "SatValidationTypeStatus",
     "SatValidationStatus",
     "SatValidationResult",
+    # Ticket models (Auto CFDI)
+    "TicketStatus",
+    "TicketEventType",
+    "TicketActorType",
+    "TicketIssuer",
+    "TicketItemTax",
+    "TicketItem",
+    "TicketEvent",
+    "Ticket",
+    "TicketIngestionResult",
+    "TicketCodeResult",
+    "TicketListFilters",
     # Servicios
     "BaseService",
     "ApiKeyService",
@@ -325,6 +354,7 @@ __all__ = [
     "SatValidationService",
     "StampService",
     "ManifestService",
+    "TicketService",
     # Cliente principal
     "FiscalApiClient",
 ]

{fiscalapi-4.0.418 → fiscalapi-4.0.439}/fiscalapi/models/__init__.py

@@ -61,11 +61,26 @@ from .sat_validation_models import (
     SatValidationStatus,
     SatValidationResult,
 )
+from .ticket_models import (
+    # Ticket models (Auto CFDI)
+    TicketStatus,
+    TicketEventType,
+    TicketActorType,
+    TicketIssuer,
+    TicketItemTax,
+    TicketItem,
+    TicketEvent,
+    Ticket,
+    TicketIngestionResult,
+    TicketCodeResult,
+    TicketListFilters,
+)
 from .fiscalapi_models import (
     # Product models
     ProductTax,
     Product,
     # Person models
+    CreditBalance,
     Person,
     EmployeeData,
     EmployerData,
@@ -188,6 +203,7 @@ __all__ = [
     "ProductTax",
     "Product",
     # Person models
+    "CreditBalance",
     "Person",
     "EmployeeData",
     "EmployerData",
@@ -273,4 +289,16 @@ __all__ = [
     "SatValidationTypeStatus",
     "SatValidationStatus",
     "SatValidationResult",
+    # Ticket models (Auto CFDI)
+    "TicketStatus",
+    "TicketEventType",
+    "TicketActorType",
+    "TicketIssuer",
+    "TicketItemTax",
+    "TicketItem",
+    "TicketEvent",
+    "Ticket",
+    "TicketIngestionResult",
+    "TicketCodeResult",
+    "TicketListFilters",
 ]

{fiscalapi-4.0.418 → fiscalapi-4.0.439}/fiscalapi/models/common_models.py

@@ -10,6 +10,8 @@ class ApiResponse(BaseModel, Generic[T]):
     details: Optional[str] = Field(default=None, alias="details")
     data: Optional[T] = Field(default=None, alias="data")
     http_status_code: Optional[int] = Field(default=None, alias="httpStatusCode")
+    trace_identifier: Optional[str] = Field(default=None, alias="traceIdentifier", description="Identificador de la petición en los registros de FiscalAPI. Viene en los errores (por ejemplo, un 500 o un 502): inclúyalo al escribir a soporte@fiscalapi.com.")
+    error_data: Optional[Any] = Field(default=None, alias="errorData", description="El data crudo de una respuesta de error (dict o lista tal cual), por ejemplo existingTicketId en el 409 de tickets.create o expectedTotal y computedTotal en su 422. None en las respuestas exitosas y en los errores sin data; data no cambia (en un error sigue en None).")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -30,7 +32,7 @@ class ValidationFailure(BaseModel):
     """Modelo para errores de validación."""
     property_name: str = Field(alias="propertyName")
     error_message: str = Field(alias="errorMessage")
-    attempted_value: Optional[Any] = Field(default=None, alias="attemptedValue")
+    attempted_value: Optional[Any] = Field(default=None, alias="attemptedValue", description="Valor recibido. El de un secreto (contraseñas, códigos, tokens, archivos y contraseñas de CSD/FIEL) llega como \"[masked: n]\", o \"[masked]\" si es un objeto o lista que lo contiene.")
 
     model_config = ConfigDict(populate_by_name=True)
 

{fiscalapi-4.0.418 → fiscalapi-4.0.439}/fiscalapi/models/fiscalapi_models.py

@@ -4,7 +4,7 @@ from pydantic import BaseModel, ConfigDict, Field
 from fiscalapi.models.common_models import BaseDto, CatalogDto
 from fiscalapi.models.carta_porte_models import CartaPorteComplement
 from fiscalapi.models.comercio_exterior_models import ComercioExteriorComplement
-from typing import Literal, Optional
+from typing import Optional, Union
 from datetime import datetime
 
 # products models
@@ -14,13 +14,13 @@ class ProductTax(BaseDto):
     
     rate: Decimal = Field(default=..., ge=0, le=1, alias="rate", description="Tasa de impuesto")
     
-    tax_id: Optional[Literal["001", "002", "003"]] = Field(default=None, alias="taxId", description="Impuesto")
+    tax_id: Optional[str] = Field(default=None, alias="taxId", description="Impuesto: clave del catálogo c_Impuesto del SAT (\"001\" ISR, \"002\" IVA, \"003\" IEPS). La valida el API.")
     tax: Optional[CatalogDto] = Field(default=None, alias="tax", description="Impuesto expandido")
 
-    tax_flag_id: Optional[Literal["T", "R"]] = Field(default=None, alias="taxFlagId", description="Traslado o Retención")
+    tax_flag_id: Optional[str] = Field(default=None, alias="taxFlagId", description="Naturaleza del impuesto: \"T\" (traslado) o \"R\" (retención). La valida el API.")
     tax_flag: Optional[CatalogDto] = Field(default=None, alias="taxFlag", description="Traslado o Retención expandido")
     
-    tax_type_id: Optional[Literal["Tasa", "Cuota", "Exento"]] = Field(default=None, alias="taxTypeId", description="Tipo de impuesto")
+    tax_type_id: Optional[str] = Field(default=None, alias="taxTypeId", description="Tipo factor: clave del catálogo c_TipoFactor del SAT (\"Tasa\", \"Cuota\" o \"Exento\"). La valida el API.")
     tax_type: Optional[CatalogDto] = Field(default=None, alias="taxType",  description="Tipo de impuesto expandido")
     
     
@@ -48,33 +48,49 @@ class Product(BaseDto):
 
 # people models
 
+class CreditBalance(BaseModel):
+    """Saldo de una persona para un tipo de crédito (Person.balances).
+
+    Un tipo ausente tiene saldo 0; un tipo que este SDK no conoce conserva su número en credit_type.
+    """
+
+    credit_type: int = Field(default=..., alias="creditType", description="Tipo de crédito: 1 timbres, 2 créditos de validación, 3 créditos de ticket.")
+    available: int = Field(default=..., alias="available", description="Saldo disponible.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
 class Person(BaseDto):
     """Modelo persona en FiscalAPI."""
 
     legal_name: Optional[str] = Field(default=None, alias="legalName", description="Razón social de la persona sin régimen de capital.")
     email: Optional[str] = Field(default=None, alias="email", description="Correo electrónico de la persona. El API valida el formato.")
-    password: Optional[str]  = Field(default=None, alias="password", description="Contraseña para acceder al dashboard.")
-    capital_regime: Optional[str] = Field(default=None, alias="CapitalRegime", description="[Deprecado] El API no expone este campo; se conserva por compatibilidad y se ignora.")
-    sat_tax_regime_id: Optional[Literal["601", "603", "605", "606", "607", "608", "610", "611", "612", "614", "615", "616", "620", "621", "622", "623", "624", "625", "626"]] = Field(default=None, alias="satTaxRegimeId", description="Código del régimen fiscal del emisor.")
+    password: Optional[str]  = Field(default=None, alias="password", description="Contraseña para acceder al dashboard. Requerida al crear; al actualizar, None o vacía conserva la actual. El API nunca la devuelve.")
+    phone_number: Optional[str] = Field(default=None, alias="phoneNumber", description="Teléfono de la persona.")
+    sat_tax_regime_id: Optional[str] = Field(default=None, alias="satTaxRegimeId", description="Código del régimen fiscal: clave del catálogo c_RegimenFiscal del SAT. La valida el API.")
     sat_tax_regime: Optional[CatalogDto] = Field(default=None, alias="satTaxRegime", description="Código del régimen fiscal expandido.")
-    sat_cfdi_use_id: Optional[Literal["G01", "G02", "G03", "I01", "I02", "I03", "I04", "I05", "I06", "I07", "I08", "D01", "D02", "D03", "D04", "D05", "D06", "D07", "D08", "D09", "D10", "S01", "CP01", "CN01"]] = Field(default=None, alias="satCfdiUseId", description="Código de uso del CFDI.")
+    sat_cfdi_use_id: Optional[str] = Field(default=None, alias="satCfdiUseId", description="Código de uso del CFDI: clave del catálogo c_UsoCFDI del SAT. La valida el API.")
     sat_cfdi_use: Optional[CatalogDto] = Field(default=None, alias="satCfdiUse", description="Código de uso del CFDI expandido.")
-    user_type_id: Optional[Literal["T","C", "U"]] = Field(default=None, alias="userTypeId", description="Tipo de persona.")
+    user_type_id: Optional[str] = Field(default=None, alias="userTypeId", description="Tipo de persona: C (cliente, por omisión al crear) o U (usuario). T (tenant) solo llega en respuestas: el API lo rechaza al crear y al actualizar solo lo acepta si la persona ya es T.")
     user_type: Optional[CatalogDto] = Field(default=None, alias="userType", description="Tipo de persona expandido.")
     tin: Optional[str] = Field(default=None, alias="tin", description="RFC del emisor (Tax Identification Number).")
     zip_code: Optional[str] = Field(default=None, alias="zipCode", description="Código postal del emisor.")
     curp: Optional[str] = Field(default=None, alias="curp", description="CURP de la persona.")
     base64_photo: Optional[str] = Field(default=None, alias="base64Photo", description="Foto de perfil en formato base64.")
-    tax_password: Optional[str] = Field(default=None, alias="taxPassword", description="Contraseña de los certificados CSD del emisor.")
+    tax_password: Optional[str] = Field(default=None, alias="taxPassword", description="Contraseña de la llave privada (.key) que la persona guarda en su perfil. El API no la usa para sellar (al timbrar usa la de los certificados registrados o la de tax_credentials). Con valor solo para la propia persona y el owner del tenant; los demás reciben None. Al actualizar, None la conserva y \"\" la borra.")
     available_balance: Optional[Decimal] = Field(default=None, alias="availableBalance", description="Saldo disponible en la cuenta.")
-    committed_balance: Optional[Decimal] = Field(default=None, alias="committedBalance", description="Saldo en tránsito.")
+    committed_balance: Optional[Decimal] = Field(default=None, alias="committedBalance", description="Campo heredado: el API ya no lo calcula y siempre vale 0 (solo lectura). Para el saldo use available_balance o balances.")
     available_validation_balance: Optional[int] = Field(default=None, alias="availableValidationBalance", description="Créditos de validación SAT disponibles en la cuenta.")
+    balances: Optional[list[CreditBalance]] = Field(default=None, alias="balances", description="Saldos por tipo de crédito (solo lectura). Solo aparecen los tipos que la persona ha tenido.")
     manifest_status_id: Optional[str] = Field(default=None, alias="manifestStatusId", description="Estado de la carta manifiesto de la persona.")
     manifest_status: Optional[CatalogDto] = Field(default=None, alias="manifestStatus", description="Estado de la carta manifiesto expandido.")
     tenant_id: Optional[str] = Field(default=None, alias="tenantId", description="ID del tenant al que pertenece el emisor.")
     tenant: Optional[CatalogDto] = Field(default=None, alias="tenant", description="Tenant expandido.")
+    is_owner: Optional[bool] = Field(default=None, alias="isOwner", description="True si la persona es el owner de su tenant (solo lectura).")
+    valid_to: Optional[datetime] = Field(default=None, alias="validTo", description="Fin de vigencia de la persona (solo lectura). La asigna el API; casi siempre es None y es informativa (no limita el timbrado ni el acceso al API).")
     country_id: Optional[str] = Field(default=None, alias="countryId", description="Código del país de residencia para extranjeros (catálogo c_Pais).")
     foreign_tin: Optional[str] = Field(default=None, alias="foreignTin", description="Número de identificación fiscal del extranjero.")
+    country: Optional[CatalogDto] = Field(default=None, alias="country", description="País de residencia fiscal expandido (solo lectura).")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -132,10 +148,10 @@ class TaxFile(BaseDto):
         """Modelo TaxFile que representa un componente de un par CSD: certificado (.cer) o llave privada (.key)."""
 
         person_id: Optional[str] = Field(default=None, alias="personId", description="Id de la persona propietaria del certificado.")
-        tin: Optional[str] = Field(default=None, alias="tin", description="RFC del propietario del certificado. Debe coincidir con el RFC del certificado.")
+        tin: Optional[str] = Field(default=None, alias="tin", description="RFC de la persona. Opcional al subir: si se omite, el API usa el RFC de la persona; si se envía, debe ser el RFC de la persona (sin distinguir mayúsculas) o el API responde 400 con la falla en Tin. El API siempre devuelve el RFC de la persona.")
         base64_file: Optional[str] = Field(default=None, alias="base64File", description="Archivo certificado o llave privada en formato base64.")
-        file_type: Optional[Literal[0, 1]] = Field(default=None, alias="fileType", description="Tipo de archivo: 0 para certificado, 1 para llave privada.")
-        password: Optional[str] = Field(default=None, alias="password", description="Contraseña de la llave privada.")
+        file_type: Optional[int] = Field(default=None, alias="fileType", description="Tipo de archivo: 0 certificado CSD (.cer), 1 llave privada CSD (.key), 2 certificado FIEL (.cer), 3 llave privada FIEL (.key). El API valida el valor.")
+        password: Optional[str] = Field(default=None, alias="password", description="Contraseña de la llave privada. Solo se envía al subir (tax_files.create()): en las consultas (get_list(), get_by_id() y la respuesta de create()) el API la devuelve vacía (''); solo get_default_values() la devuelve.")
         valid_from: Optional[datetime] = Field(default=None, alias="validFrom", description="Fecha de inicio de vigencia del certificado o llave privada.")
         valid_to: Optional[datetime] = Field(default=None, alias="validTo", description="Fecha de fin de vigencia del certificado o llave privada.")
         sequence: Optional[int] = Field(default=None, alias="sequence", description="Numero de secuencia que identifica el par entre certificado y llave privada.")
@@ -185,11 +201,11 @@ class InvoiceRecipientEmployeeData(BaseDto):
     model_config = ConfigDict(populate_by_name=True)
 
 
-class TaxCredential(BaseDto):
+class TaxCredential(BaseModel):
     """Modelo para los sellos del emisor (archivos .cer y .key)."""
     base64_file: str = Field(default=..., alias="base64File", description="Archivo en formato base64.")
-    file_type: Literal[0, 1] = Field(default=..., alias="fileType", description="Tipo de archivo: 0 para certificado, 1 para llave privada.")
-    password: str = Field(default=..., alias="password", description="Contraseña del archivo .key independientemente de si es un archivo .cer o .key.")
+    file_type: int = Field(default=..., alias="fileType", description="Tipo de archivo: 0 para certificado, 1 para llave privada (el par CSD). El API valida el valor.")
+    password: Optional[str] = Field(default=None, alias="password", description="Contraseña de la llave privada. Requerida en el objeto .key (file_type 1); en el .cer el API no la usa.")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -230,7 +246,7 @@ class ItemTax(BaseDto):
     tax_code: Optional[str] = Field(default=None, alias="taxCode", description="Código del impuesto.")
     tax_type_code: Optional[str] = Field(default=None, alias="taxTypeCode", description="Tipo de factor.")
     tax_rate: Optional[Decimal] = Field(default=None, alias="taxRate", description="Tasa del impuesto.")
-    tax_flag_code: Optional[Literal["T", "R"]] = Field(default=None, alias="taxFlagCode", description="Código que indica la naturaleza del impuesto. (T)raslado o (R)etención.")
+    tax_flag_code: Optional[str] = Field(default=None, alias="taxFlagCode", description="Código que indica la naturaleza del impuesto. (T)raslado o (R)etención.")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -288,6 +304,7 @@ class InvoiceItem(BaseDto):
     customs_info: Optional[list[ItemCustomsInfo]] = Field(default=None, alias="customsInfo", description="Información aduanera.")
     property_info: Optional[list[ItemPropertyInfo]] = Field(default=None, alias="propertyInfo", description="Información predial.")
     parts: Optional[list[ItemPart]] = Field(default=None, alias="parts", description="Partes del concepto.")
+    ticket_id: Optional[str] = Field(default=None, alias="ticketId", description="Id del ticket de Auto CFDI que este concepto factura. Solo en una factura global de ingreso (tipo I con global_information) con el emisor por referencia (issuer.id); un ticket puede ir en varios conceptos, uno por grupo de objeto de impuesto e impuestos. En None no se envía.")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -313,7 +330,7 @@ class PaidInvoiceTax(BaseDto):
     tax_code: str = Field(default=..., alias="taxCode", description="Código del impuesto.")
     tax_type_code: str = Field(default=..., alias="taxTypeCode", description="Tipo de factor.")
     tax_rate: Decimal = Field(default=..., alias="taxRate", description="Tasa del impuesto.")
-    tax_flag_code: Optional[Literal["T", "R"]] = Field(default=None, alias="taxFlagCode", description="Código que indica la naturaleza del impuesto. (T)raslado o (R)etención.")
+    tax_flag_code: Optional[str] = Field(default=None, alias="taxFlagCode", description="Código que indica la naturaleza del impuesto. (T)raslado o (R)etención.")
     
     model_config = ConfigDict(populate_by_name=True)
     
@@ -343,7 +360,7 @@ class InvoicePayment(BaseDto):
     payment_date: str = Field(default=..., alias="paymentDate", description="Fecha de pago.")
     payment_form_code: str = Field(default=..., alias="paymentFormCode", description="Código de la forma de pago.")
     
-    currency_code: Literal ["MXN", "USD", "EUR"] = Field(default="MXN", alias="currencyCode", description="Código de la moneda utilizada en el pago.")
+    currency_code: str = Field(default="MXN", alias="currencyCode", description="Código de la moneda utilizada en el pago: una clave del catálogo c_Moneda del SAT, en mayúsculas, distinta de XXX.")
     exchange_rate: Optional[Decimal] = Field(default=Decimal("1"), alias="exchangeRate", description="Tipo de cambio FIX conforme a la moneda registrada en la factura. Si la moneda es MXN, el tipo de cambio debe ser 1..")
     amount: Decimal = Field(default=..., description="Monto del pago.")
     source_bank_tin: str = Field(default=..., alias="sourceBankTin", description="RFC del banco origen. (Rfc del banco emisor del pago)")
@@ -363,7 +380,7 @@ class LocalTax(BaseDto):
     tax_name: Optional[str] = Field(default=None, alias="taxName", description="Nombre del impuesto local.")
     tax_rate: Optional[Decimal] = Field(default=None, alias="taxRate", description="Tasa del impuesto local.")
     tax_amount: Optional[Decimal] = Field(default=None, alias="taxAmount", description="Monto del impuesto local.")
-    tax_flag_code: Optional[Literal["T", "R"]] = Field(default=None, alias="taxFlagCode", description="Traslado o Retención.")
+    tax_flag_code: Optional[str] = Field(default=None, alias="taxFlagCode", description="Traslado o Retención.")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -588,7 +605,7 @@ class CancelInvoiceRequest(BaseDto):
     id: Optional[str] = Field(default=None, alias="id", description="ID de la factura a cancelar. Obligatorio cuando se cancela por referencias.")
     invoice_uuid: Optional[str] = Field(default=None, alias="invoiceUuid", description="UUID de la factura a cancelar. Obligatorio cuando se cancela por valores.")
     tin: Optional[str] = Field(default=None, alias="tin", description="RFC del emisor de la factura. Obligatorio cuando se cancela por valores.")
-    cancellation_reason_code: Literal["01", "02", "03", "04"] = Field(default=..., alias="cancellationReasonCode", description="Código del motivo de cancelación.")
+    cancellation_reason_code: str = Field(default=..., alias="cancellationReasonCode", description="Código del motivo de cancelación, catálogo c_MotivoCancelacion del SAT: 01, 02, 03 o 04. El API valida el valor.")
     replacement_uuid: Optional[str] = Field(default=None, alias="replacementUuid", description="UUID de la factura de reemplazo. Obligatorio si el motivo de cancelación es '01'.")
     tax_credentials: Optional[list[TaxCredential]] = Field(default=None, alias="taxCredentials", description="Sellos del emisor. Obligatorio cuando se cancela por valores.")
 
@@ -738,7 +755,8 @@ class DownloadRequest(BaseDto):
     download_request_status: Optional[CatalogDto] = Field(default=None, alias="downloadRequestStatus", description="Estado de la solicitud de descarga Fiscalapi.")
     
     last_attempt_date: Optional[datetime] = Field(default=None, alias="lastAttemptDate", description="Fecha del último intento para la solicitud asociada.")
-    next_attempt_date: Optional[datetime] = Field(default=None, alias="nextAttemptDate", description="Fecha del siguiente intento para la solicitud asociada.")
+    # Obsoleto: el API ya no devuelve nextAttemptDate (siempre era null). Se eliminará en una versión mayor.
+    next_attempt_date: Optional[datetime] = Field(default=None, alias="nextAttemptDate", description="Obsoleto: el API ya no lo devuelve; siempre era null porque Fiscalapi no programa un siguiente intento por solicitud. Se eliminará en una versión mayor; use last_attempt_date.")
     
     invoice_count: Optional[int] = Field(default=None, alias="invoiceCount", description="Número de CFDIs encontrados para la solicitud cuando la solicitud ha terminado.")
     package_ids: Optional[list[str]] = Field(default_factory=list, alias="packageIds", description="Lista de IDs de paquetes disponibles para descarga cuando la solicitud ha terminado.")
@@ -994,12 +1012,13 @@ class Xml(BaseDto):
 class CreditType(IntEnum):
     """Tipo de crédito de una transacción de timbres.
 
-    Los saldos nunca se mezclan: STAMP afecta ``Person.available_balance`` y VALIDATION afecta
-    ``Person.available_validation_balance``.
+    Los saldos nunca se mezclan: STAMP afecta ``Person.available_balance``, VALIDATION afecta
+    ``Person.available_validation_balance`` y TICKET afecta el saldo de tipo TICKET en ``Person.balances``.
     """
 
     STAMP = 1
     VALIDATION = 2
+    TICKET = 3
 
 
 class StampTransactionType(IntEnum):
@@ -1038,7 +1057,9 @@ class StampTransaction(BaseDto):
     transaction_status: Optional[int] = Field(default=None, alias="transactionStatus", description="Estado de la transacción.")
     reference_id: Optional[str] = Field(default=None, alias="referenceId", description="ID de referencia de la transacción.")
     comments: Optional[str] = Field(default=None, alias="comments", description="Comentarios de la transacción.")
-    credit_type: Optional[CreditType] = Field(default=None, alias="creditType", description="Tipo de crédito que mueve la transacción: timbres o créditos de validación.")
+    # left_to_right: un tipo conocido llega como miembro de CreditType y uno que este SDK todavía no conoce
+    # conserva su número (int) en lugar de lanzar ValidationError y perder la respuesta completa.
+    credit_type: Optional[Union[CreditType, int]] = Field(default=None, alias="creditType", union_mode="left_to_right", description="Tipo de crédito que mueve la transacción: timbres, créditos de validación o créditos de ticket. Un tipo que este SDK no conoce conserva su número (int).")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -1049,6 +1070,6 @@ class StampTransactionParams(BaseModel):
     to_person_id: str = Field(default=..., alias="toPersonId", description="ID de la persona destino.")
     amount: int = Field(default=..., alias="amount", description="Cantidad de timbres a transferir.")
     comments: Optional[str] = Field(default=None, alias="comments", description="Comentarios de la transferencia.")
-    credit_type: CreditType = Field(default=CreditType.STAMP, alias="creditType", description="Tipo de crédito a transferir: STAMP (timbres, por defecto) o VALIDATION (créditos de validación SAT).")
+    credit_type: CreditType = Field(default=CreditType.STAMP, alias="creditType", description="Tipo de crédito a transferir: STAMP (timbres, por defecto), VALIDATION (créditos de validación SAT) o TICKET (créditos de ticket).")
 
     model_config = ConfigDict(populate_by_name=True)