Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Eleazarguitar18/kantuta_pos_front/llms.txt

Use this file to discover all available pages before exploring further.

The Users module manages the two-layer identity model used in Kantuta POS: a Usuario (system account with credentials and a role) and a Persona (personal identity record with name and demographic data). Every Usuario is backed by exactly one Persona. Registration creates both records in a single call. Update operations are split — account-level fields (email, password, role) go to /usuario/:id, while personal details go to /persona. The mail endpoint provides a simple transactional email utility for notifications.

​
TypeScript Interfaces

export interface BaseEntityAudit {
  estado: boolean;
  id_user_create: number | null;
  id_user_update?: number | null;
  created_at: string; // ISO Date String
  updated_at: string; // ISO Date String
}

export interface Role {
  id: number;
  nombre: "admin" | "user" | string;
  descripcion?: string;
}

export interface Persona extends BaseEntityAudit {
  id: number;
  nombres: string;
  p_apellido: string;
  s_apellido?: string;
  fecha_nacimiento: string; // Format: "YYYY-MM-DD"
  genero: string;           // "M" or "F"
}

export interface Usuario extends BaseEntityAudit {
  id: number;
  name: string;   // Display name
  email: string;
  persona: Persona;
  role: Role;
}

​
User Endpoints

​
Register a New User

POST /usuario/register — Creates a new Usuario and its associated Persona in a single request.
This endpoint is public — no Authorization header is required. It is the only user endpoint that can be called without an existing authenticated session, allowing admin-driven onboarding flows.
​
email
string
required
Unique email address for the new account. Must be a valid email format.
​
password
string
Account password. Should be provided for all standard registrations.
​
nombres
string
required
First name(s) of the person (e.g., "María Elena").
​
p_apellido
string
required
First (paternal) surname (e.g., "García").
​
s_apellido
string
Second (maternal) surname (e.g., "López"). Optional.
​
fecha_nacimiento
string
required
Date of birth in YYYY-MM-DD format (e.g., "1992-04-15").
​
genero
string
required
Gender identifier (e.g., "M" for male, "F" for female).
​
name
string
Optional display name shown in the POS UI. If omitted, the backend may derive it from nombres.
​
estado
boolean
Initial account status. Defaults to true (active) if omitted.
​
id_role
number
Role ID to assign to the new user. If omitted, the backend assigns the default role.
curl -X POST http://localhost:3000/usuario/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Segura#2024",
    "nombres": "Carlos Alberto",
    "p_apellido": "Mamani",
    "s_apellido": "Quispe",
    "fecha_nacimiento": "1995-08-22",
    "genero": "M",
    "name": "carlitos",
    "estado": true
  }'
Response: Usuario — the full user object including the created Persona and assigned Role.

​
List All Users

GET /usuario — Returns all registered user accounts with their associated persona and role data. 
curl -X GET http://localhost:3000/usuario \
  -H "Authorization: Bearer <access_token>"
Response: 
{
  "status": 200,
  "message": "Usuarios encontrados",
  "data": [
    {
      "id": 1,
      "name": "carlitos",
      "email": "[email protected]",
      "estado": true,
      "id_user_create": null,
      "created_at": "2024-08-22T14:00:00.000Z",
      "updated_at": "2024-08-22T14:00:00.000Z",
      "persona": {
        "id": 1,
        "nombres": "Carlos Alberto",
        "p_apellido": "Mamani",
        "s_apellido": "Quispe",
        "fecha_nacimiento": "1995-08-22",
        "genero": "M",
        "estado": true,
        "id_user_create": null,
        "created_at": "2024-08-22T14:00:00.000Z",
        "updated_at": "2024-08-22T14:00:00.000Z"
      },
      "role": {
        "id": 2,
        "nombre": "user",
        "descripcion": "Cajero estándar"
      }
    }
  ]
}

​
Update a User

PATCH /usuario/:id — Partially updates an existing user’s account-level fields. Only the fields provided in the request body are changed.
​
name
string
Updated display name.
​
email
string
Updated email address.
​
password
string
New password. Will be hashed before storage.
​
estado
boolean
Set to false to deactivate the account without deleting it.
​
id_role
number
Reassign the user to a different role by ID.
curl -X PATCH http://localhost:3000/usuario/1 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "estado": false }'
Response: Usuario (updated object)

​
Persona Endpoints

​
Create a Persona

POST /persona — Creates a standalone Persona record without an associated Usuario. Useful for tracking individuals who are not system users.
​
nombres
string
required
First name(s).
​
p_apellido
string
required
Paternal surname.
​
s_apellido
string
required
Maternal surname.
​
fecha_nacimiento
string
required
Date of birth in YYYY-MM-DD format.
​
genero
string
required
Gender code (e.g., "M" or "F").
curl -X POST http://localhost:3000/persona \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombres": "Ana Lucía",
    "p_apellido": "Flores",
    "s_apellido": "Condori",
    "fecha_nacimiento": "1988-03-10",
    "genero": "F"
  }'
Response: 
{
  "status": 200,
  "message": "Se creó la persona con éxito!",
  "data": { ... }
}

​
List All Personas

GET /persona — Returns all persona records (requires authentication). 
curl -X GET http://localhost:3000/persona \
  -H "Authorization: Bearer <access_token>"
Response: Wrapped response with status, message, and data: Persona[].

​
Get Persona by ID

GET /persona/:id — Returns a single persona record by its ID. 
curl -X GET http://localhost:3000/persona/3 \
  -H "Authorization: Bearer <access_token>"
Response: Persona

​
Update a Persona

PUT /persona — Updates an existing persona’s personal details. The target persona ID is passed in the request body (not as a URL path parameter). Uses PUT semantics.
​
id
number
required
ID of the persona to update.
​
id_user_update
number
required
ID of the user performing the update. Auto-injected by the frontend service from the logged-in session.
​
nombres
string
Updated first name(s).
​
p_apellido
string
Updated paternal surname.
​
s_apellido
string
Updated maternal surname.
​
fecha_nacimiento
string
Updated date of birth in YYYY-MM-DD format.
​
genero
string
Updated gender code.
curl -X PUT http://localhost:3000/persona \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 3,
    "id_user_update": 1,
    "p_apellido": "Flores Arce"
  }'
Response: Persona (updated object)

​
Mail Endpoint

​
Send a Transactional Email

POST /mail — Sends a plain-text email through the configured SMTP transport. Useful for confirmations, notifications, and password recovery flows.
This endpoint is public — no Authorization header is required. Protect your usage at the application layer to avoid abuse.
​
email
string
required
Recipient’s email address.
​
subject
string
required
Email subject line.
​
message
string
required
Plain-text body of the email.
​
name
string
required
Recipient’s display name, used in the email greeting.
curl -X POST http://localhost:3000/mail \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "subject": "Bienvenido a Kantuta POS",
    "message": "Tu cuenta ha sido creada exitosamente.",
    "name": "Carlos"
  }'
Response: SMTP transport confirmation object (structure depends on the mail provider configuration).

Build docs developers (and LLMs) love

Get started for freeTalk to us