fiscalapi 4.0.439__tar.gz → 4.0.462__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.439
+Version: 4.0.462
 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
@@ -284,6 +284,12 @@ invoice = Invoice(
 api_response = client.invoices.create(invoice)
 ```
 
+Para reintentar la creación sin duplicar la factura, pasa una `idempotency_key` propia (hasta 64 caracteres). El SDK la envía como header `Idempotency-Key`; repetir la misma llave de idempotencia con la misma factura en 24 h devuelve la respuesta original:
+
+```python
+api_response = client.invoices.create(invoice, idempotency_key="550e8400-e29b-41d4-a716-446655440000")
+```
+
 ### 6. Crear la Misma Factura de Ingreso (Por Valores)
 
 ```python
@@ -588,6 +594,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)**
@@ -604,6 +667,8 @@ Tras una firma exitosa, todas las personas del tenant con el RFC del certificado
   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
 

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

@@ -247,6 +247,12 @@ invoice = Invoice(
 api_response = client.invoices.create(invoice)
 ```
 
+Para reintentar la creación sin duplicar la factura, pasa una `idempotency_key` propia (hasta 64 caracteres). El SDK la envía como header `Idempotency-Key`; repetir la misma llave de idempotencia con la misma factura en 24 h devuelve la respuesta original:
+
+```python
+api_response = client.invoices.create(invoice, idempotency_key="550e8400-e29b-41d4-a716-446655440000")
+```
+
 ### 6. Crear la Misma Factura de Ingreso (Por Valores)
 
 ```python
@@ -551,6 +557,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)**
@@ -567,6 +630,8 @@ Tras una firma exitosa, todas las personas del tenant con el RFC del certificado
   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
 

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

@@ -90,6 +90,14 @@ from .models.ticket_models import (
     TicketListFilters,
 )
 
+# Modelos de webhooks
+from .models.webhook_models import (
+    WebhookEventTypes,
+    WebhookRelatedObject,
+    WebhookEventData,
+    WebhookEvent,
+)
+
 # Modelos de dominio
 from .models.fiscalapi_models import (
     # Product models
@@ -194,6 +202,10 @@ 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",
@@ -338,6 +350,11 @@ __all__ = [
     "TicketIngestionResult",
     "TicketCodeResult",
     "TicketListFilters",
+    # Webhook models
+    "WebhookEventTypes",
+    "WebhookRelatedObject",
+    "WebhookEventData",
+    "WebhookEvent",
     # Servicios
     "BaseService",
     "ApiKeyService",
@@ -357,4 +374,7 @@ __all__ = [
     "TicketService",
     # Cliente principal
     "FiscalApiClient",
+    # Webhooks
+    "webhooks",
+    "WebhookVerificationException",
 ]

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

@@ -75,6 +75,13 @@ from .ticket_models import (
     TicketCodeResult,
     TicketListFilters,
 )
+from .webhook_models import (
+    # Webhook models
+    WebhookEventTypes,
+    WebhookRelatedObject,
+    WebhookEventData,
+    WebhookEvent,
+)
 from .fiscalapi_models import (
     # Product models
     ProductTax,
@@ -301,4 +308,9 @@ __all__ = [
     "TicketIngestionResult",
     "TicketCodeResult",
     "TicketListFilters",
+    # Webhook models
+    "WebhookEventTypes",
+    "WebhookRelatedObject",
+    "WebhookEventData",
+    "WebhookEvent",
 ]

{fiscalapi-4.0.439 → fiscalapi-4.0.462}/fiscalapi/models/ticket_models.py

@@ -132,8 +132,8 @@ class Ticket(BaseModel):
 
 
 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."""
+    """Respuesta de ``tickets.create``: un ticket nuevo (201) y la repetición con la misma llave de idempotencia y el mismo
+    cuerpo devuelven la misma respuesta original."""
 
     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).")

fiscalapi-4.0.462/fiscalapi/models/webhook_models.py

@@ -0,0 +1,101 @@
+"""Modelos de los eventos de webhook de FiscalAPI: el mismo sobre para todo tipo de evento.
+
+Un ``WebhookEvent`` lo devuelve ``fiscalapi.webhooks.verify`` después de validar la firma de la entrega. Es una
+notificación ligera: para el estado autoritativo del recurso (el orden de llegada no está garantizado), consulte
+``data.related_object`` con el servicio de su tipo (por ejemplo ``client.invoices.get_by_id``).
+"""
+
+import re
+from datetime import datetime, timezone
+from typing import Final, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# createdAt como lo envía el back: fecha, hora con segundos (fracción opcional) y zona (Z o desfase), en dígitos ASCII.
+_ISO_8601_WITH_TIME_AND_ZONE = re.compile(
+    r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})"
+)
+
+
+class WebhookEventTypes:
+    """Tipos de evento de webhook, como llegan en ``WebhookEvent.type``.
+
+    Los de un cambio de estado nombran el estado al que llegó el recurso. Son una ayuda para comparar
+    (``event.type == WebhookEventTypes.INVOICE_CANCELED``): el catálogo puede crecer y un tipo desconocido se ignora.
+    """
+
+    INVOICE_CANCELLATION_REQUESTED: Final = "invoice.cancellation_requested"
+    """La factura pasó de vigente a cancelación en proceso (``V`` → ``C``)."""
+
+    INVOICE_CANCELED: Final = "invoice.canceled"
+    """La cancelación en proceso terminó y la factura quedó cancelada (``C`` → ``X``)."""
+
+    INVOICE_CANCELLATION_REJECTED: Final = "invoice.cancellation_rejected"
+    """La cancelación en proceso se rechazó y la factura volvió a vigente (``C`` → ``V``)."""
+
+    DOWNLOAD_REQUEST_COMPLETED: Final = "download_request.completed"
+    """La solicitud de descarga masiva terminó con éxito (→ ``3``)."""
+
+    DOWNLOAD_REQUEST_ABANDONED: Final = "download_request.abandoned"
+    """La solicitud de descarga masiva se abandonó (→ ``-1``). No implica un error: el motivo está en la solicitud
+    (``client.download_requests.get_by_id``)."""
+
+    DOWNLOAD_RULE_SUSPENDED: Final = "download_rule.suspended"
+    """La regla de descarga masiva quedó suspendida (``2`` → ``4``)."""
+
+    WEBHOOK_TEST: Final = "webhook.test"
+    """Prueba de un webhook: no se suscribe; llega solo al pulsar "Enviar prueba"
+    (``POST /api/v4/webhooks/{id}/test``), y solo a ese webhook. Su ``related_object`` es el webhook mismo
+    (``type`` ``webhook``, ``url`` ``/api/v4/webhooks/{id}``), sin persona ni estados."""
+
+
+class WebhookRelatedObject(BaseModel):
+    """El recurso al que se refiere un ``WebhookEvent``."""
+
+    id: Optional[str] = Field(default=None, alias="id", description="Id del recurso: el que reciben los get_by_id de los servicios del SDK.")
+    type: Optional[str] = Field(default=None, alias="type", description="Tipo de recurso: invoice, download_request, download_rule o webhook (el de WebhookEventTypes.WEBHOOK_TEST); el conjunto puede crecer.")
+    url: Optional[str] = Field(default=None, alias="url", description="Ruta relativa del GET v4 del recurso (por ejemplo /api/v4/invoices/{id}), sin host: el mismo evento es idéntico en pruebas y en producción. Para leer el recurso use su servicio con id.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class WebhookEventData(BaseModel):
+    """Datos de un ``WebhookEvent``."""
+
+    related_object: Optional[WebhookRelatedObject] = Field(default=None, alias="relatedObject", description="El recurso que cambió de estado.")
+    status: Optional[str] = Field(default=None, alias="status", description="Estado al que llegó el recurso, con los códigos públicos de la API v4 (factura V, C, X; solicitud de descarga 1, 2, 3, -1; regla de descarga 1..4, -1); None si el tipo de evento no lo lleva.")
+    previous_status: Optional[str] = Field(default=None, alias="previousStatus", description="Estado del que salió el recurso, con los mismos códigos que status; None si no aplica.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class WebhookEvent(BaseModel):
+    """Un evento de webhook de FiscalAPI: el mismo sobre para todo tipo de evento, sin clases por tipo.
+
+    Lo devuelve ``fiscalapi.webhooks.verify``. Los campos que esta versión del SDK no conoce se ignoran sin error.
+    """
+
+    id: Optional[str] = Field(default=None, alias="id", description="Id del evento; es también el header webhook-id y no cambia entre reintentos: úselo para descartar entregas repetidas.")
+    type: Optional[str] = Field(default=None, alias="type", description="Tipo de evento (ver WebhookEventTypes). Es texto y no un enum: un tipo que esta versión del SDK no conoce llega tal cual, sin error, y se ignora.")
+    created_at: Optional[datetime] = Field(default=None, alias="createdAt", description="Momento del cambio de estado, en UTC (tzinfo timezone.utc), al segundo. Llega como ISO 8601 con fecha, hora y zona; otro formato rechaza la entrega.")
+    person_id: Optional[str] = Field(default=None, alias="personId", description="Persona del tenant dueña del recurso; None si el recurso no tiene una (factura emitida por valores).")
+    data: Optional[WebhookEventData] = Field(default=None, alias="data", description="El recurso que cambió y sus estados.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator("created_at", mode="before")
+    @classmethod
+    def _iso_8601_with_time_and_zone(cls, value: object) -> object:
+        # Estricto, como el back lo envía: un epoch, una fecha sin hora o una hora sin zona no son un createdAt. En
+        # código, un datetime con zona también se acepta.
+        if value is None or (isinstance(value, datetime) and value.tzinfo is not None):
+            return value
+        if isinstance(value, str) and _ISO_8601_WITH_TIME_AND_ZONE.fullmatch(value):
+            return value
+        raise ValueError("createdAt debe ser ISO 8601 con fecha, hora y zona, por ejemplo 2026-10-12T18:47:53Z.")
+
+    @field_validator("created_at")
+    @classmethod
+    def _in_utc(cls, value: Optional[datetime]) -> Optional[datetime]:
+        # El back envía UTC con Z; un valor con otro desfase se convierte.
+        return None if value is None else value.astimezone(timezone.utc)

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

@@ -8,6 +8,9 @@ from fiscalapi.models.common_models import ApiResponse, FiscalApiSettings, Valid
 
 T = TypeVar('T')
 
+# Header que el integrador usa para reintentar una petición sin duplicarla (crear factura, timbres y tickets).
+IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+
 
 class BaseService:
     def __init__(self, settings: FiscalApiSettings):

{fiscalapi-4.0.439 → fiscalapi-4.0.462}/fiscalapi/services/invoice_service.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from fiscalapi.models.common_models import ApiResponse, PagedList
 from fiscalapi.models.fiscalapi_models import (
     CancelInvoiceRequest,
@@ -9,7 +11,7 @@ from fiscalapi.models.fiscalapi_models import (
     InvoiceStatusResponse,
     SendInvoiceRequest,
 )
-from fiscalapi.services.base_service import BaseService
+from fiscalapi.services.base_service import IDEMPOTENCY_KEY_HEADER, BaseService
 
 
 class InvoiceService(BaseService):
@@ -25,7 +27,7 @@ class InvoiceService(BaseService):
         endpoint = f"invoices/{invoice_id}"
         return self.send_request("GET", endpoint, Invoice, details=details)
 
-    def create(self, invoice: Invoice) -> ApiResponse[Invoice]:
+    def create(self, invoice: Invoice, idempotency_key: Optional[str] = None) -> ApiResponse[Invoice]:
         """
         Crea una nueva factura CFDI.
 
@@ -36,14 +38,20 @@ class InvoiceService(BaseService):
         - 'N': Nómina
         - 'T': Traslado
 
+        Con idempotency_key (hasta 64 caracteres ASCII visibles, sin espacios) se envía el header Idempotency-Key:
+        repetir la llave de idempotencia con la misma petición en 24 h devuelve la respuesta original; con otra petición
+        responde 422, y mientras la original sigue en proceso, 409. Sin llave de idempotencia el header no se envía.
+
         Args:
             invoice: Modelo de factura con los datos requeridos.
+            idempotency_key: Valor del header Idempotency-Key, o None para no enviarlo.
 
         Returns:
             ApiResponse con la factura creada y timbrada.
         """
         endpoint = "invoices"
-        return self.send_request("POST", endpoint, Invoice, payload=invoice)
+        headers = {} if idempotency_key is None else {IDEMPOTENCY_KEY_HEADER: idempotency_key}
+        return self.send_request("POST", endpoint, Invoice, payload=invoice, headers=headers)
 
     def cancel(self, cancel_invoice_request: CancelInvoiceRequest) -> ApiResponse[CancelInvoiceResponse]:
         """Cancela una factura."""

{fiscalapi-4.0.439 → fiscalapi-4.0.462}/fiscalapi/services/stamp_service.py

@@ -1,5 +1,7 @@
 """Servicio para gestionar transacciones de timbres (stamps)."""
 
+from typing import Optional
+
 from fiscalapi.models import (
     ApiResponse,
     FiscalApiSettings,
@@ -7,7 +9,7 @@ from fiscalapi.models import (
     StampTransaction,
     StampTransactionParams,
 )
-from fiscalapi.services.base_service import BaseService
+from fiscalapi.services.base_service import IDEMPOTENCY_KEY_HEADER, BaseService
 
 
 class StampService(BaseService):
@@ -41,20 +43,26 @@ class StampService(BaseService):
         endpoint = f"stamps/{transaction_id}"
         return self.send_request("GET", endpoint, StampTransaction)
 
-    def transfer_stamps(self, request: StampTransactionParams) -> ApiResponse[bool]:
+    def transfer_stamps(self, request: StampTransactionParams, idempotency_key: Optional[str] = None) -> ApiResponse[bool]:
         """Transfer stamps or validation credits from one person to another.
 
         Use ``request.credit_type`` to pick which balance moves: ``CreditType.STAMP`` (default) moves
         stamps, ``CreditType.VALIDATION`` moves SAT validation credits. The two balances never mix.
 
+        With ``idempotency_key`` (up to 64 visible ASCII characters, no spaces) the ``Idempotency-Key`` header is
+        sent: repeating the idempotency key with the same transfer within 24 hours answers the original response; with another
+        transfer, 422; while the original is still in progress, 409. Without it the header is not sent.
+
         Args:
             request: StampTransactionParams containing transfer details.
+            idempotency_key: Value of the Idempotency-Key header, or None to not send it.
 
         Returns:
             ApiResponse containing a boolean indicating success.
         """
         endpoint = "stamps"
-        return self.send_request("POST", endpoint, bool, payload=request)
+        headers = {} if idempotency_key is None else {IDEMPOTENCY_KEY_HEADER: idempotency_key}
+        return self.send_request("POST", endpoint, bool, payload=request, headers=headers)
 
     def withdraw_stamps(self, request: StampTransactionParams) -> ApiResponse[bool]:
         """Withdraw stamps or validation credits from a person.

{fiscalapi-4.0.439 → fiscalapi-4.0.462}/fiscalapi/services/ticket_service.py

@@ -5,9 +5,7 @@ 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"
+from fiscalapi.services.base_service import IDEMPOTENCY_KEY_HEADER, BaseService
 
 
 class TicketService(BaseService):
@@ -16,9 +14,11 @@ class TicketService(BaseService):
     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.
+        With ``idempotency_key`` (1 to 64 visible ASCII characters, no spaces) the ``Idempotency-Key`` header is sent:
+        repeating the same idempotency key with the same body, within 24 hours, returns the original response (201, with
+        the ``Idempotent-Replayed: true`` header) without registering another ticket or charging again; with another
+        body, 422; with the original still in progress, 409 with Retry-After. Without a key the header is not sent. An
+        active folio and series of the issuer answers 409.
 
         Args:
             ticket: Ticket to ingest.