Overview The Clientes API provides comprehensive customer management functionality for the POS system. All endpoints require JWT authentication via Bearer token.
All routes are protected with verifyToken middleware. Include your authentication token in the Authorization header.
Authentication Authorization: Bearer < your_jwt_toke n >
The JWT token must contain usuario and password fields which are used for database connection credentials.
Create Cliente Creates a new customer using the stored procedure sp_crear_cliente. The customer code is auto-generated by the database.
Request Body City code (foreign key). Maximum 10 characters.
Customer name. Maximum 120 characters.
RUC or ID number. Must be numeric (13 digits).
Phone number. Must be exactly 10 numeric digits.
Email address. Maximum 60 characters.
Example Request curl -X POST https://api.example.com/api/pos/clientes \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ct_codigo": "UIO001", "cli_nombre": "Juan Pérez", "cli_ruc_ced": "1234567890001", "cli_telefono": "0987654321", "cli_mail": "[email protected] ", "cli_direccion": "Av. Principal 123", "cli_celular": "0998765432" }'
Response Created customer data Auto-generated customer code
Customer status (ACT, INA, SUS)
{ "message" : "Cliente creado exitosamente" , "data" : { "cli_codigo" : "GENERATED_BY_DB" , "ct_codigo" : "UIO001" , "cli_nombre" : "Juan Pérez" , "cli_ruc_ced" : "1234567890001" , "cli_telefono" : "0987654321" , "cli_mail" : "[email protected] " , "cli_direccion" : "Av. Principal 123" , "cli_celular" : "0998765432" , "cli_estado" : "ACT" } }
{ "errors" : [ "ct_codigo es requerido y máximo 10 caracteres" , "cli_telefono es requerido y debe tener 10 dígitos numéricos" ] }
{ "message" : "Error interno al crear cliente" , "detail" : "Database connection error" }
Get All Clientes Retrieves a paginated list of all active customers (estado = ‘ACT’). Results are ordered by name and limited to 20 records per page.
Query Parameters Page number for pagination (1-based)
Example Request curl -X GET "https://api.example.com/api/pos/clientes?page=1" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Number of records returned
Array of customer objects Show Customer object properties
Customer status (ACT, INA, SUS)
{ "message" : "Listado obtenido correctamente" , "count" : 20 , "data" : [ { "cli_codigo" : "CLI001" , "cli_nombre" : "Juan Pérez" , "cli_ruc_ced" : "1234567890001" , "cli_telefono" : "0987654321" , "cli_mail" : "[email protected] " , "cli_direccion" : "Av. Principal 123" , "cli_celular" : "0998765432" , "cli_estado" : "ACT" , "ct_codigo" : "UIO001" } ] }
{ "message" : "Error al obtener clientes" }
Get Cliente by ID Retrieves detailed information for a specific customer by their unique code.
Path Parameters Customer code (cli_codigo)
Example Request curl -X GET https://api.example.com/api/pos/clientes/CLI001 \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response { "cli_codigo" : "CLI001" , "cli_nombre" : "Juan Pérez" , "cli_ruc_ced" : "1234567890001" , "cli_telefono" : "0987654321" , "cli_mail" : "[email protected] " , "cli_direccion" : "Av. Principal 123" , "cli_celular" : "0998765432" , "cli_estado" : "ACT" , "ct_codigo" : "UIO001" , "cli_fecha_alta" : "2024-03-01T10:00:00Z" }
{ "message" : "Cliente no encontrado" }
{ "message" : "Error al buscar cliente" }
Search Clientes by Name Performs a case-insensitive partial match search on customer names. Returns up to 10 matching results using ILIKE pattern matching.
The search endpoint uses a different path than the ID lookup. Make sure to use /search before the query parameters.
Query Parameters Name search term (partial match supported)
Example Request curl -X GET "https://api.example.com/api/pos/clientes/search?name=juan" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response { "data" : [ { "cli_codigo" : "CLI001" , "cli_nombre" : "Juan Pérez" , "cli_ruc_ced" : "1234567890001" , "cli_telefono" : "0987654321" , "cli_mail" : "[email protected] " , "cli_direccion" : "Av. Principal 123" , "cli_celular" : "0998765432" , "cli_estado" : "ACT" , "ct_codigo" : "UIO001" }, { "cli_codigo" : "CLI025" , "cli_nombre" : "Juan Carlos Rodríguez" , "cli_ruc_ced" : "1234567890025" , "cli_telefono" : "0987654322" , "cli_mail" : "[email protected] " , "cli_direccion" : "Calle Secundaria 456" , "cli_celular" : "0998765433" , "cli_estado" : "ACT" , "ct_codigo" : "UIO001" } ] }
{ "message" : "El parámetro 'name' es requerido" }
{ "message" : "Error en la búsqueda" }
Get Clientes for Select Returns a simplified list of active customers containing only code and name. Optimized for dropdown/selector components in UI.
Example Request curl -X GET https://api.example.com/api/pos/clientes/type \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response [ { "cli_codigo" : "CLI001" , "cli_nombre" : "Juan Pérez" }, { "cli_codigo" : "CLI002" , "cli_nombre" : "María González" }, { "cli_codigo" : "CLI003" , "cli_nombre" : "Carlos López" } ]
{ "message" : "Error al obtener lista de tipos" }
Update Cliente Updates an existing customer. Only provided fields will be updated (partial update supported using COALESCE).
Path Parameters Customer code (cli_codigo)
Request Body All fields are optional. Only include fields you want to update.
Customer name. Maximum 120 characters.
RUC or ID number. Must be numeric.
Phone number. Must be exactly 10 numeric digits.
Email address. Maximum 60 characters.
City code. Maximum 10 characters.
Example Request curl -X PUT https://api.example.com/api/pos/clientes/CLI001 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cli_telefono": "0987654999", "cli_mail": "[email protected] " }'
Response { "message" : "Cliente actualizado correctamente" , "data" : { "cli_codigo" : "CLI001" , "cli_nombre" : "Juan Pérez" , "cli_ruc_ced" : "1234567890001" , "cli_telefono" : "0987654999" , "cli_mail" : "[email protected] " , "cli_direccion" : "Av. Principal 123" , "cli_celular" : "0998765432" , "cli_estado" : "ACT" , "ct_codigo" : "UIO001" } }
{ "errors" : [ "cli_telefono es requerido y debe tener 10 dígitos numéricos" ] }
{ "message" : "Cliente no encontrado para actualizar" }
{ "message" : "Error al actualizar cliente" }
Delete Cliente Performs a logical deletion by setting customer status to ‘INA’ (inactive). The customer record is not physically removed from the database.
This is a soft delete operation. The customer status is changed to inactive and the cli_fecha_alta timestamp is updated.
Path Parameters Customer code (cli_codigo)
Example Request curl -X DELETE https://api.example.com/api/pos/clientes/CLI001 \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response { "message" : "Cliente eliminado correctamente" }
{ "message" : "Error al eliminar cliente" }
Data Validation Rules The following validation rules are enforced by the validateClienteDTO function:
All validation errors return a 400 status code with an errors array containing specific validation messages.
Field Rule Error Message ct_codigo Required (create), max 10 chars ”ct_codigo es requerido y máximo 10 caracteres” cli_nombre Required (create), max 120 chars ”cli_nombre es requerido y máximo 120 caracteres” cli_ruc_ced Required (create), numeric ”cli_ruc_ced es requerido y debe ser numérico” cli_telefono Required (create), exactly 10 digits ”cli_telefono es requerido y debe tener 10 dígitos numéricos” cli_mail Required (create), max 60 chars ”cli_mail es requerido y máximo 60 caracteres”
Customer Status Values
ACT - Active customerINA - Inactive customer (soft deleted)SUS - Suspended customer Error Handling All endpoints follow consistent error response patterns:
Common Error Responses { "errors" : [ "Validation error message 1" , "Validation error message 2" ] }
{ "message" : "Token inválido o expirado" }
{ "message" : "Cliente no encontrado" }
500 Internal Server Error
{ "message" : "Error interno al procesar solicitud" , "detail" : "Detailed error message" }
Implementation Details Source Code Reference
Routes : src/routes/pos.cliente.routes.jsController : src/controllers/pos.cliente.controller.jsModel : src/models/cliente.model.jsDTO : src/dtos/cliente.dto.jsStored Procedure : sp_crear_cliente (database)
Database Connection The API uses JWT-based database connection credentials:
const connectFromJWT = ( req ) => { const { usuario , password } = req . user ; return getConnectionWithCredentials ( usuario , password ); };
Each request establishes a new database connection using credentials extracted from the JWT token, ensuring proper authentication and authorization at the database level.
List endpoints use page-based pagination:
Default page: 1
Records per page: 20
Offset calculation: (page - 1) * limit
Search Implementation The name search uses PostgreSQL’s ILIKE operator for case-insensitive pattern matching:
SELECT * FROM public . cliente WHERE cli_nombre ILIKE '%search_term%' LIMIT 10
