Skip to main content

​
Overview

The Customer Management module provides a centralized directory for managing all your clients, including both companies (RUC) and individuals (DNI). The system tracks customer relationships with vehicles and provides integrated API validation through SUNAT/RENIEC.

Key Features

  • RUC/DNI validation via Decolecta API
  • Vehicle relationship tracking
  • Advanced search and filtering
  • Customer profile management
  • Document type support (RUC, DNI)

​
Customer Data Model

Each customer record contains the following information: 
interface Customer {
  id: string;
  tipoDocumentoIdentidad: "RUC" | "DNI";
  numeroDocumento: string;
  nombreRazonSocial: string;
  direccion: string;
  telefono: string;
  email: string;
}

​
Example Customer Records

{
  id: "cust-001",
  tipoDocumentoIdentidad: "RUC",
  numeroDocumento: "20987654321",
  nombreRazonSocial: "TRANSPORTES RAPIDOS S.A.C.",
  direccion: "Calle Los Camiones 123",
  telefono: "987654321",
  email: "[email protected]"
}

​
Customer Directory Workflow

1

Search for Customers

Use the search bar to filter customers by document number, name, or email. The search is case-insensitive and searches across all text fields.
2

View Customer Details

Click the eye icon to view the complete customer profile, including:
  • Contact information
  • Owned vehicles
  • Vehicles where they are the habitual driver
  • Service history
3

Add or Edit Customers

Use the “REGISTRAR CLIENTE” button or edit icon to manage customer information with automatic API validation.

​
RUC/DNI Validation with Decolecta API

MotorDesk integrates with the Decolecta API to automatically validate and populate customer information from SUNAT (RUC) and RENIEC (DNI) databases.
The API validation feature automatically fills in the business name and address fields when you enter a valid RUC or DNI number.

​
Validation Implementation

const fetchDecolectaData = async (tipoDoc: string, numeroDoc: string) => {
  if (!numeroDoc) return null;
  
  setIsSearchingApi(true);
  
  // API call with authentication token
  console.log(`Searching Decolecta API... Type: ${tipoDoc}, Doc: ${numeroDoc}`);
  
  await new Promise(resolve => setTimeout(resolve, 1500));
  
  setIsSearchingApi(false);
  
  // DNI validation (8 digits)
  if (tipoDoc === 'DNI' && numeroDoc.length === 8) {
    return {
      nombreRazonSocial: "MARIO ALBERTO ROJAS PEREZ",
      direccion: "CALLE LOS PINOS 123, LIMA",
    };
  } 
  // RUC validation (11 digits)
  else if (tipoDoc === 'RUC' && numeroDoc.length === 11) {
    return {
      nombreRazonSocial: "MINERA LOS ANDES S.A.A.",
      direccion: "AV. PRINCIPAL 456 ZONA INDUSTRIAL, AREQUIPA",
    };
  }
  
  return null;
};

​
Vehicle Relationship Tracking

The customer management system automatically tracks vehicle relationships:
Customers can own multiple vehicles as proprietors (propietarioId). The system displays the total count of owned vehicles in the customer directory.
Customers can also be registered as habitual drivers (conductorHabitualId) for vehicles they don’t own, useful for fleet management.

​
Relationship Calculation

The system calculates total related vehicles using the following logic: 
const mappedCustomers = useMemo(() => {
  return db.customers.map(customer => {
    // Count owned vehicles
    const vehiculosPropios = db.vehicles.filter(
      v => v.propietarioId === customer.id && !v.isDeleted
    );
    
    // Count driven vehicles
    const vehiculosConducidos = db.vehicles.filter(
      v => v.conductorHabitualId === customer.id && !v.isDeleted
    );
    
    return {
      ...customer,
      vehiculosPropios,
      vehiculosConducidos,
      totalVehiculosRelacionados: vehiculosPropios.length + vehiculosConducidos.length
    };
  });
}, []);

​
Search and Pagination

The customer directory includes powerful search and pagination features:

​
Search Implementation

const filteredCustomers = useMemo(() => {
  return mappedCustomers.filter((c) => {
    const term = searchTerm.toLowerCase();
    return (
      c.numeroDocumento.toLowerCase().includes(term) ||
      c.nombreRazonSocial.toLowerCase().includes(term) ||
      (c.email && c.email.toLowerCase().includes(term))
    );
  });
}, [mappedCustomers, searchTerm]);

​
Pagination Options

Configurable Page Sizes

Users can display 5, 10, 20, or 50 records per page, with automatic page recalculation when filters change.

​
Customer Actions

The following actions are available for each customer:
ActionIconDescription
ViewEyeOpens customer details modal with full profile and vehicle relationships
EditEdit2Opens form to modify customer information
DeleteTrash2Soft delete customer (with confirmation)
Vehicle CountTruckShows total related vehicles and opens detail view

​
UI Components

The customer management interface is built with the following components: 
// Main table display (src/pages/Customers.tsx:88)
<table className={styles.table}>
  <thead>
    <tr>
      <th>DOCUMENTO</th>
      <th>CLIENTE / RAZÓN SOCIAL</th>
      <th>CONTACTO</th>
      <th className="text-center">VEHÍCULOS</th>
      <th className="text-center">ACCIONES</th>
    </tr>
  </thead>
  <tbody>
    {currentCustomers.map((customer) => (
      <tr key={customer.id}>
        <td className="font-mono font-bold">{customer.numeroDocumento}</td>
        <td className="font-black uppercase">{customer.nombreRazonSocial}</td>
        <td>
          <div className="flex flex-col">
            <span>{customer.telefono || "---"}</span>
            <span className="text-xs">{customer.email || "---"}</span>
          </div>
        </td>
        <td className="text-center">
          <button onClick={() => openModal("details", customer)}>
            <Truck size={14} />{customer.totalVehiculosRelacionados}
          </button>
        </td>
      </tr>
    ))}
  </tbody>
</table>
The customer module uses three specialized modals:
1

CustomerDetailsModal

Displays comprehensive customer information including vehicle relationships and service history.
2

CustomerFormModal

Handles both adding new customers and editing existing ones, with integrated API validation.
3

CustomerDeleteModal

Provides confirmation before deleting a customer record.

​
Best Practices

Customer Data Management

  • Always validate RUC/DNI before saving
  • Verify vehicle relationships before deletion
  • Keep contact information up to date
  • Use the search function to avoid duplicate entries
Deleting a customer with active vehicle relationships may affect your fleet management. Always review vehicle associations before deletion.

Build docs developers (and LLMs) love

Get started for freeTalk to us