Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/interezante456-pixel/Miercoles-Proyecto/llms.txt

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

El módulo de Clientes centraliza la base de datos de compradores de Tiendas Mi Cholo. Desde aquí se registran personas naturales y empresas con sus documentos de identidad, datos de contacto y dirección. Los clientes son obligatorios al registrar una venta, por lo que mantener esta información actualizada asegura comprobantes y reportes precisos. Todos los roles autenticados (ADMIN, VENDEDOR, ALMACENERO) tienen acceso completo a este módulo.

​
Tipos de Documento Soportados

El sistema acepta cuatro tipos de documento de identidad definidos como enum TipoDocumento en la entidad Cliente:
ValorDescripción
DNIDocumento Nacional de Identidad (personas naturales peruanas)
RUCRegistro Único de Contribuyentes (empresas y personas con actividad comercial)
PASAPORTEPasaporte (clientes extranjeros)
CECarné de Extranjería (residentes extranjeros)
El campo nroDoc es único en toda la tabla clientes y actúa como identificador natural del cliente. Al integrar con sistemas de facturación electrónica (SUNAT, por ejemplo), usa nroDoc junto a tipoDoc para enlazar registros sin depender del ID interno.

​
Campos del Cliente

CampoTipoRequeridoValidaciónDescripción
nombresString✅max=100Nombres del cliente
apellidosString✅max=100Apellidos del cliente
tipoDocTipoDocumento✅enumTipo de documento: DNI, RUC, PASAPORTE, CE
nroDocString✅max=20, únicoNúmero de documento de identidad
emailString⬜max=150Correo electrónico de contacto
telefonoString⬜max=20Número de teléfono
direccionString⬜max=300Dirección postal
activoBoolean—default=trueEstado del registro (manejado por la API)

​
Endpoints

​
Listar clientes activos

GET /api/clientes
Authorization: Bearer <token>
Devuelve todos los clientes con activo = true. Respuesta 200 OK 
[
  {
    "id": 1,
    "nombres": "Carlos Alberto",
    "apellidos": "Rodríguez Silva",
    "tipoDoc": "DNI",
    "nroDoc": "12345678",
    "email": "carlos@email.com",
    "telefono": "987654321",
    "direccion": "Av. Principal 123, Lima",
    "activo": true,
    "createdAt": "2024-01-01T08:00:00",
    "updatedAt": "2024-01-15T10:00:00"
  }
]

​
Buscar clientes

GET /api/clientes/buscar?q={término}
Authorization: Bearer <token>
Búsqueda flexible que consulta simultáneamente por nombres, apellidos y nroDoc. Útil para localizar un cliente rápidamente desde la pantalla de registro de ventas.
​
q
String
required
Término de búsqueda. Puede ser parte del nombre, apellido o número de documento.
Ejemplo: 
GET /api/clientes/buscar?q=carlos
GET /api/clientes/buscar?q=12345678
Respuesta 200 OK: lista de clientes que coinciden con el término, en el mismo formato que el listado general.

​
Obtener cliente por ID

GET /api/clientes/{id}
Authorization: Bearer <token>
​
id
Long
required
ID interno del cliente.
Respuesta 404 Not Found: 
{
  "timestamp": "2024-01-15T10:30:00",
  "status": 404,
  "error": "Cliente no encontrado: 99"
}

​
Crear cliente

POST /api/clientes
Authorization: Bearer <token>
Content-Type: application/json

{
  "nombres": "Ana Lucía",
  "apellidos": "Torres Mendoza",
  "tipoDoc": "DNI",
  "nroDoc": "87654321",
  "email": "ana@email.com",
  "telefono": "912345678",
  "direccion": "Jr. Los Olivos 456, Miraflores"
}
Respuesta 200 OK: objeto Cliente creado con su id generado automáticamente.

​
Actualizar cliente

PUT /api/clientes/{id}
Authorization: Bearer <token>
Content-Type: application/json
​
id
Long
required
ID del cliente a actualizar.
El cuerpo tiene la misma estructura que el POST. Todos los campos se sobrescriben con los valores enviados, incluido nroDoc (asegúrate de que el nuevo valor siga siendo único). Respuesta 200 OK: objeto Cliente actualizado.

​
Eliminar cliente (baja lógica)

DELETE /api/clientes/{id}
Authorization: Bearer <token>
​
id
Long
required
ID del cliente a desactivar.
Establece activo = false. El cliente no se borra de la base de datos; su historial de ventas se preserva íntegramente. El cliente desaparecerá del listado general pero seguirá siendo referenciado en las ventas previas. Respuesta 204 No Content — sin cuerpo.

​
Flujo de Registro de un Cliente

1

Buscar si ya existe

Antes de crear, usa GET /api/clientes/buscar?q={nroDoc} para verificar que el documento no esté registrado y evitar duplicados.
2

Elegir el tipo de documento

Selecciona el tipoDoc correcto según la naturaleza del cliente: DNI para personas naturales, RUC para empresas.
3

Crear el registro

Envía el POST /api/clientes con los datos completos. Guarda el id retornado para vincularlo en futuras ventas.
4

Asociar en una venta

Al registrar una venta en POST /api/ventas, incluye el clienteId obtenido en el paso anterior.

​
Respuestas de Error Comunes

CódigoCausa
400 Bad RequestValidación fallida (campos requeridos vacíos, nroDoc duplicado)
401 UnauthorizedToken JWT ausente, inválido o expirado
404 Not FoundEl id no existe en la base de datos

Build docs developers (and LLMs) love

Get started for freeTalk to us