Overview
The Clients (Clientes) API allows you to manage client information for the advertising platform. Clients can be associated with companies and campaigns, and may own vehicles that participate in advertising activities.Base Endpoint
Model Structure
Cliente Model
The Cliente model represents a client in the system with the following fields:Unique identifier for the client (auto-generated primary key)
Foreign key reference to the Usuario (User) model. Links the client to their user account
Client’s identification number (cedula). Maximum 10 characters
Client’s first name. Maximum 20 characters
Client’s last name. Maximum 20 characters
Client’s date of birth in ISO 8601 format (YYYY-MM-DD)
Client’s email address. Maximum 40 characters
Client’s gender represented as an integer:
0: Female1: Male
Client’s phone number. Maximum 10 characters
Foreign key reference to the Ciudad (City) model. Defaults to 1
Foreign key reference to the Pais (Country) model. Defaults to 1
Foreign key reference to the Empresa (Company) model. Can be null or blank if the client is not associated with a company
Foreign key reference to the CampanaPublicitaria (Advertising Campaign) model. Can be null or blank if not currently enrolled in a campaign
Current status of the client:
0: Inactive1: Active3: Disabled
Endpoints
List All Clients
GET /Database/Database/clientes/
Retrieve a list of all clients in the system
Response
Client’s unique identifier
Associated user account ID
Client’s identification number
Client’s first name
Client’s last name
Client’s date of birth
Client’s email address
Client’s gender (0: Female, 1: Male)
Client’s phone number
City ID where the client is located
Country ID where the client is located
Associated company ID (nullable)
Associated campaign ID (nullable)
Client’s status (0: Inactive, 1: Active, 3: Disabled)
Example Response
Get Single Client
GET /Database/Database/clientes/{id}/
Retrieve details of a specific client by ID
Path Parameters
The unique identifier of the client
Example Response
Create New Client
POST /Database/Database/clientes/
Create a new client in the system
Request Body
User account ID to associate with this client
Client’s identification number (max 10 characters)
Client’s first name (max 20 characters)
Client’s last name (max 20 characters)
Client’s date of birth (YYYY-MM-DD)
Client’s email address (max 40 characters)
Client’s gender (0 or 1)
Client’s phone number (max 10 characters)
City ID (defaults to 1 if not provided)
Country ID (defaults to 1 if not provided)
Company ID to associate with this client (optional)
Campaign ID to associate with this client (optional)
Client status (0, 1, or 3)
Example Request
Example Response
Update Client
PUT /Database/Database/clientes/{id}/
Update an existing client’s information (full update)
Path Parameters
The unique identifier of the client to update
Request Body
All fields from the create request are required for a full update.Example Request
Partial Update Client
PATCH /Database/Database/clientes/{id}/
Partially update a client’s information
Path Parameters
The unique identifier of the client to update
Request Body
Include only the fields you want to update.Example Request
Delete Client
DELETE /Database/Database/clientes/{id}/
Delete a client from the system
Path Parameters
The unique identifier of the client to delete
Response
Relationships
Related Models
The Cliente model has foreign key relationships with:- Usuario (
id_usuario): Links to the user account. Each client must have an associated user account with authentication credentials - Ciudad (
id_ciudad): Links to the city where the client is located - Pais (
id_pais): Links to the country where the client is located - Empresa (
id_empresa): Optional link to a company that the client represents or works with - CampanaPublicitaria (
id_campana): Optional link to an active advertising campaign the client is participating in
Referenced By
Clients are referenced by:- Vehiculo model via
id_cliente- Links vehicles owned by clients - MovimientoCapital model - Tracks financial transactions associated with clients
Business Logic
Client Registration Flow
- A user account must be created first with appropriate role
- The Cliente record is then created linking to the user via
id_usuario - Clients can optionally be associated with a company during or after registration
- Clients can enroll in advertising campaigns by setting
id_campana
Campaign Association
- Clients can be associated with advertising campaigns to track their participation
- The
id_campanafield allows tracking which campaign a client is currently active in - Multiple clients can be associated with the same campaign
- Clients can change campaigns by updating the
id_campanafield
Company Association
- Clients can represent companies by linking via
id_empresa - This is useful for corporate clients who manage vehicles on behalf of their organization
- The company association is optional and can be null for individual clients
Status Management
- Active (1): Client can participate in campaigns and use the system
- Inactive (0): Client account exists but is not currently active
- Disabled (3): Client has been disabled by administrators and cannot access the system
Validation Notes
cedula_clienteshould be exactly 10 digits for most Latin American countriesemailmust be a valid email formattelefonoshould follow local phone number format (typically 10 digits)id_usuariomust reference an existing user with appropriate client roleid_empresaandid_campanaare optional and can be null- The same
cedula_clienteshould not be registered multiple times
Query Parameters
The API supports filtering clients using query parameters:?estado=1- Filter by status?id_empresa=5- Filter by company?id_campana=12- Filter by campaign?id_ciudad=2- Filter by city?id_pais=1- Filter by country
Example Use Cases
Creating a New Individual Client
Enrolling a Client in a Campaign
Filtering Active Clients by Company
Updating Client Contact Information
Deactivating a Client
Financial Integration
Clients are connected to the financial system through theMovimientoCapital model, which tracks:
- Capital transactions related to campaigns
- Payment history
- Account balances
- Transaction descriptions
Data Privacy Notes
- Client personal information (cedula, email, phone) should be handled according to data protection regulations
- Email addresses should be validated and verified
- Phone numbers may be used for notifications and authentication
- Identification numbers (cedula) are sensitive and should be protected