py-vucem 0.1.0__py3-none-any.whl

py_vucem/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from py_vucem.client import VucemClient
+from py_vucem.tipos_documento import TipoDocumento, TIPOS_DOCUMENTO
+from py_vucem.utils.banxico import BanxicoClient, BanxicoError

py_vucem/client.py

@@ -0,0 +1,316 @@
+from py_vucem.utils import FielHandler
+from py_vucem.services.cove_consulta import CoveConsultaService
+from py_vucem.services.digitalizar_documento import DigitalizacionService
+from py_vucem.services.pedimentos_service import PedimentosService
+from py_vucem.services.manifestacion_service import ManifestacionService
+
+class VucemClient:
+    """Cliente central de VUCEM."""
+
+    def __init__(self, cer_path: str, key_path: str, password: str, clave_ws: str, rfc: str, ambiente: str = "PROD"):
+        self.ambiente = ambiente.upper()
+        self.clave_ws = clave_ws
+
+        self.fiel = FielHandler(cer_path, key_path, password)
+        self.rfc = rfc or self.fiel.obtener_rfc()
+
+        # Caché de instancias
+        self._cove_consulta_service = None
+        self._digitalizacion_service = None
+        self._pedimentos_service = None
+        self._manifestacion_service = None
+
+    @property
+    def url_base(self) -> str:
+        if self.ambiente == "TEST":
+            return "https://qa.vucem.gob.mx"
+        return "https://www.ventanillaunica.gob.mx"
+
+    @property
+    def servicio_cove_consulta(self) -> CoveConsultaService:
+        """Propiedad perezosa para el servicio de Consulta de COVE."""
+        if self._cove_consulta_service is None:
+            wsdl_url = f"{self.url_base}/ventanilla/ConsultarEdocumentService?wsdl"
+            self._cove_consulta_service = CoveConsultaService(
+                wsdl_url=wsdl_url,
+                username=self.rfc,
+                password_ws=self.clave_ws
+            )
+        return self._cove_consulta_service
+
+    # -------------------------------------------------------------------------
+    # Métodos Públicos
+    # -------------------------------------------------------------------------
+
+    def consultar_cove(self, edocument: str):
+        """
+        Consulta y descarga un COVE específico utilizando su eDocument.
+        """
+        return self.servicio_cove_consulta.consultar_cove(
+            fiel=self.fiel,
+            rfc=self.rfc,
+            edocument=edocument
+        )
+    
+    @property
+    def servicio_digitalizacion(self) -> DigitalizacionService:
+        if self._digitalizacion_service is None:
+            # VUCEM no sirve el ?wsdl de digitalización; el servicio usa el WSDL
+            # local empaquetado y sólo necesita el endpoint SOAP real (puerto 443).
+            endpoint_url = f"{self.url_base}/ventanilla/DigitalizarDocumentoService"
+
+            self._digitalizacion_service = DigitalizacionService(
+                endpoint_url=endpoint_url,
+                username=self.rfc,
+                password_ws=self.clave_ws
+            )
+        return self._digitalizacion_service
+    
+   
+    def digitalizar_documento(self, correo: str, id_tipo_documento: str, nombre_documento: str,
+                              archivo_bytes: bytes, rfc_consulta: str = None):
+        """Genera un e-Document a partir de un archivo PDF válido en VUCEM."""
+        return self.servicio_digitalizacion.digitalizar_documento(
+            fiel=self.fiel,
+            rfc_solicitante=self.rfc,
+            correo=correo,
+            id_tipo_documento=id_tipo_documento,
+            nombre_documento=nombre_documento,
+            archivo_bytes=archivo_bytes,
+            rfc_consulta=rfc_consulta
+        )
+
+    def consultar_tipos_documento(self):
+        """Consulta el catálogo de tipos de documento disponibles en VUCEM."""
+        return self.servicio_digitalizacion.consultar_tipos_documento(
+            fiel=self.fiel,
+            rfc=self.rfc
+        )
+
+    def consultar_estatus_digitalizacion(self, numero_operacion: int):
+        """Consulta el estatus/resultado de una digitalización por su numeroOperacion."""
+        return self.servicio_digitalizacion.consultar_estatus(
+            fiel=self.fiel,
+            rfc=self.rfc,
+            numero_operacion=numero_operacion
+        )
+
+    @property
+    def servicio_pedimentos(self) -> PedimentosService:
+        if self._pedimentos_service is None:
+            self._pedimentos_service = PedimentosService(
+                url_base=self.url_base,
+                username=self.rfc,
+                password_ws=self.clave_ws,
+            )
+        return self._pedimentos_service
+
+    def listar_pedimentos(self, aduana: str,
+                          patente: int = None, pedimento: int = None,
+                          edocument_cove: str = None, rfc: str = None,
+                          contenedor: str = None, guia: str = None,
+                          fecha_inicio=None, fecha_fin=None):
+        """Lista pedimentos filtrados. aduana debe ser string de 3 dígitos (ej. '016').
+
+        Combinaciones válidas (aduana siempre requerida):
+            listar_pedimentos('016', pedimento=6006665)
+            listar_pedimentos('016', patente=3977, fecha_inicio=date(2026,1,1), fecha_fin=date(2026,6,30))
+            listar_pedimentos('016', rfc='PME241011C34', fecha_inicio=date(2026,1,1), fecha_fin=date(2026,6,30))
+        """
+        return self.servicio_pedimentos.listar_pedimentos(
+            aduana=aduana,
+            patente=patente,
+            pedimento=pedimento,
+            edocument_cove=edocument_cove,
+            rfc=rfc,
+            contenedor=contenedor,
+            guia=guia,
+            fecha_inicio=fecha_inicio,
+            fecha_fin=fecha_fin,
+        )
+
+    def consultar_estado_pedimentos(self, aduana: int, patente: int, pedimento: int, numero_operacion: int):
+        """Consulta el estado de un pedimento aduanal."""
+        return self.servicio_pedimentos.consultar_estado_pedimentos(
+            aduana=aduana,
+            patente=patente,
+            pedimento=pedimento,
+            numero_operacion=numero_operacion,
+        )
+
+    def consultar_remesas(self, aduana: int, patente: int, pedimento: int, numero_operacion: int):
+        """Consulta las remesas asociadas a un pedimento."""
+        return self.servicio_pedimentos.consultar_remesas(
+            aduana=aduana,
+            patente=patente,
+            pedimento=pedimento,
+            numero_operacion=numero_operacion,
+        )
+
+    def consultar_partida(self, aduana: str, patente: int, pedimento: int,
+                          numero_operacion: int, numero_partida: int):
+        """Consulta el detalle de una partida específica de un pedimento."""
+        return self.servicio_pedimentos.consultar_partida(
+            aduana=aduana,
+            patente=patente,
+            pedimento=pedimento,
+            numero_operacion=numero_operacion,
+            numero_partida=numero_partida,
+        )
+
+    def consultar_pedimento_completo(self, aduana: str, patente: int, pedimento: int):
+        """Consulta el detalle completo de un pedimento aduanal."""
+        return self.servicio_pedimentos.consultar_pedimento_completo(
+            aduana=aduana,
+            patente=patente,
+            pedimento=pedimento,
+        )
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Manifestación de Valor Electrónica (MV)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    @property
+    def servicio_manifestacion(self) -> ManifestacionService:
+        if self._manifestacion_service is None:
+            self._manifestacion_service = ManifestacionService(
+                username=self.rfc,
+                password_ws=self.clave_ws,
+            )
+        return self._manifestacion_service
+
+    def consultar_manifestacion(self, numero_operacion: int = None, edocument: str = None):
+        """Consulta una MV por su numero_operacion o su eDocument (número MV tipo MNVA…).
+
+        Solo uno de los dos parámetros es necesario.
+        """
+        return self.servicio_manifestacion.consultar_manifestacion(
+            numero_operacion=numero_operacion,
+            edocument=edocument,
+        )
+
+    def registrar_manifestacion(self, rfc_importador: str, documentos: list,
+                                informacion_coves: list, valor_en_aduana: dict,
+                                personas_consulta: list = None):
+        """Registra una nueva Manifestación de Valor en VUCEM.
+
+        Consulta ManifestacionService.registrar_manifestacion para la estructura
+        esperada de informacion_coves y valor_en_aduana.
+
+        Returns:
+            {'numeroOperacion': int, 'mensaje': [...]} en éxito.
+        """
+        return self.servicio_manifestacion.registrar_manifestacion(
+            fiel=self.fiel,
+            rfc_importador=rfc_importador,
+            documentos=documentos,
+            informacion_coves=informacion_coves,
+            valor_en_aduana=valor_en_aduana,
+            personas_consulta=personas_consulta,
+        )
+
+    def registrar_manifestacion_desde_xml(self, xml_str: str) -> dict:
+        """Envia el XML SOAP firmado directamente a VUCEM (sin validacion zeep).
+
+        Usa registrar_desde_xml() para evitar el rechazo por minOccurs
+        cuando precioPorPagar / compensoPago / decrementables estan vacios.
+        """
+        return self.servicio_manifestacion.registrar_desde_xml(xml_str)
+
+    def descargar_acuse(self, id_edocument: str, es_cove: bool = False) -> dict:
+        """Descarga el acuse PDF de un trámite por su eDocument.
+
+        Usa el servicio oficial VUCEM (Hoja Informativa No. 23):
+        https://www.ventanillaunica.gob.mx/ventanilla-acuses-HA/ConsultaAcusesServiceWS?wsdl
+
+        Args:
+            id_edocument: eDocument del trámite (número numérico o COVE...).
+            es_cove: True para usar consultarAcuseCove (COVEs),
+                     False para consultarAcuseEdocument (digitalizaciones).
+
+        Returns:
+            dict con 'pdf' (bytes) si se descargó, o 'error'/'_raw' para depuración.
+        """
+        return self.servicio_manifestacion.descargar_acuse(id_edocument, es_cove=es_cove)
+
+    def actualizar_manifestacion(self, numero_mv: str, edocuments: list,
+                                 personas_consulta: list = None):
+        """Agrega e-Documents y/o personas autorizadas a una MV existente.
+
+        Args:
+            numero_mv: Identificador MV, ej. "MNVA250000XXX".
+            edocuments: Lista de eDocument strings a agregar.
+            personas_consulta: Lista de {"rfc": ..., "tipoFigura": ...} (opcional).
+        """
+        return self.servicio_manifestacion.actualizar_manifestacion(
+            fiel=self.fiel,
+            numero_mv=numero_mv,
+            edocuments=edocuments,
+            personas_consulta=personas_consulta,
+        )
+
+    def registrar_manifestacion_desde_modelo(self, modelo: dict):
+        """Registra una MV a partir del modelo amigable (formato mv_modelo.json).
+
+        El mapper:
+          - Distribuye los pedimentos del root a todos los COVEs
+            (cada factura puede sobreescribir con su propio campo 'pedimentos')
+          - Calcula valor_en_aduana automáticamente sumando todos los montos
+          - Convierte fechas (YYYY-MM-DD o DD/MM/YYYY → datetime)
+          - Convierte vinculacion/cargoImportador bool → 0/1
+
+        Uso::
+
+            import json
+            modelo = json.load(open("mi_mv.json"))
+            resultado = client.registrar_manifestacion_desde_modelo(modelo)
+
+        Args:
+            modelo: dict cargado desde mv_modelo.json (o construido en código).
+
+        Returns:
+            {'numeroOperacion': int, 'mensaje': [...]} en éxito.
+        """
+        from py_vucem.models.mv_mapper import desde_modelo
+        datos = desde_modelo(modelo)
+        return self.registrar_manifestacion(**datos)
+
+    def generar_xml_mv(self, modelo: dict, con_firma: bool = False) -> str:
+        """Genera el XML SOAP completo de MVE sin enviarlo (para preview o depuración).
+
+        Args:
+            modelo:    dict con el formato amigable de mv_modelo.json.
+            con_firma: si True incluye la firma electrónica real de la FIEL configurada;
+                       si False (default) usa placeholders para revisión rápida.
+
+        Returns:
+            String XML SOAP formateado, listo para imprimir, guardar o depurar.
+        """
+        from py_vucem.models.mv_xml import generar_xml
+        return generar_xml(
+            modelo=modelo,
+            rfc=self.rfc,
+            clave_ws=self.clave_ws,
+            fiel=self.fiel if con_firma else None,
+        )
+
+    def validar_xml_mv(self, xml_string: str) -> list[str]:
+        """Valida un XML SOAP de MVE contra el XSD de VUCEM.
+
+        Útil para verificar que el XML generado es correcto antes de enviarlo.
+
+        Args:
+            xml_string: XML generado por ``generar_xml_mv`` o ``generar_xml``.
+
+        Returns:
+            Lista de errores (vacía = XML válido).
+
+        Ejemplo::
+
+            xml = client.generar_xml_mv(modelo)
+            errores = client.validar_xml_mv(xml)
+            if not errores:
+                resultado = client.registrar_manifestacion_desde_modelo(modelo)
+        """
+        from py_vucem.models.mv_xml import validar_xml
+        return validar_xml(xml_string)

py_vucem/exceptions.py

@@ -0,0 +1,7 @@
+class VucemError(Exception):
+    """Clase base para todas las excepciones de py_vucem."""
+    pass
+
+class VucemDocumentoInvalidoError(VucemError):
+    """Excepción lanzada cuando un documento viola las reglas físicas de VUCEM."""
+    pass

py_vucem/models/__init__.py

@@ -0,0 +1,4 @@
+from py_vucem.models.mv_mapper import desde_modelo
+from py_vucem.models.mv_xml import generar_xml, generar_xml_cuerpo, validar_xml
+
+__all__ = ["desde_modelo", "generar_xml", "generar_xml_cuerpo", "validar_xml"]

py_vucem/models/mv_builder.py

@@ -0,0 +1,295 @@
+"""Builder de Manifestacion de Valor Electronica.
+
+Permite construir una MVE paso a paso en codigo, sin necesidad de JSON.
+Si se configura un BanxicoClient, el TC se consulta automaticamente
+por fecha y moneda desde el SIE de Banco de Mexico.
+
+Uso SIN TC automatico (tc manual obligatorio):
+    mv = ManifestacionValor("PME241011C34")
+    f = mv.nueva_factura("COVE2680TJDY6", incoterm="TIPINC.FOB")
+    f.agregar_pago(total=21328, forma="FORPAG.TE", moneda="USD",
+                   tc=20.1234, fecha="2026-02-03")
+
+Uso CON TC automatico (Banxico):
+    from py_vucem.utils.banxico import BanxicoClient
+    banxico = BanxicoClient("tu-token-banxico")
+
+    mv = ManifestacionValor("PME241011C34", banxico=banxico)
+    f = mv.nueva_factura("COVE2680TJDY6", incoterm="TIPINC.FOB")
+    f.agregar_pago(total=21328, forma="FORPAG.TE", moneda="USD",
+                   fecha="2026-02-03")  # tc se consulta solo
+
+Registro final:
+    resultado = client.registrar_manifestacion_desde_modelo(mv.to_dict())
+    xml       = client.generar_xml_mv(mv.to_dict())
+"""
+
+from decimal import Decimal
+
+
+class Factura:
+    """Una factura (COVE) dentro de una ManifestacionValor."""
+
+    def __init__(self, cove: str, incoterm: str, vinculacion: bool = False,
+                 metodo: str = "VALADU.VTM", banxico=None):
+        self.cove = cove
+        self.incoterm = incoterm
+        self.vinculacion = vinculacion
+        self.metodo = metodo
+        self._banxico = banxico
+        self._pagado: list[dict] = []
+        self._por_pagar: list[dict] = []
+        self._compenso: list[dict] = []
+        self._incrementables: list[dict] = []
+        self._decrementables: list[dict] = []
+        self._pedimentos: list[dict] | None = None
+
+    # ── Resolucion de TC ──────────────────────────────────────────────────────
+
+    def _resolver_tc(self, moneda: str, fecha: str, tc=None) -> Decimal:
+        """Devuelve el TC: usa el provisto, o lo consulta en Banxico si es None."""
+        if tc is not None:
+            tc_dec = Decimal(str(tc))
+            if self._banxico is not None:
+                # Valida el TC declarado contra Banxico
+                try:
+                    tc_oficial, diff_pct = self._banxico.validar_tc(moneda, fecha, tc_dec)
+                    if diff_pct > 1.0:
+                        print(
+                            f"  [!] TC declarado {tc_dec} para {moneda}/{fecha} "
+                            f"difiere {diff_pct:.2f}% del TC Banxico oficial ({tc_oficial}). "
+                            f"Considera usar el TC oficial."
+                        )
+                    else:
+                        print(f"  [TC] {moneda}/{fecha}: {tc_dec} (declarado, "
+                              f"Banxico={tc_oficial}, diff={diff_pct:.3f}%)")
+                except Exception as e:
+                    print(f"  [!] No se pudo validar TC contra Banxico: {e}")
+            return tc_dec
+
+        # tc no proporcionado — consultar Banxico
+        if self._banxico is None:
+            raise ValueError(
+                f"tc no proporcionado para {moneda}/{fecha} y no hay cliente "
+                f"Banxico configurado.\n"
+                f"Opciones:\n"
+                f"  1. Agrega tc=XX.XXXX al llamado\n"
+                f"  2. Configura banxico=BanxicoClient(token) en ManifestacionValor"
+            )
+
+        try:
+            tc_val = self._banxico.tc(moneda, fecha)
+            print(f"  [TC] {moneda}/{fecha}: {tc_val} (Banxico FIX)")
+            return tc_val
+        except Exception as e:
+            raise ValueError(
+                f"No se pudo obtener TC de Banxico para {moneda}/{fecha}: {e}\n"
+                f"Proporciona tc= manualmente."
+            ) from e
+
+    # ── Precios pagados ───────────────────────────────────────────────────────
+
+    def agregar_pago(self, total: float, forma: str, moneda: str, fecha: str,
+                     tc: float = None, especifique: str = None) -> "Factura":
+        """Agrega un precio pagado (pago ya realizado).
+
+        Args:
+            total:       Monto pagado en la moneda indicada.
+            forma:       Clave de forma de pago (ej. 'FORPAG.TE').
+            moneda:      Clave ISO 4217 (ej. 'USD', 'EUR', 'CNY').
+            fecha:       Fecha del pago ('YYYY-MM-DD' o 'DD/MM/YYYY').
+            tc:          Tipo de cambio MXN por unidad de moneda extranjera.
+                         Si es None y hay BanxicoClient configurado, se consulta
+                         automaticamente el TC FIX de Banxico para esa fecha.
+            especifique: Descripcion obligatoria cuando forma='FORPAG.OT'.
+        """
+        tc_resuelto = self._resolver_tc(moneda, fecha, tc)
+        entry = {"fecha": fecha, "total": total, "forma": forma,
+                 "moneda": moneda, "tc": float(tc_resuelto)}
+        if especifique:
+            entry["especifique"] = especifique
+        self._pagado.append(entry)
+        return self
+
+    def agregar_por_pagar(self, total: float, forma: str, moneda: str, fecha: str,
+                          tc: float = None, situacion: str = None,
+                          especifique: str = None) -> "Factura":
+        """Agrega un precio por pagar (pago pendiente o diferido).
+
+        Args:
+            situacion: Descripcion de la situacion del pago pendiente.
+                       Ej. 'Credito a 60 dias plazo desde la fecha de embarque'.
+        """
+        tc_resuelto = self._resolver_tc(moneda, fecha, tc)
+        entry = {"fecha": fecha, "total": total, "forma": forma,
+                 "moneda": moneda, "tc": float(tc_resuelto)}
+        if situacion:
+            entry["situacion"] = situacion
+        if especifique:
+            entry["especifique"] = especifique
+        self._por_pagar.append(entry)
+        return self
+
+    def agregar_compenso(self, motivo: str, mercancia: str, forma: str,
+                         fecha: str, especifique: str = None) -> "Factura":
+        """Agrega un pago por compensacion (intercambio de bienes/servicios)."""
+        entry = {"fecha": fecha, "motivo": motivo, "mercancia": mercancia,
+                 "forma": forma}
+        if especifique:
+            entry["especifique"] = especifique
+        self._compenso.append(entry)
+        return self
+
+    # ── Incrementables / Decrementables ───────────────────────────────────────
+
+    def agregar_incrementable(self, tipo: str, total: float, moneda: str,
+                              fecha: str, tc: float = None,
+                              cargo_importador: bool = True) -> "Factura":
+        """Agrega un concepto incrementable al valor en aduana.
+
+        Args:
+            tipo:             Clave del catalogo (ej. 'INCRE.GS' para fletes).
+            cargo_importador: True si fue a cargo del importador (FOB = True).
+            tc:               TC del dia de la erogacion. Si es None, se
+                              consulta Banxico automaticamente.
+        """
+        tc_resuelto = self._resolver_tc(moneda, fecha, tc)
+        self._incrementables.append({
+            "tipo": tipo, "fecha": fecha, "total": total,
+            "moneda": moneda, "tc": float(tc_resuelto),
+            "cargoImportador": cargo_importador,
+        })
+        return self
+
+    def agregar_decrementable(self, tipo: str, total: float, moneda: str,
+                              fecha: str, tc: float = None) -> "Factura":
+        """Agrega un concepto decrementable al valor en aduana."""
+        tc_resuelto = self._resolver_tc(moneda, fecha, tc)
+        self._decrementables.append({
+            "tipo": tipo, "fecha": fecha, "total": total,
+            "moneda": moneda, "tc": float(tc_resuelto),
+        })
+        return self
+
+    # ── Pedimentos propios (sobreescribe los del root) ────────────────────────
+
+    def agregar_pedimento(self, pedimento: str, patente: str,
+                          aduana: str) -> "Factura":
+        """Agrega un pedimento especifico a esta factura (sobreescribe los del root)."""
+        if self._pedimentos is None:
+            self._pedimentos = []
+        self._pedimentos.append({"pedimento": pedimento,
+                                  "patente": patente, "aduana": aduana})
+        return self
+
+    # ── Serialización ─────────────────────────────────────────────────────────
+
+    def to_dict(self) -> dict:
+        d = {
+            "cove": self.cove,
+            "incoterm": self.incoterm,
+            "vinculacion": self.vinculacion,
+            "pagado": list(self._pagado),
+            "porPagar": list(self._por_pagar),
+            "compenso": list(self._compenso),
+            "metodo": self.metodo,
+            "incrementables": list(self._incrementables),
+            "decrementables": list(self._decrementables),
+        }
+        if self._pedimentos is not None:
+            d["pedimentos"] = list(self._pedimentos)
+        return d
+
+    def __repr__(self):
+        return (f"Factura(cove={self.cove!r}, pagos={len(self._pagado)}, "
+                f"inc={len(self._incrementables)}, dec={len(self._decrementables)})")
+
+
+class ManifestacionValor:
+    """Builder de una Manifestacion de Valor Electronica (MVE).
+
+    Construye el modelo paso a paso y genera el dict compatible con
+    ``registrar_manifestacion_desde_modelo()`` y ``generar_xml()``.
+
+    Args:
+        rfc_importador: RFC del importador.
+        banxico:        (Opcional) BanxicoClient para consultar TC automaticamente.
+                        Si no se proporciona, tc= es obligatorio en cada pago.
+    """
+
+    def __init__(self, rfc_importador: str, banxico=None):
+        self.rfc_importador = rfc_importador
+        self._banxico = banxico
+        self._consulta: list[dict] = []
+        self._documentos: list[str] = []
+        self._pedimentos: list[dict] = []
+        self._facturas: list[Factura] = []
+
+    # ── Metadatos de la operacion ─────────────────────────────────────────────
+
+    def agregar_consulta(self, rfc: str, figura: str) -> "ManifestacionValor":
+        """Agrega una persona autorizada a consultar la MV.
+
+        Args:
+            rfc:    RFC de la persona o agencia aduanal.
+            figura: Clave del catalogo ('TIPFIG.AGE', 'TIPFIG.REP', etc.).
+        """
+        self._consulta.append({"rfc": rfc, "figura": figura})
+        return self
+
+    def agregar_documento(self, edocument: str) -> "ManifestacionValor":
+        """Agrega un eDocument (numero de COVE) a la operacion."""
+        self._documentos.append(edocument)
+        return self
+
+    def agregar_pedimento(self, pedimento: str, patente: str,
+                          aduana: str) -> "ManifestacionValor":
+        """Agrega un pedimento compartido entre todas las facturas.
+
+        Si una factura necesita pedimentos diferentes usa
+        ``Factura.agregar_pedimento()`` en su lugar.
+        """
+        self._pedimentos.append({"pedimento": pedimento,
+                                  "patente": patente, "aduana": aduana})
+        return self
+
+    # ── Facturas ──────────────────────────────────────────────────────────────
+
+    def nueva_factura(self, cove: str, incoterm: str, vinculacion: bool = False,
+                      metodo: str = "VALADU.VTM") -> Factura:
+        """Crea y registra una nueva factura (COVE) en la MV.
+
+        Args:
+            cove:        Numero de COVE (ej. 'COVE2680TJDY6').
+            incoterm:    Clave del catalogo (ej. 'TIPINC.FOB').
+            vinculacion: True si hay vinculacion entre comprador y vendedor.
+            metodo:      Metodo de valoracion (default VALADU.VTM).
+        """
+        f = Factura(cove=cove, incoterm=incoterm,
+                    vinculacion=vinculacion, metodo=metodo,
+                    banxico=self._banxico)
+        self._facturas.append(f)
+        return f
+
+    # ── Exportar ──────────────────────────────────────────────────────────────
+
+    def to_dict(self) -> dict:
+        """Convierte la MV al formato dict compatible con todas las funciones.
+
+        Compatible con:
+            client.registrar_manifestacion_desde_modelo(mv.to_dict())
+            generar_xml(mv.to_dict(), rfc=..., clave_ws=...)
+        """
+        return {
+            "importador":  self.rfc_importador,
+            "consulta":    list(self._consulta),
+            "documentos":  list(self._documentos),
+            "pedimentos":  list(self._pedimentos),
+            "facturas":    [f.to_dict() for f in self._facturas],
+        }
+
+    def __repr__(self):
+        modo_tc = "Banxico auto" if self._banxico else "tc manual"
+        return (f"ManifestacionValor(importador={self.rfc_importador!r}, "
+                f"facturas={len(self._facturas)}, "
+                f"docs={len(self._documentos)}, tc={modo_tc})")