Skip to main content

​
Overview

The Customer Service (jea-cliente) maintains a comprehensive customer database with full CRUD operations, enabling detailed customer relationship management and sales tracking.

​
Key Features

Customer Profiles

Complete customer information including identification, contact details, and status

Unique Identification

DNI (national ID) and email uniqueness enforcement for data integrity

Contact Management

Full contact information including phone, email, and physical address

Registration Tracking

Automatic registration date tracking for customer lifecycle analysis

Status Management

Active/inactive status for customer account management

Sales Integration

Direct integration with sales service for transaction history

​
Customer Entity Structure

The customer entity captures all essential information for relationship management: 
@Entity
@Table(name = "cliente", uniqueConstraints = {
        @UniqueConstraint(columnNames = {"dni"})
})
public class Cliente {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String dni;              // National ID (unique)

    @Column(nullable = false)
    private String nombre;           // First name

    private String apellido;         // Last name

    private String direccion;        // Physical address

    private String telefono;         // Phone number

    @Column(nullable = false, unique = true)
    private String email;            // Email address (unique)

    private LocalDateTime fechaRegistro;  // Registration date

    private Boolean activo = true;   // Active status
}

​
Automatic Registration Tracking

Customer registration dates are automatically recorded when new customers are created: 
@PrePersist
public void prePersist() {
    this.fechaRegistro = LocalDateTime.now();
    if (activo == null) {
        activo = true;
    }
}
This ensures every customer has an accurate registration timestamp for:
  • Customer lifecycle analysis
  • Loyalty program qualification
  • Registration date reporting
  • Customer segmentation by registration period

​
Available Endpoints

The Customer Service provides comprehensive customer management operations:
MethodEndpointDescription
GET/clienteList all customers
GET/cliente/{id}Get customer by ID
POST/clienteCreate new customer
PUT/cliente/{id}Update customer
DELETE/cliente/{id}Delete customer
GET/cliente/dni/{dni}Find customer by DNI
GET/cliente/email/{email}Find customer by email
GET/cliente/activosList active customers only

​
Customer Profile Management

​
Creating Customers

When creating a new customer, the following fields are required:
  • DNI - Must be unique across the system
  • Nombre - Customer first name
  • Email - Must be unique across the system
Optional fields include:
  • Apellido (last name)
  • Direccion (address)
  • Telefono (phone number)

​
Updating Customer Information

Customer information can be updated at any time while maintaining:
  • DNI uniqueness
  • Email uniqueness
  • Registration date preservation

​
Customer Status

Customers can be marked as active or inactive:
  • Active - Can make purchases and receive communications
  • Inactive - Soft deleted but retained for historical data
Inactive customers are retained in the system to preserve transaction history and reporting accuracy. Use the status field instead of deleting customer records.

​
Data Validation

​
Unique Constraints

The system enforces uniqueness for:
  • DNI - National identification number
  • Email - Email address
Attempts to create duplicate DNI or email values will result in validation errors.

​
Required Fields

The following fields are mandatory:
  • DNI
  • Nombre (first name)
  • Email
Missing required fields will prevent customer creation.

​
Sales Integration

Customers are integrated with the sales system:

​
Customer Sales History

  • View all purchases by customer
  • Track customer spending patterns
  • Calculate customer lifetime value
  • Generate customer-specific reports

​
Sales Process Integration

The Sales Service uses Feign clients to:
  • Validate customer existence before creating sales
  • Retrieve customer details for invoices
  • Link transactions to customer records
  • Enable customer-based reporting

​
Search Capabilities

Quickly find customers by national ID: 
GET /cliente/dni/12345678
Useful for point-of-sale scenarios where customers provide ID numbers. Find customers by email address: 
GET /cliente/email/[email protected]
Ideal for online orders and email-based customer lookup.

​
Active Customer Filter

Retrieve only active customers: 
GET /cliente/activos
Useful for marketing campaigns and active customer reporting.

​
Customer Segmentation

Segment customers based on various criteria:
  • Registration Date - New vs. established customers
  • Active Status - Active vs. inactive customers
  • Purchase History - High-value vs. occasional buyers
  • Geographic Location - By address or region

​
Privacy and Compliance

​
Data Protection

Customer data is protected through:
  • Unique identification requirements
  • Controlled access via API endpoints
  • Authentication required for all operations
  • Audit trails through timestamp tracking

​
Customer Data Rights

  • Access - Customers can request their data via GET endpoints
  • Modification - Customer information can be updated
  • Deletion - Soft deletion via inactive status
  • History Preservation - Transaction history is maintained

​
Best Practices

Validate DNI format before creating customer records. In Peru, DNI should be 8 digits. Implement client-side validation to prevent errors.
Consider implementing email verification workflows to ensure email addresses are valid and owned by the customer.
Before creating new customers, search by DNI and email to prevent duplicate records. Use the search endpoints to check for existing customers.
Regularly prompt customers to update their contact information to maintain accurate records for communications and deliveries.
Use the activo field instead of deleting customer records. This preserves historical data while preventing new transactions.

​
Customer Lifecycle Management

​
Registration

  • Capture complete customer information at registration
  • Validate DNI and email uniqueness
  • Assign automatic registration timestamp
  • Set initial active status

​
Active Period

  • Process sales and transactions
  • Update contact information as needed
  • Track purchase history
  • Generate customer reports

​
Deactivation

  • Mark customer as inactive when needed
  • Preserve all historical data
  • Prevent new transactions
  • Maintain reporting accuracy

​
Reporting and Analytics

Customer data enables various analytics:
  • Customer Acquisition - Track new customer registrations over time
  • Customer Retention - Monitor active vs. inactive customers
  • Geographic Distribution - Analyze customers by location
  • Contact Preferences - Track communication channels

​
Next Steps

API Reference

Detailed customer API documentation

Sales Management

Process customer transactions

Analytics & Reporting

Customer analytics and insights

Payment Processing

Customer payment options

Build docs developers (and LLMs) love

Get started for freeTalk to us