@nubiia/mcp-freematica 0.7.0 → 0.9.0

package/README.md

@@ -20,6 +20,9 @@ MCP server que expone operaciones del API REST de Freemática (ERP: facturación
 
 | Tool                                                 | Endpoint Freemática                                          | Descripción                                                                                        |
 | ---------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `freematica_list_articulos`                          | `GET /part/v1/articulos`                                     | Catálogo de artículos/materiales/consumibles (referencias, familias, proveedores)                  |
+| `freematica_get_articulo`                            | `GET /part/v1/articulos/{idreg}`                             | Detalle de un artículo                                                                             |
+| `freematica_get_precio_articulo`                     | `GET /pgrl/v1/precio-articulo/{idreg}`                       | Precios de venta de un artículo (PRECIO_VENTA, DESCUENTO, FACTURABLE)                              |
 | `freematica_list_materiales_asignados_servicios`     | `GET /pvss/v2/contratos-servicios-material`                  | Lista de material asignado a servicios                                                             |
 | `freematica_get_master_data`                         | (24 endpoints según `catalog`)                               | Devuelve un catálogo de datos maestros (tipos, geográficos, organizativos, inventario, financiero) |
 | `freematica_list_clientes`                           | `GET /pgrl/v2/clientes`                                      | Lista paginada de clientes                                                                         |
@@ -31,7 +34,7 @@ MCP server que expone operaciones del API REST de Freemática (ERP: facturación
 | `freematica_get_ficha_prev_cliente`                  | `GET /pprl/v2/ficha-prev-cliente`                            | Ficha PRL de un cliente                                                                            |
 | `freematica_list_vigilancia_salud`                   | `GET /pprl/v1/vigilancia-salud`                              | Lista paginada de registros de Vigilancia de la Salud                                              |
 | `freematica_get_vigilancia_salud`                    | `GET /pprl/v1/vigilancia-salud/{idreg}`                      | Detalle de un registro de Vigilancia de la Salud                                                   |
-| `freematica_list_personal`                           | `GET /pers/v2/personal`                                      | Lista paginada de personas (RRHH)                                                                  |
+| `freematica_list_personal`                           | `GET /pers/v1/personal`                                      | Lista paginada de personas (RRHH)                                                                  |
 | `freematica_get_persona`                             | `GET /pers/v2/personal/{idreg}`                              | Detalle de una persona                                                                             |
 | `freematica_list_calendarios`                        | `GET /pgrl/v1/calendarios`                                   | Lista paginada de calendarios laborales                                                            |
 | `freematica_list_calendario_periodos`                | `GET /pgrl/v1/calendarios/{idreg}/periodos`                  | Periodos de un calendario laboral                                                                  |
@@ -65,6 +68,8 @@ MCP server que expone operaciones del API REST de Freemática (ERP: facturación
 | `freematica_get_servicio_contrato`                   | `GET /pvss/v2/contratos-servicios/{idReg}`                   | Detalle de un servicio de contrato                                                                 |
 | `freematica_list_contratos_opcionales`               | `GET /ppre/v2/contratos/opcionales`                          | Lista paginada de opcionales de contratos                                                          |
 | `freematica_get_contrato_opcionales`                 | `GET /ppre/v2/contratos/opcionales/{idReg}`                  | Detalle de un registro de opcionales                                                               |
+| `freematica_list_localizaciones_envio_clientes`      | `GET /pgrl/v2/localizaciones-envio-clientes`                 | Localizaciones de envío de clientes                                                                |
+| `freematica_list_localizaciones_factura_clientes`    | `GET /pgrl/v2/localizaciones-factura-clientes`               | Localizaciones de factura de clientes                                                              |
 
 ### Tools de escritura (requieren `FREEMATICA_ENABLE_WRITES=true`)
 
@@ -82,6 +87,12 @@ Por defecto el servidor es de **solo lectura**. Con `FREEMATICA_ENABLE_WRITES=tr
 | `freematica_update_servicio_facturacion`       | `PUT /pvss/v2/contratos/{id}/servicios-facturacion/{id}`        | Datos de facturación del servicio (precios hora, forma de pago…) |
 | `freematica_create_contrato_opcionales`        | `POST /ppre/v2/contratos/opcionales`                            | Alta de opcionales de contrato                                   |
 | `freematica_update_contrato_opcionales`        | `PUT /ppre/v2/contratos/opcionales/{idReg}`                     | Actualización de opcionales de contrato                          |
+| `freematica_create_cliente`                    | `POST /pgrl/v2/clientes`                                        | Alta de cliente (idReg derivado de grupo+código)                 |
+| `freematica_update_cliente`                    | `PUT /pgrl/v2/clientes/{idReg}`                                 | Actualización parcial de cliente (fetch+merge)                   |
+| `freematica_create_contacto_cliente`           | `POST /pgrl/v2/contactos-clientes`                              | Alta de contacto de cliente                                      |
+| `freematica_update_contacto_cliente`           | `PUT /pgrl/v2/contactos-clientes/{idReg}`                       | Actualización parcial de contacto (fetch+merge)                  |
+| `freematica_create_localizacion_cliente`       | `POST /pgrl/v2/localizaciones-{tipo}-clientes`                  | Alta de localización (tipo: cobro/envio/factura/servicio)        |
+| `freematica_update_localizacion_cliente`       | `PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg}`           | Actualización parcial de localización (fetch+merge)              |
 
 ## Filtros tipados (FIQL interno)
 
@@ -97,8 +108,8 @@ freematica_list_cartera_clientes({
   estado: 'pendiente',
 });
 
-// El MCP construye internamente:
-// rquery=CARCL_EMP==0001;CARCL_FECDOC=ge=2026-01-01;CARCL_SITCAR==1
+// El MCP construye internamente (valores siempre entre comillas simples):
+// rquery=CARCL_EMP=='0001';CARCL_FECDOC=ge='2026-01-01';CARCL_SITCAR=='1'
 ```
 
 ### Ventajas del patrón
@@ -116,14 +127,16 @@ freematica_list_facturas_cabecera({
   empresa: '0001',
   traspasadoContabilidad: false,
 });
-// → rquery=FAC_CODEMP==0001;FAC_TRASP_CONTAB==0
+// → rquery=FVC_CODEMP=='0001';FVC_TRASP_CONTAB=='0'
 
-// Proveedores activos que contienen "GARCIA" en el nombre:
+// Proveedor por nombre EXACTO (el API no soporta búsqueda parcial: =lk=
+// responde 400 y los wildcards % devuelven 0 resultados). El filtro activo
+// de proveedores post-filtra las bajas en cliente (FIQL no tiene IS NULL):
 freematica_list_proveedores({
-  nombre: 'GARCIA',
+  nombre: 'LEJIAS PONS S.A.',
   activo: true,
 });
-// → rquery=NOMBRE_PRO=lk=GARCIA;FECHA_BAJA==null
+// → rquery=NOMBRE_PRO=='LEJIAS PONS S.A.'
 ```
 
 ## Modos de transporte

package/dist/clients/fiql-builder.d.ts

@@ -15,11 +15,29 @@
  *   - `;`    AND (combina expresiones)
  *   - `,`    OR  (combina expresiones)
  *
+ * Quoting de valores: TODOS los valores escalares se emiten entre comillas
+ * simples (`CAMPO=='valor'`). El API de Freemática lo exige para columnas de
+ * texto y fecha (sin comillas responde 400 "Error al ejecutar sentencia" o
+ * ignora el filtro silenciosamente) y lo acepta también en columnas
+ * numéricas. Verificado empíricamente contra /pers/v1/personal,
+ * /part/v1/articulos, /pcon/v2/cuentas, /pven/v1/facturas-cabecera,
+ * /pcar/v1/cartera-clientes y /pgrl/v2/proveedores.
+ *
  * Caracteres que requieren escape en valores FIQL:
- *   `;` `,` `(` `)` `"` `'` espacios → percent-encoding (%3B, %2C, %28, %29, %22, %27, %20)
+ *   `;` `,` `(` `)` `"` `'` → percent-encoding (%3B, %2C, %28, %29, %22, %27)
  *   `=` → %3D  (evita ambigüedad con operadores FIQL del tipo `=op=`)
  *   `!` → %21  (evita ambigüedad con el operador `!=`)
  *   El `==` en un valor se convierte en `%3D%3D` automáticamente.
+ *   El espacio NO se escapea: dentro de comillas simples el API lo acepta
+ *   tal cual, y percent-encodearlo rompe el match (doble encoding al pasar
+ *   la FIQL por URLSearchParams).
+ *
+ * LIMITACIÓN CONOCIDA: los valores que contienen caracteres reservados
+ * (comas, apóstrofes, paréntesis…) viajan percent-encoded dentro del quoting
+ * y el servidor los compara literalmente, así que un filtro por un valor con
+ * esos caracteres puede devolver 0 resultados (verificado con comas en
+ * DESC_ART; sin datos con apóstrofes para verificar alternativas). El escape
+ * se mantiene porque no escaparlos rompería la gramática FIQL (inyección).
  */
 /**
  * Operadores escalares soportados.
@@ -62,19 +80,19 @@ export type FiqlFilters = FiqlGroup | {
  * **Grupo plano** (se unen con AND):
  * ```ts
  * buildFiql({ COD_CLI: '123', ESTADO: 'activo' })
- * // → 'COD_CLI==123;ESTADO==activo'
+ * // → "COD_CLI=='123';ESTADO=='activo'"
  * ```
  *
  * **Operador explícito**:
  * ```ts
  * buildFiql({ IMPORTE: { op: 'gt', value: 1000 } })
- * // → 'IMPORTE=gt=1000'
+ * // → "IMPORTE=gt='1000'"
  * ```
  *
  * **Operador IN con array**:
  * ```ts
  * buildFiql({ COD_CLI: { op: 'in', value: ['A1', 'A2'] } })
- * // → 'COD_CLI=in=(A1,A2)'
+ * // → "COD_CLI=in=('A1','A2')"
  * ```
  *
  * **Composición AND/OR**:
@@ -82,19 +100,25 @@ export type FiqlFilters = FiqlGroup | {
  * buildFiql({
  *   and: [{ EMPRESA: '1' }, { DELEGACION: 'MAD' }],
  * })
- * // → 'EMPRESA==1;DELEGACION==MAD'
+ * // → "EMPRESA=='1';DELEGACION=='MAD'"
  *
  * buildFiql({
  *   or: [{ ESTADO: 'activo' }, { ESTADO: 'pendiente' }],
  * })
- * // → 'ESTADO==activo,ESTADO==pendiente'
+ * // → "ESTADO=='activo',ESTADO=='pendiente'"
  * ```
  *
+ * AVISO: la composición OR (`,`) responde 400 en los endpoints probados del
+ * API real (pers, part); para expresar "uno de varios valores" usar el
+ * operador `in`, que sí está soportado.
+ *
  * ### Reglas
+ * - Todos los valores escalares se emiten entre comillas simples.
  * - Los valores `undefined` se omiten silenciosamente.
  * - Si todos los filtros son `undefined` o el objeto está vacío → retorna `""`.
- * - Los caracteres reservados FIQL (`;`, `,`, `(`, `)`, `"`, `'`, espacio, `=`, `!`)
- *   en los valores se percent-encodean automáticamente.
+ * - Los caracteres reservados FIQL (`;`, `,`, `(`, `)`, `"`, `'`, `=`, `!`)
+ *   en los valores se percent-encodean automáticamente. El espacio va tal
+ *   cual (protegido por el quoting).
  * - Las claves `and`/`or` sólo activan composición si su valor es un `Array`.
  *   Si el valor es un string, number u otro tipo primitivo, se tratan como
  *   nombres de campo ordinarios (ej. `{ and: 'val' }` → `AND==val`).

package/dist/clients/fiql-builder.js

@@ -15,11 +15,29 @@
  *   - `;`    AND (combina expresiones)
  *   - `,`    OR  (combina expresiones)
  *
+ * Quoting de valores: TODOS los valores escalares se emiten entre comillas
+ * simples (`CAMPO=='valor'`). El API de Freemática lo exige para columnas de
+ * texto y fecha (sin comillas responde 400 "Error al ejecutar sentencia" o
+ * ignora el filtro silenciosamente) y lo acepta también en columnas
+ * numéricas. Verificado empíricamente contra /pers/v1/personal,
+ * /part/v1/articulos, /pcon/v2/cuentas, /pven/v1/facturas-cabecera,
+ * /pcar/v1/cartera-clientes y /pgrl/v2/proveedores.
+ *
  * Caracteres que requieren escape en valores FIQL:
- *   `;` `,` `(` `)` `"` `'` espacios → percent-encoding (%3B, %2C, %28, %29, %22, %27, %20)
+ *   `;` `,` `(` `)` `"` `'` → percent-encoding (%3B, %2C, %28, %29, %22, %27)
  *   `=` → %3D  (evita ambigüedad con operadores FIQL del tipo `=op=`)
  *   `!` → %21  (evita ambigüedad con el operador `!=`)
  *   El `==` en un valor se convierte en `%3D%3D` automáticamente.
+ *   El espacio NO se escapea: dentro de comillas simples el API lo acepta
+ *   tal cual, y percent-encodearlo rompe el match (doble encoding al pasar
+ *   la FIQL por URLSearchParams).
+ *
+ * LIMITACIÓN CONOCIDA: los valores que contienen caracteres reservados
+ * (comas, apóstrofes, paréntesis…) viajan percent-encoded dentro del quoting
+ * y el servidor los compara literalmente, así que un filtro por un valor con
+ * esos caracteres puede devolver 0 resultados (verificado con comas en
+ * DESC_ART; sin datos con apóstrofes para verificar alternativas). El escape
+ * se mantiene porque no escaparlos rompería la gramática FIQL (inyección).
  */
 // ---------------------------------------------------------------------------
 // Internals
@@ -47,7 +65,7 @@ const OP_MAP = {
  *   `CAMPO==x=gt=0`  → parser puede interpretar `x=gt=0` como sub-operador
  *   `CAMPO==123==EVIL` → parser puede ver un doble operador
  */
-const FIQL_RESERVED_RE = /[;,()"' =!]/g;
+const FIQL_RESERVED_RE = /[;,()"'=!]/g;
 const RESERVED_ENCODE_MAP = {
     ';': '%3B',
     ',': '%2C',
@@ -55,7 +73,6 @@ const RESERVED_ENCODE_MAP = {
     ')': '%29',
     '"': '%22',
     "'": '%27',
-    ' ': '%20',
     '=': '%3D',
     '!': '%21',
 };
@@ -73,13 +90,18 @@ function escapeFiqlValue(raw) {
     return raw.replace(FIQL_RESERVED_RE, (ch) => RESERVED_ENCODE_MAP[ch] ?? ch);
 }
 /**
- * Convierte un valor primitivo a string FIQL escapado.
+ * Convierte un valor primitivo a string FIQL escapado y quoted.
+ *
+ * El valor SIEMPRE va entre comillas simples: es el formato que exige el
+ * API de Freemática para columnas de texto/fecha y que acepta también en
+ * columnas numéricas. Las comillas simples internas van percent-encoded
+ * (%27) para que no puedan cerrar el quoting.
  *
  * @param val - Primitivo (`string | number | boolean`).
- * @returns Representación FIQL del valor.
+ * @returns Representación FIQL del valor (ej. `'123'`).
  */
 function primitiveToFiql(val) {
-    return escapeFiqlValue(String(val));
+    return `'${escapeFiqlValue(String(val))}'`;
 }
 /**
  * Genera una expresión FIQL simple para `campo operador valor`.
@@ -97,7 +119,7 @@ function buildExpression(key, fiqlValue) {
             const arr = Array.isArray(value) ? value : [value];
             if (arr.length === 0)
                 return '';
-            const encoded = arr.map((v) => escapeFiqlValue(String(v))).join(',');
+            const encoded = arr.map((v) => primitiveToFiql(v)).join(',');
             return `${key}${fiqlOp}(${encoded})`;
         }
         const scalar = Array.isArray(value) ? value[0] : value;
@@ -167,19 +189,19 @@ function isComposition(filters) {
  * **Grupo plano** (se unen con AND):
  * ```ts
  * buildFiql({ COD_CLI: '123', ESTADO: 'activo' })
- * // → 'COD_CLI==123;ESTADO==activo'
+ * // → "COD_CLI=='123';ESTADO=='activo'"
  * ```
  *
  * **Operador explícito**:
  * ```ts
  * buildFiql({ IMPORTE: { op: 'gt', value: 1000 } })
- * // → 'IMPORTE=gt=1000'
+ * // → "IMPORTE=gt='1000'"
  * ```
  *
  * **Operador IN con array**:
  * ```ts
  * buildFiql({ COD_CLI: { op: 'in', value: ['A1', 'A2'] } })
- * // → 'COD_CLI=in=(A1,A2)'
+ * // → "COD_CLI=in=('A1','A2')"
  * ```
  *
  * **Composición AND/OR**:
@@ -187,19 +209,25 @@ function isComposition(filters) {
  * buildFiql({
  *   and: [{ EMPRESA: '1' }, { DELEGACION: 'MAD' }],
  * })
- * // → 'EMPRESA==1;DELEGACION==MAD'
+ * // → "EMPRESA=='1';DELEGACION=='MAD'"
  *
  * buildFiql({
  *   or: [{ ESTADO: 'activo' }, { ESTADO: 'pendiente' }],
  * })
- * // → 'ESTADO==activo,ESTADO==pendiente'
+ * // → "ESTADO=='activo',ESTADO=='pendiente'"
  * ```
  *
+ * AVISO: la composición OR (`,`) responde 400 en los endpoints probados del
+ * API real (pers, part); para expresar "uno de varios valores" usar el
+ * operador `in`, que sí está soportado.
+ *
  * ### Reglas
+ * - Todos los valores escalares se emiten entre comillas simples.
  * - Los valores `undefined` se omiten silenciosamente.
  * - Si todos los filtros son `undefined` o el objeto está vacío → retorna `""`.
- * - Los caracteres reservados FIQL (`;`, `,`, `(`, `)`, `"`, `'`, espacio, `=`, `!`)
- *   en los valores se percent-encodean automáticamente.
+ * - Los caracteres reservados FIQL (`;`, `,`, `(`, `)`, `"`, `'`, `=`, `!`)
+ *   en los valores se percent-encodean automáticamente. El espacio va tal
+ *   cual (protegido por el quoting).
  * - Las claves `and`/`or` sólo activan composición si su valor es un `Array`.
  *   Si el valor es un string, number u otro tipo primitivo, se tratan como
  *   nombres de campo ordinarios (ej. `{ and: 'val' }` → `AND==val`).

package/dist/clients/fiql-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"fiql-builder.js","sourceRoot":"","sources":["../../src/clients/fiql-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fiql-builder.js","sourceRoot":"","sources":["../../src/clients/fiql-builder.ts"],"names":[],"mappings":"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"}

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

@@ -3,6 +3,7 @@ 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 LocalizacionTipo } from '../schemas/localizaciones.js';
 import type { Cliente } from '../types/clientes.js';
 import type { ContactoCliente } from '../types/contactos-clientes.js';
 import type { MasterDataItem } from '../types/master-data.js';
@@ -36,6 +37,64 @@ export declare class FreematicaClient extends BaseClient {
      * Endpoint: GET /pvss/v2/contratos-servicios-material
      */
     getMaterialesAsignadosServicios(): Promise<ListResult<VoContratosServMatAsignado>>;
+    /**
+     * Lista paginada de artículos del catálogo de inventario.
+     *
+     * Endpoint: GET /part/v1/articulos
+     *
+     * Todos los filtros son de coincidencia EXACTA (el endpoint no soporta
+     * búsqueda parcial: =lk= responde 400 y los wildcards % devuelven 0
+     * resultados — verificado contra el API real). OJO: COD_ARTICULO puede
+     * llevar espacios iniciales en Freemática (ej. " QQ10615") que forman
+     * parte del código.
+     *
+     * El filtro `activo` mapea a MOTIVO_BAJA (columna de texto — las columnas
+     * de fecha no permiten comparar con vacío):
+     * - `true`  → MOTIVO_BAJA=='' (sin motivo de baja).
+     * - `false` → MOTIVO_BAJA!='' (con motivo de baja).
+     * Los artículos con MOTIVO_BAJA nulo (≈36 de 6304 en producción) no
+     * matchean ninguno de los dos valores.
+     *
+     * @param opts - Paginación y filtros opcionales.
+     * @returns Lista paginada de artículos (cada item incluye `idReg`).
+     */
+    listArticulos(opts: {
+        page?: number;
+        items?: number;
+        codArticulo?: string;
+        tipoCodigo?: string;
+        codProveedor?: string;
+        linea?: string;
+        familia?: string;
+        subfamilia?: string;
+        descripcion?: string;
+        codigoBarras?: string;
+        activo?: boolean;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Detalle de un artículo por `idReg` opaco.
+     *
+     * Endpoint: GET /part/v1/articulos/{idreg}
+     *
+     * El API devuelve un envelope de LISTA con un único item (verificado contra
+     * el API real), no un objeto detalle; este método lo desenvuelve.
+     *
+     * @param idReg - Identificador opaco (base64) del artículo.
+     * @returns Objeto con todos los campos del artículo.
+     */
+    getArticulo(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Precios de venta de un artículo por `idReg` opaco.
+     *
+     * Endpoint: GET /pgrl/v1/precio-articulo/{idreg}
+     *
+     * Devuelve un objeto con PRECIO_VENTA, DESCUENTO y FACTURABLE.
+     *
+     * @param idReg - Identificador opaco (base64) del artículo (el mismo que
+     *                devuelve freematica_list_articulos).
+     * @returns Objeto de precios del artículo.
+     */
+    getPrecioArticulo(idReg: string): Promise<Record<string, unknown>>;
     /**
      * Obtener un catálogo de datos maestros.
      */
@@ -101,23 +160,13 @@ export declare class FreematicaClient extends BaseClient {
      *
      * 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.
+     * @param opts - Paginación y filtro opcional idRegPersona.
      * @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.
@@ -139,12 +188,11 @@ export declare class FreematicaClient extends BaseClient {
     /**
      * Lista paginada de personas (empleados) con filtros FIQL opcionales.
      *
-     * Endpoint: GET /pers/v2/personal
+     * Endpoint: GET /pers/v1/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).
+     * Todos los filtros son de coincidencia EXACTA: el endpoint no soporta
+     * búsqueda parcial (=lk= responde 400 y los wildcards % / * devuelven 0
+     * resultados — verificado contra el API real).
      *
      * @param opts - Opciones de paginación y filtrado.
      * @returns Lista paginada de personas.
@@ -161,14 +209,18 @@ export declare class FreematicaClient extends BaseClient {
         situacion?: string;
         departamento?: string;
         seccion?: string;
-        activo?: boolean;
     }): Promise<ListResult<Record<string, unknown>>>;
     /**
-     * Detalle de una persona por `idReg` opaco.
+     * Detalle de una persona por su `idReg` opaco.
      *
-     * Endpoint: GET /pers/v2/personal/{idreg}
+     * Endpoint: GET /pers/v1/personal/{idreg}
      *
-     * @param idReg - Identificador opaco de la persona.
+     * v1, igual que el listado: garantiza que todo idReg devuelto por
+     * freematica_list_personal funciona aquí (la vista v2 es un subconjunto
+     * de sincronización incremental). El API devuelve un envelope de LISTA
+     * con un único item (verificado contra el API real); se desenvuelve.
+     *
+     * @param idReg - Identificador opaco (base64) de la persona.
      * @returns Objeto con todos los campos de la persona.
      */
     getPersona(idReg: string): Promise<Record<string, unknown>>;
@@ -237,12 +289,11 @@ export declare class FreematicaClient extends BaseClient {
      * 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 `soloImpagados=true` genera `CARCL_FECIMPAG=ge='1900-01-01'`
+     * (cualquier fecha de impago con valor). El FIQL de Freemática no tiene
+     * IS NOT NULL: `!=null` devuelve 0 resultados silenciosamente y `!='null'`
+     * responde 500 (verificado contra el API real; con este rango devuelve
+     * 382 impagados de 72054 documentos).
      *
      * El filtro `estado` mapea a los valores numéricos de `CARCL_SITCAR`
      * (1=pendiente, 2=cancelado, 3=derivado).
@@ -314,13 +365,16 @@ export declare class FreematicaClient extends BaseClient {
     /**
      * 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 `activo` mapea a FECHA_BAJA. El API no soporta IS NULL en FIQL
+     * (`==null` devuelve 0 resultados y `=='null'` responde 500 — verificado
+     * contra el API real), así que:
+     * - `false` → `FECHA_BAJA=ge='1900-01-01'` (cualquier fecha de baja).
+     * - `true`  → sin filtro server-side; las bajas se descartan post-process
+     *             sobre la página recibida (FECHA_BAJA con valor). El `total`
+     *             devuelto es el del dataset sin filtrar.
      *
-     * El filtro `nombre` usa operador FIQL `=lk=` para búsqueda parcial (LIKE).
+     * El filtro `nombre` es coincidencia EXACTA: el operador `=lk=` responde
+     * 400 en este endpoint y los wildcards % devuelven 0 resultados.
      *
      * Endpoint: GET /pgrl/v2/proveedores
      */
@@ -377,7 +431,11 @@ export declare class FreematicaClient extends BaseClient {
      * 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).
+     * codProvincia (COD_PROVINCIA), representante (COD_REPRES).
+     *
+     * La vista NO tiene columna FECHA_BAJA (filtrar por ella responde 400
+     * "Error en rquery" — verificado contra el API real), así que no existe
+     * filtro activo/baja en este recurso.
      *
      * Endpoint: GET /pgrl/v2/localizaciones-servicio-clientes
      */
@@ -387,7 +445,6 @@ export declare class FreematicaClient extends BaseClient {
         codPais?: string;
         codProvincia?: string;
         representante?: string;
-        activo?: boolean;
     }): Promise<ListResult<Record<string, unknown>>>;
     /**
      * Detalle de una factura de ventas (cabecera) por `idReg` opaco.
@@ -790,6 +847,80 @@ export declare class FreematicaClient extends BaseClient {
      * Nivel debug: body completo, para poder reconstruir la operación.
      */
     private logWrite;
+    /**
+     * Alta de cliente.
+     *
+     * Endpoint: POST /pgrl/v2/clientes — body VoClientes.
+     * Requeridos por el API: idReg, COD_GRUPO_CLI, COD_CLI, NOMBRE_CLI, NIF,
+     * TIPO_IMPTO, COD_DIVISA, TIPO_FACT.
+     */
+    createCliente(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Actualización de cliente.
+     *
+     * Endpoint: PUT /pgrl/v2/clientes/{idReg} — body VoClientes completo
+     * (el caller hace fetch+merge antes de llamar).
+     */
+    updateCliente(idReg: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Detalle de un contacto de cliente por `idReg` opaco.
+     *
+     * Endpoint: GET /pgrl/v1/contactos-clientes/{idreg}
+     * (v2 solo expone el listado; el singular es v1 pero devuelve las mismas
+     * columnas CC_*). Se usa en el fetch+merge del update.
+     */
+    getContactoCliente(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Alta de contacto de cliente.
+     *
+     * Endpoint: POST /pgrl/v2/contactos-clientes — body VoContactosClientes.
+     * Requeridos por el API: CC_GRUPO_CLI, CC_CLI.
+     */
+    createContactoCliente(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Actualización de contacto de cliente.
+     *
+     * Endpoint: PUT /pgrl/v2/contactos-clientes/{idReg}.
+     */
+    updateContactoCliente(idReg: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Detalle de una localización de cliente por tipo e `idReg` opaco.
+     *
+     * Usa el GET singular v2 del tipo (v1 para factura, que no tiene v2; las
+     * columnas son las mismas). Se emplea en el fetch+merge de los updates.
+     */
+    getLocalizacionCliente(tipo: LocalizacionTipo, idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de localizaciones de envío de clientes.
+     *
+     * Endpoint: GET /pgrl/v2/localizaciones-envio-clientes
+     */
+    listLocalizacionesEnvioClientes(opts?: ListOptions & {
+        codCliente?: string;
+        grupoCliente?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de localizaciones de factura de clientes.
+     *
+     * Endpoint: GET /pgrl/v1/localizaciones-factura-clientes
+     * (la lista solo existe en v1; el v2 de este recurso es solo POST/PUT).
+     */
+    listLocalizacionesFacturaClientes(opts?: ListOptions & {
+        codCliente?: string;
+        grupoCliente?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Alta de localización de cliente (cobro, envío, factura o servicio).
+     *
+     * Endpoint: POST /pgrl/v2/localizaciones-{tipo}-clientes — body Vo del tipo.
+     */
+    createLocalizacionCliente(tipo: LocalizacionTipo, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Actualización de localización de cliente (cobro, envío, factura o servicio).
+     *
+     * Endpoint: PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg}.
+     */
+    updateLocalizacionCliente(tipo: LocalizacionTipo, idReg: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
     private listResource;
     /**
      * Helper genérico para endpoints de lista que soportan paginación + filtros FIQL