fiscalapi 4.0.450__tar.gz → 4.0.462__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.450
+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

{fiscalapi-4.0.450 → 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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.450
+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

{fiscalapi-4.0.450 → fiscalapi-4.0.462}/fiscalapi.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ fiscalapi/services/tax_file_service.py
 fiscalapi/services/ticket_service.py
 tests/test_cycle_contract.py
 tests/test_error_trace_identifier.py
+tests/test_idempotency_key.py
 tests/test_invoice_item_ticket_id.py
 tests/test_response_tolerance.py
 tests/test_ticket_service.py

{fiscalapi-4.0.450 → fiscalapi-4.0.462}/setup.py

@@ -2,7 +2,7 @@
 import os
 from setuptools import setup, find_packages
 
-VERSION = "4.0.450"
+VERSION = "4.0.462"
 
 DESCRIPTION = "Genera facturas CFDI válidas ante el SAT consumiendo el API de https://www.fiscalapi.com"
 

fiscalapi-4.0.462/tests/test_idempotency_key.py

@@ -0,0 +1,87 @@
+"""Llave de idempotencia opcional en crear factura y transferir timbres.
+
+Con ``idempotency_key`` el SDK manda el header ``Idempotency-Key`` con ese valor, y sin ella no manda el header. La llave de idempotencia
+no cambia el cuerpo de la petición. El SDK no genera ni reintenta la llave de idempotencia: solo la pasa.
+"""
+from fiscalapi import Invoice, InvoiceIssuer, StampTransactionParams
+
+INVOICES_URL = "https://sdk-tests.fiscalapi.invalid/api/v4/invoices"
+STAMPS_URL = "https://sdk-tests.fiscalapi.invalid/api/v4/stamps"
+ISSUER_ID = "4b1c2d3e-0000-4000-8000-000000000002"
+PERSON_ID = "96b46762-d246-4a67-a562-510a25dbafa9"
+IDEMPOTENCY_KEY = "pos-01-F-1001"
+
+CREATED_INVOICE = {"succeeded": True, "message": "OK", "data": {"id": "7c1d2e3f-0000-4000-8000-0000000000b2"}}
+TRANSFERRED = {"succeeded": True, "message": "OK", "data": True}
+
+
+def _invoice() -> Invoice:
+    return Invoice(version_code="4.0", series="F", type_code="I", issuer=InvoiceIssuer(id=ISSUER_ID))
+
+
+def _transfer() -> StampTransactionParams:
+    return StampTransactionParams(from_person_id=ISSUER_ID, to_person_id=PERSON_ID, amount=10)
+
+
+# Crear factura
+
+def test_create_invoice_sends_the_idempotency_key_header(client, fake_api):
+    fake_api.respond_with(CREATED_INVOICE)
+
+    client.invoices.create(_invoice(), idempotency_key=IDEMPOTENCY_KEY)
+
+    [request] = fake_api.requests
+    assert request["method"] == "POST"
+    assert request["url"] == INVOICES_URL
+    assert request["headers"]["Idempotency-Key"] == IDEMPOTENCY_KEY
+
+
+def test_create_invoice_without_a_key_does_not_send_the_header(client, fake_api):
+    fake_api.respond_with(CREATED_INVOICE)
+
+    client.invoices.create(_invoice())
+
+    [request] = fake_api.requests
+    assert "Idempotency-Key" not in request["headers"]
+
+
+def test_create_invoice_key_does_not_change_the_body(client, fake_api):
+    fake_api.respond_with(CREATED_INVOICE)
+
+    client.invoices.create(_invoice())
+    client.invoices.create(_invoice(), idempotency_key=IDEMPOTENCY_KEY)
+
+    without_key, with_key = fake_api.requests
+    assert with_key["json"] == without_key["json"]
+
+
+# Transferir timbres
+
+def test_transfer_stamps_sends_the_idempotency_key_header(client, fake_api):
+    fake_api.respond_with(TRANSFERRED)
+
+    client.stamps.transfer_stamps(_transfer(), idempotency_key=IDEMPOTENCY_KEY)
+
+    [request] = fake_api.requests
+    assert request["method"] == "POST"
+    assert request["url"] == STAMPS_URL
+    assert request["headers"]["Idempotency-Key"] == IDEMPOTENCY_KEY
+
+
+def test_transfer_stamps_without_a_key_does_not_send_the_header(client, fake_api):
+    fake_api.respond_with(TRANSFERRED)
+
+    client.stamps.transfer_stamps(_transfer())
+
+    [request] = fake_api.requests
+    assert "Idempotency-Key" not in request["headers"]
+
+
+def test_transfer_stamps_key_does_not_change_the_body(client, fake_api):
+    fake_api.respond_with(TRANSFERRED)
+
+    client.stamps.transfer_stamps(_transfer())
+    client.stamps.transfer_stamps(_transfer(), idempotency_key=IDEMPOTENCY_KEY)
+
+    without_key, with_key = fake_api.requests
+    assert with_key["json"] == without_key["json"]

{fiscalapi-4.0.450 → fiscalapi-4.0.462}/tests/test_ticket_service.py

@@ -1,7 +1,7 @@
 """Servicio de tickets de Auto CFDI (POST/GET/DELETE /api/v4/tickets).
 
 Los mismos escenarios viven en los SDK de .NET, Node.js, PHP y Java: el cuerpo exacto de la ingesta y el header
-Idempotency-Key solo si se pasa; las respuestas 201 y 200 de la ingesta; el 409 y el 422 con la forma de error del SDK
+Idempotency-Key solo si se pasa; la respuesta 201 de la ingesta; el 409 y el 422 con la forma de error del SDK
 (``details`` con el texto del API y ``data`` en None); la query de la lista con ``status`` repetido; el detalle con y sin
 ``details``; el código; la cancelación con DELETE, y un estado que el SDK no conoce, conservado como texto.
 """
@@ -26,7 +26,7 @@ BASE_URL = "https://sdk-tests.fiscalapi.invalid/api/v4/tickets"
 ISSUER_ID = "4b1c2d3e-0000-4000-8000-000000000002"
 TICKET_ID = "9f8e7d6c-0000-4000-8000-0000000000a1"
 GLOBAL_INVOICE_ID = "7c1d2e3f-0000-4000-8000-0000000000b2"
-IDEMPOTENCY_KEY = "pos-01-F-1001"
+IDEMPOTENCY_KEY = "550e8400-e29b-41d4-a716-446655440000"
 
 INGESTED = {
     "id": TICKET_ID,
@@ -158,16 +158,15 @@ def test_create_without_a_key_does_not_send_the_idempotency_key_header(client, f
     assert "Idempotency-Key" not in request["headers"]
 
 
-# b. Respuestas de la ingesta
+# b. Respuesta de la ingesta: la repetición con la misma llave de idempotencia devuelve esta misma 201
 
-@pytest.mark.parametrize("status_code", [201, 200])
-def test_create_reads_the_new_ticket_and_the_idempotent_replay_with_the_same_shape(client, fake_api, status_code):
-    fake_api.respond_with(_ok(INGESTED, status_code), status_code=status_code)
+def test_create_reads_the_new_ticket_with_its_shape(client, fake_api):
+    fake_api.respond_with(_ok(INGESTED, 201), status_code=201)
 
     response = client.tickets.create(_new_ticket(), IDEMPOTENCY_KEY)
 
     assert response.succeeded is True
-    assert response.http_status_code == status_code
+    assert response.http_status_code == 201
     assert response.error_data is None
     ingested = response.data
     assert ingested.id == TICKET_ID