catalogmx 0.3.0__py3-none-any.whl

catalogmx/catalogs/sat/comercio_exterior/claves_pedimento.py

@@ -0,0 +1,77 @@
+"""
+Catálogo c_ClavePedimento - Claves de Pedimento Aduanero
+
+Identificadores del tipo de operación aduanera que ampara el CFDI.
+
+Fuente: SAT - Anexo 22 de las RGCE
+"""
+
+import json
+from pathlib import Path
+
+
+class ClavePedimentoCatalog:
+    """Catálogo de claves de pedimento aduanero"""
+
+    _data: list[dict] | None = None
+    _clave_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"
+                / "claves_pedimento.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("claves", data)
+
+            cls._clave_by_code = {item["clave"]: item for item in cls._data}
+
+    @classmethod
+    def get_clave(cls, code: str) -> dict | None:
+        """Obtiene una clave de pedimento por su código"""
+        cls._load_data()
+        return cls._clave_by_code.get(code.upper())
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si una clave de pedimento es válida"""
+        return cls.get_clave(code) is not None
+
+    @classmethod
+    def is_export(cls, code: str) -> bool:
+        """Verifica si la clave corresponde a exportación"""
+        clave = cls.get_clave(code)
+        return clave.get("regimen") == "exportacion" if clave else False
+
+    @classmethod
+    def is_import(cls, code: str) -> bool:
+        """Verifica si la clave corresponde a importación"""
+        clave = cls.get_clave(code)
+        return clave.get("regimen") == "importacion" if clave else False
+
+    @classmethod
+    def get_by_regime(cls, regime: str) -> list[dict]:
+        """
+        Obtiene claves por régimen
+
+        Args:
+            regime: exportacion, importacion, retorno, transito, etc.
+        """
+        cls._load_data()
+        return [item for item in cls._data if item.get("regimen") == regime]
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todas las claves de pedimento"""
+        cls._load_data()
+        return cls._data.copy()

catalogmx/catalogs/sat/comercio_exterior/estados.py

@@ -0,0 +1,122 @@
+"""Catálogo c_Estado - Estados de USA y Provincias de Canadá"""
+
+import json
+from pathlib import Path
+
+
+class EstadoCatalog:
+    """Catálogo de estados/provincias de USA y Canadá para comercio exterior"""
+
+    _estados_usa: list[dict] | None = None
+    _provincias_canada: list[dict] | None = None
+    _estado_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._estados_usa is None:
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "comercio_exterior"
+                / "estados_usa_canada.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                data = json.load(f)
+                # Handle both dict with keys or direct list
+                if isinstance(data, dict):
+                    cls._estados_usa = data.get("estados_usa", [])
+                    cls._provincias_canada = data.get("provincias_canada", [])
+                else:
+                    # Direct list - separate by country field
+                    cls._estados_usa = [item for item in data if item.get("country") == "USA"]
+                    cls._provincias_canada = [item for item in data if item.get("country") == "CAN"]
+
+            # Crear índice unificado por código
+            cls._estado_by_code = {}
+            for estado in cls._estados_usa:
+                cls._estado_by_code[estado["code"]] = estado
+            for provincia in cls._provincias_canada:
+                cls._estado_by_code[provincia["code"]] = provincia
+
+    @classmethod
+    def get_estado(cls, code: str, country: str | None = None) -> dict | None:
+        """
+        Obtiene un estado/provincia por su código
+
+        Args:
+            code: Código del estado (TX, CA, ON, etc.)
+            country: Opcional - 'USA' o 'CAN' para filtrar
+
+        Returns:
+            dict con información del estado/provincia
+        """
+        cls._load_data()
+        code_upper = code.upper()
+        estado = cls._estado_by_code.get(code_upper)
+
+        if estado and country:
+            if estado["country"] != country.upper():
+                return None
+
+        return estado
+
+    @classmethod
+    def get_estado_usa(cls, code: str) -> dict | None:
+        """Obtiene un estado de USA por su código"""
+        return cls.get_estado(code, "USA")
+
+    @classmethod
+    def get_provincia_canada(cls, code: str) -> dict | None:
+        """Obtiene una provincia de Canadá por su código"""
+        return cls.get_estado(code, "CAN")
+
+    @classmethod
+    def is_valid(cls, code: str, country: str | None = None) -> bool:
+        """Verifica si un código de estado/provincia es válido"""
+        return cls.get_estado(code, country) is not None
+
+    @classmethod
+    def get_all_usa(cls) -> list[dict]:
+        """Retorna todos los estados de USA"""
+        cls._load_data()
+        return cls._estados_usa.copy()
+
+    @classmethod
+    def get_all_canada(cls) -> list[dict]:
+        """Retorna todas las provincias de Canadá"""
+        cls._load_data()
+        return cls._provincias_canada.copy()
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todos los estados y provincias"""
+        cls._load_data()
+        return cls._estados_usa + cls._provincias_canada
+
+    @classmethod
+    def validate_foreign_address(cls, address_data: dict) -> dict:
+        """
+        Valida dirección extranjera para comercio exterior
+
+        Args:
+            address_data: dict con 'pais', 'estado', 'num_reg_id_trib'
+
+        Returns:
+            dict con 'valid' (bool) y 'errors' (list)
+        """
+        errors = []
+        pais = address_data.get("pais", "").upper()
+        estado = address_data.get("estado", "").upper()
+
+        # Validar que USA/CAN tengan estado
+        if pais in ["USA", "CAN"]:
+            if not estado:
+                errors.append(f"Campo Estado es obligatorio para país {pais}")
+            elif not cls.is_valid(estado, pais):
+                errors.append(f"Estado {estado} no válido para país {pais}")
+
+        return {"valid": len(errors) == 0, "errors": errors}

catalogmx/catalogs/sat/comercio_exterior/incoterms.py

@@ -0,0 +1,226 @@
+"""
+Catálogo c_INCOTERM - Términos Internacionales de Comercio (INCOTERMS 2020)
+
+Los INCOTERMS definen las responsabilidades entre comprador y vendedor
+en operaciones de comercio internacional.
+
+Fuente: ICC - International Chamber of Commerce / SAT México
+"""
+
+import json
+from pathlib import Path
+
+
+class IncotermsValidator:
+    """Validador y catálogo de INCOTERMS 2020 para Comercio Exterior"""
+
+    _data: list[dict] | None = None
+    _incoterm_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__)
+            # Navegar a shared-data desde packages/python/catalogmx/catalogs/sat/comercio_exterior
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "comercio_exterior"
+                / "incoterms.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("incoterms", data)
+
+            # Crear índice por código
+            cls._incoterm_by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_incoterm(cls, code: str) -> dict | None:
+        """
+        Obtiene un INCOTERM por su código
+
+        Args:
+            code: Código INCOTERM (EXW, FCA, FOB, CIF, etc.)
+
+        Returns:
+            Dict con información del INCOTERM o None si no existe
+
+        Example:
+            >>> incoterm = IncotermsValidator.get_incoterm('CIF')
+            >>> print(incoterm['name'])
+            Cost, Insurance and Freight
+        """
+        cls._load_data()
+        return cls._incoterm_by_code.get(code.upper())
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """
+        Verifica si un código INCOTERM es válido
+
+        Args:
+            code: Código INCOTERM a validar
+
+        Returns:
+            True si el código es válido
+
+        Example:
+            >>> IncotermsValidator.is_valid('FOB')
+            True
+            >>> IncotermsValidator.is_valid('XXX')
+            False
+        """
+        return cls.get_incoterm(code) is not None
+
+    @classmethod
+    def is_valid_for_transport(cls, code: str, transport_type: str) -> bool:
+        """
+        Verifica si un INCOTERM es válido para un tipo de transporte
+
+        Args:
+            code: Código INCOTERM
+            transport_type: Tipo de transporte ('sea', 'land', 'air', 'multimodal', 'any')
+
+        Returns:
+            True si el INCOTERM es válido para ese transporte
+
+        Example:
+            >>> IncotermsValidator.is_valid_for_transport('CIF', 'sea')
+            True
+            >>> IncotermsValidator.is_valid_for_transport('CIF', 'land')
+            False
+            >>> IncotermsValidator.is_valid_for_transport('FCA', 'land')
+            True
+        """
+        incoterm = cls.get_incoterm(code)
+        if not incoterm:
+            return False
+
+        suitable_for = incoterm.get("suitable_for", [])
+
+        if transport_type == "any" or incoterm["transport_mode"] == "any":
+            return True
+
+        return transport_type in suitable_for
+
+    @classmethod
+    def get_multimodal_incoterms(cls) -> list[str]:
+        """
+        Retorna lista de INCOTERMS válidos para cualquier modo de transporte
+
+        Returns:
+            Lista de códigos INCOTERM multimodales
+
+        Example:
+            >>> multimodal = IncotermsValidator.get_multimodal_incoterms()
+            >>> print(multimodal)
+            ['EXW', 'FCA', 'CPT', 'CIP', 'DAP', 'DPU', 'DDP']
+        """
+        cls._load_data()
+        return [item["code"] for item in cls._data if item["transport_mode"] == "any"]
+
+    @classmethod
+    def get_maritime_incoterms(cls) -> list[str]:
+        """
+        Retorna lista de INCOTERMS válidos solo para transporte marítimo
+
+        Returns:
+            Lista de códigos INCOTERM marítimos
+
+        Example:
+            >>> maritime = IncotermsValidator.get_maritime_incoterms()
+            >>> print(maritime)
+            ['FAS', 'FOB', 'CFR', 'CIF']
+        """
+        cls._load_data()
+        return [item["code"] for item in cls._data if item["transport_mode"] == "maritime"]
+
+    @classmethod
+    def seller_pays_freight(cls, code: str) -> bool:
+        """
+        Verifica si el vendedor paga el flete en este INCOTERM
+
+        Args:
+            code: Código INCOTERM
+
+        Returns:
+            True si el vendedor paga flete
+
+        Example:
+            >>> IncotermsValidator.seller_pays_freight('CIF')
+            True
+            >>> IncotermsValidator.seller_pays_freight('EXW')
+            False
+        """
+        incoterm = cls.get_incoterm(code)
+        return incoterm.get("seller_pays_freight", False) if incoterm else False
+
+    @classmethod
+    def seller_pays_insurance(cls, code: str) -> bool:
+        """
+        Verifica si el vendedor paga el seguro en este INCOTERM
+
+        Args:
+            code: Código INCOTERM
+
+        Returns:
+            True si el vendedor paga seguro
+
+        Example:
+            >>> IncotermsValidator.seller_pays_insurance('CIF')
+            True
+            >>> IncotermsValidator.seller_pays_insurance('CFR')
+            False
+        """
+        incoterm = cls.get_incoterm(code)
+        return incoterm.get("seller_pays_insurance", False) if incoterm else False
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """
+        Retorna todos los INCOTERMS disponibles
+
+        Returns:
+            Lista completa de INCOTERMS
+
+        Example:
+            >>> all_incoterms = IncotermsValidator.get_all()
+            >>> print(len(all_incoterms))
+            11
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def search(cls, query: str) -> list[dict]:
+        """
+        Busca INCOTERMS por nombre o descripción
+
+        Args:
+            query: Texto a buscar
+
+        Returns:
+            Lista de INCOTERMS que coinciden
+
+        Example:
+            >>> results = IncotermsValidator.search('insurance')
+            >>> print([r['code'] for r in results])
+            ['CIP', 'CIF']
+        """
+        cls._load_data()
+        query_lower = query.lower()
+
+        return [
+            item
+            for item in cls._data
+            if (
+                query_lower in item["name"].lower()
+                or query_lower in item["name_es"].lower()
+                or query_lower in item["description"].lower()
+            )
+        ]

catalogmx/catalogs/sat/comercio_exterior/monedas.py

@@ -0,0 +1,107 @@
+"""Catálogo c_Moneda - Códigos de Monedas ISO 4217"""
+
+import json
+from pathlib import Path
+
+
+class MonedaCatalog:
+    """Catálogo de monedas para operaciones de comercio exterior"""
+
+    _data: list[dict] | None = None
+    _moneda_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"
+                / "monedas.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("monedas", data)
+
+            cls._moneda_by_code = {item["codigo"]: item for item in cls._data}
+
+    @classmethod
+    def get_moneda(cls, code: str) -> dict | None:
+        """Obtiene una moneda por su código ISO 4217"""
+        cls._load_data()
+        return cls._moneda_by_code.get(code.upper())
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de moneda es válido"""
+        return cls.get_moneda(code) is not None
+
+    @classmethod
+    def validate_conversion_usd(cls, cfdi_data: dict) -> dict:
+        """
+        Valida la conversión a USD según reglas SAT
+
+        Args:
+            cfdi_data: dict con 'moneda', 'total', 'tipo_cambio_usd', 'total_usd'
+
+        Returns:
+            dict con 'valid' (bool) y 'errors' (list)
+        """
+        errors = []
+        moneda = cfdi_data.get("moneda", "").upper()
+        tipo_cambio = cfdi_data.get("tipo_cambio_usd")
+        total = cfdi_data.get("total")
+        total_usd = cfdi_data.get("total_usd")
+
+        # Validar que la moneda existe
+        if not cls.is_valid(moneda):
+            errors.append(f"Moneda {moneda} no válida")
+            return {"valid": False, "errors": errors}
+
+        # Si es USD, tipo_cambio debe ser 1
+        if moneda == "USD":
+            if tipo_cambio and tipo_cambio != 1:
+                errors.append("Para USD, TipoCambioUSD debe ser 1")
+
+            if total != total_usd:
+                errors.append("Para USD, Total debe ser igual a TotalUSD")
+
+        # Si NO es USD, tipo_cambio es obligatorio
+        else:
+            if not tipo_cambio:
+                errors.append("TipoCambioUSD es obligatorio cuando Moneda != USD")
+
+            # Validar cálculo de TotalUSD
+            if tipo_cambio and total and total_usd:
+                expected_total_usd = round(total * tipo_cambio, 2)
+                if abs(total_usd - expected_total_usd) > 0.01:
+                    errors.append(f"TotalUSD incorrecto. Esperado: {expected_total_usd}")
+
+        return {"valid": len(errors) == 0, "errors": errors}
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todas las monedas"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def search(cls, query: str) -> list[dict]:
+        """Busca monedas por código, nombre o país"""
+        cls._load_data()
+        query_lower = query.lower()
+
+        return [
+            item
+            for item in cls._data
+            if (
+                query_lower in item["codigo"].lower()
+                or query_lower in item["nombre"].lower()
+                or query_lower in item.get("pais", "").lower()
+            )
+        ]

catalogmx/catalogs/sat/comercio_exterior/motivos_traslado.py

@@ -0,0 +1,54 @@
+"""Catálogo c_MotivoTraslado - Motivos de Traslado para CFDI tipo T"""
+
+import json
+from pathlib import Path
+
+
+class MotivoTrasladoCatalog:
+    """Catálogo de motivos de traslado para CFDI con comercio exterior"""
+
+    _data: list[dict] | None = None
+    _motivo_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"
+                / "motivos_traslado.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("motivos", data)
+
+            cls._motivo_by_code = {item["code"]: item for item in cls._data}
+
+    @classmethod
+    def get_motivo(cls, code: str) -> dict | None:
+        """Obtiene un motivo de traslado por su código"""
+        cls._load_data()
+        return cls._motivo_by_code.get(code)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de motivo es válido"""
+        return cls.get_motivo(code) is not None
+
+    @classmethod
+    def requires_propietario(cls, code: str) -> bool:
+        """Verifica si el motivo requiere nodo <Propietario>"""
+        motivo = cls.get_motivo(code)
+        return motivo.get("requires_propietario", False) if motivo else False
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todos los motivos de traslado"""
+        cls._load_data()
+        return cls._data.copy()

catalogmx/catalogs/sat/comercio_exterior/paises.py

@@ -0,0 +1,88 @@
+"""Catálogo c_Pais - Códigos de Países ISO 3166-1"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class PaisCatalog:
+    """Catálogo de países para identificar origen/destino en comercio exterior"""
+
+    _data: list[dict] | None = None
+    _pais_by_code: dict[str, dict] | None = None
+    _pais_by_iso2: 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"
+                / "paises.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+            cls._pais_by_code = {item["codigo"]: item for item in cls._data}
+            cls._pais_by_iso2 = {item["iso2"]: item for item in cls._data}
+
+    @classmethod
+    def get_pais(cls, code: str) -> dict | None:
+        """Obtiene un país por su código ISO 3166-1 Alpha-3"""
+        cls._load_data()
+        code_upper = code.upper()
+
+        # Intentar primero con Alpha-3
+        pais = cls._pais_by_code.get(code_upper)
+        if pais:
+            return pais
+
+        # Intentar con Alpha-2
+        return cls._pais_by_iso2.get(code_upper)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de país es válido"""
+        return cls.get_pais(code) is not None
+
+    @classmethod
+    def requires_subdivision(cls, code: str) -> bool:
+        """
+        Verifica si el país requiere subdivisión (estado/provincia)
+
+        Args:
+            code: Código del país (USA, CAN, etc.)
+
+        Returns:
+            True si requiere estado/provincia
+        """
+        pais = cls.get_pais(code)
+        return pais.get("requiere_subdivision", False) if pais else False
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Retorna todos los países"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def search(cls, query: str) -> list[dict]:
+        """Busca países por código o nombre (insensible a acentos)"""
+        cls._load_data()
+        query_normalized = normalize_text(query)
+
+        return [
+            item
+            for item in cls._data
+            if (
+                query_normalized in normalize_text(item["codigo"])
+                or query_normalized in normalize_text(item["nombre"])
+                or query_normalized in normalize_text(item.get("iso2", ""))
+            )
+        ]