Skip to main content

​
Clientes API

The clientes_firestore.js module provides functions for managing customer records with intelligent text normalization and fuzzy search capabilities.

​
Functions

​
crearCliente

Creates a new customer record with automatic text normalization for efficient searching. 
import { crearCliente } from './services/clientes_firestore';

const result = await crearCliente({
  nombre: 'Juan Pérez García',
  telefono: '5551234567',
  direccion: 'Calle Principal 123',
  numeroSeriePreferido: 'ABC123',
  omitirNumeroSerie: false
});

console.log(result); // { id: 'abc123' }
​
data
object
required
Customer information
​
id
string
The created customer document ID
Note: The function automatically generates normalized search fields:
  • nombreNorm - Normalized name with spaces for prefix search
  • nombreCompact - Compacted name without spaces for fuzzy matching

​
actualizarCliente

Updates an existing customer record with automatic normalization. 
import { actualizarCliente } from './services/clientes_firestore';

await actualizarCliente('abc123', {
  telefono: '5559876543',
  direccion: 'Nueva Calle 456',
  omitirNumeroSerie: true
});
​
id
string
required
The customer document ID
​
patch
object
required
Object containing fields to update (partial update supported)
Special behavior:
  • Automatically clears numeroSeriePreferido when omitirNumeroSerie is set to true
  • Regenerates normalized search fields if name changes
  • Updates updatedAt timestamp

​
buscarClientesSimilares

Searches for customers using fuzzy text matching with Levenshtein distance ranking. 
import { buscarClientesSimilares } from './services/clientes_firestore';

const resultados = await buscarClientesSimilares('Juan Perez', {
  maxFetch: 50,
  maxReturn: 8
});

resultados.forEach(cliente => {
  console.log(`${cliente.nombre} (dist: ${cliente._dist})`);
});
​
input
string
required
Search query (name or partial name)
​
options
object
Search configuration
​
result
array
Array of customer objects sorted by similarity (closest match first), with _dist field indicating edit distance
Search algorithm:
  1. Normalizes input text (removes accents, lowercases, handles camelCase)
  2. Performs prefix search on nombreNorm field
  3. Falls back to full collection scan for legacy records
  4. Ranks results using Levenshtein distance on compacted names
  5. Returns top matches sorted by similarity

​
listarClientes

Lists customers ordered by most recently updated. 
import { listarClientes } from './services/clientes_firestore';

const clientes = await listarClientes({ max: 100 });

clientes.forEach(cliente => {
  console.log(`${cliente.nombre} - ${cliente.telefono}`);
});
​
options
object
​
max
number
default:"100"
Maximum number of customers to return
​
result
array
Array of customer objects ordered by updatedAt (newest first)

​
obtenerClientePorId

Retrieves a single customer by document ID. 
import { obtenerClientePorId } from './services/clientes_firestore';

const cliente = await obtenerClientePorId('abc123');

if (cliente) {
  console.log(`Name: ${cliente.nombre}`);
  console.log(`Phone: ${cliente.telefono}`);
} else {
  console.log('Cliente not found');
}
​
id
string
required
The customer document ID
​
result
object | null
Customer object with id and all customer data, or null if not found

​
listarServiciosPorClienteId

Lists all services associated with a specific customer. 
import { listarServiciosPorClienteId } from './services/clientes_firestore';

const servicios = await listarServiciosPorClienteId('abc123');

servicios.forEach(servicio => {
  console.log(`Folio: ${servicio.folio}, Status: ${servicio.status}`);
});
​
clienteId
string
required
The customer document ID
​
result
array
Array of service objects for the specified customer, sorted by creation date (newest first)

​
Utility Functions

​
normalizarTexto

Normalizes text for searching by removing accents, lowercasing, and handling camelCase. 
import { normalizarTexto } from './services/clientes_firestore';

const normalized = normalizarTexto('JuánPérez García');
console.log(normalized); // 'juan perez garcia'
​
raw
string
required
Text to normalize
​
result
string
Normalized text with spaces, lowercase, no accents

​
compact

Compacts text by removing all spaces (useful for fuzzy matching). 
import { compact } from './services/clientes_firestore';

const compacted = compact('Juan Pérez García');
console.log(compacted); // 'juanperezgarcia'
​
raw
string
required
Text to compact
​
result
string
Normalized text without spaces

​
Data Structure

Each customer document contains: 
{
  id: 'abc123',
  nombre: 'Juan Pérez García',
  nombreNorm: 'juan perez garcia',      // for prefix search
  nombreCompact: 'juanperezgarcia',     // for fuzzy matching
  telefono: '5551234567',
  direccion: 'Calle Principal 123',
  numeroSeriePreferido: 'ABC123',
  omitirNumeroSerie: false,
  createdAt: Timestamp,
  updatedAt: Timestamp,
  puntos: 0                              // loyalty points
}

​
Search Implementation Details

The fuzzy search uses Levenshtein distance algorithm to calculate edit distance between strings:
  • Distance 0: Exact match
  • Distance 1-2: Very similar (typo, missing letter)
  • Distance 3-5: Moderately similar
  • Distance 6+: Less similar
Results are sorted by distance, showing closest matches first. This enables finding customers even with:
  • Typos
  • Missing accents
  • Incomplete names
  • Different spacing

Build docs developers (and LLMs) love

Get started for freeTalk to us