Productos

Productos

Prefijo: /api/productos
Requiere Auth: Sí
Permiso requerido: productos, *

Módulo de productos del catálogo. Incluye búsqueda por código y nombre, y filtro por categoría.

Nota: Los productos utilizan soft delete — al eliminar un producto se marca como eliminado sin borrarse físicamente.

GET /api/productos/

Descripción: Lista todos los productos con paginación
Requiere Auth: Sí
Permiso requerido: productos, leer

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "codigo": "PROD001",
    "nombre": "Café Latte",
    "proveedor_id": 1,
    "stock": 100,
    "precio": 5000,
    "precioc": 3500,
    "utilidad": 1500,
    "iva": 19.0,
    "categoria_id": 1,
    "unidad_medida": "94",
    "codigo_barras": "7701234567890",
    "tenant_id": "uuid-tenant",
    "fecha": "2025-01-01T00:00:00",
    "valor_iva": 950.0,
    "precio_iva": 5950.0,
    "unidad_id": 1,
    "impuesto_id": 1,
    "categoria": {
      "id": 1,
      "nombre": "Bebidas",
      "descripcion": "Bebidas frías y calientes",
      "tenant_id": "uuid-tenant",
      "fecha_creacion": "2025-01-01T00:00:00"
    }
  }
]

cURL:

curl "http://localhost/api/productos/?skip=0&limit=20" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/productos/",
    params={"skip": 0, "limit": 20},
    headers={"Authorization": f"Bearer {token}"})
productos = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/productos/?skip=0&limit=20', {
  headers: {'Authorization': `Bearer ${token}`}
});
const productos = await resp.json();

---

GET /api/productos/{producto_id}

Descripción: Obtiene un producto por ID
Requiere Auth: Sí
Permiso requerido: productos, leer

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl http://localhost/api/productos/1 -H "Authorization: Bearer <token>"

---

POST /api/productos/

Descripción: Crea un nuevo producto
Requiere Auth: Sí
Permiso requerido: productos, crear

Request:

{
  "codigo": "PROD003",
  "nombre": "Nuevo Producto",
  "proveedor_id": 1,
  "stock": 50,
  "precio": 10000,
  "precioc": 7000,
  "utilidad": 3000,
  "iva": 19,
  "categoria_id": 1,
  "unidad_medida": "94",
  "codigo_barras": "7701234567891"
}

Respuesta exitosa: 201 Created

cURL:

curl -X POST http://localhost/api/productos/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"codigo":"PROD003","nombre":"Nuevo Producto","proveedor_id":1,"stock":50,"precio":10000,"precioc":7000,"iva":19,"categoria_id":1,"unidad_medida":"94"}'

Python:

import httpx
resp = httpx.post("http://localhost/api/productos/",
    json={"codigo": "PROD003", "nombre": "Nuevo Producto", "proveedor_id": 1, "stock": 50, "precio": 10000, "precioc": 7000, "iva": 19, "categoria_id": 1, "unidad_medida": "94"},
    headers={"Authorization": f"Bearer {token}"})
producto = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/productos/', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${token}`},
  body: JSON.stringify({codigo: 'PROD003', nombre: 'Nuevo Producto', proveedor_id: 1, stock: 50, precio: 10000, precioc: 7000, iva: 19, categoria_id: 1, unidad_medida: '94'})
});

---

PUT /api/productos/{producto_id}

Descripción: Actualiza un producto
Requiere Auth: Sí
Permiso requerido: productos, actualizar

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl -X PUT http://localhost/api/productos/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"precio":5500,"stock":120}'

---

DELETE /api/productos/{producto_id}

Descripción: Elimina (soft delete) un producto
Requiere Auth: Sí
Permiso requerido: productos, eliminar

Respuesta exitosa: 204 No Content
Errores: 404 (no encontrado)

cURL:

curl -X DELETE http://localhost/api/productos/1 -H "Authorization: Bearer <token>"

---

Búsqueda

GET /api/productos/search/codigo

Descripción: Busca un producto por código
Requiere Auth: Sí
Permiso requerido: productos, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
codigo	string	✅	Código exacto del producto

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl "http://localhost/api/productos/search/codigo?codigo=PROD001" -H "Authorization: Bearer <token>"

---

GET /api/productos/search/nombre

Descripción: Busca productos por nombre (búsqueda parcial)
Requiere Auth: Sí
Permiso requerido: productos, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
nombre	string	✅	Texto parcial del nombre

Respuesta exitosa: 200 OK

cURL:

curl "http://localhost/api/productos/search/nombre?nombre=Café" -H "Authorization: Bearer <token>"

---

GET /api/productos/categoria/{categoria_id}

Descripción: Obtiene productos por categoría
Requiere Auth: Sí
Permiso requerido: productos, leer

Respuesta exitosa: 200 OK

cURL:

curl http://localhost/api/productos/categoria/1 -H "Authorization: Bearer <token>"