Users API: Register and Manage Kantuta POS Accounts

The /usuario resource handles everything related to user accounts in Kantuta POS. The registration endpoint is public and atomically creates both a Usuario (login credentials and display name) and its linked Persona (personal profile — real name, birthdate, gender) in a single request. All other endpoints require a valid Bearer token. There is a strict one-to-one relationship between a Usuario and a Persona: you cannot have a user without a personal profile.

POST /usuario/register is the only public endpoint in this resource. All other operations require Authorization: Bearer <access_token>.

POST /usuario/register

PUBLIC Registers a new user account and simultaneously creates the linked Persona record in a single atomic operation. The combined request body carries both the login credentials and the personal profile fields. On success the full Usuario object — including the populated persona relation — is returned.

You do not need to call POST /persona separately when registering a user. This endpoint creates both records in one transaction.

Request body

string

required

The new user’s email address. Must be unique across the system and in a valid email format.

password

string

required

The new user’s password in plain text. Hashed server-side with bcrypt before storage.

nombres

string

required

Given name(s) for the user’s personal profile. Stored in the Persona record (max 100 characters).

p_apellido

string

required

First (paternal) surname. Stored in the Persona record (max 50 characters).

s_apellido

string

required

Second (maternal) surname. Stored in the Persona record (max 50 characters).

fecha_nacimiento

string

required

Date of birth in YYYY-MM-DD format — e.g. "1995-03-22".

genero

string

required

Gender code. Typical values: "M" (male) or "F" (female).

name

string

Optional display name shown in the UI (e.g. a username or alias). Defaults to the email prefix if omitted.

estado

boolean

Whether the account is active immediately on creation. Defaults to true.

Response

Returns the newly created Usuario object with the embedded Persona and Role.

number

Auto-generated primary key of the user account.

name

string

Display name for the account.

string

The registered email address.

estado

boolean

Account active flag — true if the account is enabled.

persona

Persona

The personal profile record automatically created alongside this account. See the Persona interface below.

role

Role

The role assigned to the account. Defaults to the base user role unless id_role is specified.

created_at

string

ISO 8601 timestamp of account creation.

updated_at

string

ISO 8601 timestamp of the last update.

curl -X POST http://localhost:3000/usuario/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "ClaveFuerte123!",
    "nombres": "María Elena",
    "p_apellido": "Quispe",
    "s_apellido": "Condori",
    "fecha_nacimiento": "1995-03-22",
    "genero": "F",
    "name": "maria.quispe",
    "estado": true
  }'

{
  "id": 4,
  "name": "maria.quispe",
  "email": "[email protected]",
  "estado": true,
  "created_at": "2024-07-10T14:22:00.000Z",
  "updated_at": "2024-07-10T14:22:00.000Z",
  "persona": {
    "id": 4,
    "nombres": "María Elena",
    "p_apellido": "Quispe",
    "s_apellido": "Condori",
    "fecha_nacimiento": "1995-03-22",
    "genero": "F",
    "estado": true,
    "created_at": "2024-07-10T14:22:00.000Z",
    "updated_at": "2024-07-10T14:22:00.000Z"
  },
  "role": {
    "id": 3,
    "nombre": "user",
    "descripcion": "Cajero estándar"
  }
}

GET /usuario

PROTECTED Returns all registered user accounts as an array. Each user record includes the linked Persona and Role objects. Deactivated accounts (estado: false) are included in the response — filter client-side if needed.

Request headers

Authorization

string

required

Bearer <access_token> — obtained from POST /auth/login.

Response

status

number

HTTP status code mirrored in the body — 200 on success.

message

string

Human-readable status message, e.g. "Listado de usuarios registradas!".

data

Usuario[]

Array of Usuario objects, each containing nested persona and role.

curl -X GET http://localhost:3000/usuario \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "status": 200,
  "message": "Listado de usuarios registradas!",
  "data": [
    {
      "id": 1,
      "name": "Admin Kantuta",
      "email": "[email protected]",
      "estado": true,
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:00:00.000Z",
      "persona": {
        "id": 1,
        "nombres": "Carlos",
        "p_apellido": "Flores",
        "s_apellido": "Mamani",
        "fecha_nacimiento": "1990-06-15",
        "genero": "M",
        "estado": true
      },
      "role": { "id": 1, "nombre": "admin" }
    }
  ]
}

GET /usuario/:id

PROTECTED Retrieves a single Usuario by its numeric ID, including the linked Persona and Role.

Path parameters

number

required

The numeric primary key of the user to retrieve.

Request headers

Authorization

string

required

Bearer <access_token>.

Response

status

number

200 on success.

message

string

"Usuario encontrado!" on success.

data

Usuario

The requested user with nested persona and role.

curl -X GET http://localhost:3000/usuario/4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

PATCH /usuario/:id

PROTECTED Partially updates a user account. Only the fields included in the request body are modified. To update the linked personal profile (name, birthdate, etc.) use PUT /persona instead.

Path parameters

number

required

The numeric ID of the user account to update.

Request headers

Authorization

string

required

Bearer <access_token>.

Request body (all fields optional)

name

string

Updated display name.

string

Updated email address. Must be unique across all user accounts.

password

string

New password in plain text. Hashed before storage.

estado

boolean

Set to false to deactivate the account without deleting it.

Response

Returns the updated Usuario object.

curl -X PATCH http://localhost:3000/usuario/4 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{"name": "maria.quispe.cajera", "estado": true}'

{
  "id": 4,
  "name": "maria.quispe.cajera",
  "email": "[email protected]",
  "estado": true,
  "created_at": "2024-07-10T14:22:00.000Z",
  "updated_at": "2024-07-10T15:05:00.000Z",
  "persona": {
    "id": 4,
    "nombres": "María Elena",
    "p_apellido": "Quispe",
    "s_apellido": "Condori",
    "fecha_nacimiento": "1995-03-22",
    "genero": "F"
  },
  "role": { "id": 3, "nombre": "user" }
}

DELETE /usuario/:id

PROTECTED Removes the user account identified by id. Requires a valid Bearer token.

Path parameters

number

required

The numeric primary key of the user account to delete.

Request headers

Authorization

string

required

Bearer <access_token> — obtained from POST /auth/login.

Response

Returns the result from the underlying service call on success.

curl -X DELETE http://localhost:3000/usuario/4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Usuario TypeScript Interface

Use these interfaces in your React + TypeScript frontend (e.g. src/types/api.d.ts):

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

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

export interface Persona extends BaseEntityAudit {
  id: number;
  nombres: string;         // Max 100 chars
  p_apellido: string;      // Max 50 chars
  s_apellido?: string;     // Max 50 chars, nullable
  fecha_nacimiento: string; // YYYY-MM-DD
  genero: string;           // 'M' | 'F'
}

export interface Usuario extends BaseEntityAudit {
  id: number;
  name: string;       // Display name, max 100 chars
  email: string;      // Unique, max 150 chars
  persona: Persona;   // One-to-one: always present
  role: Role;
}

// Registration request body
export interface RegisterUsuarioRequest {
  email: string;
  password: string;
  nombres: string;
  p_apellido: string;
  s_apellido: string;
  fecha_nacimiento: string; // 'YYYY-MM-DD'
  genero: string;
  name?: string;
  estado?: boolean;         // default: true
}

// Partial update request body
export interface UpdateUsuarioRequest {
  name?: string;
  email?: string;
  password?: string;
  estado?: boolean;
}

Axios usage example

import api from './api'; // The configured Axios instance (see Auth page)
import { RegisterUsuarioRequest, Usuario } from './types';

export async function registerUser(data: RegisterUsuarioRequest): Promise<Usuario> {
  const response = await api.post<Usuario>('/usuario/register', data);
  return response.data;
}

export async function listUsers(): Promise<{ status: number; message: string; data: Usuario[] }> {
  const response = await api.get('/usuario');
  return response.data;
}

export async function updateUser(id: number, patch: Partial<RegisterUsuarioRequest>): Promise<Usuario> {
  const response = await api.patch<Usuario>(`/usuario/${id}`, patch);
  return response.data;
}

export async function deleteUser(id: number): Promise<void> {
  await api.delete(`/usuario/${id}`);
}

Authentication

Users & People

Inventory

Operations

Integrations

Users API: Register and Manage Kantuta POS Accounts

POST /usuario/register

Request body

Response

GET /usuario

Request headers

Response

GET /usuario/:id

Path parameters

Request headers

Response

PATCH /usuario/:id

Path parameters

Request headers

Request body (all fields optional)

Response

DELETE /usuario/:id

Path parameters

Request headers

Response

Usuario TypeScript Interface

Axios usage example

Build docs developers (and LLMs) love

Authentication

Users & People

Inventory

Operations

Integrations

Documentation Index

​POST /usuario/register

​Request body

​Response

​GET /usuario

​Request headers

​Response

​GET /usuario/:id

​Path parameters

​Request headers

​Response

​PATCH /usuario/:id

​Path parameters

​Request headers

​Request body (all fields optional)

​Response

​DELETE /usuario/:id

​Path parameters

​Request headers

​Response

​Usuario TypeScript Interface

​Axios usage example

Build docs developers (and LLMs) love

POST /usuario/register

Request body

Response

GET /usuario

Request headers

Response

GET /usuario/:id

Path parameters

Request headers

Response

PATCH /usuario/:id

Path parameters

Request headers

Request body (all fields optional)

Response

DELETE /usuario/:id

Path parameters

Request headers

Response

Usuario TypeScript Interface

Axios usage example