Client Management

Overview

Core Projects maintains a centralized client database with support for both individual and corporate clients. The system tracks client information, document types, and purchase history.

Client Model

Clients are identified by their document number (primary key):

class Cliente extends Model
{
    protected $table = 'clientes';
    protected $primaryKey = 'documento';
    public $incrementing = false;  // Non-numeric primary key
    
    protected $fillable = [
        'nombre',
        'id_tipo_cliente',      // Client type (natural person, company, etc.)
        'id_tipo_documento',    // Document type (CC, NIT, passport, etc.)
        'documento',            // Document number (primary key)
        'direccion',            // Address
        'telefono',             // Phone
        'correo',               // Email
    ];
    
    public function tipoCliente()
    {
        return $this->belongsTo(TipoCliente::class, 'id_tipo_cliente');
    }
    
    public function tipoDocumento()
    {
        return $this->belongsTo(TipoDocumento::class, 'id_tipo_documento');
    }
    
    public function ventas()
    {
        return $this->hasMany(Venta::class, 'documento_cliente', 'documento');
    }
}

Client Types

Clients are classified by type:

Natural Person

Individual buyers with personal identification documents

Legal Entity

Companies and organizations with tax identification numbers

Other Classifications

Custom client types based on business needs (investors, partners, etc.)

Document Types

The system supports multiple document types:

CC (Cédula de Ciudadanía): National ID card
NIT (Número de Identificación Tributaria): Tax ID for companies
CE (Cédula de Extranjería): Foreign resident ID
Passport: International identification
Other: Additional document types as needed

Creating Clients

Clients can be created from the admin panel or during sales processes:

public function store(Request $request)
{
    $validated = $request->validate([
        'nombre' => 'required|string|max:150',
        'id_tipo_cliente' => 'required|exists:tipos_cliente,id_tipo_cliente',
        'id_tipo_documento' => 'required|exists:tipos_documento,id_tipo_documento',
        'documento' => 'required|string|max:40|unique:clientes,documento',
        'direccion' => 'nullable|string|max:200',
        'telefono' => 'nullable|string|max:30',
        'correo' => 'nullable|email|max:150',
    ]);
    
    Cliente::create($validated);
    
    return redirect()
        ->route('admin.clientes.index')
        ->with('success', 'Cliente creado exitosamente.');
}

Validation Rules

Unique document number

Document numbers must be unique across the system. Attempting to create a client with an existing document will fail.

Valid email format

If provided, email must be in valid format. Email is optional.

Required fields

Name, client type, document type, and document number are mandatory.

Client List View

The client index displays:

public function index(Request $request)
{
    $empleado = $request->user()->load('cargo');
    $clientes = Cliente::with([
        'tipoCliente', 
        'tipoDocumento', 
        'ventas'
    ])
    ->orderBy('nombre')
    ->get();
    
    return Inertia::render('Admin/Cliente/Index', [
        'clientes' => $clientes,
        'empleado' => $empleado,
    ]);
}

Client Information Displayed

Full name
Client type
Document type and number
Contact information (phone, email)
Number of purchases
Actions (view, edit, delete)

Client Detail View

The detail view shows comprehensive client information:

Personal Information

Name
Document type and number
Client type classification
Contact details

Purchase History

All sales and separations
Units purchased
Total investment
Payment status

public function show($documento, Request $request)
{
    $empleado = $request->user()->load('cargo');
    $cliente = Cliente::with([
        'tipoCliente', 
        'tipoDocumento', 
        'ventas.apartamento',
        'ventas.local',
        'ventas.proyecto'
    ])
    ->where('documento', $documento)
    ->firstOrFail();
    
    return Inertia::render('Admin/Cliente/Show', [
        'cliente' => $cliente,
        'empleado' => $empleado,
    ]);
}

Updating Client Information

Client records can be updated except for the document number:

public function update(Request $request, $documento)
{
    $validated = $request->validate([
        'nombre' => 'required|string|max:255',
        'id_tipo_cliente' => 'required|exists:tipos_cliente,id_tipo_cliente',
        'id_tipo_documento' => 'required|exists:tipos_documento,id_tipo_documento',
        'direccion' => 'nullable|string|max:255',
        'telefono' => 'nullable|string|max:20',
        'correo' => 'nullable|email|max:255',
    ]);
    
    $cliente = Cliente::where('documento', $documento)->firstOrFail();
    $cliente->update($validated);
    
    return redirect()
        ->route('admin.clientes.index', $documento)
        ->with('success', 'Cliente actualizado exitosamente');
}

Document number cannot be changed as it serves as the primary key and is referenced throughout the system in sales records.

Deleting Clients

Clients can only be deleted if they have no associated sales:

public function destroy($documento)
{
    $cliente = Cliente::where('documento', $documento)->firstOrFail();
    
    // Check for associated sales
    if ($cliente->ventas()->count() > 0) {
        return back()->withErrors([
            'delete' => 'No se puede eliminar el cliente porque tiene ventas asociadas.'
        ]);
    }
    
    $cliente->delete();
    
    return redirect()
        ->route('admin.clientes.index')
        ->with('success', 'Cliente eliminado correctamente.');
}

Quick Client Creation in Sales Flow

Clients can be created on-the-fly during the sales process:

Start sale or separation

Begin creating a new sale/separation from the Ventas module

Client not found

If client doesn’t exist, click “Create New Client” button

Enter client details

Fill in required information in modal/form

Save and continue

Client is created and automatically selected for the sale

Client Search

The system supports searching clients by:

Name (partial match)
Document number
Email
Phone number

Client Relationships

Clients are linked to multiple entities:

// Get client with all related data
$cliente = Cliente::with([
    'tipoCliente',
    'tipoDocumento',
    'ventas' => function ($query) {
        $query->with([
            'apartamento.torre.proyecto',
            'local.torre.proyecto',
            'empleado',
            'pagos'
        ]);
    }
])->find($documento);

// Client statistics
$totalInversion = $cliente->ventas->sum('valor_total');
$unidadesCompradas = $cliente->ventas->count();
$pagosPendientes = $cliente->ventas->sum('valor_restante');

Client Types Configuration

Administrators can manage client types:

Client Type Configuration

Fields:

Type name (e.g., “Natural Person”, “Company”)
Description
Active/inactive status

Usage: Used for client classification and potential business rules (e.g., companies might require additional documentation)

Document Types Configuration

Administrators can manage document types:

Document Type Configuration

Fields:

Type name (e.g., “CC”, “NIT”, “Passport”)
Description
Format rules (optional)
Active/inactive status

Usage: Defines what types of identification are accepted in the system

Data Privacy

Client data is sensitive and protected:

Access control

Only authorized employees can view and edit client information based on their role.

Audit trail

The system tracks creation and modification timestamps for all client records.

GDPR/Data protection

Best Practices

Verify document numbers

Always verify client document numbers are entered correctly to avoid duplicate records.

Keep contact info current

Encourage sales advisors to verify and update client contact information during each interaction.

Use correct client type

Properly classify clients (individual vs. company) for accurate reporting and legal documentation.

Complete all information

While some fields are optional, complete information improves communication and reporting.

Reporting

Client data is used in various reports:

Client purchase history
Sales by client type
Top clients by investment
Client acquisition over time
Contact list exports

Get Started

Core Concepts

Features

User Guides

Overview

Client Model

Client Types

Natural Person

Legal Entity

Other Classifications

Document Types

Creating Clients

Validation Rules

Client List View

Client Information Displayed

Client Detail View

Personal Information

Purchase History

Updating Client Information

Deleting Clients

Quick Client Creation in Sales Flow

Client Search

Client Relationships

Client Types Configuration

Client Type Configuration

Document Types Configuration

Document Type Configuration

Data Privacy

Best Practices

Reporting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

User Guides

​Overview

​Client Model

​Client Types

Natural Person

Legal Entity

Other Classifications

​Document Types

​Creating Clients

​Validation Rules

​Client List View

Client Information Displayed

​Client Detail View

Personal Information

Purchase History

​Updating Client Information

​Deleting Clients

​Quick Client Creation in Sales Flow

​Client Search

​Client Relationships

​Client Types Configuration

Client Type Configuration

​Document Types Configuration

Document Type Configuration

​Data Privacy

​Best Practices

​Reporting

Build docs developers (and LLMs) love

Overview

Client Model

Client Types

Document Types

Creating Clients

Validation Rules

Client List View

Client Detail View

Updating Client Information

Deleting Clients

Quick Client Creation in Sales Flow

Client Search

Client Relationships

Client Types Configuration

Document Types Configuration

Data Privacy

Best Practices

Reporting