API Overview - RestAPI

Base URL

The API has two types of endpoints with different base URL structures: Model-based CRUD endpoints (via Django REST Framework router):

https://your-domain.com/Database/Database/

Custom endpoints (send_email, notifications, user-specific views):

https://your-domain.com/Database/

Router-based endpoints (usuarios, empresas, vehiculos, etc.) use /Database/Database/ while custom endpoints use /Database/ directly.

Authentication

The RestAPI uses JWT (JSON Web Token) authentication for secure access to protected endpoints.

JWT Configuration

Authentication Class: JWTAuthentication from rest_framework_simplejwt
Token Lifetime: 8 hours
Token Type: Bearer token

Using JWT Tokens

Include the JWT token in the Authorization header of your requests:

Authorization: Bearer <your-jwt-token>

Example Request with Authentication

curl -X GET https://your-domain.com/Database/Database/usuarios/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

HTTP Methods

The API supports the following HTTP methods for CRUD operations:

Method	Description	Usage
`GET`	Retrieve resources	List all items or get a specific item by ID
`POST`	Create new resources	Create a new item with provided data
`PUT`	Update entire resource	Replace all fields of an existing item
`PATCH`	Partial update	Update specific fields of an existing item
`DELETE`	Remove resources	Delete an item by ID

Response Formats

All API responses are returned in JSON format with appropriate HTTP status codes.

Success Responses

List Resources (GET)

[
  {
    "id": 1,
    "field1": "value1",
    "field2": "value2"
  },
  {
    "id": 2,
    "field1": "value3",
    "field2": "value4"
  }
]

Single Resource (GET/POST/PUT/PATCH)

{
  "id": 1,
  "field1": "value1",
  "field2": "value2",
  "created_at": "2024-03-09T10:30:00Z"
}

Delete Resource (DELETE)

{
  "message": "Resource deleted successfully"
}

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Resource deleted successfully
`400`	Bad Request	Invalid request data or validation error
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`500`	Internal Server Error	Server-side error occurred

Error Handling

Error Response Format

{
  "error": "Error message describing what went wrong"
}

Common Error Scenarios

Validation Errors (400)

{
  "field_name": [
    "This field is required."
  ],
  "another_field": [
    "Invalid value provided."
  ]
}

Not Found Errors (404)

{
  "error": "Usuario no encontrado"
}

Server Errors (500)

{
  "error": "An error occurred"
}

Available Endpoint Categories

The RestAPI provides comprehensive endpoints organized into the following categories:

System & Configuration

State management, countries, cities, and banking entities

User Management

Users, roles, permissions, and authentication

Company & Business

Companies, advertisers, clients, and business relationships

Vehicle Management

Vehicles, brands, models, and drivers

Campaign Management

Advertising campaigns, verifications, and registrations

Financial Operations

Capital movements and revenue tracking

Services & Operations

Workshops, branding services, and completed routes

Communication

Notifications, email, and FCM push notifications

System & Configuration

Estado: /Database/Database/estado/ - Status management
Países: /Database/Database/paises/ - Country information
Ciudades: /Database/Database/ciudades/ - City information
Entidades Bancarias: /Database/Database/entidadesbancarias/ - Banking entity management

User Management

Usuarios: /Database/Database/usuarios/ - User CRUD operations
Rol Usuarios: /Database/Database/rolusuarios/ - User role management
Detalle Permisos: /Database/Database/detallepermisos/ - Permission details
Permisos por Rol: /Database/Database/permisosxrol/ - Role-based permissions
Menús: /Database/Database/menus/ - Menu configuration
Vistas: /Database/Database/vistas/ - View management
Opciones: /Database/Database/opciones/ - System options

Company & Business

Empresas: /Database/Database/empresas/ - Company management
Empresa Imágenes: /Database/Database/empresaimages/ - Company image uploads
Publicistas: /Database/Database/publicistas/ - Advertiser management
Empresa por Publicista: /Database/Database/empresaxpublicistas/ - Company-advertiser relationships
Clientes: /Database/Database/clientes/ - Client management
Sectores: /Database/Database/sectores/ - Sector/zone management
Sectores por Usuario: /Database/sectores_por_usuario/<usuario_id>/ - User-specific sectors (custom endpoint)

Vehicle Management

Marcas de Vehículos: /Database/Database/marcasvehiculos/ - Vehicle brands
Modelos de Vehículos: /Database/Database/modelosvehiculos/ - Vehicle models
Vehículos: /Database/Database/vehiculos/ - Vehicle registry
Choferes: /Database/Database/choferes/ - Driver management
Recorridos Realizados: /Database/Database/recorridosrealizados/ - Completed route tracking

Campaign Management

Campañas Publicitarias: /Database/Database/campaniaspublicitarias/ - Advertising campaigns
Publicidades: /Database/Database/publicidades/ - Advertisement content
Formulario Registro Campaña: /Database/Database/formularioregistrocampana/ - Campaign registration forms
Vehículos Admisibles: /Database/Database/vehiculosadmisiblescampana/ - Campaign-eligible vehicles
Verificación Conductor: /Database/Database/verificacionesconductorcampana/ - Driver verification for campaigns
Ingreso Conductor Campaña: /Database/Database/ingresoconductorcampana/ - Driver campaign enrollment

Financial Operations

Movimiento Capital: /Database/Database/movimientocapital/ - Capital movement tracking

Services & Operations

Taller por Empresa: /Database/Database/tallerxempresas/ - Company workshop assignments
Taller Brandeo: /Database/Database/tallerbrandeos/ - Branding workshop services

Communication

Notificaciones: /Database/Database/notificaciones/ - In-app notifications
Enviar Email: /Database/send_email/ - Email sending service (custom endpoint)
Enviar Notificación FCM: /Database/send_fcm_notification/ - Firebase Cloud Messaging notifications (custom endpoint)

Custom Endpoints

Get Sectors by User

Retrieves sectors accessible to a specific user based on their role.

GET /Database/sectores_por_usuario/<usuario_id>/

Role-based logic:

Administrator (role 1): Returns all sectors
Advertiser (role 2): Returns sectors from associated companies
Company (role 3): Returns sectors belonging to the company

Get Companies List by User

Retrieves companies accessible to a specific user based on their role.

GET /Database/empresas_list/<usuario_id>/

Role-based logic:

Administrator (role 1): Returns companies where user is administrator
Advertiser (role 2): Returns associated companies

API Documentation

Interactive API documentation is available at:

https://your-domain.com/Database/documents/

This provides a browsable interface to explore all endpoints and test requests.

CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) with the following methods:

GET
POST
PUT
PATCH
DELETE
OPTIONS

In production, CORS is configured with specific allowed origins. In development mode, all origins are allowed for testing purposes.

Pagination & Filtering

All ViewSet endpoints support Django REST Framework’s default pagination and filtering capabilities. Refer to individual endpoint documentation for specific query parameters and filtering options.

Getting Started

To start using the API:

Obtain a JWT token through the authentication endpoint
Include the token in the Authorization header
Make requests to the desired endpoints
Handle responses according to the HTTP status codes

For detailed information about specific endpoints, refer to the individual endpoint documentation pages.

Overview

Authentication & Users

Campaigns

Companies & Advertisers

Vehicles

Drivers & Clients

Campaign Operations

Financial

Workshops

Location & System

Permissions

Utilities

​Base URL

​Authentication

​JWT Configuration

​Using JWT Tokens

​Example Request with Authentication

​HTTP Methods

​Response Formats

​Success Responses

​List Resources (GET)

​Single Resource (GET/POST/PUT/PATCH)

​Delete Resource (DELETE)

​HTTP Status Codes

​Error Handling

​Error Response Format

​Common Error Scenarios

​Validation Errors (400)

​Not Found Errors (404)

​Server Errors (500)

​Available Endpoint Categories

System & Configuration

User Management

Company & Business

Vehicle Management

Campaign Management

Financial Operations

Services & Operations

Communication

​System & Configuration

​User Management

​Company & Business

​Vehicle Management

​Campaign Management

​Financial Operations

​Services & Operations

​Communication

​Custom Endpoints

​Get Sectors by User

​Get Companies List by User

​API Documentation

​CORS Configuration

​Pagination & Filtering

​Getting Started

Build docs developers (and LLMs) love

Base URL

Authentication

JWT Configuration

Using JWT Tokens

Example Request with Authentication

HTTP Methods

Response Formats

Success Responses

List Resources (GET)

Single Resource (GET/POST/PUT/PATCH)

Delete Resource (DELETE)

HTTP Status Codes

Error Handling

Error Response Format

Common Error Scenarios

Validation Errors (400)

Not Found Errors (404)

Server Errors (500)

Available Endpoint Categories

System & Configuration

User Management

Company & Business

Vehicle Management

Campaign Management

Financial Operations

Services & Operations

Communication

Custom Endpoints

Get Sectors by User

Get Companies List by User

API Documentation

CORS Configuration

Pagination & Filtering

Getting Started