@nubiia/mcp-freematica 0.6.1

package/dist/clients/freematica-client.d.ts

@@ -0,0 +1,659 @@
+import { BaseClient } from './base-client.js';
+import { type MasterDataCatalog } from '../schemas/master-data.js';
+import { type ListCarteraFilters } from '../schemas/cartera.js';
+import type { ListFacturasCabeceraFilters, ListFacturaLineasFilters, ListFacturaIvaFilters, ListFacturaVencimientosFilters } from '../schemas/facturas-ventas.js';
+import { type ListPedidosCompraFilters } from '../schemas/pedidos-compras.js';
+import type { Cliente } from '../types/clientes.js';
+import type { ContactoCliente } from '../types/contactos-clientes.js';
+import type { MasterDataItem } from '../types/master-data.js';
+import type { OportunidadNegocio } from '../types/oportunidades-negocio.js';
+import type { VoContratosServMatAsignado } from '../types/contratos.js';
+export interface ListResult<T> {
+    items: T[];
+    total: number;
+}
+export interface ListOptions {
+    page?: number;
+    items?: number;
+}
+/**
+ * Typed client for the Freemática REST API.
+ *
+ * One method per exposed endpoint (or per family of endpoints). The wrapper
+ * `{ errorCode, errorMessage, data }` is unwrapped by `BaseClient.request`,
+ * so methods only see `data`.
+ *
+ * For list endpoints, `data` has shape `{ total, items, rowHeight }`. List
+ * methods unwrap that to `{ items, total }` (string total → number; rowHeight
+ * discarded).
+ *
+ * For detail endpoints, `data` is the entity directly.
+ */
+export declare class FreematicaClient extends BaseClient {
+    /**
+     * Obtener lista de material asignado a servicios.
+     *
+     * Endpoint: GET /pvss/v2/contratos-servicios-material
+     */
+    getMaterialesAsignadosServicios(): Promise<ListResult<VoContratosServMatAsignado>>;
+    /**
+     * Obtener un catálogo de datos maestros.
+     */
+    getMasterData(catalog: MasterDataCatalog): Promise<ListResult<MasterDataItem>>;
+    /** Lista paginada de clientes. */
+    listClientes(opts?: ListOptions): Promise<ListResult<Cliente>>;
+    /** Detalle de un cliente por `idReg` opaco. */
+    getCliente(idReg: string): Promise<Cliente>;
+    /** Lista paginada de contactos de clientes. */
+    listContactosClientes(opts?: ListOptions): Promise<ListResult<ContactoCliente>>;
+    /** Lista paginada de oportunidades de negocio. */
+    listOportunidadesNegocio(opts?: ListOptions): Promise<ListResult<OportunidadNegocio>>;
+    /** Detalle de una oportunidad por `idReg` opaco. */
+    getOportunidadNegocio(idReg: string): Promise<OportunidadNegocio>;
+    /**
+     * Datos ampliados de una oportunidad por `idReg` opaco.
+     *
+     * Puede devolver `not_found` si la oportunidad no tiene datos ampliados.
+     * El caller debe manejar el `FreematicaError` con código `not_found`.
+     */
+    getOportunidadNegocioDatosAmpliados(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Opciones de filtro para getFichaPrevCliente.
+     *
+     * Los query params mapean directamente a los parámetros nativos del endpoint
+     * GET /pprl/v2/ficha-prev-cliente. NO se usa FIQL en este endpoint.
+     */
+    /**
+     * Obtiene la ficha de PRL de un cliente.
+     *
+     * Endpoint: GET /pprl/v2/ficha-prev-cliente
+     *
+     * Los filtros se envían como query params nativos (codCli, grpCli, locServ,
+     * codigo). La validación de "al menos uno" es responsabilidad del caller
+     * (la tool lo hace via Zod .refine()).
+     *
+     * @param opts - Filtros: codCliente, grupoCliente, codLocalizacionServicio, codigoFicha.
+     * @returns Lista de fichas PRL que coinciden con los filtros.
+     */
+    getFichaPrevCliente(opts: {
+        codCliente?: string;
+        grupoCliente?: number;
+        codLocalizacionServicio?: number;
+        codigoFicha?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista de cuentas del plan contable.
+     *
+     * Endpoint: GET /pcon/v2/cuentas
+     *
+     * Los filtros opcionales se mapean a una expresión FIQL y se pasan como
+     * query param `rquery`. El prefijoCuenta usa operador `=ge=` / `=lt=` para
+     * emular un prefix match sobre COD_CTA (rango léxico).
+     *
+     * @param opts - Filtros opcionales: codPlan, prefijoCuenta, activa, grupoCuenta.
+     */
+    listCuentasContables(opts?: CuentasContablesOptions): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Opciones de filtro para listVigilanciaSalud.
+     */
+    /**
+     * Lista paginada de registros de Vigilancia de la Salud.
+     *
+     * Endpoint: GET /pprl/v1/vigilancia-salud
+     *
+     * `idRegPersona` se envía como query param nativo. El resto de filtros se
+     * codifican en FIQL y se envían como `rquery`.
+     *
+     * @param opts - Opciones de paginación y filtrado.
+     * @returns Lista paginada de registros VS.
+     */
+    listVigilanciaSalud(opts: {
+        page?: number;
+        items?: number;
+        idRegPersona?: string;
+        empresa?: string;
+        delegacion?: string;
+        codPersona?: string;
+        tipoRevision?: string;
+        resultado?: string;
+        fechaCitaDesde?: string;
+        fechaCitaHasta?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista de cuentas analíticas.
+     *
+     * Endpoint: GET /pcon/v2/cuentas-analiticas
+     *
+     * @param opts - Filtros opcionales: codPlan, prefijoCuenta, activa, grupoCuenta, area, delegacion.
+     */
+    listCuentasAnaliticas(opts?: CuentasAnaliticasOptions): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de un registro de Vigilancia de la Salud por `idReg` opaco.
+     *
+     * Endpoint: GET /pprl/v1/vigilancia-salud/{idreg}
+     *
+     * @param idReg - Identificador opaco del registro.
+     * @returns Objeto con todos los campos del registro VS.
+     */
+    getVigilanciaSalud(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de personas (empleados) con filtros FIQL opcionales.
+     *
+     * Endpoint: GET /pers/v2/personal
+     *
+     * El filtro `activo` (boolean) se traduce a `VSSPER_ACTIVO==S` (true) o
+     * `VSSPER_ACTIVO==N` (false). Las búsquedas por `nombre` y `apellido` usan
+     * el operador de igualdad estándar FIQL (el servidor aplica LIKE internamente
+     * para estos campos).
+     *
+     * @param opts - Opciones de paginación y filtrado.
+     * @returns Lista paginada de personas.
+     */
+    listPersonal(opts: {
+        page?: number;
+        items?: number;
+        empresa?: string;
+        delegacion?: string;
+        codPersona?: string;
+        nombre?: string;
+        apellido?: string;
+        nif?: string;
+        situacion?: string;
+        departamento?: string;
+        seccion?: string;
+        activo?: boolean;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de una persona por `idReg` opaco.
+     *
+     * Endpoint: GET /pers/v2/personal/{idreg}
+     *
+     * @param idReg - Identificador opaco de la persona.
+     * @returns Objeto con todos los campos de la persona.
+     */
+    getPersona(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de calendarios laborales.
+     *
+     * Endpoint: GET /pgrl/v1/calendarios
+     *
+     * @param opts - Opciones de paginación.
+     * @returns Lista paginada de calendarios.
+     */
+    listCalendarios(opts?: ListOptions): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de periodos de un calendario laboral.
+     *
+     * Endpoint: GET /pgrl/v1/calendarios/{idreg}/periodos
+     *
+     * @param idCalendario - idReg opaco del calendario.
+     * @param opts - Opciones de paginación.
+     * @returns Lista paginada de periodos del calendario.
+     */
+    listCalendarioPeriodos(idCalendario: string, opts?: ListOptions): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Exporta asientos contables de Freemática.
+     *
+     * Endpoint: GET /pcon/v2/export-asientos
+     *
+     * Los parámetros `empresa`, `cal` y `periodo` son query params nativos.
+     * Los filtros `fechaDesde`, `fechaHasta`, `diario` y `borrador` se envían
+     * como expresión FIQL en el param `rquery`.
+     *
+     * Protección de tamaño: si el JSON serializado supera
+     * `FREEMATICA_MAX_RESPONSE_SIZE_MB` (default 10 MB), los items se truncan
+     * y se añade un campo `warning` a la respuesta.
+     *
+     * @param opts - Opciones de exportación.
+     * @returns Resultado con `items`, `total`, y opcionalmente `truncated`+`warning`.
+     */
+    exportAsientos(opts: ExportAsientosOptions): Promise<ExportAsientosResult>;
+    /**
+     * Lista paginada de facturas de compras con filtros FIQL + query params nativos.
+     *
+     * El campo `exportado` es un enum nativo del endpoint (no FIQL): `all` | `not_exported`.
+     * El resto de filtros se envían mediante el query param `rquery` (FIQL).
+     *
+     * Endpoint: GET /pcmp/v2/facturas-compras
+     */
+    listFacturasCompras(opts?: ListOptions & {
+        fechaDesde?: string;
+        fechaHasta?: string;
+        empresa?: string;
+        codProveedor?: string;
+        serie?: string;
+        numFactura?: string;
+        formaPago?: string;
+        traspasadoContabilidad?: boolean;
+        delegacion?: string;
+        lineaNegocio?: string;
+        exportado?: 'all' | 'not_exported';
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de documentos de cartera de clientes con filtros FIQL.
+     *
+     * Endpoint: GET /pcar/v1/cartera-clientes
+     *
+     * Construye la FIQL a partir de los filtros tipados y la añade como `rquery`
+     * usando `appendRquery()` (patrón canónico del foundation TD-117).
+     *
+     * El filtro `soloImpagados=true` genera `CARCL_FECIMPAG!=null`, donde el
+     * valor `'null'` es la convención centinela de Freemática para indicar "sin
+     * valor" en campos de fecha opcionales (assumption empírica: observado en
+     * datos reales de la API; documentado para futuras implementaciones).
+     * El operador `ne` se pasa vía `buildFiql` para garantizar escaping
+     * consistente con el resto de filtros.
+     *
+     * El filtro `estado` mapea a los valores numéricos de `CARCL_SITCAR`
+     * (1=pendiente, 2=cancelado, 3=derivado).
+     *
+     * @param opts - Filtros tipados del schema `ListCarteraFiltersSchema`.
+     * @returns Lista paginada de documentos de cartera.
+     */
+    listCarteraClientes(opts?: ListCarteraFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de una factura de compra por `idReg` opaco.
+     *
+     * Endpoint: GET /pcmp/v2/facturas-compras/{idReg}
+     */
+    getFacturaCompra(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de pedidos de compra con diseño mixto de filtros.
+     *
+     * Endpoint: GET /pcmp/v2/pedidos
+     *
+     * DISEÑO MIXTO: el endpoint combina 4 query params nativos con filtros FIQL
+     * adicionales vía `rquery`.
+     *
+     * Filtros que van como **query params nativos** (NO FIQL):
+     * - `empresa` (4c) → `codEmpresa`
+     * - `codProveedor` (≤10c) → `codProveedor`
+     * - `fechaPedidoDesde` (ISO date) → `desdeFecha`
+     * - `fechaPedidoHasta` (ISO date) → `hastaFecha`
+     *
+     * Filtros que van como **FIQL en `rquery`** (campos `ALCC_*`):
+     * - `numPedido` → `ALCC_NUMDOC==N`
+     * - `codDocumento` → `ALCC_CODDOC==XXXX`
+     * - `delegacion` → `ALCC_DELEG==XXXX`
+     * - `formaPago` → `ALCC_FPAGO==XXX`
+     * - `tipoIva` → `ALCC_TIPO_IVA==XXXX`
+     * - `codCliente` → `ALCC_COD_CLIENTE==X`
+     * - `codInstalador` → `ALCC_COD_INSTALADOR==X`
+     * - `codMantenedor` → `ALCC_COD_MANTENEDOR==X`
+     * - `fechaEntregaDesde` → `ALCC_FCHENTREGA=ge=YYYY-MM-DD`
+     * - `fechaEntregaHasta` → `ALCC_FCHENTREGA=le=YYYY-MM-DD`
+     * - `referencia` → `ALCC_REFERENCIA==X`
+     * - `estado` → expresión compuesta sobre `ALCC_PED_BLOQ` y `ALCC_PED_RECIB`
+     *   (ver `buildEstadoPedidoFiql` y comentario empírico en `EstadoPedidoEnum`)
+     *
+     * @param opts - Filtros tipados del schema `ListPedidosCompraFiltersSchema`.
+     * @returns Lista paginada de pedidos de compra.
+     */
+    listPedidosCompra(opts?: ListPedidosCompraFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de un pedido de compra por `idReg` opaco.
+     *
+     * Endpoint: GET /pcmp/v2/pedidos/{idreg}
+     *
+     * La respuesta es un objeto compuesto `{ VoPedidosCompraCab, cabecera_proveedor, lineas[] }`
+     * que se devuelve sin aplanar para conservar la estructura original del API.
+     *
+     * @param idReg - Identificador opaco (puede contener caracteres como "==" de base64).
+     * @returns Objeto compuesto con la cabecera, datos del proveedor y líneas del pedido.
+     */
+    getPedidoCompra(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Detalle de un documento de cartera de clientes por `idReg` opaco.
+     *
+     * Endpoint: GET /pcar/v1/cartera-clientes/{idreg}
+     *
+     * @param idReg - Identificador opaco (base64) del documento.
+     * @returns Documento de cartera completo.
+     */
+    getCarteraCliente(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de proveedores con filtros FIQL.
+     *
+     * El filtro `activo` mapea a FECHA_BAJA:
+     * - `true`  → FECHA_BAJA es nula (proveedor activo). Se usa el operador `=is-null=true` si el
+     *             API lo soporta; como fallback se omite el filtro y se filtra post-process.
+     *             En Freemática el convenio estándar es: activo=true → `FECHA_BAJA==null` (FIQL `==null`).
+     * - `false` → FECHA_BAJA tiene valor (proveedor de baja).
+     *
+     * El filtro `nombre` usa operador FIQL `=lk=` para búsqueda parcial (LIKE).
+     *
+     * Endpoint: GET /pgrl/v2/proveedores
+     */
+    listProveedores(opts?: ListOptions & {
+        codProveedor?: string;
+        grupoProveedor?: string;
+        nif?: string;
+        nombre?: string;
+        activo?: boolean;
+        tipoIdent?: string;
+        codProvincia?: string;
+        codPais?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de cabeceras de facturas de ventas con filtros FIQL.
+     *
+     * Endpoint: GET /pven/v1/facturas-cabecera
+     *
+     * @param opts - Filtros tipados del schema `ListFacturasCabeceraFiltersSchema`.
+     * @returns Lista paginada de cabeceras de facturas.
+     */
+    listFacturasCabecera(opts?: ListFacturasCabeceraFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de un proveedor por `idReg` opaco.
+     *
+     * Endpoint: GET /pgrl/v2/proveedores/{idReg}
+     */
+    getProveedor(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de localizaciones de cobro de clientes.
+     *
+     * Filtros soportados: codCliente (COD_CLI), grupoCliente (GRUPO_CLI), formaPago (COD_FORMA_COBRO).
+     *
+     * Endpoint: GET /pgrl/v2/localizaciones-cobro-clientes
+     */
+    listLocalizacionesCobroClientes(opts?: ListOptions & {
+        codCliente?: string;
+        grupoCliente?: string;
+        formaPago?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de localizaciones de pago de proveedores.
+     *
+     * Filtros soportados: codProveedor (COD_PRO), grupoProveedor (COD_GRUPO_PRO), formaPago (COD_FORMA_PAGO).
+     *
+     * Endpoint: GET /pgrl/v2/localizaciones-pago-proveedores
+     */
+    listLocalizacionesPagoProveedores(opts?: ListOptions & {
+        codProveedor?: string;
+        grupoProveedor?: string;
+        formaPago?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de localizaciones de servicio de clientes.
+     *
+     * Filtros soportados: codCliente (COD_CLI), grupoCliente (GRUPO_CLI), codPais (COD_PAIS),
+     * codProvincia (COD_PROVINCIA), representante (COD_REPRES), activo (FECHA_BAJA nulo/no nulo).
+     *
+     * Endpoint: GET /pgrl/v2/localizaciones-servicio-clientes
+     */
+    listLocalizacionesServicioClientes(opts?: ListOptions & {
+        codCliente?: string;
+        grupoCliente?: string;
+        codPais?: string;
+        codProvincia?: string;
+        representante?: string;
+        activo?: boolean;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de una factura de ventas (cabecera) por `idReg` opaco.
+     *
+     * Endpoint: GET /pven/v1/facturas-cabecera/{idreg}
+     *
+     * @param idReg - Identificador opaco (base64) de la factura.
+     * @returns Factura cabecera completa.
+     */
+    getFacturaCabecera(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de líneas de una factura de ventas con filtros FIQL.
+     *
+     * Endpoint: GET /pven/v1/facturas-cabecera/{idreg}/lineas
+     *
+     * @param idReg - idReg opaco de la factura cabecera.
+     * @param opts - Filtros tipados del schema `ListFacturaLineasFiltersSchema`.
+     * @returns Lista paginada de líneas de factura.
+     */
+    listFacturaLineas(idReg: string, opts?: ListFacturaLineasFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de líneas de IVA de una factura de ventas con filtros FIQL.
+     *
+     * Endpoint: GET /pven/v1/facturas-cabecera/{idreg}/iva
+     *
+     * @param idReg - idReg opaco de la factura cabecera.
+     * @param opts - Filtros tipados del schema `ListFacturaIvaFiltersSchema`.
+     * @returns Lista paginada de líneas de IVA.
+     */
+    listFacturaIva(idReg: string, opts?: ListFacturaIvaFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de vencimientos de una factura de ventas con filtros FIQL.
+     *
+     * Endpoint: GET /pven/v1/facturas-cabecera/{idreg}/vencimientos
+     *
+     * @param idReg - idReg opaco de la factura cabecera.
+     * @param opts - Filtros tipados del schema `ListFacturaVencimientosFiltersSchema`.
+     * @returns Lista paginada de vencimientos.
+     */
+    listFacturaVencimientos(idReg: string, opts?: ListFacturaVencimientosFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de facturas electrónicas con filtros nativos (NO FIQL).
+     *
+     * Endpoint: GET /pven/v1/facturas
+     *
+     * Diferente de listFacturasCabecera: expone las facturas firmadas/enviadas vía
+     * Facturae, EDICOM y/o FACe. Los filtros son query params nativos del API.
+     *
+     * @param opts - Filtros nativos: empresa, codCliente, fechaDesde/Hasta, estado, leido + paginación.
+     * @returns Lista paginada de facturas electrónicas con campos FACED_*.
+     */
+    listFacturasElectronicas(opts: import('../schemas/facturas-electronicas.js').ListFacturasElectronicasFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de albaranes de ventas con filtros nativos del endpoint.
+     *
+     * Endpoint: GET /pven/v2/albaranes-ventas
+     *
+     * El endpoint usa exclusivamente query params nativos para los filtros
+     * principales (no FIQL). `codEmpresa` es obligatorio según el spec OpenAPI.
+     */
+    listAlbaranesVentas(opts: {
+        page?: number;
+        items?: number;
+        empresa: string;
+        delegacion?: string;
+        codCliente?: string;
+        codDocumento?: string;
+        fechaDesde?: string;
+        fechaHasta?: string;
+        order?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de una factura electrónica por `idReg` opaco.
+     *
+     * Endpoint: GET /pven/v1/facturas/{idreg}
+     *
+     * @param idReg - Identificador opaco (base64) de la factura electrónica.
+     * @returns Objeto con los campos de la factura electrónica.
+     */
+    getFacturaElectronica(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Recupera el documento (PDF o XML Facturae firmado) de una factura electrónica.
+     *
+     * Endpoint: GET /pven/v1/facturas/{idreg}/documento
+     *
+     * La API devuelve un JSON (VoFacturasDocumento) con los documentos codificados en base64
+     * en los campos FACED_DOCUMENTO_PDF, FACED_DOCUMENTO_XML, etc.
+     *
+     * Si el tamaño del JSON supera FREEMATICA_MAX_RESPONSE_SIZE_MB, la tool aplica el
+     * guardrail de tamaño y devuelve `{ truncated: true, warning, sizeBytes }` sin el cuerpo.
+     *
+     * @param idReg - Identificador opaco de la factura.
+     * @param opts - Opciones: documentType (tipo de documento), actualizaLeido (marcar como leído).
+     * @returns Objeto VoFacturasDocumento con campos FACED_DOCUMENTO_*.
+     */
+    getFacturaDocumento(idReg: string, opts?: {
+        documentType?: string;
+        actualizaLeido?: boolean;
+    }): Promise<FacturaDocumentoResult>;
+    /**
+     * Log de auditoría de una factura electrónica (envío, recepción, aceptación AAPP, etc.).
+     *
+     * Endpoint: GET /pven/v1/facturas/{idreg}/log
+     *
+     * @param idReg - Identificador opaco de la factura.
+     * @param opts - Opciones de paginación.
+     * @returns Lista paginada de eventos de auditoría con campos FVCTRLE_*.
+     */
+    getFacturaLog(idReg: string, opts?: ListOptions): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Configuración de la integración EDICOM (empresa, aplicación, URLs, credenciales).
+     *
+     * Endpoint: GET /pven/v1/facturas/edicominfo
+     *
+     * Devuelve una lista de configuraciones EDICOM (campos EDICOM_*).
+     * NOTA: incluye campos sensibles (EDICOM_USER, EDICOM_PASSWORD). Usar con precaución.
+     *
+     * @param opts - Opciones de paginación.
+     * @returns Lista de configuraciones EDICOM con campos EDICOM_*.
+     */
+    getEdicomInfo(opts?: ListOptions): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Descarga masiva de documentos de facturas electrónicas (PDF/XML/ERROR).
+     *
+     * Endpoint: GET /pven/v1/facturas/download
+     *
+     * Permite recuperar múltiples documentos filtrando por identificadores y tipo.
+     * Los documentos se devuelven con campos VoEFraDoc (empresa, serie, numFra, documentoPdf, etc.).
+     *
+     * @param opts - Filtros: documents (IDs separados por comas), documentType (PDF/XML/ERROR).
+     * @returns Lista de documentos con campos VoEFraDoc.
+     */
+    listFacturasDocumentos(opts?: import('../schemas/facturas-electronicas.js').ListFacturasDocumentosFilters): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de un albarán de venta por `idReg` opaco.
+     *
+     * Endpoint: GET /pven/v2/albaranes-ventas/{idReg}
+     *
+     * @param idReg - Identificador opaco (base64) del albarán.
+     * @returns Objeto completo del albarán de venta.
+     */
+    getAlbaranVenta(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de vinculaciones albarán↔factura.
+     *
+     * Endpoint: GET /pven/v2/albaranes-facturas
+     *
+     * El filtro `idReg` es un query param nativo. Los filtros empresa, serie,
+     * numFactura y codCliente se envían como FIQL en el parámetro `rQuery`.
+     *
+     * Mapeo de filtros FIQL:
+     * | opts.empresa    | FVCA_CODEMP   |
+     * | opts.serie      | FVCA_SERIEFRA |
+     * | opts.numFactura | FVCA_NUMFRA   |
+     * | opts.codCliente | FVCA_CODCLI   |
+     *
+     * @param opts - Opciones de paginación y filtros.
+     * @returns Lista paginada de vinculaciones albarán-factura.
+     */
+    listAlbaranesFactura(opts: {
+        page?: number;
+        items?: number;
+        idReg?: string;
+        empresa?: string;
+        serie?: string;
+        numFactura?: string;
+        codCliente?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de una vinculación albarán↔factura por `idReg` opaco.
+     *
+     * Endpoint: GET /pven/v2/albaranes-facturas/{idReg}
+     *
+     * @param idReg - Identificador opaco (base64) del registro de vinculación.
+     * @returns Objeto completo de la vinculación albarán-factura.
+     */
+    getAlbaranFactura(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de resultados del proceso batch de facturación de vigilancia.
+     *
+     * Endpoint: GET /pvss/v1/facturacion-resultados
+     *
+     * Todos los filtros se envían como FIQL en el parámetro `rquery`.
+     * El parámetro `order` es nativo del endpoint.
+     *
+     * Mapeo de filtros FIQL:
+     * | opts.empresa    | FACT_EMP     |
+     * | opts.delegacion | FACT_DELEG   |
+     * | opts.codCliente | FACT_COD_CLI |
+     * | opts.calendario | FACT_CAL     |
+     * | opts.mes        | FACT_MES     |
+     * | opts.contrato   | FACT_CTRT    |
+     * | opts.servicio   | FACT_SERV    |
+     * | opts.tipoFac    | FACT_TIPFAC  |
+     * | opts.traspasado | FACT_TRASP   |
+     *
+     * @param opts - Opciones de paginación y filtros FIQL.
+     * @returns Lista paginada de resultados de facturación.
+     */
+    listResultadosFacturacion(opts: {
+        page?: number;
+        items?: number;
+        empresa?: string;
+        delegacion?: string;
+        codCliente?: string;
+        calendario?: string;
+        mes?: number;
+        contrato?: string;
+        servicio?: string;
+        tipoFac?: string;
+        traspasado?: string;
+        order?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    private listResource;
+    /**
+     * Helper genérico para endpoints de lista que soportan paginación + filtros FIQL
+     * vía query param `rquery`.
+     *
+     * @param path - Path base del endpoint (sin query string).
+     * @param opts - Opciones de paginación.
+     * @param fiqlFields - Mapa de nombre de campo FIQL → valor. Los valores `undefined` se omiten.
+     * @returns Lista de items con total.
+     */
+    private listResourceWithFiql;
+}
+/** Filtros para listCuentasContables. */
+export interface CuentasContablesOptions {
+    codPlan?: string;
+    prefijoCuenta?: string;
+    activa?: boolean;
+    grupoCuenta?: string;
+}
+/** Filtros para listCuentasAnaliticas. */
+export interface CuentasAnaliticasOptions {
+    codPlan?: string;
+    prefijoCuenta?: string;
+    activa?: boolean;
+    grupoCuenta?: string;
+    area?: string;
+    delegacion?: string;
+}
+/** Opciones para exportAsientos. */
+export interface ExportAsientosOptions {
+    empresa: string;
+    cal: string;
+    periodo?: string;
+    fechaDesde?: string;
+    fechaHasta?: string;
+    diario?: string;
+    borrador?: boolean;
+}
+/** Resultado de exportAsientos. */
+export interface ExportAsientosResult extends ListResult<Record<string, unknown>> {
+    truncated: boolean;
+    warning?: string;
+}
+/**
+ * Resultado de getFacturaDocumento.
+ *
+ * - Si truncated=false: incluye todos los campos VoFacturasDocumento (FACED_DOCUMENTO_PDF, etc.).
+ * - Si truncated=true: incluye solo `truncated`, `warning` y `sizeBytes` (sin el cuerpo del documento).
+ */
+export type FacturaDocumentoResult = ({
+    truncated: false;
+} & Record<string, unknown>) | {
+    truncated: true;
+    warning: string;
+    sizeBytes: number;
+};