Notificaciones API

Overview

The Notificaciones (Notifications) API manages notifications sent to users regarding campaigns and system events.

Model Structure

The Notificacion model represents notifications with read/unread status tracking.

Fields

id_notificacion

integer

required

Primary key. Auto-incremented unique identifier for the notification.

fecha_envio

date

required

Date when the notification was sent. Format: YYYY-MM-DD

id_campana

integer

required

Campaign ID associated with this notification. Links to CampanaPublicitaria.

estado

string

required

Notification read status. Must be one of the following choices:

"leido": Notification has been read by the user
"no leido": Notification has not been read yet

Maximum 20 characters.

titulo

string

required

Notification title. Brief subject line. Maximum 20 characters.

descripcion

string

required

Notification description. Detailed message content. Maximum 100 characters.

Endpoints

List Notifications

GET /api/notificaciones/

Retrieves all notifications in the system.

Query Parameters

estado

string

Filter notifications by read status. Values: "leido" or "no leido"

id_campana

integer

Filter notifications by campaign ID

fecha_envio

date

Filter notifications by send date (YYYY-MM-DD)

Response

id_notificacion

integer

Unique identifier for the notification

fecha_envio

date

Date the notification was sent

id_campana

integer

Associated campaign ID

estado

string

Read status: "leido" or "no leido"

titulo

string

Notification title

descripcion

string

Notification description

Example Response

[
  {
    "id_notificacion": 1,
    "fecha_envio": "2024-03-15",
    "id_campana": 5,
    "estado": "no leido",
    "titulo": "Nueva Campaña",
    "descripcion": "Se ha lanzado una nueva campaña publicitaria en tu ciudad. ¡Participa y gana!"
  },
  {
    "id_notificacion": 2,
    "fecha_envio": "2024-03-14",
    "id_campana": 3,
    "estado": "leido",
    "titulo": "Pago Procesado",
    "descripcion": "Tu pago de $250.00 ha sido procesado exitosamente."
  },
  {
    "id_notificacion": 3,
    "fecha_envio": "2024-03-13",
    "id_campana": 5,
    "estado": "leido",
    "titulo": "Recordatorio",
    "descripcion": "Recuerda completar tu registro para la campaña antes del 20 de marzo."
  }
]

Get Notification

GET /api/notificaciones/{id_notificacion}/

Retrieves a specific notification by ID.

Path Parameters

id_notificacion

integer

required

The unique identifier of the notification to retrieve

Response

id_notificacion

integer

Unique identifier for the notification

fecha_envio

date

Date the notification was sent

id_campana

integer

Associated campaign ID

estado

string

Read status: "leido" or "no leido"

titulo

string

Notification title

descripcion

string

Notification description

Example Response

{
  "id_notificacion": 1,
  "fecha_envio": "2024-03-15",
  "id_campana": 5,
  "estado": "no leido",
  "titulo": "Nueva Campaña",
  "descripcion": "Se ha lanzado una nueva campaña publicitaria en tu ciudad. ¡Participa y gana!"
}

Get Unread Notifications

GET /api/notificaciones/?estado=no leido

Retrieves all unread notifications.

Example Response

[
  {
    "id_notificacion": 1,
    "fecha_envio": "2024-03-15",
    "id_campana": 5,
    "estado": "no leido",
    "titulo": "Nueva Campaña",
    "descripcion": "Se ha lanzado una nueva campaña publicitaria en tu ciudad. ¡Participa y gana!"
  },
  {
    "id_notificacion": 4,
    "fecha_envio": "2024-03-15",
    "id_campana": 7,
    "estado": "no leido",
    "titulo": "Aprobación Pendiente",
    "descripcion": "Tu solicitud está siendo revisada por el equipo administrativo."
  }
]

Create Notification

POST /api/notificaciones/

Creates a new notification.

Request Body

fecha_envio

date

required

Date the notification is sent. Format: YYYY-MM-DD

id_campana

integer

required

ID of the associated campaign

estado

string

required

Initial read status. Values: "leido" or "no leido". Typically set to "no leido" for new notifications.

titulo

string

required

Notification title. Maximum 20 characters.

descripcion

string

required

Notification description. Maximum 100 characters.

Example Request

{
  "fecha_envio": "2024-03-16",
  "id_campana": 8,
  "estado": "no leido",
  "titulo": "Bienvenido",
  "descripcion": "Gracias por registrarte. Tu cuenta ha sido activada exitosamente."
}

Response

id_notificacion

integer

Unique identifier for the newly created notification

fecha_envio

date

Date the notification was sent

id_campana

integer

Associated campaign ID

estado

string

Read status

titulo

string

Notification title

descripcion

string

Notification description

Update Notification

PUT /api/notificaciones/{id_notificacion}/

Updates an existing notification.

Path Parameters

id_notificacion

integer

required

The unique identifier of the notification to update

Request Body

fecha_envio

date

required

Date the notification was sent

id_campana

integer

required

ID of the associated campaign

estado

string

required

Read status. Values: "leido" or "no leido"

titulo

string

required

Notification title. Maximum 20 characters.

descripcion

string

required

Notification description. Maximum 100 characters.

Example Request

{
  "fecha_envio": "2024-03-15",
  "id_campana": 5,
  "estado": "leido",
  "titulo": "Nueva Campaña",
  "descripcion": "Se ha lanzado una nueva campaña publicitaria en tu ciudad. ¡Participa y gana!"
}

Mark as Read

PATCH /api/notificaciones/{id_notificacion}/

Marks a notification as read. This is a partial update endpoint commonly used to change notification status.

Path Parameters

id_notificacion

integer

required

The unique identifier of the notification to mark as read

Request Body

estado

string

required

Set to "leido" to mark as read

Example Request

{
  "estado": "leido"
}

Example Response

{
  "id_notificacion": 1,
  "fecha_envio": "2024-03-15",
  "id_campana": 5,
  "estado": "leido",
  "titulo": "Nueva Campaña",
  "descripcion": "Se ha lanzado una nueva campaña publicitaria en tu ciudad. ¡Participa y gana!"
}

Bulk Mark as Read

POST /api/notificaciones/bulk_mark_read/

Marks multiple notifications as read in a single request.

Request Body

notification_ids

array

required

Array of notification IDs to mark as read

Example Request

{
  "notification_ids": [1, 4, 7, 9]
}

Example Response

{
  "updated": 4,
  "message": "4 notifications marked as read"
}

Delete Notification

DELETE /api/notificaciones/{id_notificacion}/

Deletes a notification from the system.

Path Parameters

id_notificacion

integer

required

The unique identifier of the notification to delete

Response

Returns 204 No Content on successful deletion.

Estado Field Values

The estado field uses specific string choices:

Available States

leido

string

Leido - Notification has been read by the user

Used when: User opens and views the notification
Display label: “Leído”

no leido

string

No Leido - Notification has not been read

Used when: Notification is first created or hasn’t been opened
Display label: “No Leído”
Default state for new notifications

Example Estado Usage

{
  "estado": "no leido"  // Correct
}

{
  "estado": "No Leido"  // Incorrect - case sensitive
}

{
  "estado": "unread"  // Incorrect - must use Spanish values
}

Relationships

The Notificacion model references:

CampanaPublicitaria: Notifications are associated with specific campaigns via id_campana

Usage Notes

The estado field must be exactly "leido" or "no leido" (case-sensitive)
New notifications should typically be created with estado: "no leido"
The titulo field is limited to 20 characters - keep titles concise
The descripcion field is limited to 100 characters - keep messages brief
Use the fecha_envio to track when notifications were sent for sorting and filtering
Consider implementing pagination for notification lists in high-volume scenarios

Best Practices

User Experience: Show unread count as a badge in the UI
Automatic Marking: Mark notifications as read when user views them
Sorting: Display newest notifications first (orden_by=-fecha_envio)
Cleanup: Implement periodic cleanup of old read notifications
Push Notifications: Integrate with Usuario.token_notificacion for push notifications
Grouping: Group notifications by campaign or date for better organization
Validation: Ensure id_campana references a valid campaign before creating

Integration with Push Notifications

The notification system integrates with user push notification tokens:

# Example: Send push notification when creating a Notificacion
user = Usuario.objects.get(...)  # Get target user
notification = Notificacion.objects.create(
    fecha_envio=date.today(),
    id_campana=campaign_id,
    estado="no leido",
    titulo="Nueva Campaña",
    descripcion="Se ha lanzado una nueva campaña..."
)

# Send push notification using user.token_notificacion
send_push_notification(
    token=user.token_notificacion,
    title=notification.titulo,
    body=notification.descripcion
)

Common Notification Types

Campaign Notifications

New campaign launches
Campaign approval/rejection
Campaign expiration reminders
Registration deadlines

Payment Notifications

Payment processed
Payment pending
Payment failed

System Notifications

Account activation
Profile updates
Document verification status
Terms and conditions updates

Example Notification Templates

[
  {
    "titulo": "Campaña Activa",
    "descripcion": "Tu campaña publicitaria está ahora activa y visible para conductores."
  },
  {
    "titulo": "Pago Recibido",
    "descripcion": "Se ha acreditado $150.00 a tu cuenta por tu participación en la campaña."
  },
  {
    "titulo": "Verificación Req.",
    "descripcion": "Por favor sube tu licencia de conducir para completar tu perfil."
  },
  {
    "titulo": "Último Día",
    "descripcion": "Hoy es el último día para registrarte en la campaña de Coca-Cola."
  }
]

Overview

Authentication & Users

Campaigns

Companies & Advertisers

Vehicles

Drivers & Clients

Campaign Operations

Financial

Workshops

Location & System

Permissions

Utilities

​Overview

​Model Structure

​Fields

​Endpoints

​List Notifications

​Query Parameters

​Response

​Example Response

​Get Notification

​Path Parameters

​Response

​Example Response

​Get Unread Notifications

​Example Response

​Create Notification

​Request Body

​Example Request

​Response

​Update Notification

​Path Parameters

​Request Body

​Example Request

​Mark as Read

​Path Parameters

​Request Body

​Example Request

​Example Response

​Bulk Mark as Read

​Request Body

​Example Request

​Example Response

​Delete Notification

​Path Parameters

​Response

​Estado Field Values

​Available States

​Example Estado Usage

​Relationships

​Usage Notes

​Best Practices

​Integration with Push Notifications

​Common Notification Types

​Campaign Notifications

​Payment Notifications

​System Notifications

​Example Notification Templates

Build docs developers (and LLMs) love

Overview

Model Structure

Fields

Endpoints

List Notifications

Query Parameters

Response

Example Response

Get Notification

Path Parameters

Response

Example Response

Get Unread Notifications

Example Response

Create Notification

Request Body

Example Request

Response

Update Notification

Path Parameters

Request Body

Example Request

Mark as Read

Path Parameters

Request Body

Example Request

Example Response

Bulk Mark as Read

Request Body

Example Request

Example Response

Delete Notification

Path Parameters

Response

Estado Field Values

Available States

Example Estado Usage

Relationships

Usage Notes

Best Practices

Integration with Push Notifications

Common Notification Types

Campaign Notifications

Payment Notifications

System Notifications

Example Notification Templates