fiscalapi 4.0.0__tar.gz → 4.0.2__tar.gz

{fiscalapi-4.0.0 → fiscalapi-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: fiscalapi
-Version: 4.0.0
+Version: 4.0.2
 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

fiscalapi-4.0.2/fiscalapi/__init__.py

@@ -0,0 +1,88 @@
+# fiscalapi/__init__.py
+
+# Re-exportar modelos de common_models
+from .models.common_models import (
+    ApiResponse,
+    PagedList,
+    ValidationFailure,
+    BaseDto,
+    CatalogDto,
+    FiscalApiSettings,
+)
+
+# Re-exportar modelos de fiscalapi_models
+from .models.fiscalapi_models import (
+    ProductTax,
+    Product,
+    Person,
+    TaxFile,
+    TaxCredential,
+    InvoiceIssuer,
+    InvoiceRecipient,
+    ItemTax,
+    InvoiceItem,
+    GlobalInformation,
+    RelatedInvoice,
+    PaidInvoiceTax,
+    PaidInvoice,
+    InvoicePayment,
+    InvoiceResponse,
+    Invoice,
+    CancelInvoiceRequest,
+    CancelInvoiceResponse,
+    CreatePdfRequest,
+    FileResponse,
+    SendInvoiceRequest,
+)
+
+# Re-exportar servicios
+from .services.catalog_service import CatalogService
+from .services.invoice_service import InvoiceService
+from .services.people_service import PeopleService
+from .services.product_service import ProductService
+from .services.tax_file_servive import TaxFileService   # Asegúrate de que coincida con tu nombre real (tax_file_service o tax_file_servive)
+
+# Re-exportar la clase FiscalApiClient
+# (asumiendo que la definición está en fiscalapi/services/fiscalapi_client.py)
+from .services.fiscalapi_client import FiscalApiClient
+
+__all__ = [
+    # Modelos
+    "ApiResponse",
+    "PagedList",
+    "ValidationFailure",
+    "BaseDto",
+    "CatalogDto",
+    "FiscalApiSettings",
+    "ProductTax",
+    "Product",
+    "Person",
+    "TaxFile",
+    "TaxCredential",
+    "InvoiceIssuer",
+    "InvoiceRecipient",
+    "ItemTax",
+    "InvoiceItem",
+    "GlobalInformation",
+    "RelatedInvoice",
+    "PaidInvoiceTax",
+    "PaidInvoice",
+    "InvoicePayment",
+    "InvoiceResponse",
+    "Invoice",
+    "CancelInvoiceRequest",
+    "CancelInvoiceResponse",
+    "CreatePdfRequest",
+    "FileResponse",
+    "SendInvoiceRequest",
+
+    # Servicios
+    "CatalogService",
+    "InvoiceService",
+    "PeopleService",
+    "ProductService",
+    "TaxFileService",
+    
+    # Cliente principal
+    "FiscalApiClient",
+]

fiscalapi-4.0.2/fiscalapi/models/common_models.py

@@ -0,0 +1,68 @@
+from datetime import datetime
+from typing import Any, Generic, List, Optional, TypeVar
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_snake
+
+T = TypeVar('T', bound=BaseModel)
+
+class ApiResponse(BaseModel, Generic[T]):
+    succeeded: bool = Field(alias="succeeded")
+    message: Optional[str] = Field(alias="message")
+    details: Optional[str] = Field(alias="details")
+    data: Optional[T] = Field(None, alias="data")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=to_snake
+    )
+
+
+class PagedList(BaseModel, Generic[T]):
+    """Modelo para la estructura de la lista paginada."""
+    items: List[T] = Field(default=[], alias="items", description="Lista de elementos paginados")
+    page_number: int = Field(alias="pageNumber", description="Número de página actual")
+    total_pages: int = Field(alias="totalPages", description="Cantidad total de páginas")
+    total_count: int = Field(alias="totalCount", description="Cantidad total de elementos")
+    has_previous_page: bool = Field(alias="hasPreviousPage", description="Indica si hay una página anterior")
+    has_next_page: bool = Field(alias="hasNextPage", description="Indica si hay una página siguiente")
+
+
+class ValidationFailure(BaseModel):
+    """Modelo para errores de validación."""
+    propertyName: str
+    errorMessage: str
+    attemptedValue: Optional[Any] = None
+    customState: Optional[Any] = None
+    severity: Optional[int] = None
+    errorCode: Optional[str] = None
+    formattedMessagePlaceholderValues: Optional[dict] = None
+
+
+class BaseDto(BaseModel):
+    """Modelo base para DTOs."""
+    id: Optional[str] = Field(default=None, alias="id")
+    created_at: Optional[datetime] = Field(default=None, alias="createdAt")
+    updated_at: Optional[datetime] = Field(default=None, alias="updatedAt")
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+class CatalogDto(BaseDto):
+    """Modelo para catálogos."""
+    description: str = Field(alias="description")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class FiscalApiSettings(BaseModel):
+    """
+    Objeto que contiene la configuración necesaria para interactuar con Fiscalapi.
+    """
+    api_url: str = Field(..., description="URL base de la api.")
+    api_key: str = Field(..., description="Api Key")
+    tenant: str = Field(..., description="Tenant Key.")
+    api_version: str = Field("v4", description="Versión de la api.")
+    time_zone: str = Field("America/Mexico_City", description="Zona horaria ")
+
+    class Config:
+        title = "FiscalApi Settings"
+        description = "Configuración para Fiscalapi"

fiscalapi-4.0.2/fiscalapi/models/fiscalapi_models.py

@@ -0,0 +1,323 @@
+from decimal import Decimal
+from pydantic import ConfigDict, EmailStr, Field
+from fiscalapi.models.common_models import BaseDto, CatalogDto
+from typing import Dict, List, Literal, Optional
+from datetime import datetime
+
+# products models
+
+class ProductTax(BaseDto):
+    """Modelo impuesto de producto."""
+    
+    rate: Decimal = Field(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: 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: 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: Optional[CatalogDto] = Field(default=None, alias="taxType",  description="Tipo de impuesto expandido")
+    
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+
+class Product(BaseDto):
+    """Modelo producto."""
+    description: str = Field(alias="description")
+    unit_price: Decimal = Field(alias="unitPrice")
+    
+    sat_unit_measurement_id: Optional[str] = Field(default="H87", alias="satUnitMeasurementId", description="Unidad de medida SAT")
+    sat_unit_measurement: Optional[CatalogDto] = Field(default=None, alias="satUnitMeasurement", description="Unidad de medida SAT expandida")
+    
+    sat_tax_object_id: Optional[str] = Field(default="02", alias="satTaxObjectId", description="Objeto de impuesto SAT")
+    sat_tax_object: Optional[CatalogDto] = Field(default=None, alias="satTaxObject", description="Objeto de impuesto SAT expandido")
+    
+    sat_product_code_id: Optional[str] = Field(default="01010101", alias="satProductCodeId", description="Código de producto SAT")
+    sat_product_code: Optional[CatalogDto] = Field(default=None, alias="satProductCode", description="Código de producto SAT expandido")
+    
+    product_taxes: Optional[list[ProductTax]] = Field(default=None, alias="productTaxes", description="Impuestos del producto")
+    
+    
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+
+# people models
+
+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[EmailStr] = Field(default=None, alias="email", description="Correo electrónico de la persona.")
+    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="Régimen de capital de la persona.")
+    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.")
+    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: Optional[CatalogDto] = Field(default=None, alias="cfdiUse", 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: 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.")
+    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.")
+    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.")
+    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.")
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+    
+    
+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.")
+        base64_file: Optional[str] = Field(default=None, alias="base64File", description="Archivo certificado o llave privada en formato base64.")
+        file_type: 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.")
+        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.")
+
+        model_config = ConfigDict(
+            populate_by_name=True
+        )
+        
+
+# invoices models
+
+
+class TaxCredential(BaseDto):
+    """Modelo para los sellos del emisor (archivos .cer y .key)."""
+    base64_file: str = Field(..., alias="base64File", description="Archivo en formato base64.")
+    file_type: Literal[0, 1] = Field(..., alias="fileType", description="Tipo de archivo: 0 para certificado, 1 para llave privada.")
+    password: str = Field(..., alias="password", description="Contraseña del archivo .key independientemente de si es un archivo .cer o .key.")
+
+class InvoiceIssuer(BaseDto):
+    """Modelo para el emisor de la factura."""
+    id: Optional[str] = Field(default=None, alias="id", description="ID de la persona (emisora) en fiscalapi.")
+    tin: Optional[str] = Field(default=None, alias="tin", description="RFC del emisor (Tax Identification Number).")
+    legal_name: Optional[str] = Field(default=None, alias="legalName", description="Razón social del emisor sin regimen de capital.")
+    tax_regime_code: Optional[str] = Field(default=None, alias="taxRegimeCode", description="Código del régimen fiscal del emisor.")
+    tax_credentials: Optional[List[TaxCredential]] = Field(default=None, alias="taxCredentials", description="Sellos del emisor (archivos .cer y .key).")
+
+class InvoiceRecipient(BaseDto):
+    """Modelo para el receptor de la factura."""
+    id: Optional[str] = Field(default=None, alias="id", description="ID de la persona (receptora) en fiscalapi.")
+    tin: Optional[str] = Field(default=None, alias="tin", description="RFC del receptor (Tax Identification Number).")
+    legal_name: Optional[str] = Field(default=None, alias="legalName", description="Razón social del receptor sin regimen de capital.")
+    tax_regime_code: Optional[str] = Field(default=None, alias="taxRegimeCode", description="Código del régimen fiscal del receptor.")
+    cfdi_use_code: Optional[str] = Field(default=None, alias="cfdiUseCode", description="Código del uso CFDI.")
+    zip_code: Optional[str] = Field(default=None, alias="zipCode", description="Código postal del receptor. Debe coincidir con el código postal de su constancia de residencia fiscal.")
+    email: Optional[str] = Field(default=None, description="Correo electrónico del receptor.")
+
+class ItemTax(BaseDto):
+    """Modelo para los impuestos aplicables a un producto o servicio."""
+    tax_code: str = Field(..., alias="taxCode", description="Código del impuesto.")
+    tax_type_code: str = Field(..., alias="taxTypeCode", description="Tipo de factor.")
+    tax_rate: Decimal = Field(..., 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.")
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+
+
+class InvoiceItem(BaseDto):
+    """Modelo para los conceptos de la factura (productos o servicios)."""
+    id: Optional[str] = Field(default=None, alias="id", description="ID del producto en fiscalapi.")
+    item_code: Optional[str] = Field(default=None, alias="itemCode", description="Código SAT del producto o servicio.")
+    quantity: Decimal = Field(..., alias="quantity", description="Cantidad del producto o servicio.")
+    discount: Optional[Decimal] = Field(default=None, alias="discount", description="Cantidad monetaria del descuento aplicado.")
+    unit_of_measurement_code: Optional[str] = Field(default=None, alias="unitOfMeasurementCode", description="Código SAT de la unidad de medida.")
+    description: Optional[str] = Field(default=None,alias="description", description="Descripción del producto o servicio.")
+    unit_price: Optional[Decimal] = Field(default=None, alias="unitPrice", description="Precio unitario del producto o servicio.")
+    tax_object_code: Optional[str] = Field(default=None, alias="taxObjectCode", description="Código SAT de obligaciones de impuesto.")
+    item_sku: Optional[str] = Field(default=None, alias="itemSku", description="SKU o clave del sistema externo.")
+    item_taxes: Optional[List[ItemTax]] = Field(default=None, alias="itemTaxes", description="Impuestos aplicables al producto o servicio.")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+
+class GlobalInformation(BaseDto):
+    """Modelo para la información global de la factura global."""
+    periodicity_code: str = Field(..., alias="periodicityCode", description="Código SAT de la periodicidad de la factura global.")
+    month_code: str = Field(..., alias="monthCode", description="Código SAT del mes de la factura global.")
+    year: int = Field(..., description="Año de la factura global a 4 dígitos.")
+
+class RelatedInvoice(BaseDto):
+    """Modelo para representar la relacion entre la factura actual y otras facturas previas."""
+    relationship_type_code: str = Field(..., alias="relationshipTypeCode", description="Código de la relación de la factura relacionada.")
+    uuid: str = Field(..., description="UUID de la factura relacionada.")
+
+class PaidInvoiceTax(BaseDto):
+    """Modelo para los impuestos aplicables a la factura pagada."""
+    tax_code: str = Field(..., alias="taxCode", description="Código del impuesto.")
+    tax_type_code: str = Field(..., alias="taxTypeCode", description="Tipo de factor.")
+    tax_rate: Decimal = Field(..., 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.")
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+    
+class PaidInvoice(BaseDto):
+    """Modelo para las facturas pagadas con el pago recibido."""
+    uuid: str = Field(..., alias="uuid", description="UUID de la factura pagada.")
+    series: str = Field(..., alias="series", description="Serie de la factura pagada.")
+       
+    partiality_number: int = Field(..., alias="partialityNumber", description="Número de parcialidad.")
+    sub_total: Decimal = Field(..., alias="subTotal", description="Subtotal de la factura pagada.")
+    previous_balance: Decimal = Field(..., alias="previousBalance", description="Saldo anterior de la factura pagada.")
+    payment_amount: Decimal = Field(..., alias="paymentAmount", description="Monto pagado de la factura.")
+    remaining_balance: Decimal = Field(..., alias="remainingBalance", description="Saldo restante de la factura pagada.")
+    
+    number: str = Field(..., alias="number", description="Folio de la factura pagada.")
+    currency_code: str = Field(default="MXN", alias="currencyCode", description="Código de la moneda utilizada en la factura pagada.")
+    tax_object_code: str = Field(..., alias="taxObjectCode", description="Código de obligaciones de impuesto.")
+    equivalence: Optional[Decimal] = Field(default=1, description="Equivalencia de la moneda. Este campo es obligatorio cuando la moneda del documento relacionado (PaidInvoice.CurrencyCode) difiere de la moneda en que se realiza el pago ( InvoicePayment.CurrencyCode).")
+    paid_invoice_taxes: List[PaidInvoiceTax] = Field(..., alias="paidInvoiceTaxes", description="Impuestos aplicables a la factura pagada.")
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+    
+
+    
+class InvoicePayment(BaseDto):
+    """Modelo para los pagos recibidos para liquidar la factura."""
+    payment_date: str = Field(..., alias="paymentDate", description="Fecha de pago.")
+    payment_form_code: str = Field(..., 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.")
+    exchange_rate: Optional[Decimal] = Field(default=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(..., description="Monto del pago.")
+    source_bank_tin: str = Field(..., alias="sourceBankTin", description="RFC del banco origen. (Rfc del banco emisor del pago)")
+    source_bank_account: str = Field(..., alias="sourceBankAccount", description="Cuenta bancaria origen. (Cuenta bancaria del banco emisor del pago)")
+    target_bank_tin: str = Field(..., alias="targetBankTin", description="RFC del banco destino. (Rfc del banco receptor del pago)")
+    target_bank_account: str = Field(..., alias="targetBankAccount", description="Cuenta bancaria destino (Cuenta bancaria del banco receptor del pago)")
+    paid_invoices: List[PaidInvoice] = Field(..., alias="paidInvoices", description="Facturas pagadas con el pago recibido.")
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+
+
+
+class InvoiceResponse(BaseDto):
+    """Modelo para la respuesta del SAT después del timbrado de la factura."""
+    id: Optional[str] = Field(default=None, description="ID de la respuesta.")
+    invoice_id: Optional[str] = Field(default=None, alias="invoiceId", description="ID de la factura a la que pertenece la respuesta.")
+    invoice_uuid: Optional[str] = Field(default=None, alias="invoiceUuid", description="Folio Fiscal (UUID) proporcionado por el SAT tras el timbrado de la factura.")
+    invoice_certificate_number: Optional[str] = Field(default=None, alias="invoiceCertificateNumber", description="Número de certificado del emisor.")
+    invoice_base64_sello: Optional[str] = Field(default=None, alias="invoiceBase64Sello", description="Sello digital del CFDI en formato Base64.")
+    invoice_signature_date: Optional[datetime] = Field(default=None, alias="invoiceSignatureDate", description="Fecha y hora de la firma electrónica del CFDI por parte del emisor.")
+    invoice_base64_qr_code: Optional[str] = Field(default=None, alias="invoiceBase64QrCode", description="Imagen del código QR en formato Base64.")
+    invoice_base64: Optional[str] = Field(default=None, alias="invoiceBase64", description="XML de la factura en formato Base64.")
+    sat_base64_sello: Optional[str] = Field(default=None, alias="satBase64Sello", description="Sello digital del SAT en formato Base64.")
+    sat_base64_original_string: Optional[str] = Field(default=None, alias="satBase64OriginalString", description="Cadena original de la factura codificada en Base64.")
+    sat_certificate_number: Optional[str] = Field(default=None, alias="satCertificateNumber", description="Número de certificado del SAT.")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={datetime: lambda v: v.isoformat()}
+    )
+    
+    
+class Invoice(BaseDto):
+    """Modelo para la factura."""
+    version_code: Optional[str] = Field(default="4.0", alias="versionCode", description="Código de la versión de la factura.")
+    series: str = Field(..., description="Número de serie que utiliza el contribuyente para control interno.")
+    date: datetime = Field(..., description="Fecha y hora de expedición del comprobante fiscal.")
+    payment_form_code: Optional[str] = Field(default=None, alias="paymentFormCode", description="Código de la forma de pago.")
+    currency_code: Literal["MXN", "USD", "EUR", "XXX"] = Field(default="MXN", alias="currencyCode", description="Código de la moneda utilizada.")
+    type_code: Optional[Literal["I", "E", "T", "N", "P"]] = Field(default="I", alias="typeCode", description="Código de tipo de factura.")
+    expedition_zip_code: str = Field(..., alias="expeditionZipCode", description="Código postal del emisor.")
+    export_code: Optional[Literal["01", "02", "03", "04"]] = Field(default="01", alias="exportCode", description="Código que identifica si la factura ampara una operación de exportación.")
+    payment_method_code: Optional[Literal["PUE", "PPD"]] = Field(default=None, alias="paymentMethodCode", description="Código de método para la factura de pago.")
+    exchange_rate: Optional[Decimal] = Field(default=1, alias="exchangeRate", description="Tipo de cambio FIX.")
+    issuer: Optional[InvoiceIssuer] = Field(..., description="El emisor de la factura.")
+    recipient: Optional[InvoiceRecipient] = Field(..., description="El receptor de la factura.")
+    items: Optional[List[InvoiceItem]] = Field(default=[], description="Conceptos de la factura (productos o servicios).")
+    global_information: Optional[GlobalInformation] = Field(default=None, alias="globalInformation", description="Información global de la factura.")
+    related_invoices: Optional[List[RelatedInvoice]] = Field(default=None, alias="relatedInvoices", description="Facturas relacionadas.")
+    payments: Optional[List[InvoicePayment]] = Field(default=None, description="Pago o pagos recibidos para liquidar la factura cuando la factura es un complemento de pago.")
+    responses: Optional[List[InvoiceResponse]] = Field(default=None, description="Respuestas del SAT. Contiene la información de timbrado de la factura.")
+    
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={Decimal: str}
+    )
+
+
+        
+class CancelInvoiceRequest(BaseDto):
+    """Modelo de cancelación de factura."""
+    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(..., alias="cancellationReasonCode", description="Código del motivo de cancelación.")
+    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.")
+
+    class Config:
+        populate_by_name = True
+        
+class CancelInvoiceResponse(BaseDto):
+    """Modelo de respuesta para la cancelación de factura."""
+    base64_cancellation_acknowledgement: str = Field(default=None, alias="base64CancellationAcknowledgement", description="Acuse de cancelación en formato base64. Contiene el XML del acuse de cancelación del SAT codificado en base64.")
+    invoice_uuids: Optional[Dict[str, str]] = Field(default=None, alias="invoiceUuids", description="Diccionario de UUIDs de facturas con su respectivo código de estatus de cancelación. La llave es el UUID de la factura y el valor es el código de estatus.")
+
+    class Config:
+        populate_by_name = True
+
+
+class CreatePdfRequest(BaseDto):
+    """Modelo para la generación de PDF de una factura."""
+    invoice_id: str = Field(..., alias="invoiceId", description="ID de la factura para la cual se generará el PDF.")
+    band_color: Optional[str] = Field(default=None, alias="bandColor", description="Color de la banda del PDF en formato hexadecimal. Ejemplo: '#FFA500'.")
+    font_color: Optional[str] = Field(default=None, alias="fontColor", description="Color de la fuente del texto sobre la banda en formato hexadecimal. Ejemplo: '#FFFFFF'.")
+    base64_logo: Optional[str] = Field(default=None, alias="base64Logo", description="Logotipo en formato base64 que se mostrará en el PDF.")
+
+    class Config:
+        populate_by_name = True
+
+class FileResponse(BaseDto):
+    """Modelo de respuesta para la generación de PDF o recuperación de XML."""
+    base64_file: Optional[str] = Field(default=None, alias="base64File", description="Contenido del archivo en formato base64.")
+    file_name: Optional[str] = Field(default=None, alias="fileName", description="Nombre del archivo generado.")
+    file_extension: Optional[str] = Field(default=None, alias="fileExtension", description="Extensión del archivo. Ejemplo: '.pdf'.")
+
+    class Config:
+        populate_by_name = True
+        
+        
+class SendInvoiceRequest(BaseDto):
+    """Modelo para el envío de facturas por correo electrónico."""
+    invoice_id: str = Field(..., alias="invoiceId", description="ID de la factura para la cual se enviará el PDF.")
+    to_email: str = Field(..., alias="toEmail", description="Correo electrónico del destinatario.")
+    band_color: Optional[str] = Field(default=None, alias="bandColor", description="Color de la banda del PDF en formato hexadecimal. Ejemplo: '#FFA500'.")
+    font_color: Optional[str] = Field(default=None, alias="fontColor", description="Color de la fuente del texto sobre la banda en formato hexadecimal. Ejemplo: '#FFFFFF'.")
+    base64_logo: Optional[str] = Field(default=None, alias="base64Logo", description="Logotipo en formato base64 que se mostrará en el PDF.")
+
+    class Config:
+        populate_by_name = True

fiscalapi-4.0.2/fiscalapi/services/base_service.py

@@ -0,0 +1,218 @@
+import urllib3 
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+from typing import Type, TypeVar, get_args, get_origin
+import certifi
+from pydantic import BaseModel
+import requests
+from fiscalapi.models.common_models import ApiResponse, FiscalApiSettings, ValidationFailure
+
+T = TypeVar('T')
+
+
+class BaseService:
+    def __init__(self, settings: FiscalApiSettings):
+        self.settings = settings
+        self.api_version = settings.api_version
+        self.base_url = settings.api_url
+        self.api_key = settings.api_key
+
+    def _get_headers(self) -> dict:
+        return {
+            "Content-Type": "application/json",
+            "X-TENANT-KEY": self.settings.tenant,
+            "X-API-KEY": self.settings.api_key,
+            "X-TIME-ZONE": self.settings.time_zone,
+        }
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
+        url = f"{self.base_url}/api/{self.api_version}/{endpoint}"
+        headers = self._get_headers()
+
+        if "headers" in kwargs:
+            headers.update(kwargs.pop("headers"))
+
+        # Disable certificate validation (for development only!)
+        # kwargs.setdefault("verify", False)
+
+
+        # print payload request
+        print("***Payload Request:", kwargs.get("json"))
+        
+        # print line breaks 
+        print("\n\n")
+        
+       
+       # *** DEV ONLY: Disable SSL verification for localhost ***
+        if "localhost" in url or "127.0.0.1" in url:
+            kwargs["verify"] = False
+        else:
+            # Use the default cert store
+            kwargs["verify"] = certifi.where()
+        
+        
+        # send request
+        response = requests.request(method=method, url=url, headers=headers, **kwargs)
+        
+        # print payload response
+        print("***Payload Response:", response.text)
+         
+        # print line breaks 
+        print("\n\n")
+
+        return response
+
+    # def _process_response(self, response: requests.Response, response_model: Type[T]) -> ApiResponse[T]:
+    #     status_code = response.status_code
+    #     raw_content = response.text
+
+    #     try:
+    #         response_data = response.json()
+    #     except ValueError:
+    #         return ApiResponse[T](
+    #             succeeded=False,
+    #             http_status_code=status_code,
+    #             message="Error processing server response",
+    #             details=raw_content,
+    #             data=None
+    #         )
+
+    #     if 200 <= status_code < 300:
+            
+    #         if issubclass(response_model, BaseModel) and isinstance(response_data["data"], dict):
+    #             response_data["data"] = response_model.model_validate(response_data["data"])
+                
+    #         return ApiResponse[T].model_validate(response_data)
+
+    #     try:
+    #         generic_error = ApiResponse[object].model_validate(response_data)
+    #     except Exception:
+    #         return ApiResponse[T](
+    #             succeeded=False,
+    #             http_status_code=status_code,
+    #             message="Error processing server error response",
+    #             details=raw_content,
+    #             data=None
+    #         )
+
+    #     if status_code == 400 and isinstance(response_data.get("data"), list):
+    #         try:
+    #             failures = [ValidationFailure.model_validate(item) for item in response_data["data"]]
+    #             if failures:
+    #                 details_str = "; ".join(f"{f.propertyName}: {f.errorMessage}" for f in failures)
+    #                 return ApiResponse[T](
+    #                     succeeded=False,
+    #                     http_status_code=400,
+    #                     message=generic_error.message,
+    #                     details=details_str,
+    #                     data=None
+    #                 )
+    #         except Exception:
+    #             pass
+
+    #     return ApiResponse[T](
+    #         succeeded=False,
+    #         http_status_code=status_code,
+    #         message=generic_error.message or f"HTTP Error {status_code}",
+    #         details=generic_error.details or raw_content,
+    #         data=None
+    #     )
+
+    
+    def _process_response(self, response: requests.Response, response_model: Type[T]) -> ApiResponse[T]:
+        status_code = response.status_code
+        raw_content = response.text
+
+        try:
+            response_data = response.json()
+        except ValueError:
+            return ApiResponse[T](
+                succeeded=False,
+                http_status_code=status_code,
+                message="Error processing server response",
+                details=raw_content,
+                data=None
+            )
+
+        if 200 <= status_code < 300:
+            # -- Manejo de data con modelos pydantic o lista de modelos pydantic
+            origin = get_origin(response_model)
+            if origin == list:
+                # Significa que es algo como list[TaxFile]
+                (model_type,) = get_args(response_model)
+                # Validar cada elemento de la lista si data es una lista
+                if issubclass(model_type, BaseModel) and isinstance(response_data["data"], list):
+                    response_data["data"] = [
+                        model_type.model_validate(item) 
+                        for item in response_data["data"]
+                    ]
+            else:
+                # Manejo de caso donde response_model es un modelo Pydantic "simple"
+                if (
+                    isinstance(response_model, type) 
+                    and issubclass(response_model, BaseModel) 
+                    and isinstance(response_data["data"], dict)
+                ):
+                    response_data["data"] = response_model.model_validate(response_data["data"])
+
+            # Finalmente se parsea la respuesta como ApiResponse[T]
+            return ApiResponse[T].model_validate(response_data)
+
+        # -- Manejo de respuestas de error --
+        try:
+            generic_error = ApiResponse[object].model_validate(response_data)
+        except Exception:
+            return ApiResponse[T](
+                succeeded=False,
+                http_status_code=status_code,
+                message="Error processing server error response",
+                details=raw_content,
+                data=None
+            )
+
+        if status_code == 400 and isinstance(response_data.get("data"), list):
+            try:
+                failures = [ValidationFailure.model_validate(item) for item in response_data["data"]]
+                if failures:
+                    details_str = "; ".join(f"{f.propertyName}: {f.errorMessage}" for f in failures)
+                    return ApiResponse[T](
+                        succeeded=False,
+                        http_status_code=400,
+                        message=generic_error.message,
+                        details=details_str,
+                        data=None
+                    )
+            except Exception:
+                pass
+
+        return ApiResponse[T](
+            succeeded=False,
+            http_status_code=status_code,
+            message=generic_error.message or f"HTTP Error {status_code}",
+            details=generic_error.details or raw_content,
+            data=None
+        )
+    
+    
+    
+    # def send_request(self, method: str, endpoint: str, response_model: Type[T], **kwargs) -> ApiResponse[T]:
+    #     payload = kwargs.pop("payload", None)
+    #     if payload is not None and isinstance(payload, BaseModel):
+    #         # Excluir propiedades con valor None
+    #         kwargs["json"] = payload.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+    #     response = self._request(method, endpoint, **kwargs)
+    #     return self._process_response(response, response_model)
+    
+    def send_request(self, method: str, endpoint: str, response_model: Type[T], details: bool = False, **kwargs) -> ApiResponse[T]:
+        if details:
+            endpoint += "?details=true"
+        
+        payload = kwargs.pop("payload", None)
+        if payload is not None and isinstance(payload, BaseModel):
+            # Excluir propiedades con valor None
+            kwargs["json"] = payload.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+        response = self._request(method, endpoint, **kwargs)
+        return self._process_response(response, response_model)
+    
+    

fiscalapi-4.0.2/fiscalapi/services/catalog_service.py

@@ -0,0 +1,20 @@
+from fiscalapi.models.common_models import ApiResponse, CatalogDto, PagedList
+from fiscalapi.services.base_service import BaseService
+
+
+class CatalogService(BaseService):
+    
+    # get list of catalogs available in fiscalapi
+    def get_list(self) -> ApiResponse[list[str]]:
+        endpoint = "catalogs"
+        return self.send_request("GET", endpoint, list[str])
+
+    # get record by catalog name and its id
+    def get_record_by_id(self, catalog_name: str, id: str) -> ApiResponse[CatalogDto]:
+        endpoint = f"catalogs/{catalog_name}/key/{id}"
+        return self.send_request("GET", endpoint, CatalogDto)
+
+    # Search whithin a catalog by catalog name and search text
+    def search_catalog(self, catalog_name: str, search_text: str, page_number: int = 1, page_size: int = 50) -> ApiResponse[PagedList[CatalogDto]]:
+        endpoint = f"catalogs/{catalog_name}/{search_text}?pageNumber={page_number}&pageSize={page_size}"
+        return self.send_request("GET", endpoint, PagedList[CatalogDto])

fiscalapi-4.0.2/fiscalapi/services/fiscalapi_client.py

@@ -0,0 +1,18 @@
+from fiscalapi.models.common_models import FiscalApiSettings
+from fiscalapi.services.catalog_service import CatalogService
+from fiscalapi.services.invoice_service import InvoiceService
+from fiscalapi.services.people_service import PeopleService
+from fiscalapi.services.product_service import ProductService
+from fiscalapi.services.tax_file_servive import TaxFileService
+
+
+
+class FiscalApiClient:
+    
+    def __init__(self, settings: FiscalApiSettings):
+        self.products = ProductService(settings)
+        self.people = PeopleService(settings)
+        self.tax_files = TaxFileService(settings)
+        self.catalogs = CatalogService(settings)
+        self.invoices = InvoiceService(settings)
+        self.settings = settings

fiscalapi-4.0.2/fiscalapi/services/invoice_service.py

@@ -0,0 +1,66 @@
+from fiscalapi.models.common_models import ApiResponse, PagedList
+from fiscalapi.models.fiscalapi_models import CancelInvoiceRequest, CancelInvoiceResponse, CreatePdfRequest, FileResponse, Invoice, SendInvoiceRequest
+from fiscalapi.services.base_service import BaseService
+
+
+class InvoiceService(BaseService):
+    
+    # get paged list of invoices
+    def get_list(self, page_number: int, page_size: int) -> ApiResponse[PagedList[Invoice]]:
+        endpoint = f"invoices?pageNumber={page_number}&pageSize={page_size}"
+        return self.send_request("GET", endpoint, PagedList[Invoice])
+    
+    # get invoice by id
+    def get_by_id(self, invoice_id: int, details: bool = False) -> ApiResponse[Invoice]:
+        endpoint = f"invoices/{invoice_id}"
+        return self.send_request("GET", endpoint, Invoice, details=details)
+    
+    
+     # helper method to determine the endpoint based on invoice type
+    def _get_endpoint_by_type(self, type_code: str) -> str:
+        if type_code == "I":
+            return "invoices/income"
+        elif type_code == "E":
+            return "invoices/credit-note"
+        elif type_code == "P":
+            return "invoices/payment"
+        else:
+            raise ValueError(f"Unsupported invoice type: {type_code}")
+        
+    # create invoice
+    def create(self, invoice: Invoice) -> ApiResponse[Invoice]:
+        if invoice is None:
+            raise ValueError("request_model cannot be null")
+
+        endpoint = self._get_endpoint_by_type(invoice.type_code)
+        return self.send_request("POST", endpoint, Invoice, payload=invoice)
+    
+    
+    # cancel invoice
+    def cancel(self, cancel_invoice_request: CancelInvoiceRequest) -> ApiResponse[CancelInvoiceResponse]:
+        if cancel_invoice_request is None:
+            raise ValueError("request_model cannot be null")
+        
+        endpoint = "invoices"
+        return self.send_request("DELETE", endpoint, CancelInvoiceResponse, payload=cancel_invoice_request)
+    
+    # create invoice's pdf
+    def get_pdf(self, create_pdf_request:CreatePdfRequest) -> ApiResponse[FileResponse]:
+        if create_pdf_request is None:
+            raise ValueError("request_model cannot be null")
+        
+        endpoint = "invoices/pdf"
+        return self.send_request("POST", endpoint, FileResponse, payload=create_pdf_request)
+  
+    
+    # send invoice by email
+ 
+    def send(self, send_invoice_request : SendInvoiceRequest):
+        if not send_invoice_request:
+            raise ValueError("Invalid request")
+        
+        endpoint = "invoices/send"
+        
+        return self.send_request("POST", endpoint, bool, payload=send_invoice_request)
+    
+    

fiscalapi-4.0.2/fiscalapi/services/people_service.py

@@ -0,0 +1,32 @@
+from fiscalapi.models.common_models import ApiResponse, PagedList
+from fiscalapi.models.fiscalapi_models import Person, Product
+from fiscalapi.services.base_service import BaseService
+
+
+class PeopleService(BaseService):
+    
+    # get paged list of people
+    def get_list(self, page_number: int, page_size: int) -> ApiResponse[PagedList[Person]]:
+        endpoint = f"people?pageNumber={page_number}&pageSize={page_size}"
+        return self.send_request("GET", endpoint, PagedList[Person])
+    
+    # get person by id
+    def get_by_id(self, person_id: int) -> ApiResponse[Person]:
+        endpoint = f"people/{person_id}"
+        return self.send_request("GET", endpoint, Person)
+    
+    # create person
+    def create(self, person: Person) -> ApiResponse[Person]:
+        endpoint = "people"
+        return self.send_request("POST", endpoint, Person, payload=person)
+    
+    # update person
+    def update(self, person: Person) -> ApiResponse[Person]:
+        endpoint = f"people/{person.id}"
+        return self.send_request("PUT", endpoint, Person, payload=person)
+    
+    # delete person
+    def delete(self, person_id: str) -> ApiResponse[bool]:
+        endpoint = f"people/{person_id}"
+        return self.send_request("DELETE", endpoint, bool)
+    

fiscalapi-4.0.2/fiscalapi/services/product_service.py

@@ -0,0 +1,31 @@
+from fiscalapi.models.common_models import ApiResponse, PagedList
+from fiscalapi.models.fiscalapi_models import Product
+from fiscalapi.services.base_service import BaseService
+
+
+class ProductService(BaseService):
+    
+    # get paged list of products
+    def get_list(self, page_number: int, page_size: int) -> ApiResponse[PagedList[Product]]:
+        endpoint = f"products?pageNumber={page_number}&pageSize={page_size}"
+        return self.send_request("GET", endpoint, PagedList[Product])
+    
+    # get product by id
+    def get_by_id(self, product_id: int) -> ApiResponse[Product]:
+        endpoint = f"products/{product_id}"
+        return self.send_request("GET", endpoint, Product)
+    
+    # create product
+    def create(self, product: Product) -> ApiResponse[Product]:
+        endpoint = "products"
+        return self.send_request("POST", endpoint, Product, payload=product)
+    
+    # update product
+    def update(self, product: Product) -> ApiResponse[Product]:
+        endpoint = f"products/{product.id}"
+        return self.send_request("PUT", endpoint, Product, payload=product)
+    
+    # delete product
+    def delete(self, product_id: str) -> ApiResponse[bool]:
+        endpoint = f"products/{product_id}"
+        return self.send_request("DELETE", endpoint, bool)

fiscalapi-4.0.2/fiscalapi/services/tax_file_servive.py

@@ -0,0 +1,41 @@
+from fiscalapi.models.common_models import ApiResponse, PagedList
+from fiscalapi.models.fiscalapi_models import TaxFile
+from fiscalapi.services.base_service import BaseService
+
+class TaxFileService(BaseService):
+      
+        # get paged list of tax files
+        def get_list(self, page_number: int, page_size: int) -> ApiResponse[PagedList[TaxFile]]:
+            endpoint = f"tax-files?pageNumber={page_number}&pageSize={page_size}"
+            return self.send_request("GET", endpoint, PagedList[TaxFile])
+        
+        # get tax file by id
+        def get_by_id(self, tax_file_id: int) -> ApiResponse[TaxFile]:
+            endpoint = f"tax-files/{tax_file_id}"
+            return self.send_request("GET", endpoint, TaxFile)
+        
+                       
+        # create tax file (upload tax file)
+        def create(self, tax_file: TaxFile) -> ApiResponse[TaxFile]:
+            endpoint = "tax-files"
+            return self.send_request("POST", endpoint, TaxFile, payload=tax_file)
+        
+        
+        # delete tax file
+        def delete(self, tax_file_id: str) -> ApiResponse[bool]:
+            endpoint = f"tax-files/{tax_file_id}"
+            return self.send_request("DELETE", endpoint, bool)
+        
+         # get default tax files for a given person)
+         # obtiene el último par de certificados válidos y vigente de una persona. Es decir sus certificados por defecto.
+        def get_default_values(self, person_id: int) -> ApiResponse[list[TaxFile]]:
+            endpoint = f"tax-files/{person_id}/default-values"
+            return self.send_request("GET", endpoint, list[TaxFile])
+       
+        
+        # get default references for a given person
+        # obtiene el último par de ids de certificados válidos y vigente de una persona. Es decir sus certificados por defecto (solo los ids)
+        def get_default_references(self, person_id: int) -> ApiResponse[list[TaxFile]]:
+            endpoint = f"tax-files/{person_id}/default-references"
+            return self.send_request("GET", endpoint, list[TaxFile])
+      

{fiscalapi-4.0.0 → fiscalapi-4.0.2}/fiscalapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: fiscalapi
-Version: 4.0.0
+Version: 4.0.2
 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

fiscalapi-4.0.2/fiscalapi.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE.txt
+README.md
+setup.py
+fiscalapi/__init__.py
+fiscalapi.egg-info/PKG-INFO
+fiscalapi.egg-info/SOURCES.txt
+fiscalapi.egg-info/dependency_links.txt
+fiscalapi.egg-info/requires.txt
+fiscalapi.egg-info/top_level.txt
+fiscalapi/models/__init__.py
+fiscalapi/models/common_models.py
+fiscalapi/models/fiscalapi_models.py
+fiscalapi/services/__init__.py
+fiscalapi/services/base_service.py
+fiscalapi/services/catalog_service.py
+fiscalapi/services/fiscalapi_client.py
+fiscalapi/services/invoice_service.py
+fiscalapi/services/people_service.py
+fiscalapi/services/product_service.py
+fiscalapi/services/tax_file_servive.py

fiscalapi-4.0.2/fiscalapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+fiscalapi

{fiscalapi-4.0.0 → fiscalapi-4.0.2}/setup.py

@@ -2,7 +2,7 @@
 import os
 from setuptools import setup, find_packages
 
-VERSION = "4.0.0"
+VERSION = "4.0.2"
 # Descripción breve basada en el .csproj
 DESCRIPTION = "Genera facturas CFDI válidas ante el SAT consumiendo el API de https://www.fiscalapi.com"
 

fiscalapi-4.0.0/fiscalapi.egg-info/SOURCES.txt

@@ -1,8 +0,0 @@
-LICENSE.txt
-README.md
-setup.py
-fiscalapi.egg-info/PKG-INFO
-fiscalapi.egg-info/SOURCES.txt
-fiscalapi.egg-info/dependency_links.txt
-fiscalapi.egg-info/requires.txt
-fiscalapi.egg-info/top_level.txt

fiscalapi-4.0.0/fiscalapi.egg-info/top_level.txt

@@ -1 +0,0 @@
-