fiscalapi 4.0.433__tar.gz → 4.0.439__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.433
+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
@@ -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.
@@ -576,17 +596,20 @@ Tras una firma exitosa, todas las personas del tenant con el RFC del certificado
   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.433 → 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
@@ -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.
@@ -539,17 +559,20 @@ Tras una firma exitosa, todas las personas del tenant con el RFC del certificado
   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.433 → 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 (
@@ -175,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
@@ -311,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",
@@ -327,6 +354,7 @@ __all__ = [
     "SatValidationService",
     "StampService",
     "ManifestService",
+    "TicketService",
     # Cliente principal
     "FiscalApiClient",
 ]

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

@@ -61,6 +61,20 @@ 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,
@@ -275,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.433 → fiscalapi-4.0.439}/fiscalapi/models/common_models.py

@@ -11,6 +11,7 @@ class ApiResponse(BaseModel, Generic[T]):
     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)
 

{fiscalapi-4.0.433 → 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 Optional
+from typing import Optional, Union
 from datetime import datetime
 
 # products models
@@ -54,7 +54,7 @@ class CreditBalance(BaseModel):
     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.")
+    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)
@@ -304,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)
 
@@ -1011,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):
@@ -1055,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)
 
@@ -1066,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)

fiscalapi-4.0.439/fiscalapi/models/ticket_models.py

@@ -0,0 +1,183 @@
+"""Modelos de tickets de Auto CFDI (endpoints /api/v4/tickets).
+
+Un ticket es una venta pagada del punto de venta que el receptor puede autofacturar o que entra a una factura global.
+Ingerirlo cobra 1 crédito de ticket. Los conceptos e impuestos llevan los nombres de los conceptos de las facturas.
+"""
+
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Optional, Union
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TicketStatus(str, Enum):
+    """Estados de un ticket, como llegan en ``Ticket.status`` (texto camelCase)."""
+
+    PENDING = "pending"
+    INVOICING = "invoicing"
+    INVOICED = "invoiced"
+    GLOBALIZING = "globalizing"
+    GLOBALIZED = "globalized"
+    CANCELLED = "cancelled"
+
+
+class TicketEventType(str, Enum):
+    """Tipos de hecho de la historia de un ticket, como llegan en ``TicketEvent.type``."""
+
+    INGESTED = "ingested"
+    INVOICING_STARTED = "invoicingStarted"
+    INVOICED = "invoiced"
+    INVOICE_REJECTED = "invoiceRejected"
+    OUTCOME_UNKNOWN = "outcomeUnknown"
+    LEASE_EXPIRED = "leaseExpired"
+    GLOBALIZING = "globalizing"
+    GLOBALIZED = "globalized"
+    RELEASED_FROM_GLOBAL = "releasedFromGlobal"
+    CANCELLED = "cancelled"
+    RECOVERY_FAILED = "recoveryFailed"
+    RECOVERED = "recovered"
+    RESENT = "resent"
+    RETURNED_TO_PENDING = "returnedToPending"
+
+
+class TicketActorType(str, Enum):
+    """Quién actuó en un hecho del ticket, como llega en ``TicketEvent.actor_type``."""
+
+    TENANT = "tenant"
+    PORTAL = "portal"
+    SYSTEM = "system"
+
+
+class TicketIssuer(BaseModel):
+    """Emisor de un ticket: una persona del tenant, por su id."""
+
+    id: Optional[str] = Field(default=None, alias="id", description="Id de la persona emisora.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TicketItemTax(BaseModel):
+    """Impuesto de un concepto del ticket."""
+
+    tax_code: Optional[str] = Field(default=None, alias="taxCode", description="Impuesto: 001 (ISR), 002 (IVA) o 003 (IEPS).")
+    tax_type_code: Optional[str] = Field(default=None, alias="taxTypeCode", description="Tipo de factor: Tasa, Cuota o Exento.")
+    tax_rate: Optional[Decimal] = Field(default=None, alias="taxRate", description="Tasa o cuota; se envía tal cual, sin redondear.")
+    tax_flag_code: Optional[str] = Field(default=None, alias="taxFlagCode", description="T (traslado) o R (retención).")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TicketItem(BaseModel):
+    """Concepto de un ticket, con los nombres de los conceptos de las facturas (sin terceros, aduanas, predial ni partes)."""
+
+    item_code: Optional[str] = Field(default=None, alias="itemCode", description="Clave de producto o servicio (c_ClaveProdServ).")
+    item_sku: Optional[str] = Field(default=None, alias="itemSku", description="Número de identificación (SKU) del producto en el punto de venta.")
+    quantity: Optional[Decimal] = Field(default=None, alias="quantity", description="Cantidad.")
+    unit_of_measurement_code: Optional[str] = Field(default=None, alias="unitOfMeasurementCode", description="Clave de unidad (c_ClaveUnidad).")
+    description: Optional[str] = Field(default=None, alias="description", description="Descripción.")
+    unit_price: Optional[Decimal] = Field(default=None, alias="unitPrice", description="Valor unitario.")
+    discount: Optional[Decimal] = Field(default=None, alias="discount", description="Descuento del concepto. Opcional.")
+    tax_object_code: Optional[str] = Field(default=None, alias="taxObjectCode", description="Objeto de impuesto (c_ObjetoImp): 02 exige impuestos; 01, 03, 04 y 05 no admiten.")
+    item_taxes: Optional[list[TicketItemTax]] = Field(default=None, alias="itemTaxes", description="Impuestos del concepto.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TicketEvent(BaseModel):
+    """Un hecho de la historia del ticket (solo lectura; llega con ``details=True``).
+
+    ``type`` y ``actor_type`` llegan como miembro del enum si el SDK los conoce y como texto si no.
+    """
+
+    type: Optional[Union[TicketEventType, str]] = Field(default=None, alias="type", union_mode="left_to_right", description="Tipo de hecho; uno que el SDK no conoce llega como texto.")
+    occurred_at: Optional[datetime] = Field(default=None, alias="occurredAt", description="Momento del hecho.")
+    actor_type: Optional[Union[TicketActorType, str]] = Field(default=None, alias="actorType", union_mode="left_to_right", description="Quién actuó; uno que el SDK no conoce llega como texto.")
+    invoice_id: Optional[str] = Field(default=None, alias="invoiceId", description="Factura del hecho; None si no aplica.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class Ticket(BaseModel):
+    """Ticket de Auto CFDI: se envía en ``tickets.create`` y llega en ``tickets.get_list`` y ``tickets.get_by_id``.
+
+    Los miembros de solo lectura (id, person_id, importes calculados, status, vigencia, facturas, created_at y events)
+    los asigna el API: al crear quedan en None y no se envían.
+    """
+
+    id: Optional[str] = Field(default=None, alias="id", description="Id del ticket. Solo lectura.")
+    issuer: Optional[TicketIssuer] = Field(default=None, alias="issuer", description="Emisor por referencia. Se envía al crear; no llega en las consultas.")
+    person_id: Optional[str] = Field(default=None, alias="personId", description="Persona emisora del tenant. Solo lectura.")
+    folio: Optional[str] = Field(default=None, alias="folio", description="Folio del punto de venta (no es el folio del CFDI).")
+    series: Optional[str] = Field(default=None, alias="series", description="Serie del punto de venta. Opcional.")
+    payment_date: Optional[datetime] = Field(default=None, alias="paymentDate", description="Momento del pago en hora civil de México; un datetime sin zona viaja como yyyy-MM-ddTHH:mm:ss.")
+    payment_form_code: Optional[str] = Field(default=None, alias="paymentFormCode", description="Forma de pago (c_FormaPago), por ejemplo 01 (efectivo).")
+    currency_code: Optional[str] = Field(default=None, alias="currencyCode", description="Moneda (c_Moneda). Opcional: sin ella, el API usa MXN.")
+    exchange_rate: Optional[Decimal] = Field(default=None, alias="exchangeRate", description="Tipo de cambio. Opcional.")
+    expedition_zip_code: Optional[str] = Field(default=None, alias="expeditionZipCode", description="Código postal de expedición. Opcional: sin él, el API usa el del emisor.")
+    subtotal: Optional[Decimal] = Field(default=None, alias="subtotal", description="Subtotal calculado por el API. Solo lectura.")
+    total_transferred_taxes: Optional[Decimal] = Field(default=None, alias="totalTransferredTaxes", description="Total de impuestos trasladados calculado por el API. Solo lectura.")
+    total_withheld_taxes: Optional[Decimal] = Field(default=None, alias="totalWithheldTaxes", description="Total de impuestos retenidos calculado por el API. Solo lectura.")
+    total: Optional[Decimal] = Field(default=None, alias="total", description="Total que cobró el punto de venta: debe cuadrar al centavo con el calculado (si no, 422).")
+    status: Optional[Union[TicketStatus, str]] = Field(default=None, alias="status", union_mode="left_to_right", description="Estado del ticket. Solo lectura; uno que el SDK no conoce llega como texto.")
+    self_invoice_eligible: Optional[bool] = Field(default=None, alias="selfInvoiceEligible", description="Si hoy el receptor puede autofacturarlo. Solo lectura.")
+    eligible_until: Optional[datetime] = Field(default=None, alias="eligibleUntil", description="Último momento de la ventana de autofactura; None si no cierra. Solo lectura.")
+    invoice_id: Optional[str] = Field(default=None, alias="invoiceId", description="Factura individual (estado invoiced). Solo lectura.")
+    global_invoice_id: Optional[str] = Field(default=None, alias="globalInvoiceId", description="Factura global (estado globalized). Solo lectura.")
+    created_at: Optional[datetime] = Field(default=None, alias="createdAt", description="Fecha de alta. Solo lectura.")
+    items: Optional[list[TicketItem]] = Field(default=None, alias="items", description="Conceptos. Obligatorios al crear; en las consultas solo llegan con details=True.")
+    events: Optional[list[TicketEvent]] = Field(default=None, alias="events", description="Historia del ticket en orden. Solo lectura; solo llega con details=True.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TicketIngestionResult(BaseModel):
+    """Respuesta de ``tickets.create``: la misma forma en el 201 de un ticket nuevo y en el 200 de una repetición con la
+    misma Idempotency-Key y el mismo cuerpo."""
+
+    id: Optional[str] = Field(default=None, alias="id", description="Id del ticket.")
+    ticket_code: Optional[str] = Field(default=None, alias="ticketCode", description="Código sin guiones, como lo lleva el QR; se imprime en grupos (XXXX-XXXX-XXXX).")
+    qr_url: Optional[str] = Field(default=None, alias="qrUrl", description="URL del portal de autofactura que abre el ticket.")
+    status: Optional[Union[TicketStatus, str]] = Field(default=None, alias="status", union_mode="left_to_right", description="Estado actual (al ingerir, pending); uno que el SDK no conoce llega como texto.")
+    self_invoice_eligible: Optional[bool] = Field(default=None, alias="selfInvoiceEligible", description="Si hoy el receptor puede autofacturarlo.")
+    eligible_until: Optional[datetime] = Field(default=None, alias="eligibleUntil", description="Último momento de la ventana de autofactura; None si no cierra.")
+    subtotal: Optional[Decimal] = Field(default=None, alias="subtotal", description="Subtotal calculado.")
+    total_transferred_taxes: Optional[Decimal] = Field(default=None, alias="totalTransferredTaxes", description="Total de impuestos trasladados calculado.")
+    total_withheld_taxes: Optional[Decimal] = Field(default=None, alias="totalWithheldTaxes", description="Total de impuestos retenidos calculado.")
+    total: Optional[Decimal] = Field(default=None, alias="total", description="Total calculado (cuadra con el enviado).")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TicketCodeResult(BaseModel):
+    """Código de un ticket y la URL de su QR, para reimprimirlo (GET /api/v4/tickets/{id}/code)."""
+
+    ticket_code: Optional[str] = Field(default=None, alias="ticketCode", description="Código sin guiones, el mismo de la ingesta.")
+    qr_url: Optional[str] = Field(default=None, alias="qrUrl", description="URL del portal de autofactura que abre el ticket.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TicketListFilters(BaseModel):
+    """Filtros de ``tickets.get_list`` (GET /api/v4/tickets). Cada filtro aplica solo si se asigna; los que quedan en
+    None no se envían. ``from_`` lleva el guion bajo porque ``from`` es palabra reservada de Python."""
+
+    status: Optional[list[Union[TicketStatus, str]]] = Field(default=None, alias="status", description="Uno o más estados; se envían repitiendo la llave status.")
+    person_id: Optional[str] = Field(default=None, alias="personId", description="Persona emisora.")
+    details: Optional[bool] = Field(default=None, alias="details", description="Con true, cada ticket trae sus conceptos con impuestos (sin la historia).")
+    global_invoice_id: Optional[str] = Field(default=None, alias="globalInvoiceId", description="Factura global que ampara los tickets.")
+    from_: Optional[date] = Field(default=None, alias="from", description="Primer día del pago (incluido), en fecha civil de México.")
+    to: Optional[date] = Field(default=None, alias="to", description="Último día del pago (incluido), en fecha civil de México.")
+    page_number: Optional[int] = Field(default=None, alias="pageNumber", description="Página, desde 1. Sin ella, el API devuelve la primera.")
+    page_size: Optional[int] = Field(default=None, alias="pageSize", description="Tamaño de página (1 a 50). Sin él, el API usa 10.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def to_query_params(self) -> list[tuple[str, str]]:
+        """Los filtros asignados como pares de la query string: ``status`` se repite por cada estado, y ``details``
+        solo viaja como ``true`` (``False`` no se envía)."""
+        params: list[tuple[str, str]] = []
+        for key, value in self.model_dump(mode="json", by_alias=True, exclude_none=True).items():
+            values = value if isinstance(value, list) else [value]
+            params.extend((key, "true" if item is True else str(item)) for item in values if item is not False)
+        return params

{fiscalapi-4.0.433 → fiscalapi-4.0.439}/fiscalapi/services/__init__.py

@@ -16,6 +16,7 @@ from .product_service import ProductService
 from .sat_validation_service import SatValidationService
 from .stamp_service import StampService
 from .tax_file_service import TaxFileService
+from .ticket_service import TicketService
 
 __all__ = [
     "BaseService",
@@ -34,4 +35,5 @@ __all__ = [
     "SatValidationService",
     "StampService",
     "TaxFileService",
+    "TicketService",
 ]

{fiscalapi-4.0.433 → fiscalapi-4.0.439}/fiscalapi/services/base_service.py

@@ -114,6 +114,7 @@ class BaseService:
                         message=generic_error.message,
                         details=details_str,
                         trace_identifier=generic_error.trace_identifier,
+                        error_data=response_data.get("data"),
                         data=None
                     )
             except Exception:
@@ -125,6 +126,7 @@ class BaseService:
             message=generic_error.message or f"HTTP Error {status_code}",
             details=generic_error.details or raw_content,
             trace_identifier=generic_error.trace_identifier,
+            error_data=response_data.get("data"),
             data=None
         )
 

{fiscalapi-4.0.433 → fiscalapi-4.0.439}/fiscalapi/services/fiscalapi_client.py

@@ -11,6 +11,7 @@ from fiscalapi.services.download_request_service import DownloadRequestService
 from fiscalapi.services.sat_validation_service import SatValidationService
 from fiscalapi.services.stamp_service import StampService
 from fiscalapi.services.manifest_service import ManifestService
+from fiscalapi.services.ticket_service import TicketService
 
 
 
@@ -29,4 +30,5 @@ class FiscalApiClient:
         self.stamps = StampService(settings)
         self.sat_validations = SatValidationService(settings)
         self.manifests = ManifestService(settings)
+        self.tickets = TicketService(settings)
         self.settings = settings

fiscalapi-4.0.439/fiscalapi/services/ticket_service.py

@@ -0,0 +1,102 @@
+"""Servicio de tickets de Auto CFDI: ingesta, consulta con filtros, código para reimprimir y cancelación."""
+
+from typing import Optional
+from urllib.parse import urlencode
+
+from fiscalapi.models.common_models import ApiResponse, PagedList
+from fiscalapi.models.ticket_models import Ticket, TicketCodeResult, TicketIngestionResult, TicketListFilters
+from fiscalapi.services.base_service import BaseService
+
+IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+
+
+class TicketService(BaseService):
+    """Service for Auto CFDI tickets (endpoints /api/v4/tickets)."""
+
+    def create(self, ticket: Ticket, idempotency_key: Optional[str] = None) -> ApiResponse[TicketIngestionResult]:
+        """Ingest a ticket and charge 1 ticket credit. POST /api/v4/tickets
+
+        With ``idempotency_key`` (up to 64 characters) the ``Idempotency-Key`` header is sent: repeating the key with
+        the same body answers 200 with the original ticket without charging again; with another body, 422. Without it
+        the header is not sent. An active folio and series of the issuer answers 409.
+
+        Args:
+            ticket: Ticket to ingest.
+            idempotency_key: Value of the Idempotency-Key header, or None to not send it.
+
+        Returns:
+            ApiResponse containing the TicketIngestionResult (code and QR URL to print).
+
+        Raises:
+            ValueError: If ticket is None.
+        """
+        if ticket is None:
+            raise ValueError("Se requiere el ticket.")
+
+        headers = {} if idempotency_key is None else {IDEMPOTENCY_KEY_HEADER: idempotency_key}
+        return self.send_request("POST", "tickets", TicketIngestionResult, payload=ticket, headers=headers)
+
+    def get_list(self, filters: Optional[TicketListFilters] = None) -> ApiResponse[PagedList[Ticket]]:
+        """List the tenant's tickets with the given filters (none: all of them, first page). GET /api/v4/tickets
+
+        Args:
+            filters: Status (one or more; the ``status`` key repeats), person, payment date range and page.
+
+        Returns:
+            ApiResponse containing a PagedList of Ticket, ordered by payment date.
+        """
+        params = filters.to_query_params() if filters is not None else []
+        endpoint = f"tickets?{urlencode(params)}" if params else "tickets"
+        return self.send_request("GET", endpoint, PagedList[Ticket])
+
+    def get_by_id(self, ticket_id: str, details: bool = False) -> ApiResponse[Ticket]:
+        """Get a ticket; with ``details`` it also brings its items and history. GET /api/v4/tickets/{id}
+
+        Args:
+            ticket_id: Ticket id.
+            details: Include items and events.
+
+        Returns:
+            ApiResponse containing the Ticket.
+
+        Raises:
+            ValueError: If ticket_id is empty.
+        """
+        self._ensure_ticket_id(ticket_id)
+        return self.send_request("GET", f"tickets/{ticket_id}", Ticket, details=details)
+
+    def get_code(self, ticket_id: str) -> ApiResponse[TicketCodeResult]:
+        """Get the ticket code and its QR URL, to reprint it. GET /api/v4/tickets/{id}/code
+
+        Args:
+            ticket_id: Ticket id.
+
+        Returns:
+            ApiResponse containing the TicketCodeResult.
+
+        Raises:
+            ValueError: If ticket_id is empty.
+        """
+        self._ensure_ticket_id(ticket_id)
+        return self.send_request("GET", f"tickets/{ticket_id}/code", TicketCodeResult)
+
+    def cancel(self, ticket_id: str) -> ApiResponse[bool]:
+        """Cancel a pending ticket (409 in any other status); the ticket credit is not refunded. DELETE /api/v4/tickets/{id}
+
+        Args:
+            ticket_id: Ticket id.
+
+        Returns:
+            ApiResponse containing True if the ticket was cancelled.
+
+        Raises:
+            ValueError: If ticket_id is empty.
+        """
+        self._ensure_ticket_id(ticket_id)
+        return self.send_request("DELETE", f"tickets/{ticket_id}", bool)
+
+    @staticmethod
+    def _ensure_ticket_id(ticket_id: str) -> None:
+        """Guard against an empty id, which would otherwise hit the list (GET) or the collection (DELETE)."""
+        if not ticket_id or not ticket_id.strip():
+            raise ValueError("Se requiere el id del ticket.")