fiscalapi 4.0.418__tar.gz → 4.0.433__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.418
+Version: 4.0.433
 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
@@ -180,7 +180,7 @@ from fiscalapi import TaxFile
 # Subir certificado (CER)
 certificado_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
     file_type=0,  # 0 para certificado, 1 para llave privada
     password="12345678a"    
@@ -189,7 +189,7 @@ certificado_csd = TaxFile(
 # Subir llave privada (KEY)
 clave_privada_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
     file_type=1,
     password="12345678a"
@@ -566,7 +566,7 @@ if api_response.succeeded:
     print(api_response.data.base64_file)     # PDF firmado en base64
 ```
 
-Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado en `manifest_status_id`.
+Tras una firma exitosa, todas las personas del tenant con el RFC del certificado quedan con `manifest_status_id` en `Signed`; `client.people.get_by_id(...)` lo refleja.
 
 ## 📋 Operaciones Principales
 

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

@@ -143,7 +143,7 @@ from fiscalapi import TaxFile
 # Subir certificado (CER)
 certificado_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
     file_type=0,  # 0 para certificado, 1 para llave privada
     password="12345678a"    
@@ -152,7 +152,7 @@ certificado_csd = TaxFile(
 # Subir llave privada (KEY)
 clave_privada_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
     file_type=1,
     password="12345678a"
@@ -529,7 +529,7 @@ if api_response.succeeded:
     print(api_response.data.base64_file)     # PDF firmado en base64
 ```
 
-Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado en `manifest_status_id`.
+Tras una firma exitosa, todas las personas del tenant con el RFC del certificado quedan con `manifest_status_id` en `Signed`; `client.people.get_by_id(...)` lo refleja.
 
 ## 📋 Operaciones Principales
 

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

@@ -82,6 +82,7 @@ from .models.fiscalapi_models import (
     ProductTax,
     Product,
     # Person models
+    CreditBalance,
     Person,
     EmployeeData,
     EmployerData,
@@ -190,6 +191,7 @@ __all__ = [
     "ProductTax",
     "Product",
     # Person models
+    "CreditBalance",
     "Person",
     "EmployeeData",
     "EmployerData",

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

@@ -66,6 +66,7 @@ from .fiscalapi_models import (
     ProductTax,
     Product,
     # Person models
+    CreditBalance,
     Person,
     EmployeeData,
     EmployerData,
@@ -188,6 +189,7 @@ __all__ = [
     "ProductTax",
     "Product",
     # Person models
+    "CreditBalance",
     "Person",
     "EmployeeData",
     "EmployerData",

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

@@ -10,6 +10,7 @@ class ApiResponse(BaseModel, Generic[T]):
     details: Optional[str] = Field(default=None, alias="details")
     data: Optional[T] = Field(default=None, alias="data")
     http_status_code: Optional[int] = Field(default=None, alias="httpStatusCode")
+    trace_identifier: Optional[str] = Field(default=None, alias="traceIdentifier", description="Identificador de la petición en los registros de FiscalAPI. Viene en los errores (por ejemplo, un 500 o un 502): inclúyalo al escribir a soporte@fiscalapi.com.")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -30,7 +31,7 @@ class ValidationFailure(BaseModel):
     """Modelo para errores de validación."""
     property_name: str = Field(alias="propertyName")
     error_message: str = Field(alias="errorMessage")
-    attempted_value: Optional[Any] = Field(default=None, alias="attemptedValue")
+    attempted_value: Optional[Any] = Field(default=None, alias="attemptedValue", description="Valor recibido. El de un secreto (contraseñas, códigos, tokens, archivos y contraseñas de CSD/FIEL) llega como \"[masked: n]\", o \"[masked]\" si es un objeto o lista que lo contiene.")
 
     model_config = ConfigDict(populate_by_name=True)
 

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

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

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

@@ -113,6 +113,7 @@ class BaseService:
                         http_status_code=status_code,
                         message=generic_error.message,
                         details=details_str,
+                        trace_identifier=generic_error.trace_identifier,
                         data=None
                     )
             except Exception:
@@ -123,6 +124,7 @@ class BaseService:
             http_status_code=status_code,
             message=generic_error.message or f"HTTP Error {status_code}",
             details=generic_error.details or raw_content,
+            trace_identifier=generic_error.trace_identifier,
             data=None
         )
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiscalapi
-Version: 4.0.418
+Version: 4.0.433
 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
@@ -180,7 +180,7 @@ from fiscalapi import TaxFile
 # Subir certificado (CER)
 certificado_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
     file_type=0,  # 0 para certificado, 1 para llave privada
     password="12345678a"    
@@ -189,7 +189,7 @@ certificado_csd = TaxFile(
 # Subir llave privada (KEY)
 clave_privada_csd = TaxFile(
     person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
-    tin="FUNK671228PH6",
+    tin="FUNK671228PH6",  # RFC de la persona (opcional)
     base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
     file_type=1,
     password="12345678a"
@@ -566,7 +566,7 @@ if api_response.succeeded:
     print(api_response.data.base64_file)     # PDF firmado en base64
 ```
 
-Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado en `manifest_status_id`.
+Tras una firma exitosa, todas las personas del tenant con el RFC del certificado quedan con `manifest_status_id` en `Signed`; `client.people.get_by_id(...)` lo refleja.
 
 ## 📋 Operaciones Principales
 

{fiscalapi-4.0.418 → fiscalapi-4.0.433}/fiscalapi.egg-info/SOURCES.txt

@@ -33,4 +33,7 @@ fiscalapi/services/people_service.py
 fiscalapi/services/product_service.py
 fiscalapi/services/sat_validation_service.py
 fiscalapi/services/stamp_service.py
-fiscalapi/services/tax_file_service.py
+fiscalapi/services/tax_file_service.py
+tests/test_cycle_contract.py
+tests/test_error_trace_identifier.py
+tests/test_response_tolerance.py

{fiscalapi-4.0.418 → fiscalapi-4.0.433}/pyproject.toml

@@ -18,3 +18,6 @@ target-version = "py39"
 [tool.ruff.lint]
 select = ["E", "F", "W"]
 ignore = ["E501", "W293", "W291", "W292"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{fiscalapi-4.0.418 → fiscalapi-4.0.433}/setup.py

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

fiscalapi-4.0.433/tests/test_cycle_contract.py

@@ -0,0 +1,190 @@
+"""Cambios de código del SDK en el ciclo de deuda técnica 2 (Fase III, C22).
+
+Los escenarios 1 a 3 viven también en los SDK de .NET, Node.js, PHP y Java (DEC-136), cuando el cambio aplica a cada uno:
+
+1. persona: ``valid_to`` de solo lectura y ``committed_balance`` heredado; ``capital_regime``, ``stripeCustomerId`` y
+   ``subscriptionStatus`` fuera del modelo (SDK-043, SDK-044);
+2. certificados: ``tin`` opcional al subir (SDK-045) y ``file_type`` 2 y 3 de la FIEL (SDK-058);
+3. certificados sin ``update()``: el API retiró PUT tax-files (SDK-051).
+
+Los escenarios 4 y 5 son solo de Python: el SDK deja de restringir con ``Literal`` las claves que valida el API y las
+envía tal cual, como los otros SDK (SDK-044, SDK-050, SDK-058; DEC-163 H2).
+"""
+from datetime import datetime
+from decimal import Decimal
+
+import pytest
+
+from fiscalapi import (
+    BaseDto,
+    CancelInvoiceRequest,
+    InvoicePayment,
+    Person,
+    ProductTax,
+    TaxCredential,
+    TaxFile,
+)
+from fiscalapi.models.fiscalapi_models import ItemTax, LocalTax, PaidInvoiceTax
+
+BASE_URL = "https://sdk-tests.fiscalapi.invalid/api/v4"
+PERSON_ID = "4b1c2d3e-0000-4000-8000-000000000002"
+TAX_FILE_ID = "7a1b2c3d-0000-4000-8000-0000000000f1"
+BASE64_CER = "MIIFsDCCA5igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0MTYwDQYJKoZIhvcNAQELBQAw"
+BASE64_KEY = "MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAgEAAoIBAQACAggAMBQG"
+
+RETIRED_PERSON_KEYS = ("validTo", "capitalRegime", "CapitalRegime", "stripeCustomerId", "subscriptionStatus")
+
+
+def _envelope(data) -> dict:
+    return {"data": data, "succeeded": True, "message": "", "details": "", "httpStatusCode": 200}
+
+
+# 1. Persona (SDK-043, SDK-044)
+
+
+def test_person_from_response_reads_valid_to_and_committed_balance_and_drops_the_retired_fields(client, fake_api, api_json):
+    fake_api.respond_with(api_json("person-valid-to.json"))
+
+    response = client.people.get_by_id(PERSON_ID)
+
+    person = response.data
+    assert response.succeeded is True
+    assert person.valid_to == datetime(2025, 7, 15, 10, 30)
+    assert person.committed_balance == 0
+    assert person.available_balance == 100
+    assert "capital_regime" not in Person.model_fields
+    dumped = person.model_dump(by_alias=True)
+    for key in ("capitalRegime", "CapitalRegime", "stripeCustomerId", "subscriptionStatus"):
+        assert key not in dumped
+
+
+def test_person_create_sends_neither_valid_to_nor_the_retired_fields(client, fake_api, api_json):
+    fake_api.respond_with(api_json("person-valid-to.json"))
+    person = Person(legal_name="ESCUELA KEMPER URGATE", email="someone@example.com", password="UserPass123!", tin="EKU9003173C9")
+
+    client.people.create(person)
+
+    [request] = fake_api.requests
+    assert request["method"] == "POST"
+    assert request["url"] == f"{BASE_URL}/people"
+    assert request["json"]["legalName"] == "ESCUELA KEMPER URGATE"
+    for key in RETIRED_PERSON_KEYS:
+        assert key not in request["json"]
+
+
+# 2. Certificados: tin opcional (SDK-045) y file_type de la FIEL (SDK-058)
+
+
+@pytest.mark.parametrize("file_type", [2, 3])
+def test_tax_file_create_without_tin_sends_the_file_type_as_a_number_and_no_tin(client, fake_api, file_type):
+    fake_api.respond_with(_envelope({"id": TAX_FILE_ID, "personId": PERSON_ID, "tin": "EKU9003173C9", "fileType": file_type, "sequence": 1}))
+    tax_file = TaxFile(person_id=PERSON_ID, base64_file=BASE64_CER, file_type=file_type, password="12345678a")
+
+    response = client.tax_files.create(tax_file)
+
+    assert response.succeeded is True
+    assert response.data.tin == "EKU9003173C9"
+    [request] = fake_api.requests
+    assert request["method"] == "POST"
+    assert request["url"] == f"{BASE_URL}/tax-files"
+    assert request["json"] == {"personId": PERSON_ID, "base64File": BASE64_CER, "fileType": file_type, "password": "12345678a"}
+
+
+# 3. Certificados sin update() (SDK-051)
+
+
+def test_tax_file_service_has_no_update(client):
+    assert not hasattr(client.tax_files, "update")
+
+
+def test_tax_file_delete_sends_delete_to_the_tax_file(client, fake_api):
+    fake_api.respond_with(_envelope(True))
+
+    response = client.tax_files.delete(TAX_FILE_ID)
+
+    assert response.succeeded is True
+    assert response.data is True
+    [request] = fake_api.requests
+    assert request["method"] == "DELETE"
+    assert request["url"] == f"{BASE_URL}/tax-files/{TAX_FILE_ID}"
+    assert request["json"] is None
+
+
+# 4. Cancelación por valores: TaxCredential sin BaseDto (SDK-044) y motivo como texto (SDK-058)
+
+
+@pytest.mark.parametrize("reason_code", ["02", "05"])
+def test_cancel_by_values_sends_the_reason_code_as_is_and_only_the_credential_fields(client, fake_api, reason_code):
+    fake_api.respond_with(_envelope({"base64CancellationAcknowledgement": "PD94", "invoiceUuids": {"UUID-1": "201"}}))
+    request_model = CancelInvoiceRequest(
+        invoice_uuid="UUID-1",
+        tin="EKU9003173C9",
+        cancellation_reason_code=reason_code,
+        tax_credentials=[
+            TaxCredential(base64_file=BASE64_CER, file_type=0),
+            TaxCredential(base64_file=BASE64_KEY, file_type=1, password="12345678a"),
+        ],
+    )
+
+    response = client.invoices.cancel(request_model)
+
+    assert response.succeeded is True
+    assert response.data.invoice_uuids == {"UUID-1": "201"}
+    [request] = fake_api.requests
+    assert request["method"] == "DELETE"
+    assert request["url"] == f"{BASE_URL}/invoices"
+    assert request["json"]["cancellationReasonCode"] == reason_code
+    assert request["json"]["taxCredentials"] == [
+        {"base64File": BASE64_CER, "fileType": 0},
+        {"base64File": BASE64_KEY, "fileType": 1, "password": "12345678a"},
+    ]
+
+
+def test_tax_credential_is_not_a_base_dto():
+    credential = TaxCredential(base64_file=BASE64_CER, file_type=0)
+
+    assert not isinstance(credential, BaseDto)
+    assert set(TaxCredential.model_fields) == {"base64_file", "file_type", "password"}
+    assert credential.password is None
+
+
+# 5. Claves de catálogo como texto: el SDK no las restringe, las valida el API (SDK-050, DEC-163 H2)
+
+
+def test_catalog_keys_are_sent_as_is():
+    product_tax = ProductTax(rate=Decimal("0.16"), tax_id="004", tax_flag_id="X", tax_type_id="Otro")
+    person = Person(sat_tax_regime_id="699", sat_cfdi_use_id="Z99", user_type_id="U")
+
+    assert product_tax.model_dump(mode="json", by_alias=True, exclude_none=True) == {
+        "rate": "0.16",
+        "taxId": "004",
+        "taxFlagId": "X",
+        "taxTypeId": "Otro",
+    }
+    assert person.model_dump(mode="json", by_alias=True, exclude_none=True) == {
+        "satTaxRegimeId": "699",
+        "satCfdiUseId": "Z99",
+        "userTypeId": "U",
+    }
+    for model in (
+        ItemTax(tax_flag_code="X"),
+        PaidInvoiceTax(tax_code="002", tax_type_code="Tasa", tax_rate=Decimal("0.16"), tax_flag_code="X"),
+        LocalTax(tax_flag_code="X"),
+    ):
+        assert model.model_dump(by_alias=True)["taxFlagCode"] == "X"
+
+
+def test_invoice_payment_accepts_any_currency_code_and_defaults_to_mxn():
+    common = dict(
+        payment_date="2026-10-08T10:00:00",
+        payment_form_code="03",
+        amount=Decimal("100"),
+        source_bank_tin="BSM970519DU8",
+        source_bank_account="1234567891",
+        target_bank_tin="BBA830831LJ2",
+        target_bank_account="0123456789",
+        paid_invoices=[],
+    )
+
+    assert InvoicePayment(currency_code="CAD", **common).model_dump(by_alias=True)["currencyCode"] == "CAD"
+    assert InvoicePayment(**common).currency_code == "MXN"

fiscalapi-4.0.433/tests/test_error_trace_identifier.py

@@ -0,0 +1,94 @@
+"""SDK-060 (DEC-184, consistencia DEC-136 con Java): las respuestas de error exponen ``trace_identifier``.
+
+Los textos de los 5xx del API piden enviar el traceIdentifier a soporte. El cambio es aditivo: ``message``,
+``details`` y ``http_status_code`` no cambian.
+"""
+from fiscalapi import SignManifestRequest
+
+TRACE_IDENTIFIER = "5C1E0B7A92D44F3E8A6B1D07F3C29E41"
+
+
+def _sign_request() -> SignManifestRequest:
+    return SignManifestRequest(
+        base64_cer="base64CerHere...",
+        base64_key="base64KeyHere...",
+        password="passwordPhraseHere...",
+    )
+
+
+def test_server_error_exposes_the_trace_identifier_and_keeps_message_and_details(client, fake_api):
+    fake_api.respond_with({
+        "data": None,
+        "succeeded": False,
+        "message": "Something went wrong on our end.",
+        "details": "Ocurrió un error inesperado en el servidor. Escríbenos a soporte@fiscalapi.com con el traceIdentifier de esta respuesta.",
+        "httpStatusCode": 500,
+        "traceIdentifier": TRACE_IDENTIFIER,
+    }, status_code=500)
+
+    response = client.manifests.sign(_sign_request())
+
+    assert response.succeeded is False
+    assert response.http_status_code == 500
+    assert response.message == "Something went wrong on our end."
+    assert response.details == (
+        "Ocurrió un error inesperado en el servidor. Escríbenos a soporte@fiscalapi.com con el traceIdentifier de esta respuesta."
+    )
+    assert response.trace_identifier == TRACE_IDENTIFIER
+    assert response.data is None
+
+
+def test_client_error_exposes_the_trace_identifier(client, fake_api):
+    fake_api.respond_with({
+        "data": None,
+        "succeeded": False,
+        "message": "Sorry, it's not me, it's you.",
+        "details": "No existe un usuario con RFC EKU9003173C9 en el tenant actual.",
+        "httpStatusCode": 404,
+        "traceIdentifier": TRACE_IDENTIFIER,
+    }, status_code=404)
+
+    response = client.manifests.sign(_sign_request())
+
+    assert response.http_status_code == 404
+    assert response.message == "Sorry, it's not me, it's you."
+    assert response.details == "No existe un usuario con RFC EKU9003173C9 en el tenant actual."
+    assert response.trace_identifier == TRACE_IDENTIFIER
+
+
+def test_validation_error_exposes_the_trace_identifier_and_keeps_the_joined_details(client, fake_api):
+    fake_api.respond_with({
+        "data": [{
+            "propertyName": "Password",
+            "errorMessage": "La contraseña de la llave privada (.key) es incorrecta o el archivo no es una llave privada.",
+            "attemptedValue": None,
+        }],
+        "succeeded": False,
+        "message": "Sorry, it's not me, it's you.",
+        "details": "One or more validation failures have occurred.",
+        "httpStatusCode": 400,
+        "traceIdentifier": TRACE_IDENTIFIER,
+    }, status_code=400)
+
+    response = client.manifests.sign(_sign_request())
+
+    assert response.http_status_code == 400
+    assert response.details == (
+        "Password: La contraseña de la llave privada (.key) es incorrecta o el archivo no es una llave privada."
+    )
+    assert response.trace_identifier == TRACE_IDENTIFIER
+
+
+def test_error_without_trace_identifier_leaves_it_none(client, fake_api):
+    fake_api.respond_with({
+        "data": None,
+        "succeeded": False,
+        "message": "Too Many Requests",
+        "details": "x",
+        "httpStatusCode": 429,
+    }, status_code=429)
+
+    response = client.manifests.sign(_sign_request())
+
+    assert response.http_status_code == 429
+    assert response.trace_identifier is None

fiscalapi-4.0.433/tests/test_response_tolerance.py

@@ -0,0 +1,143 @@
+"""Tolerancia del SDK a respuestas que el API devolverá en las próximas fases (SDK-001).
+
+Son pruebas de caracterización: fijan el comportamiento ACTUAL. Una prueba cuyo nombre cita SDK-012
+documenta un defecto conocido; SDK-012 la invierte al corregirlo. Los casos son:
+
+1. una transacción de timbres con ``creditType: 3`` (créditos de ticket, Fase 1);
+2. una persona con el campo nuevo ``availableTicketBalance`` (Fase 1);
+3. propiedades desconocidas en la envoltura, en ``data`` y en objetos anidados;
+4. ``globalInformation`` en la respuesta de una factura (BE-008).
+"""
+from decimal import Decimal
+
+import pytest
+from pydantic import ValidationError
+
+from fiscalapi import CreditType, GlobalInformation
+
+TICKET_CREDIT_TYPE = 3
+
+
+def _ticket_credit_type_errors(error: ValidationError) -> list:
+    return [e for e in error.errors() if e["loc"][-1] == "creditType" and e["input"] == TICKET_CREDIT_TYPE]
+
+
+# 1. creditType: 3
+
+
+def test_stamp_list_with_credit_type_3_raises_validation_error__fixed_by_SDK_012(client, fake_api, api_json):
+    fake_api.respond_with(api_json("stamps-page-credit-type-3.json"))
+
+    with pytest.raises(ValidationError) as raised:
+        client.stamps.get_list(1, 10)
+
+    assert len(_ticket_credit_type_errors(raised.value)) == 1
+    assert raised.value.error_count() == 1
+
+
+def test_stamp_by_id_with_credit_type_3_raises_validation_error__fixed_by_SDK_012(client, fake_api, api_json):
+    fake_api.respond_with(api_json("stamp-credit-type-3.json"))
+
+    with pytest.raises(ValidationError) as raised:
+        client.stamps.get_by_id("8d0f6a52-6f1e-4c3a-9a10-000000000103")
+
+    assert len(_ticket_credit_type_errors(raised.value)) == 1
+    assert raised.value.error_count() == 1
+
+
+def test_stamp_list_without_the_credit_type_3_item_deserializes_known_credit_types(client, fake_api, api_json):
+    page = api_json("stamps-page-credit-type-3.json")
+    page["data"]["items"] = [i for i in page["data"]["items"] if i["creditType"] != TICKET_CREDIT_TYPE]
+    fake_api.respond_with(page)
+
+    response = client.stamps.get_list(1, 10)
+
+    assert response.succeeded is True
+    assert [t.credit_type for t in response.data.items] == [CreditType.STAMP, CreditType.VALIDATION]
+    assert response.data.total_count == 3
+    assert fake_api.requested_urls == ["https://sdk-tests.fiscalapi.invalid/api/v4/stamps?pageNumber=1&pageSize=10"]
+
+
+# 2. availableTicketBalance
+
+
+def test_person_with_available_ticket_balance_deserializes_and_drops_the_field__exposed_by_SDK_012(
+    client, fake_api, api_json
+):
+    fake_api.respond_with(api_json("person-ticket-balance.json"))
+
+    response = client.people.get_by_id("4b1c2d3e-0000-4000-8000-000000000001")
+
+    person = response.data
+    assert response.succeeded is True
+    assert person.available_balance == Decimal("100")
+    assert person.committed_balance == Decimal("0")
+    assert person.available_validation_balance == 50
+    assert not hasattr(person, "available_ticket_balance")
+    assert "availableTicketBalance" not in person.model_dump(by_alias=True)
+
+
+# 3. Propiedades desconocidas
+
+
+def test_unknown_properties_on_a_stamp_transaction_are_ignored_and_known_fields_are_read(client, fake_api, api_json):
+    stamp = api_json("stamp-credit-type-3.json")
+    stamp["data"]["creditType"] = int(CreditType.VALIDATION)
+    fake_api.respond_with(stamp)
+
+    response = client.stamps.get_by_id("8d0f6a52-6f1e-4c3a-9a10-000000000103")
+
+    transaction = response.data
+    assert response.succeeded is True
+    assert transaction.credit_type == CreditType.VALIDATION
+    assert transaction.amount == 25
+    assert transaction.from_person.legal_name == "FISCALAPI"
+    assert "unknownScalarField" not in transaction.model_dump(by_alias=True)
+    assert "unknownNestedField" not in transaction.from_person.model_dump(by_alias=True)
+
+
+def test_unknown_properties_on_the_envelope_the_page_and_a_person_are_ignored(client, fake_api, api_json):
+    fake_api.respond_with(api_json("person-ticket-balance.json"))
+
+    response = client.people.get_by_id("4b1c2d3e-0000-4000-8000-000000000001")
+
+    assert response.succeeded is True
+    assert response.http_status_code == 200
+    assert response.data.tin == "EKU9003173C9"
+    assert "unknownEnvelopeField" not in response.model_dump(by_alias=True)
+    assert "unknownObjectField" not in response.data.model_dump(by_alias=True)
+
+
+# 4. globalInformation en la respuesta de una factura (BE-008)
+
+
+def test_invoice_with_global_information_deserializes_it(client, fake_api, api_json):
+    fake_api.respond_with(api_json("invoice-global-information.json"))
+
+    response = client.invoices.get_by_id("3f2a9c1e-0b7d-4e55-9a61-2c8f0e4d7b10")
+
+    assert response.succeeded is True
+    assert response.data.global_information == GlobalInformation(periodicity_code="04", month_code="09", year=2026)
+    assert response.data.issuer.tin == "EKU9003173C9"
+
+
+def test_invoice_with_null_global_information_deserializes_it_as_none(client, fake_api, api_json):
+    fake_api.respond_with(api_json("invoice-global-information-null.json"))
+
+    response = client.invoices.get_by_id("3f2a9c1e-0b7d-4e55-9a61-2c8f0e4d7b10")
+
+    assert response.succeeded is True
+    assert response.data.global_information is None
+    assert response.data.total == Decimal("1160")
+
+
+def test_invoice_with_null_members_in_global_information_raises_validation_error__BE_008_must_not_emit_it(
+    client, fake_api, api_json
+):
+    fake_api.respond_with(api_json("invoice-global-information-null-members.json"))
+
+    with pytest.raises(ValidationError) as raised:
+        client.invoices.get_by_id("3f2a9c1e-0b7d-4e55-9a61-2c8f0e4d7b10")
+
+    failing_fields = sorted(e["loc"][-1] for e in raised.value.errors())
+    assert failing_fields == ["monthCode", "periodicityCode", "year"]