catalogmx 0.3.0__py3-none-any.whl

catalogmx/catalogs/sat/comercio_exterior/registro_ident_trib.py

@@ -0,0 +1,76 @@
+"""Catálogo c_RegistroIdentTribReceptor - Tipos de Registro de Identificación Tributaria"""
+
+import json
+import re
+from pathlib import Path
+
+
+class RegistroIdentTribCatalog:
+    """Catálogo de tipos de registro tributario del receptor extranjero"""
+
+    _data: list[dict] | None = None
+    _tipo_by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Carga los datos del catálogo desde el archivo JSON compartido"""
+        if cls._data is None:
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "comercio_exterior"
+                / "registro_ident_trib.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("tipos_registro", data)
+
+            cls._tipo_by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_tipo(cls, code: str) -> dict | None:
+        """Obtiene un tipo de registro por su código"""
+        cls._load_data()
+        return cls._tipo_by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de tipo es válido"""
+        return cls.get_tipo(code) is not None
+
+    @classmethod
+    def validate_tax_id(cls, tipo_registro: str, num_reg_id_trib: str) -> dict:
+        """
+        Valida un número de identificación tributaria según su tipo
+
+        Args:
+            tipo_registro: Código del tipo de registro
+            num_reg_id_trib: Número de identificación tributaria
+
+        Returns:
+            dict con 'valid' (bool) y 'errors' (list)
+        """
+        tipo = cls.get_tipo(tipo_registro)
+        if not tipo:
+            return {"valid": False, "errors": ["Tipo de registro no válido"]}
+
+        errors = []
+
+        # Validar formato si está definido
+        format_pattern = tipo.get("format_pattern")
+        if format_pattern:
+            if not re.match(format_pattern, num_reg_id_trib):
+                format_desc = tipo.get("format_description", "formato no válido")
+                errors.append(f"Formato incorrecto. Esperado: {format_desc}")
+
+        return {"valid": len(errors) == 0, "errors": errors}
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todos los tipos de registro tributario"""
+        cls._load_data()
+        return cls._data.copy()

catalogmx/catalogs/sat/comercio_exterior/unidades_aduana.py

@@ -0,0 +1,54 @@
+"""Catálogo c_UnidadAduana - Unidades de Medida Aduanera"""
+
+import json
+from pathlib import Path
+
+
+class UnidadAduanaCatalog:
+    """Catálogo de unidades de medida reconocidas por aduanas"""
+
+    _data: list[dict] | None = None
+    _unidad_by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Carga los datos del catálogo desde el archivo JSON compartido"""
+        if cls._data is None:
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "comercio_exterior"
+                / "unidades_aduana.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("unidades", data)
+
+            cls._unidad_by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_unidad(cls, code: str) -> dict | None:
+        """Obtiene una unidad de medida por su código"""
+        cls._load_data()
+        return cls._unidad_by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de unidad es válido"""
+        return cls.get_unidad(code) is not None
+
+    @classmethod
+    def get_by_type(cls, unit_type: str) -> list[dict]:
+        """Obtiene unidades por tipo (weight, volume, length, area, unit, container)"""
+        cls._load_data()
+        return [item for item in cls._data if item.get("type") == unit_type]
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todas las unidades de medida aduanera"""
+        cls._load_data()
+        return cls._data.copy()

catalogmx/catalogs/sat/comercio_exterior/validator.py

@@ -0,0 +1,212 @@
+"""
+Validador completo para CFDI con Complemento de Comercio Exterior 2.0
+
+Integra todos los catálogos para validación completa de un CFDI con
+el complemento de comercio exterior.
+"""
+
+from .claves_pedimento import ClavePedimentoCatalog
+from .estados import EstadoCatalog
+from .incoterms import IncotermsValidator
+from .monedas import MonedaCatalog
+from .motivos_traslado import MotivoTrasladoCatalog
+from .paises import PaisCatalog
+from .registro_ident_trib import RegistroIdentTribCatalog
+from .unidades_aduana import UnidadAduanaCatalog
+
+
+class ComercioExteriorValidator:
+    """Validador completo para CFDI con Complemento Comercio Exterior 2.0"""
+
+    @classmethod
+    def validate(cls, cfdi_ce: dict) -> dict:
+        """
+        Valida un CFDI completo con Complemento de Comercio Exterior
+
+        Args:
+            cfdi_ce: Dict con todos los campos del CFDI y complemento
+
+        Returns:
+            Dict con 'valid' (bool), 'errors' (list), 'warnings' (list)
+
+        Example:
+            >>> cfdi_ce = {
+            ...     'tipo_comprobante': 'I',
+            ...     'incoterm': 'CIF',
+            ...     'clave_pedimento': 'A1',
+            ...     'moneda': 'USD',
+            ...     'tipo_cambio_usd': 1.0,
+            ...     'total_usd': 50000.00,
+            ...     'mercancias': [...]
+            ... }
+            >>> result = ComercioExteriorValidator.validate(cfdi_ce)
+            >>> if not result['valid']:
+            ...     for error in result['errors']:
+            ...         print(f"Error: {error}")
+        """
+        errors = []
+        warnings = []
+
+        # 1. Validar INCOTERM
+        incoterm = cfdi_ce.get("incoterm")
+        if not incoterm:
+            errors.append("INCOTERM es obligatorio")
+        elif not IncotermsValidator.is_valid(incoterm):
+            errors.append(f"INCOTERM {incoterm} no válido")
+
+        # 2. Validar Clave de Pedimento
+        clave_pedimento = cfdi_ce.get("clave_pedimento")
+        if not clave_pedimento:
+            errors.append("ClavePedimento es obligatoria")
+        elif not ClavePedimentoCatalog.is_valid(clave_pedimento):
+            errors.append(f"ClavePedimento {clave_pedimento} no válida")
+
+        # 3. Validar Moneda y conversión USD
+        moneda_result = MonedaCatalog.validate_conversion_usd(
+            {
+                "moneda": cfdi_ce.get("moneda"),
+                "total": cfdi_ce.get("total"),
+                "tipo_cambio_usd": cfdi_ce.get("tipo_cambio_usd"),
+                "total_usd": cfdi_ce.get("total_usd"),
+            }
+        )
+        errors.extend(moneda_result["errors"])
+
+        # 4. Validar Mercancías
+        mercancias = cfdi_ce.get("mercancias", [])
+        if not mercancias:
+            errors.append("Debe incluir al menos una mercancía")
+        else:
+            for i, merc in enumerate(mercancias):
+                merc_errors = cls._validate_mercancia(merc, i)
+                errors.extend(merc_errors)
+
+        # 5. Validar Receptor (dirección extranjera)
+        receptor = cfdi_ce.get("receptor", {})
+        if receptor:
+            receptor_result = cls._validate_receptor(receptor)
+            errors.extend(receptor_result["errors"])
+
+        # 6. Validar Motivo Traslado (solo si tipo comprobante = T)
+        tipo_comprobante = cfdi_ce.get("tipo_comprobante")
+        if tipo_comprobante == "T":
+            motivo_traslado = cfdi_ce.get("motivo_traslado")
+            if not motivo_traslado:
+                errors.append("MotivoTraslado es obligatorio para CFDI tipo T")
+            elif not MotivoTrasladoCatalog.is_valid(motivo_traslado):
+                errors.append(f"MotivoTraslado {motivo_traslado} no válido")
+            elif MotivoTrasladoCatalog.requires_propietario(motivo_traslado):
+                propietarios = cfdi_ce.get("propietarios", [])
+                if not propietarios:
+                    errors.append("MotivoTraslado 05 requiere al menos un Propietario")
+
+        # 7. Certificado de Origen (opcional pero validar si presente)
+        certificado_origen = cfdi_ce.get("certificado_origen")
+        if certificado_origen and certificado_origen not in ["0", "1"]:
+            errors.append("CertificadoOrigen debe ser 0 o 1")
+
+        return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+    @classmethod
+    def _validate_mercancia(cls, mercancia: dict, index: int) -> list[str]:
+        """Valida una mercancía individual"""
+        errors = []
+        prefix = f"Mercancía[{index}]"
+
+        # Fracción arancelaria (omitida por ahora, requiere TIGIE/SQLite)
+        fraccion = mercancia.get("fraccion_arancelaria")
+        if not fraccion:
+            errors.append(f"{prefix}: FraccionArancelaria es obligatoria")
+        elif len(fraccion) not in [8, 10]:
+            errors.append(f"{prefix}: FraccionArancelaria debe tener 8 o 10 dígitos")
+
+        # Unidad de medida aduanera
+        unidad_aduana = mercancia.get("unidad_aduana")
+        if not unidad_aduana:
+            errors.append(f"{prefix}: UnidadAduana es obligatoria")
+        elif not UnidadAduanaCatalog.is_valid(unidad_aduana):
+            errors.append(f"{prefix}: UnidadAduana {unidad_aduana} no válida")
+
+        # Cantidad
+        cantidad = mercancia.get("cantidad_aduana")
+        if not cantidad or cantidad <= 0:
+            errors.append(f"{prefix}: CantidadAduana debe ser mayor a 0")
+
+        # Valor unitario
+        valor_unitario = mercancia.get("valor_unitario_aduana")
+        if not valor_unitario or valor_unitario <= 0:
+            errors.append(f"{prefix}: ValorUnitarioAduana debe ser mayor a 0")
+
+        # País de origen
+        pais_origen = mercancia.get("pais_origen")
+        if not pais_origen:
+            errors.append(f"{prefix}: PaisOrigen es obligatorio")
+        elif not PaisCatalog.is_valid(pais_origen):
+            errors.append(f"{prefix}: PaisOrigen {pais_origen} no válido")
+
+        return errors
+
+    @classmethod
+    def _validate_receptor(cls, receptor: dict) -> dict:
+        """Valida los datos del receptor extranjero"""
+        errors = []
+
+        # Validar país
+        pais = receptor.get("pais")
+        if not pais:
+            errors.append("Receptor.Pais es obligatorio")
+        elif not PaisCatalog.is_valid(pais):
+            errors.append(f"Receptor.Pais {pais} no válido")
+
+        # Validar estado (obligatorio para USA/CAN)
+        if pais:
+            address_result = EstadoCatalog.validate_foreign_address(
+                {"pais": pais, "estado": receptor.get("estado", "")}
+            )
+            errors.extend(address_result["errors"])
+
+        # Validar tipo y número de identificación tributaria
+        tipo_reg = receptor.get("tipo_registro_trib")
+        num_reg = receptor.get("num_reg_id_trib")
+
+        if tipo_reg and num_reg:
+            tax_id_result = RegistroIdentTribCatalog.validate_tax_id(tipo_reg, num_reg)
+            errors.extend(tax_id_result["errors"])
+
+        return {"errors": errors}
+
+    @classmethod
+    def validate_quick(cls, field: str, value: str) -> bool:
+        """
+        Validación rápida de un campo individual
+
+        Args:
+            field: Nombre del campo (incoterm, clave_pedimento, etc.)
+            value: Valor a validar
+
+        Returns:
+            True si el valor es válido
+
+        Example:
+            >>> ComercioExteriorValidator.validate_quick('incoterm', 'FOB')
+            True
+            >>> ComercioExteriorValidator.validate_quick('clave_pedimento', 'A1')
+            True
+        """
+        validators = {
+            "incoterm": IncotermsValidator.is_valid,
+            "clave_pedimento": ClavePedimentoCatalog.is_valid,
+            "unidad_aduana": UnidadAduanaCatalog.is_valid,
+            "motivo_traslado": MotivoTrasladoCatalog.is_valid,
+            "tipo_registro_trib": RegistroIdentTribCatalog.is_valid,
+            "moneda": MonedaCatalog.is_valid,
+            "pais": PaisCatalog.is_valid,
+            "estado_usa": lambda v: EstadoCatalog.is_valid(v, "USA"),
+            "provincia_canada": lambda v: EstadoCatalog.is_valid(v, "CAN"),
+        }
+
+        validator = validators.get(field)
+        if not validator:
+            raise ValueError(f"Campo {field} no soportado para validación")
+
+        return validator(value)

catalogmx/catalogs/sat/nomina/__init__.py

@@ -0,0 +1,19 @@
+"""Catálogos SAT Nómina 1.2"""
+
+from .banco import BancoCatalog
+from .periodicidad_pago import PeriodicidadPagoCatalog
+from .riesgo_puesto import RiesgoPuestoCatalog
+from .tipo_contrato import TipoContratoCatalog
+from .tipo_jornada import TipoJornadaCatalog
+from .tipo_nomina import TipoNominaCatalog
+from .tipo_regimen import TipoRegimenCatalog
+
+__all__ = [
+    "TipoNominaCatalog",
+    "TipoContratoCatalog",
+    "TipoJornadaCatalog",
+    "TipoRegimenCatalog",
+    "PeriodicidadPagoCatalog",
+    "RiesgoPuestoCatalog",
+    "BancoCatalog",
+]

catalogmx/catalogs/sat/nomina/banco.py

@@ -0,0 +1,50 @@
+"""Catálogo c_Banco"""
+
+import json
+from pathlib import Path
+
+
+class BancoCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+    _by_name: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "nomina_1.2"
+                / "banco.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("bancos", data)
+            cls._by_code = {item["code"]: item for item in cls._data}
+            cls._by_name = {item["name"]: item for item in cls._data}
+
+    @classmethod
+    def get_banco(cls, code: str) -> dict | None:
+        """Obtiene banco por código"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def get_by_name(cls, name: str) -> dict | None:
+        """Obtiene banco por nombre corto"""
+        cls._load_data()
+        return cls._by_name.get(name)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de banco es válido"""
+        return cls.get_banco(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los bancos"""
+        cls._load_data()
+        return cls._data.copy()

catalogmx/catalogs/sat/nomina/periodicidad_pago.py

@@ -0,0 +1,48 @@
+"""Catálogo c_PeriodicidadPago"""
+
+import json
+from pathlib import Path
+
+
+class PeriodicidadPagoCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "nomina_1.2"
+                / "periodicidad_pago.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("periodicidades", data)
+            cls._by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_periodicidad(cls, code: str) -> dict | None:
+        """Obtiene periodicidad de pago por código"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de periodicidad es válido"""
+        return cls.get_periodicidad(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todas las periodicidades"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_days(cls, code: str) -> int | None:
+        """Obtiene el número de días de la periodicidad"""
+        periodicidad = cls.get_periodicidad(code)
+        return periodicidad.get("days") if periodicidad else None

catalogmx/catalogs/sat/nomina/riesgo_puesto.py

@@ -0,0 +1,56 @@
+"""Catálogo c_RiesgoPuesto"""
+
+import json
+from pathlib import Path
+
+
+class RiesgoPuestoCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "nomina_1.2"
+                / "riesgo_puesto.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("riesgos", data)
+            cls._by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_riesgo(cls, code: str) -> dict | None:
+        """Obtiene nivel de riesgo por código"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de riesgo es válido"""
+        return cls.get_riesgo(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los niveles de riesgo"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_prima_media(cls, code: str) -> float | None:
+        """Obtiene la prima media del nivel de riesgo"""
+        riesgo = cls.get_riesgo(code)
+        return riesgo.get("prima_media") if riesgo else None
+
+    @classmethod
+    def validate_prima(cls, code: str, prima: float) -> bool:
+        """Valida que la prima esté en el rango permitido"""
+        riesgo = cls.get_riesgo(code)
+        if not riesgo:
+            return False
+        return riesgo["prima_min"] <= prima <= riesgo["prima_max"]

catalogmx/catalogs/sat/nomina/tipo_contrato.py

@@ -0,0 +1,47 @@
+"""Catálogo c_TipoContrato"""
+
+import json
+from pathlib import Path
+
+
+class TipoContratoCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "nomina_1.2"
+                / "tipo_contrato.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("contratos", data)
+            cls._by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_contrato(cls, code: str) -> dict | None:
+        """Obtiene tipo de contrato por código"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de contrato es válido"""
+        return cls.get_contrato(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los tipos de contrato"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def is_indeterminado(cls, code: str) -> bool:
+        """Verifica si es contrato por tiempo indeterminado"""
+        return code == "01"

catalogmx/catalogs/sat/nomina/tipo_jornada.py

@@ -0,0 +1,42 @@
+"""Catálogo c_TipoJornada"""
+
+import json
+from pathlib import Path
+
+
+class TipoJornadaCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "nomina_1.2"
+                / "tipo_jornada.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("jornadas", data)
+            cls._by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_jornada(cls, code: str) -> dict | None:
+        """Obtiene tipo de jornada por código"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de jornada es válido"""
+        return cls.get_jornada(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los tipos de jornada"""
+        cls._load_data()
+        return cls._data.copy()

catalogmx/catalogs/sat/nomina/tipo_nomina.py

@@ -0,0 +1,52 @@
+"""Catálogo c_TipoNomina"""
+
+import json
+from pathlib import Path
+
+
+class TipoNominaCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "nomina_1.2"
+                / "tipo_nomina.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both list and dict formats
+                cls._data = data if isinstance(data, list) else data.get("tipos", data)
+            cls._by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_tipo(cls, code: str) -> dict | None:
+        """Obtiene tipo de nómina por código"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de tipo de nómina es válido"""
+        return cls.get_tipo(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los tipos de nómina"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def is_ordinaria(cls, code: str) -> bool:
+        """Verifica si es nómina ordinaria"""
+        return code == "O"
+
+    @classmethod
+    def is_extraordinaria(cls, code: str) -> bool:
+        """Verifica si es nómina extraordinaria"""
+        return code == "E"