Clients API - Inventario

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)

string

Client name (max 150 characters, required)

string

Phone number (max 20 characters, optional)

string

ID/document number (max 20 characters, optional)

boolean

Active status (default: true)

datetime

Creation timestamp (auto-generated)

integer

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

PlantillaSMS Model (SMS Template)

integer

Template identifier

string

Template name (max 100 characters)

text

Message template (use {nombre} for personalization)

boolean

Active status (default: true)

datetime

Creation timestamp

integer

Foreign key to User

CampanaSMS Model (SMS Campaign)

integer

Campaign identifier

string

Campaign name (max 200 characters)

text

Message content

integer

Total recipients (default: 0)

integer

Successfully sent count (default: 0)

integer

Failed send count (default: 0)

string

Campaign status: pendiente, procesando, completado, or error

datetime

Creation timestamp

datetime

Completion timestamp (optional)

integer

Foreign key to User

SMSLog Model (SMS Log)

integer

Log entry identifier

integer

Foreign key to CampanaSMS

integer

Foreign key to Cliente

text

Message content sent

string

Send status: enviado or fallido

string

Twilio message SID (max 100 characters, optional)

text

Error message if failed (optional)

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

string

required

Client name (max 150 characters)

string

Phone number (max 20 characters)

string

ID/document number (max 20 characters)

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"

string

required

Template name (max 100 characters)

text

required

Message template. Use {nombre} placeholder for personalization.

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"
  }'

array

required

Array of client IDs to send SMS to

string

required

Message content. Use {nombre} for personalization.

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

​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

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