fiscalapi 4.0.433__tar.gz → 4.0.450__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.433
+Version: 4.0.450
 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.
@@ -568,6 +588,63 @@ if api_response.succeeded:
 
 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.
 
+### 12. Recibir webhooks
+
+FiscalAPI firma cada entrega con [Standard Webhooks](https://www.standardwebhooks.com) y el secreto `whsec_…` de su webhook. `webhooks.verify` comprueba la firma (en tiempo constante) y que `webhook-timestamp` no difiera más de 5 minutos del reloj del receptor, y devuelve el `WebhookEvent`. La firma es la única prueba de que la entrega viene de FiscalAPI.
+
+**Verifique el cuerpo crudo**: pase los bytes tal como llegaron (`request.get_data()` en Flask, `request.body` en Django, `await request.body()` en FastAPI), antes de deserializarlos. Un cuerpo deserializado y vuelto a serializar (por ejemplo, `json.dumps(request.json)`) cambia sus bytes y la firma deja de coincidir.
+
+```python
+import os
+import queue
+import threading
+
+from flask import Flask, request
+
+from fiscalapi import FiscalApiClient, FiscalApiSettings, WebhookEventTypes, WebhookVerificationException, webhooks
+
+app = Flask(__name__)
+client = FiscalApiClient(settings=FiscalApiSettings(api_url="...", api_key="...", tenant="..."))
+webhook_secret = os.environ["FISCALAPI_WEBHOOK_SECRET"]  # whsec_… del webhook, desde su configuración segura
+
+# La cola en memoria es ilustrativa: en producción use una cola durable (Celery, RQ, SQS…).
+events = queue.Queue()
+
+
+@app.post("/webhooks/fiscalapi")
+def receive_fiscalapi_webhook():
+    try:
+        event = webhooks.verify(request.headers, request.get_data(), webhook_secret)
+    except WebhookVerificationException:
+        return "", 400  # firma inválida, header faltante o timestamp fuera de tolerancia
+
+    # Responda 2xx rápido y procese después: FiscalAPI corta cada intento a los 15 s y lo reintenta.
+    events.put(event)
+    return "", 200
+
+
+def process_events():
+    while True:
+        event = events.get()
+        # La entrega es al menos una vez: event.id (el header webhook-id) se repite en cada reintento; descarte los ya
+        # procesados. El orden de llegada no está garantizado: el estado autoritativo se lee del recurso.
+        if event.type == WebhookEventTypes.INVOICE_CANCELED:
+            invoice = client.invoices.get_by_id(event.data.related_object.id)
+        elif event.type == WebhookEventTypes.DOWNLOAD_REQUEST_COMPLETED:
+            download_request = client.download_requests.get_by_id(event.data.related_object.id)
+        # Un tipo que no conoce se ignora: el catálogo puede crecer.
+
+
+threading.Thread(target=process_events, daemon=True).start()
+```
+
+- `WebhookEvent` es el mismo sobre para todo evento: `id`, `type` (texto; compárelo con las constantes de `WebhookEventTypes`), `created_at` (`datetime` en UTC), `person_id` (`None` si el recurso no tiene persona) y `data` con `related_object` (`id`, `type`, `url`), `status` y `previous_status`.
+- `related_object.url` es la ruta relativa del GET v4 del recurso (`/api/v4/invoices/{id}`); para leerlo, use el servicio de su tipo con `related_object.id`.
+- El botón "Enviar prueba" del webhook (`POST /api/v4/webhooks/{id}/test`) envía `WebhookEventTypes.WEBHOOK_TEST` (`webhook.test`), cuyo `related_object` es el webhook mismo (`type` `webhook`, `url` `/api/v4/webhooks/{id}`), sin persona ni estados; no se suscribe.
+- Durante una rotación del secreto, FiscalAPI firma con el nuevo y con el anterior por 24 h: pase ambos, `webhooks.verify(request.headers, body, [secreto_nuevo, secreto_anterior])`.
+- La tolerancia es configurable (`webhooks.verify(request.headers, body, secreto, timedelta(minutes=2))`); el valor por omisión es `webhooks.DEFAULT_TOLERANCE`.
+- Un secreto mal copiado (no es base64), una lista de secretos vacía o una tolerancia negativa lanzan `ValueError`, y un argumento `None` lanza `TypeError`, con la posición del secreto (nunca su valor): es un error de configuración, no de la entrega.
+
 ## 📋 Operaciones Principales
 
 - **Facturas (CFDI)**
@@ -576,17 +653,22 @@ 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.
+- **Webhooks**
+  Verificación de la firma Standard Webhooks de las entregas y lectura del evento (`webhooks.verify`, `WebhookEvent`).
 
 ## 📂 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.450}/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.
@@ -531,6 +551,63 @@ if api_response.succeeded:
 
 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.
 
+### 12. Recibir webhooks
+
+FiscalAPI firma cada entrega con [Standard Webhooks](https://www.standardwebhooks.com) y el secreto `whsec_…` de su webhook. `webhooks.verify` comprueba la firma (en tiempo constante) y que `webhook-timestamp` no difiera más de 5 minutos del reloj del receptor, y devuelve el `WebhookEvent`. La firma es la única prueba de que la entrega viene de FiscalAPI.
+
+**Verifique el cuerpo crudo**: pase los bytes tal como llegaron (`request.get_data()` en Flask, `request.body` en Django, `await request.body()` en FastAPI), antes de deserializarlos. Un cuerpo deserializado y vuelto a serializar (por ejemplo, `json.dumps(request.json)`) cambia sus bytes y la firma deja de coincidir.
+
+```python
+import os
+import queue
+import threading
+
+from flask import Flask, request
+
+from fiscalapi import FiscalApiClient, FiscalApiSettings, WebhookEventTypes, WebhookVerificationException, webhooks
+
+app = Flask(__name__)
+client = FiscalApiClient(settings=FiscalApiSettings(api_url="...", api_key="...", tenant="..."))
+webhook_secret = os.environ["FISCALAPI_WEBHOOK_SECRET"]  # whsec_… del webhook, desde su configuración segura
+
+# La cola en memoria es ilustrativa: en producción use una cola durable (Celery, RQ, SQS…).
+events = queue.Queue()
+
+
+@app.post("/webhooks/fiscalapi")
+def receive_fiscalapi_webhook():
+    try:
+        event = webhooks.verify(request.headers, request.get_data(), webhook_secret)
+    except WebhookVerificationException:
+        return "", 400  # firma inválida, header faltante o timestamp fuera de tolerancia
+
+    # Responda 2xx rápido y procese después: FiscalAPI corta cada intento a los 15 s y lo reintenta.
+    events.put(event)
+    return "", 200
+
+
+def process_events():
+    while True:
+        event = events.get()
+        # La entrega es al menos una vez: event.id (el header webhook-id) se repite en cada reintento; descarte los ya
+        # procesados. El orden de llegada no está garantizado: el estado autoritativo se lee del recurso.
+        if event.type == WebhookEventTypes.INVOICE_CANCELED:
+            invoice = client.invoices.get_by_id(event.data.related_object.id)
+        elif event.type == WebhookEventTypes.DOWNLOAD_REQUEST_COMPLETED:
+            download_request = client.download_requests.get_by_id(event.data.related_object.id)
+        # Un tipo que no conoce se ignora: el catálogo puede crecer.
+
+
+threading.Thread(target=process_events, daemon=True).start()
+```
+
+- `WebhookEvent` es el mismo sobre para todo evento: `id`, `type` (texto; compárelo con las constantes de `WebhookEventTypes`), `created_at` (`datetime` en UTC), `person_id` (`None` si el recurso no tiene persona) y `data` con `related_object` (`id`, `type`, `url`), `status` y `previous_status`.
+- `related_object.url` es la ruta relativa del GET v4 del recurso (`/api/v4/invoices/{id}`); para leerlo, use el servicio de su tipo con `related_object.id`.
+- El botón "Enviar prueba" del webhook (`POST /api/v4/webhooks/{id}/test`) envía `WebhookEventTypes.WEBHOOK_TEST` (`webhook.test`), cuyo `related_object` es el webhook mismo (`type` `webhook`, `url` `/api/v4/webhooks/{id}`), sin persona ni estados; no se suscribe.
+- Durante una rotación del secreto, FiscalAPI firma con el nuevo y con el anterior por 24 h: pase ambos, `webhooks.verify(request.headers, body, [secreto_nuevo, secreto_anterior])`.
+- La tolerancia es configurable (`webhooks.verify(request.headers, body, secreto, timedelta(minutes=2))`); el valor por omisión es `webhooks.DEFAULT_TOLERANCE`.
+- Un secreto mal copiado (no es base64), una lista de secretos vacía o una tolerancia negativa lanzan `ValueError`, y un argumento `None` lanza `TypeError`, con la posición del secreto (nunca su valor): es un error de configuración, no de la entrega.
+
 ## 📋 Operaciones Principales
 
 - **Facturas (CFDI)**
@@ -539,17 +616,22 @@ 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.
+- **Webhooks**
+  Verificación de la firma Standard Webhooks de las entregas y lectura del evento (`webhooks.verify`, `WebhookEvent`).
 
 ## 📂 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.450}/fiscalapi/__init__.py

@@ -75,6 +75,28 @@ 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 webhooks
+from .models.webhook_models import (
+    WebhookEventTypes,
+    WebhookRelatedObject,
+    WebhookEventData,
+    WebhookEvent,
+)
 
 # Modelos de dominio
 from .models.fiscalapi_models import (
@@ -175,10 +197,15 @@ 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
 
+# Verificación de webhooks (fiscalapi.webhooks.verify)
+from . import webhooks
+from .webhooks import WebhookVerificationException
+
 __all__ = [
     # Modelos base
     "ApiResponse",
@@ -311,6 +338,23 @@ __all__ = [
     "SatValidationTypeStatus",
     "SatValidationStatus",
     "SatValidationResult",
+    # Ticket models (Auto CFDI)
+    "TicketStatus",
+    "TicketEventType",
+    "TicketActorType",
+    "TicketIssuer",
+    "TicketItemTax",
+    "TicketItem",
+    "TicketEvent",
+    "Ticket",
+    "TicketIngestionResult",
+    "TicketCodeResult",
+    "TicketListFilters",
+    # Webhook models
+    "WebhookEventTypes",
+    "WebhookRelatedObject",
+    "WebhookEventData",
+    "WebhookEvent",
     # Servicios
     "BaseService",
     "ApiKeyService",
@@ -327,6 +371,10 @@ __all__ = [
     "SatValidationService",
     "StampService",
     "ManifestService",
+    "TicketService",
     # Cliente principal
     "FiscalApiClient",
+    # Webhooks
+    "webhooks",
+    "WebhookVerificationException",
 ]

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

@@ -61,6 +61,27 @@ 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 .webhook_models import (
+    # Webhook models
+    WebhookEventTypes,
+    WebhookRelatedObject,
+    WebhookEventData,
+    WebhookEvent,
+)
 from .fiscalapi_models import (
     # Product models
     ProductTax,
@@ -275,4 +296,21 @@ __all__ = [
     "SatValidationTypeStatus",
     "SatValidationStatus",
     "SatValidationResult",
+    # Ticket models (Auto CFDI)
+    "TicketStatus",
+    "TicketEventType",
+    "TicketActorType",
+    "TicketIssuer",
+    "TicketItemTax",
+    "TicketItem",
+    "TicketEvent",
+    "Ticket",
+    "TicketIngestionResult",
+    "TicketCodeResult",
+    "TicketListFilters",
+    # Webhook models
+    "WebhookEventTypes",
+    "WebhookRelatedObject",
+    "WebhookEventData",
+    "WebhookEvent",
 ]

{fiscalapi-4.0.433 → fiscalapi-4.0.450}/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.450}/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.450/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