Clients API

Overview

The Clients API manages customer records with support for SMS marketing campaigns via Twilio integration.

Cliente Model (Client)

integer

Unique client identifier (auto-generated)

nombre

string

Client name (max 150 characters, required)

telefono

string

Phone number (max 20 characters, optional)

documento

string

ID/document number (max 20 characters, optional)

activo

boolean

Active status (default: true)

creado

datetime

Creation timestamp (auto-generated)

usuario

integer

Foreign key to User who created the client (PROTECT constraint)

PlantillaSMS Model (SMS Template)

integer

Template identifier

nombre

string

Template name (max 100 characters)

mensaje

text

Message template (use {nombre} for personalization)

activo

boolean

Active status (default: true)

creado

datetime

Creation timestamp

usuario

integer

Foreign key to User

CampanaSMS Model (SMS Campaign)

integer

Campaign identifier

nombre

string

Campaign name (max 200 characters)

mensaje

text

Message content

total_clientes

integer

Total recipients (default: 0)

enviados_exitosos

integer

Successfully sent count (default: 0)

enviados_fallidos

integer

Failed send count (default: 0)

estado

string

Campaign status: pendiente, procesando, completado, or error

creado

datetime

Creation timestamp

completado

datetime

Completion timestamp (optional)

usuario

integer

Foreign key to User

SMSLog Model (SMS Log)

integer

Log entry identifier

campana

integer

Foreign key to CampanaSMS

cliente

integer

Foreign key to Cliente

mensaje

text

Message content sent

estado

string

Send status: enviado or fallido

twilio_sid

string

Twilio message SID (max 100 characters, optional)

error_mensaje

text

Error message if failed (optional)

creado

datetime

Log timestamp

List Clients

Requires authentication. Returns clients owned by the authenticated user.

curl -X GET http://localhost:8000/clientes/ \
  -H "Cookie: sessionid=<your-session>"

Response

Returns rendered HTML with list of active clients.

Create Client

Requires authentication and admin role.

curl -X POST http://localhost:8000/clientes/nuevo/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "X-CSRFToken: <token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "nombre=Maria Gonzalez" \
  -d "telefono=3001234567" \
  -d "documento=987654321" \
  -d "activo=true"

Request Parameters

nombre

string

required

Client name (max 150 characters)

telefono

string

Phone number (max 20 characters)

documento

string

ID/document number (max 20 characters)

activo

boolean

default:"true"

Active status

Response

Success (HTTP 302): Redirects to /clientes/ with flash message Validation Error (HTTP 200): Re-renders form with errors

Create Client (AJAX)

curl -X POST http://localhost:8000/clientes/crear/ajax/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <token>" \
  -d '{
    "nombre": "Carlos Ruiz",
    "telefono": "3009876543",
    "documento": "123456789"
  }'

Response

{
  "success": true,
  "cliente": {
    "id": 15,
    "nombre": "Carlos Ruiz",
    "telefono": "3009876543",
    "documento": "123456789",
    "activo": true,
    "creado": "2024-03-15T10:30:00-05:00"
  }
}

Error:

{
  "success": false,
  "errors": {
    "nombre": ["This field is required."]
  }
}

Update Client

Requires authentication and admin role.

curl -X POST http://localhost:8000/clientes/editar/<pk>/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "X-CSRFToken: <token>" \
  -d "nombre=Maria Gonzalez (Updated)" \
  -d "telefono=3001112222" \
  -d "activo=true"

URL Parameters

integer

required

Client ID to update

Response

Success: Redirects to clients list Not Found (HTTP 404): Client doesn’t exist or doesn’t belong to user

Delete Client

Requires authentication and admin role. Cannot delete clients referenced in sales (PROTECT constraint).

curl -X POST http://localhost:8000/clientes/eliminar/<pk>/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "X-CSRFToken: <token>"

URL Parameters

integer

required

Client ID to delete

Response

Success: Client deleted, redirects to list Protected Error: Cannot delete due to foreign key constraint (client has sales)

SMS Templates

List SMS Templates

curl -X GET http://localhost:8000/clientes/plantillas/ \
  -H "Cookie: sessionid=<session>"

Get Templates (AJAX)

curl -X GET http://localhost:8000/clientes/plantillas-sms/ \
  -H "Cookie: sessionid=<session>"

Response

{
  "success": true,
  "plantillas": [
    {
      "id": 1,
      "nombre": "Promoción Mensual",
      "mensaje": "Hola {nombre}, aprovecha 20% de descuento este mes!"
    },
    {
      "id": 2,
      "nombre": "Recordatorio",
      "mensaje": "Hola {nombre}, te esperamos en nuestra tienda!"
    }
  ]
}

Create SMS Template

Requires authentication and admin role.

curl -X POST http://localhost:8000/clientes/plantillas/crear/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "X-CSRFToken: <token>" \
  -d "nombre=Welcome Message" \
  -d "mensaje=Hola {nombre}, bienvenido a nuestra tienda!" \
  -d "activo=true"

nombre

string

required

Template name (max 100 characters)

mensaje

text

required

Message template. Use {nombre} placeholder for personalization.

activo

boolean

default:"true"

Active status

Update SMS Template

curl -X POST http://localhost:8000/clientes/plantillas/editar/<pk>/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "X-CSRFToken: <token>" \
  -d "nombre=Welcome Message (Updated)" \
  -d "mensaje=Hola {nombre}, bienvenido!"

Delete SMS Template

curl -X POST http://localhost:8000/clientes/plantillas/eliminar/<pk>/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "X-CSRFToken: <token>"

SMS Campaigns

Send SMS to Clients

Requires Twilio credentials configured in environment variables.

curl -X POST http://localhost:8000/clientes/enviar-sms/ \
  -H "Cookie: sessionid=<session>; csrftoken=<token>" \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <token>" \
  -d '{
    "cliente_ids": [1, 2, 3, 5, 8],
    "mensaje": "Hola {nombre}, aprovecha 20% de descuento este mes!",
    "nombre_campana": "Promoción Marzo 2024"
  }'

cliente_ids

array

required

Array of client IDs to send SMS to

mensaje

string

required

Message content. Use {nombre} for personalization.

nombre_campana

string

Campaign name (optional, auto-generated if not provided)

Response

{
  "success": true,
  "campana_id": 10,
  "total_clientes": 5,
  "enviados_exitosos": 4,
  "enviados_fallidos": 1,
  "detalles": [
    {
      "cliente_id": 1,
      "nombre": "Maria Gonzalez",
      "estado": "enviado",
      "twilio_sid": "SM1234567890abcdef"
    },
    {
      "cliente_id": 2,
      "nombre": "Carlos Ruiz",
      "estado": "fallido",
      "error": "Invalid phone number"
    }
  ]
}

Message Personalization

The {nombre} placeholder is replaced with each client’s name:

# Template:
"Hola {nombre}, aprovecha 20% de descuento!"

# For cliente with nombre="Maria":
"Hola Maria, aprovecha 20% de descuento!"

Business Logic

Client Protection

Clients cannot be deleted if they have associated sales:

cliente_fk = models.ForeignKey(
    Cliente,
    on_delete=models.PROTECT  # Prevents deletion
)

Error: ProtectedError exception raised

Multi-Tenancy

Clients are isolated per user:

Admin users see only their own clients
Vendedor users see clients owned by their creado_por admin
Enforced via: Cliente.objects.filter(usuario=request.user)

SMS Campaign Tracking

Each SMS sent creates an SMSLog entry:

Links to campaign and client
Stores Twilio SID for tracking
Records success/failure status
Logs error messages

Campaign aggregates:

total_clientes - Recipients count
enviados_exitosos - Success count
enviados_fallidos - Failure count
estado - Overall campaign status

Example Workflow

# 1. Create client
curl -X POST http://localhost:8000/clientes/nuevo/ \
  -H "X-CSRFToken: <token>" \
  -d "nombre=Laura Mendez" \
  -d "telefono=+573001234567" \
  -d "documento=456789123"

# 2. Create SMS template
curl -X POST http://localhost:8000/clientes/plantillas/crear/ \
  -H "X-CSRFToken: <token>" \
  -d "nombre=New Product Launch" \
  -d "mensaje=Hola {nombre}, tenemos nuevos productos en stock!"

# 3. Get available templates
curl http://localhost:8000/clientes/plantillas-sms/

# 4. Send SMS campaign to multiple clients
curl -X POST http://localhost:8000/clientes/enviar-sms/ \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <token>" \
  -d '{
    "cliente_ids": [1, 5, 10, 15],
    "mensaje": "Hola {nombre}, tenemos nuevos productos en stock!",
    "nombre_campana": "Product Launch - March 2024"
  }'

# Response shows 4 clients, 3 sent successfully, 1 failed

# 5. Update client status
curl -X POST http://localhost:8000/clientes/editar/1/ \
  -H "X-CSRFToken: <token>" \
  -d "activo=false"  # Deactivate client

Sales API - Client sales transactions
See source: applications/clientes/models.py and applications/clientes/views.py

Overview

Endpoints

Overview

Cliente Model (Client)

PlantillaSMS Model (SMS Template)

CampanaSMS Model (SMS Campaign)

SMSLog Model (SMS Log)

List Clients

Response

Create Client

Request Parameters

Response

Create Client (AJAX)

Response

Update Client

URL Parameters

Response

Delete Client

URL Parameters

Response

SMS Templates

List SMS Templates

Get Templates (AJAX)

Response

Create SMS Template

Update SMS Template

Delete SMS Template

SMS Campaigns

Send SMS to Clients

Response

Message Personalization

Business Logic

Client Protection

Multi-Tenancy

SMS Campaign Tracking

Example Workflow

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Cliente Model (Client)

​PlantillaSMS Model (SMS Template)

​CampanaSMS Model (SMS Campaign)

​SMSLog Model (SMS Log)

​List Clients

​Response

​Create Client

​Request Parameters

​Response

​Create Client (AJAX)

​Response

​Update Client

​URL Parameters

​Response

​Delete Client

​URL Parameters

​Response

​SMS Templates

​List SMS Templates

​Get Templates (AJAX)

​Response

​Create SMS Template

​Update SMS Template

​Delete SMS Template

​SMS Campaigns

​Send SMS to Clients

​Response

​Message Personalization

​Business Logic

​Client Protection

​Multi-Tenancy

​SMS Campaign Tracking

​Example Workflow

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Cliente Model (Client)

PlantillaSMS Model (SMS Template)

CampanaSMS Model (SMS Campaign)

SMSLog Model (SMS Log)

List Clients

Response

Create Client

Request Parameters

Response

Create Client (AJAX)

Response

Update Client

URL Parameters

Response

Delete Client

URL Parameters

Response

SMS Templates

List SMS Templates

Get Templates (AJAX)

Response

Create SMS Template

Update SMS Template

Delete SMS Template

SMS Campaigns

Send SMS to Clients

Response

Message Personalization

Business Logic

Client Protection

Multi-Tenancy

SMS Campaign Tracking

Example Workflow

Related Endpoints