CRM (Customer Relationship Management)

FacturaScripts includes comprehensive CRM functionality for managing customers, suppliers, and contacts with full address management, payment terms, and fiscal information.

Core Entities

Customers

Customer master data with payment terms and credit limits

Suppliers

Supplier management with purchase terms

Contacts

Addresses and contact points for customers and suppliers

Customers (Clientes)

Customers represent the entities that purchase from your business.

Customer Structure

Located at Core/Model/Cliente.php:

class Cliente extends ModelClass
{
    use EmailAndPhonesTrait;
    use FiscalNumberTrait;
    use GravatarTrait;
    
    const SPECIAL_ACCOUNT = 'CLIENT';
    
    public $codcliente;        // Customer code (1-10 chars)
    public $nombre;            // Name
    public $razonsocial;       // Company name
    
    // Contact information
    public $email;             // Email address
    public $telefono1;         // Primary phone
    public $telefono2;         // Secondary phone
    public $fax;               // Fax number
    public $web;               // Website
    
    // Fiscal information
    public $cifnif;            // Tax ID number
    public $tipoidfiscal;      // Tax ID type
    public $personafisica;     // Individual person flag
    public $regimeniva;        // VAT regime
    public $excepcioniva;      // VAT exception
    
    // Payment terms
    public $codpago;           // Payment method code
    public $diaspago;          // Preferred payment days
    public $codretencion;      // Withholding code
    
    // Credit control
    public $riesgoalcanzado;   // Current credit used
    public $riesgomax;         // Credit limit
    
    // Configuration
    public $codserie;          // Default document series
    public $codtarifa;         // Price list code
    public $codagente;         // Sales agent code
    public $codgrupo;          // Customer group code
    
    // Accounting
    public $codsubcuenta;      // Account code
    
    // Addresses
    public $idcontactofact;    // Billing address ID
    public $idcontactoenv;     // Shipping address ID
    
    // Status
    public $debaja;            // Inactive flag
    public $fechaalta;         // Registration date
    public $fechabaja;         // Deactivation date
    
    // Localization
    public $langcode;          // Language code
    
    // Related entities
    public $codproveedor;      // Also a supplier?
    public $observaciones;     // Notes
}

Key Features

Multiple Addresses

public function getAddresses(): array
{
    // Returns all addresses (Contacto) for this customer
}

public function getDefaultAddress(string $type = 'billing'): Contacto
{
    // Returns billing or shipping address
    // $type: 'billing' or 'shipping'
    $id = $type === 'shipping' ? 
        $this->idcontactoenv : 
        $this->idcontactofact;
}

Bank Accounts

public function getBankAccounts(): array
{
    // Returns all bank accounts for direct debit
    // Used for payment receipts
}

Payment Terms

public function getPaymentDays(): array
{
    // Returns array of preferred payment days
    // Example: [5, 20] for 5th and 20th of month
    $days = [];
    foreach (explode(',', $this->diaspago) as $str) {
        if (is_numeric(trim($str))) {
            $days[] = trim($str);
        }
    }
    return $days;
}

Accounting Integration

public function getSubcuenta(string $codejercicio, bool $crear): Subcuenta
{
    // Gets or creates subaccount for this customer
    // In specified fiscal exercise
    // Uses special account 'CLIENT'
}

protected function createSubcuenta(string $codejercicio): Subcuenta
{
    // Automatically creates subaccount
    // Uses free code from CLIENT special account
    // Saves code to customer record
}

VAT Validation

public function checkVies(bool $msg = true): bool
{
    // Validates EU VAT number via VIES service
    // Returns true if valid
    $codiso = Paises::get($this->getDefaultAddress()->codpais)->codiso;
    return Vies::check($this->cifnif, $codiso, $msg) === 1;
}

Customer Groups

public function getGroup(): GrupoClientes
{
    // Returns customer group
    // Groups share settings like payment terms
    // Can inherit subaccount from group
}

Tax Withholding

public function irpf(): float
{
    // Returns withholding percentage
    // Used in invoices
    if (empty($this->codretencion)) {
        return 0.0;
    }
    
    $retention = new Retencion();
    if ($retention->load($this->codretencion)) {
        return $retention->porcentaje;
    }
    
    return 0.0;
}

Advanced Search

public function codeModelSearch(string $query, string $fieldCode = '', 
                                array $where = []): array
{
    // Searches across multiple fields:
    // - cifnif, codcliente, email, nombre
    // - observaciones, razonsocial
    // - telefono1, telefono2
    // Excludes inactive customers (fechabaja IS NULL)
}

Suppliers (Proveedores)

Suppliers represent the entities you purchase from.

Supplier Structure

Located at Core/Model/Proveedor.php:

class Proveedor extends ModelClass
{
    use EmailAndPhonesTrait;
    use FiscalNumberTrait;
    use GravatarTrait;
    
    const SPECIAL_ACCOUNT = 'PROVEE';
    const SPECIAL_CREDITOR_ACCOUNT = 'ACREED';
    
    public $codproveedor;      // Supplier code (1-10 chars)
    public $nombre;            // Name
    public $razonsocial;       // Company name
    
    // Contact information
    public $email;
    public $telefono1;
    public $telefono2;
    public $fax;
    public $web;
    
    // Fiscal information
    public $cifnif;
    public $tipoidfiscal;
    public $personafisica;
    public $regimeniva;
    
    // Purchase configuration
    public $codpago;           // Payment method
    public $codserie;          // Document series
    public $codimpuestoportes; // Shipping tax code
    public $codretencion;      // Withholding code
    
    // Accounting
    public $codsubcuenta;      // Account code
    public $acreedor;          // Creditor flag (uses ACREED account)
    
    // Addresses
    public $idcontacto;        // Main address ID
    
    // Status
    public $debaja;
    public $fechaalta;
    public $fechabaja;
    
    // Localization
    public $langcode;
    
    // Related entities
    public $codcliente;        // Also a customer?
    public $observaciones;
}

Supplier vs Creditor

public function getSubcuenta(string $codejercicio, bool $crear): Subcuenta
{
    $specialAccount = $this->acreedor ?
        static::SPECIAL_CREDITOR_ACCOUNT :  // ACREED
        static::SPECIAL_ACCOUNT;             // PROVEE
    
    // Creates subaccount using appropriate special account
}

Regular Suppliers (PROVEE):

Normal purchase transactions
Standard payment terms

Creditors (ACREED):

Short-term creditors
Different accounting treatment
Used for non-standard payables

Supplier Features

Suppliers share similar functionality with customers:

public function getAddresses(): array;
public function getBankAccounts(): array;
public function getDefaultAddress(): Contacto;
public function checkVies(bool $msg = true): bool;
public function irpf(): float;

Contacts (Contactos)

Contacts represent physical addresses and contact points.

Contact Structure

Located at Core/Model/Contacto.php:

class Contacto extends ModelClass
{
    use EmailAndPhonesTrait;
    use FiscalNumberTrait;
    use GravatarTrait;
    
    public $idcontacto;        // Primary key
    
    // Personal information
    public $nombre;            // First name
    public $apellidos;         // Last name
    public $descripcion;       // Description/label
    public $cargo;             // Job title
    
    // Company
    public $empresa;           // Company name
    
    // Contact information
    public $email;
    public $telefono1;
    public $telefono2;
    public $fax;               // Fax (deprecated)
    public $web;
    
    // Address
    public $direccion;         // Street address
    public $apartado;          // P.O. Box
    public $codpostal;         // Postal code
    public $ciudad;            // City
    public $provincia;         // Province/state
    public $codpais;           // Country code
    
    // Fiscal information
    public $cifnif;
    public $tipoidfiscal;
    public $personafisica;
    
    // Relationships
    public $codcliente;        // Customer code
    public $codproveedor;      // Supplier code
    public $codagente;         // Agent code
    
    // Privacy
    public $aceptaprivacidad;  // Privacy policy accepted
    public $admitemarketing;   // Marketing consent
    public $verificado;        // Email verified
    
    // Dates
    public $fechaalta;         // Creation date
    
    // Localization
    public $langcode;
    
    // Notes
    public $observaciones;
}

Contact Features

Full Name

public function fullName(): string
{
    return $this->nombre . ' ' . $this->apellidos;
}

Country Name

public function country(): string
{
    return Paises::get($this->codpais)->nombre ?? $this->codpais;
}

Customer/Supplier Creation

public function getCustomer(bool $create = true): Cliente
{
    // Gets existing customer or creates new one
    // Copies all relevant data from contact
    // Links contact as billing address
}

public function getSupplier(bool $create = true): Proveedor
{
    // Gets existing supplier or creates new one
    // Copies all relevant data from contact
}

VAT Validation

public function checkVies(bool $msg = true): bool
{
    $codiso = Paises::get($this->codpais)->codiso ?? '';
    return Vies::check($this->cifnif ?? '', $codiso, $msg) === 1;
}

Advanced Search

public function codeModelSearch(string $query, string $fieldCode = '', 
                                array $where = []): array
{
    // Searches across:
    // - apellidos, cifnif, descripcion
    // - email, empresa, nombre
    // - observaciones, telefono1, telefono2
}

Contact as Address

Contacts serve as addresses for customers and suppliers:

Billing addresses: Used for invoices
Shipping addresses: Used for deliveries
Multiple addresses: Each customer/supplier can have many
Default addresses: Set via idcontactofact and idcontactoenv

Common Traits

All CRM entities use shared traits:

EmailAndPhonesTrait

Provides:

$email: Email address
$telefono1: Primary phone
$telefono2: Secondary phone
testEmailAndPhones(): Validation

FiscalNumberTrait

Provides:

$cifnif: Tax ID number
$tipoidfiscal: Tax ID type
testFiscalNumber(): Validation

GravatarTrait

Provides:

Gravatar image integration
Email-based avatar display

Validation

Customer Validation

public function test(): bool
{
    // Name is required
    if (empty($this->nombre)) {
        return false;
    }
    
    // Auto-populate razonsocial from nombre
    if (empty($this->razonsocial)) {
        $this->razonsocial = $this->nombre;
    }
    
    // Validate web URL
    if (!empty($this->web) && false === Validator::url($this->web)) {
        return false;
    }
    
    // Clean HTML
    $this->nombre = Tools::noHtml($this->nombre);
    $this->razonsocial = Tools::noHtml($this->razonsocial);
    
    // Set debaja flag from fechabaja
    $this->debaja = !empty($this->fechabaja);
    
    // Validate fiscal number
    // Validate email and phones
    // Validate payment days
    return parent::test() && 
           $this->testFiscalNumber() && 
           $this->testEmailAndPhones() && 
           $this->testDiasPago();
}

Code Validation

Customer and supplier codes:

1-10 alphanumeric characters
Pattern: /^[A-Z0-9_\+\.\-]{1,10}$/i
Auto-generated if not provided

Automatic Creation

Customer Creation

When a customer is created, a default contact is automatically generated:

protected function saveInsert(): bool
{
    if (parent::saveInsert() && empty($this->idcontactofact)) {
        // Create default billing contact
        $contact = new Contacto();
        $contact->codcliente = $this->codcliente;
        $contact->nombre = $this->nombre;
        $contact->empresa = $this->razonsocial;
        $contact->email = $this->email;
        // ... copy all relevant fields
        
        if ($contact->save()) {
            $this->idcontactofact = $contact->idcontacto;
            return $this->save();
        }
    }
}

Supplier Creation

Similar automatic contact creation for suppliers.

Customer Groups

Customers can be organized into groups:

Shared settings (payment terms, subaccount)
Group-level discounts
Reporting and segmentation
Targeted marketing

// Customer inherits settings from group
if ($group->codsubcuenta) {
    return $group->getSubcuenta($codejercicio, $crear);
}

Sales Agents

Assign sales agents to customers:

public $codagente;  // Sales agent code

Benefits:

Commission tracking
Sales performance reports
Customer assignment
Territory management

Contacts include privacy fields:

public $aceptaprivacidad;  // Privacy policy accepted
public $admitemarketing;   // Marketing consent
public $verificado;        // Email verified

Use these for:

GDPR compliance
Email marketing lists
Communication preferences
Consent tracking

Best Practices

Customer Codes

Use meaningful customer codes if manually assigned. Consider including location, type, or registration year codes.

Credit Limits

Set appropriate credit limits (riesgomax) for customers. Monitor riesgoalcanzado regularly.

Multiple Addresses

Create separate contacts for each physical location. This improves delivery tracking and reporting.

Customer Groups

Use groups for wholesale vs retail customers, or by region. Apply group-level settings to simplify management.

Data Quality

Validate tax IDs using checkVies() for EU customers. Keep email addresses and phone numbers up to date.

Integration Points

With Invoicing

Default payment methods and terms
Billing and shipping addresses
Tax regime and withholding
Document series and numbering

With Accounting

Automatic subaccount creation
Customer/supplier balances
Aging reports
Payment tracking

With Inventory

Customer-specific pricing (via tariffs)
Preferred products
Purchase history
Sales analysis

Core/Model/Cliente.php - Customers
Core/Model/Proveedor.php - Suppliers
Core/Model/Contacto.php - Contacts/addresses
Core/Model/GrupoClientes.php - Customer groups
Core/Model/Agente.php - Sales agents
Core/Model/CuentaBancoCliente.php - Customer bank accounts
Core/Model/CuentaBancoProveedor.php - Supplier bank accounts
Core/Model/FormaPago.php - Payment methods
Core/Model/Retencion.php - Tax withholding

Get Started

Core Features

Administration

User Guides

​Core Entities

Customers

Suppliers

Contacts

​Customers (Clientes)

​Customer Structure

​Key Features

​Multiple Addresses

​Bank Accounts

​Payment Terms

​Accounting Integration

​VAT Validation

​Customer Groups

​Tax Withholding

​Advanced Search

​Suppliers (Proveedores)

​Supplier Structure

​Supplier vs Creditor

​Supplier Features

​Contacts (Contactos)

​Contact Structure

​Contact Features

​Full Name

​Country Name

​Customer/Supplier Creation

​VAT Validation

​Advanced Search

​Contact as Address

​Common Traits

​EmailAndPhonesTrait

​FiscalNumberTrait

​GravatarTrait

​Validation

​Customer Validation

​Code Validation

​Automatic Creation

​Customer Creation

​Supplier Creation

​Customer Groups

​Sales Agents

​Privacy and GDPR

​Best Practices

​Integration Points

​With Invoicing

​With Accounting

​With Inventory

​Related Models

​Next Steps

Invoicing

Accounting

Core Entities

Customers (Clientes)

Customer Structure

Key Features

Multiple Addresses

Bank Accounts

Payment Terms

Accounting Integration

VAT Validation

Customer Groups

Tax Withholding

Advanced Search

Suppliers (Proveedores)

Supplier Structure

Supplier vs Creditor

Supplier Features

Contacts (Contactos)

Contact Structure

Contact Features

Full Name

Country Name

Customer/Supplier Creation

VAT Validation

Advanced Search

Contact as Address

Common Traits

EmailAndPhonesTrait

FiscalNumberTrait

GravatarTrait

Validation

Customer Validation

Code Validation

Automatic Creation

Customer Creation

Supplier Creation

Customer Groups

Sales Agents

Privacy and GDPR

Best Practices

Integration Points

With Invoicing

With Accounting

With Inventory

Related Models

Next Steps