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 Proveedores almacena los datos comerciales de las empresas y personas que abastecen a Tiendas Mi Cholo. Cada proveedor activo puede ser referenciado al crear órdenes de compra, permitiendo rastrear de dónde proviene cada lote de mercadería y gestionar la comunicación con el contacto responsable. Todos los roles autenticados (ADMIN, VENDEDOR, ALMACENERO) tienen acceso completo a las operaciones CRUD de este módulo.

​
Campos del Proveedor

CampoTipoRequeridoValidaciónDescripción
razonSocialString✅max=200Nombre legal o razón social de la empresa
rucString✅max=20, únicoRUC de la empresa proveedora
emailString⬜max=150Correo electrónico de la empresa
telefonoString⬜max=20Teléfono de la empresa
direccionString⬜max=300Dirección fiscal o comercial
contactoString⬜max=150Nombre de la persona de contacto en la empresa
activoBoolean—default=trueEstado del registro (manejado por la API)
El campo ruc debe ser único en toda la tabla proveedores. Antes de crear un proveedor, usa el endpoint de búsqueda para asegurarte de que el RUC no esté ya registrado bajo una razón social diferente.

​
Endpoints

​
Listar proveedores activos

GET /api/proveedores
Authorization: Bearer <token>
Devuelve todos los proveedores con activo = true. Respuesta 200 OK 
[
  {
    "id": 1,
    "razonSocial": "Distribuidora Tech SAC",
    "ruc": "20123456789",
    "email": "ventas@techsac.com",
    "telefono": "014567890",
    "direccion": "Av. Industrial 789, Ate",
    "contacto": "Roberto Flores",
    "activo": true,
    "createdAt": "2024-01-01T08:00:00",
    "updatedAt": "2024-01-15T10:00:00"
  }
]

​
Buscar proveedores

GET /api/proveedores/buscar?q={término}
Authorization: Bearer <token>
Búsqueda que consulta simultáneamente por razonSocial, ruc y contacto. Ideal para localizar rápidamente un proveedor al momento de crear una orden de compra.
​
q
String
required
Término de búsqueda. Puede ser parte de la razón social, el RUC o el nombre del contacto.
Ejemplos: 
GET /api/proveedores/buscar?q=distribuidora
GET /api/proveedores/buscar?q=20123456789
GET /api/proveedores/buscar?q=Roberto
Respuesta 200 OK: lista de proveedores que coinciden con el término, en el mismo formato que el listado general.

​
Obtener proveedor por ID

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

​
Crear proveedor

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

{
  "razonSocial": "Importaciones XYZ EIRL",
  "ruc": "20987654321",
  "email": "contacto@xyzimport.com",
  "telefono": "016789012",
  "direccion": "Calle Comercio 321, San Isidro",
  "contacto": "Patricia Vega"
}
Respuesta 200 OK: objeto Proveedor creado con su id generado automáticamente.

​
Actualizar proveedor

PUT /api/proveedores/{id}
Authorization: Bearer <token>
Content-Type: application/json
​
id
Long
required
ID del proveedor a actualizar.
El cuerpo tiene la misma estructura que el POST. Los campos razonSocial, ruc, email, telefono, direccion y contacto se actualizan con los valores enviados. Respuesta 200 OK: objeto Proveedor actualizado.

​
Eliminar proveedor (baja lógica)

DELETE /api/proveedores/{id}
Authorization: Bearer <token>
​
id
Long
required
ID del proveedor a desactivar.
Establece activo = false. El proveedor no se elimina de la base de datos; todas sus órdenes de compra históricas permanecen vinculadas y accesibles. Desaparecerá del listado activo pero no de los registros de compra anteriores. Respuesta 204 No Content — sin cuerpo.

​
Flujo de Alta de un Proveedor

1

Verificar el RUC

Realiza GET /api/proveedores/buscar?q={ruc} para confirmar que el RUC no esté duplicado en el sistema.
2

Registrar el proveedor

Envía POST /api/proveedores con los datos comerciales completos. Incluye siempre el campo contacto para facilitar las comunicaciones.
3

Guardar el ID

El campo id de la respuesta es el que debes usar como proveedorId al crear órdenes de compra en POST /api/compras.
4

Crear la orden de compra

Con el proveedor registrado, el rol ADMIN o ALMACENERO puede emitir una nueva orden desde POST /api/compras.

​
Respuestas de Error Comunes

CódigoCausa
400 Bad RequestValidación fallida (campos requeridos vacíos, ruc 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