Home / Backend / API Flask moderna para inventario: capas, JWT y pytest
API Flask moderna para inventario: capas, JWT y pytest

API Flask moderna para inventario: capas, JWT y pytest

21 November 2026 · 26 min de lectura ··

Una API de inventario preparada para producción

Un prototipo en Flask cabe en un único archivo, pero una API que va a vivir años en producción necesita otra cosa: una estructura que permita cambiar de entorno sin editar código, probar cada pieza por separado, evolucionar la base de datos sin perder datos y proteger los endpoints con autenticación seria. En este tutorial construimos desde cero un servicio de inventario de almacén, con productos, ubicaciones y usuarios que registran movimientos de stock, usando las herramientas que hoy se consideran la forma recomendada de trabajar.

Conviene empezar aclarando el panorama de dependencias, porque en los últimos años ha cambiado bastante. Flask-RESTPlus, la extensión que durante mucho tiempo se usó para documentar APIs con Swagger, quedó abandonada. Su continuación comunitaria es Flask-RESTX, que mantiene la misma filosofía de namespaces, modelos y recursos, y cuya última versión publicada en PyPI que he podido verificar es la 1.3.2, con requisito de Python 3.9 o superior. Es una dependencia mantenida a ritmo lento, así que más adelante comentamos alternativas por si prefieres otro camino.

Las versiones que usaremos, comprobadas en las fuentes oficiales y en PyPI al redactar esto, son las siguientes. Flask está en la serie 3.1, con 3.1.3 como última versión estable encontrada. SQLAlchemy tiene como estable la serie 2.0, con la 2.1 todavía en beta, de modo que nos quedamos en la 2.0. Flask-SQLAlchemy se mantiene en la 3.1, Flask-Migrate en la 4.1 y PyJWT en la serie 2.x, con la 2.15 como la más reciente que aparece en el índice. Para las pruebas usamos pytest 9.x. Como los números de parche cambian con frecuencia, en los ejemplos fijaremos rangos compatibles en lugar de versiones exactas.

Lo que aprenderás aquí es transferible a cualquier dominio. Veremos la estructura de carpetas, la factoría de aplicación, la configuración por entorno, el modelo de datos con el estilo declarativo de SQLAlchemy 2, las migraciones con el comando flask db, una capa de servicios separada de los controladores, el hash de contraseñas, los tokens JWT con revocación y una batería de pruebas automatizadas. Todo con ejemplos que puedes copiar y adaptar.

Si después quieres profundizar en la autenticación de usuarios, tienes una guía complementaria en cómo autenticar usuarios en Flask con seguridad, y para llevar el resultado a contenedores, dockerización eficiente de aplicaciones Flask es el siguiente paso natural.

Preparar el entorno y las dependencias

Empezamos con un entorno virtual aislado. Trabajar sin él mezcla paquetes del sistema con los del proyecto y, tarde o temprano, produce errores difíciles de reproducir en otra máquina.

mkdir inventario-api && cd inventario-api
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Ahora declaramos las dependencias en un archivo de requisitos. Usamos rangos compatibles para recibir correcciones de seguridad sin saltar a versiones mayores inesperadas.

Flask>=3.1,<3.2
Flask-RESTX>=1.3,<1.4
Flask-SQLAlchemy>=3.1,<3.2
SQLAlchemy>=2.0,<2.1
Flask-Migrate>=4.1,<4.2
PyJWT>=2.10,<3
bcrypt>=4.0
python-dotenv>=1.0
pytest>=9.0

Instalamos todo con un solo comando.

pip install -r requirements.txt

Un detalle práctico: Flask-RESTX arrastra Werkzeug, y en versiones recientes de Flask algunos comportamientos del enrutador cambian ligeramente. Si tras actualizar Flask ves errores en la documentación Swagger, lo primero es revisar que las versiones de Flask, Werkzeug y Flask-RESTX sean mutuamente compatibles según sus notas de cambios. Fijar rangos y ejecutar las pruebas en integración continua evita sorpresas.

También conviene crear un archivo de variables de entorno para desarrollo, que nunca debe subirse al control de versiones.

FLASK_APP=run.py
APP_ENV=development
SECRET_KEY=cambia-esto-por-un-valor-largo-y-aleatorio
DATABASE_URL=sqlite:///inventario-dev.db

Añade ese archivo y la carpeta del entorno virtual a tu archivo de exclusiones de Git desde el primer commit. Un secreto filtrado en el historial es muy costoso de erradicar.

Estructura de carpetas por responsabilidades

La organización que proponemos separa lo que cambia por motivos distintos. Los endpoints cambian cuando cambia el contrato HTTP, la lógica de negocio cuando cambian las reglas del almacén y los modelos cuando cambia el esquema de datos. Mezclarlos en un mismo archivo hace que cualquier modificación toque todo.

inventario-api/
├── run.py
├── requirements.txt
├── .env
├── migrations/
├── app/
│   ├── __init__.py
│   ├── config.py
│   ├── extensions.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── usuario.py
│   │   ├── producto.py
│   │   └── token_revocado.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── auth_service.py
│   │   └── producto_service.py
│   └── api/
│       ├── __init__.py
│       ├── auth.py
│       ├── productos.py
│       └── seguridad.py
└── tests/
    ├── conftest.py
    ├── test_auth.py
    └── test_productos.py

Cada carpeta tiene un cometido claro. La carpeta de modelos solo describe tablas y relaciones. Los servicios contienen las operaciones de negocio y no conocen nada de HTTP: reciben datos simples y devuelven objetos o lanzan excepciones propias. La carpeta api traduce peticiones y respuestas, valida entradas y convierte las excepciones del servicio en códigos de estado. El archivo de extensiones evita los temidos imports circulares, como veremos enseguida.

Esta división de responsabilidades tiene un beneficio muy concreto: puedes probar un servicio sin levantar el servidor y puedes cambiar la forma de exponer un recurso sin tocar sus reglas. Más adelante, cuando el proyecto crezca, cada área funcional puede convertirse en su propio paquete con la misma estructura interna.

Extensiones y fábrica de aplicaciones

El primer punto de diseño importante es no crear la aplicación Flask a nivel de módulo. Si lo haces, cualquier importación la instancia con una configuración fija, y probar con otra base de datos se convierte en un malabarismo. La solución es la fábrica de aplicaciones que construye una instancia nueva cada vez que se le pide, con la configuración del entorno deseado.

Primero las extensiones, sin aplicación asociada. Aquí aparece la forma moderna de declarar la base de los modelos con SQLAlchemy 2.

# app/extensions.py
from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


db = SQLAlchemy(model_class=Base)
migrate = Migrate()

Las extensiones viven en su propio módulo porque tanto los modelos como la fábrica necesitan importarlas. Si el objeto db se definiera dentro del paquete principal junto a la fábrica, los modelos lo importarían de él y él importaría los modelos, y obtendrías un ciclo. Con un módulo intermedio ambos dependen de un tercero que no depende de nadie.

Ahora la fábrica propiamente dicha.

# app/__init__.py
import os

from flask import Flask

from .config import configuraciones
from .extensions import db, migrate


def create_app(entorno: str | None = None) -> Flask:
    entorno = entorno or os.environ.get("APP_ENV", "development")
    app = Flask(__name__)
    app.config.from_object(configuraciones[entorno])

    db.init_app(app)
    migrate.init_app(app, db)

    from . import models  # noqa: F401  registra las tablas en los metadatos
    from .api import registrar_api

    registrar_api(app)
    return app

Observa dos detalles. El import de los modelos dentro de la función garantiza que Alembic conozca todas las tablas al generar migraciones. Y la anotación de tipo con la barra vertical requiere Python 3.10 o superior, algo razonable hoy; si tu entorno es más antiguo, usa Optional.

El archivo de arranque queda mínimo.

# run.py
from dotenv import load_dotenv

load_dotenv()

from app import create_app  # noqa: E402

app = create_app()

Con esto, el comando flask run y el resto de comandos de la herramienta encuentran la aplicación gracias a la variable FLASK_APP definida antes.

Una configuración por entorno sin secretos en el código

Los entornos de desarrollo, pruebas y producción difieren en la base de datos, en el nivel de depuración y en los secretos. Para gestionarlo con orden, lo más claro es una configuración por entorno expresada como clases que heredan de una base común.

# app/config.py
import os
from datetime import timedelta


class BaseConfig:
    SECRET_KEY = os.environ.get("SECRET_KEY")
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL", "sqlite:///inventario.db")
    JWT_ALGORITMO = "HS256"
    JWT_DURACION = timedelta(minutes=30)
    RESTX_MASK_SWAGGER = False
    DEBUG = False
    TESTING = False


class DevelopmentConfig(BaseConfig):
    DEBUG = True
    SECRET_KEY = os.environ.get("SECRET_KEY", "solo-para-desarrollo-local")


class TestingConfig(BaseConfig):
    TESTING = True
    SECRET_KEY = "clave-de-pruebas"
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
    JWT_DURACION = timedelta(seconds=5)


class ProductionConfig(BaseConfig):
    def __init__(self):
        if not os.environ.get("SECRET_KEY"):
            raise RuntimeError("Falta SECRET_KEY en producción")


configuraciones = {
    "development": DevelopmentConfig,
    "testing": TestingConfig,
    "production": ProductionConfig,
}

Hay un problema en el último bloque que merece explicación: Flask carga los atributos de la clase con from_object, pero no instancia la clase, así que el constructor de producción nunca se ejecutaría. Una forma más fiable de fallar rápido es validar dentro de la fábrica, justo después de cargar la configuración.

# fragmento dentro de create_app, tras from_object
if entorno == "production" and not app.config.get("SECRET_KEY"):
    raise RuntimeError("Falta SECRET_KEY en producción")

Con esa comprobación, la aplicación se niega a arrancar en producción sin clave secreta, que es exactamente el comportamiento deseable. Quita el constructor de la clase de producción y deja que herede sin más.

La regla de oro es que los valores sensibles viajan por variables de entorno y nunca por el repositorio. En producción, un orquestador o un gestor de secretos las inyecta; en desarrollo basta con el archivo local. Para pruebas usamos una base SQLite en memoria y tokens de duración muy corta, lo que nos permitirá comprobar la expiración sin esperas largas.

Modelos con el estilo declarativo de SQLAlchemy 2

SQLAlchemy 2 introdujo una forma tipada de declarar columnas con Mapped y mapped_column. Es más legible, los editores la entienden mejor y los comprobadores de tipos pueden detectar errores antes de ejecutar. Flask-SQLAlchemy 3.1 la soporta pasando la clase base como hicimos antes.

Empezamos por los usuarios y los productos.

# app/models/usuario.py
from datetime import datetime, timezone

from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column

from ..extensions import db


class Usuario(db.Model):
    __tablename__ = "usuarios"

    id: Mapped[int] = mapped_column(primary_key=True)
    correo: Mapped[str] = mapped_column(String(120), unique=True, index=True)
    hash_clave: Mapped[bytes] = mapped_column()
    es_admin: Mapped[bool] = mapped_column(default=False)
    creado_en: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )
# app/models/producto.py
from decimal import Decimal

from sqlalchemy import Numeric, String
from sqlalchemy.orm import Mapped, mapped_column

from ..extensions import db


class Producto(db.Model):
    __tablename__ = "productos"

    id: Mapped[int] = mapped_column(primary_key=True)
    sku: Mapped[str] = mapped_column(String(40), unique=True, index=True)
    nombre: Mapped[str] = mapped_column(String(120))
    ubicacion: Mapped[str | None] = mapped_column(String(40))
    stock: Mapped[int] = mapped_column(default=0)
    precio: Mapped[Decimal] = mapped_column(Numeric(10, 2))

Un cambio importante respecto al estilo antiguo es el manejo de fechas. Las funciones que devuelven la hora UTC sin zona horaria están desaconsejadas en las versiones recientes de Python, así que usamos datetime.now con timezone.utc. Además, el dinero se guarda como Numeric y se maneja con Decimal, nunca con flotantes, para evitar errores de redondeo en precios.

Por último, la tabla que servirá para revocar tokens.

# app/models/token_revocado.py
from datetime import datetime, timezone

from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column

from ..extensions import db


class TokenRevocado(db.Model):
    __tablename__ = "tokens_revocados"

    id: Mapped[int] = mapped_column(primary_key=True)
    jti: Mapped[str] = mapped_column(String(36), unique=True, index=True)
    revocado_en: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )

Guardamos el identificador único del token y no el token completo. Es más compacto, no almacena material sensible y la búsqueda por una columna indexada es rápida.

Para que la fábrica registre todo con un solo import, el paquete de modelos reexporta las clases.

# app/models/__init__.py
from .producto import Producto
from .token_revocado import TokenRevocado
from .usuario import Usuario

__all__ = ["Producto", "TokenRevocado", "Usuario"]

Migraciones con flask db en lugar de scripts de gestión

Durante años fue habitual crear un archivo de gestión con Flask-Script para exponer comandos de migración. Ese proyecto está obsoleto, y hoy no hace falta nada de eso: Flask-Migrate se integra con la propia interfaz de línea de comandos de Flask y añade el grupo de comandos flask db. Ya registramos la extensión en la fábrica, así que podemos empezar.

flask db init
flask db migrate -m "tablas iniciales de inventario"
flask db upgrade

El primer comando crea la carpeta migrations con la configuración de Alembic. El segundo compara los modelos con el estado de la base y genera un script con las diferencias. El tercero aplica los cambios pendientes. Una salida típica del segundo comando se parece a esto.

INFO  [alembic.autogenerate.compare] Detected added table 'usuarios'
INFO  [alembic.autogenerate.compare] Detected added table 'productos'
INFO  [alembic.autogenerate.compare] Detected added table 'tokens_revocados'
  Generating migrations/versions/3f2a1c9d_tablas_iniciales_de_inventario.py ...  done

Dos hábitos evitan la mayoría de los problemas. El primero es revisar siempre el script generado antes de aplicarlo: la autogeneración no detecta renombrados de columnas, que interpreta como un borrado seguido de una creación, con la consiguiente pérdida de datos. El segundo es guardar la carpeta de migraciones en el repositorio, porque es el historial reproducible de tu esquema.

Para volver atrás tienes flask db downgrade, y para consultar el estado, flask db current y flask db history. En SQLite, algunas alteraciones de tablas requieren el modo de lotes de Alembic; si trabajas con SQLite en desarrollo y PostgreSQL en producción, conviene probar las migraciones también contra el motor real antes de desplegar.

Una advertencia sobre la coherencia entre entornos: si usas bases distintas en desarrollo y producción, algunos tipos se comportan de manera diferente, por ejemplo la precisión de los números decimales. Lo ideal es ejecutar la misma base en ambos sitios, algo sencillo con contenedores.

La capa de servicios con las consultas de SQLAlchemy 2

Los servicios concentran la lógica. Aquí se aprecia el segundo gran cambio de SQLAlchemy 2: las consultas usan select y se ejecutan a través de la sesión, en lugar de la antigua interfaz de consulta asociada al modelo, que ahora se considera heredada.

Definimos primero excepciones propias para que los controladores puedan traducirlas sin conocer los detalles internos.

# app/services/__init__.py
class ErrorDeNegocio(Exception):
    codigo_http = 400


class NoEncontrado(ErrorDeNegocio):
    codigo_http = 404


class Conflicto(ErrorDeNegocio):
    codigo_http = 409


class NoAutorizado(ErrorDeNegocio):
    codigo_http = 401

Con ellas escribimos el servicio de productos.

# app/services/producto_service.py
from sqlalchemy import select

from ..extensions import db
from ..models import Producto
from . import Conflicto, ErrorDeNegocio, NoEncontrado


def listar(pagina: int = 1, por_pagina: int = 20):
    consulta = select(Producto).order_by(Producto.nombre)
    return db.paginate(consulta, page=pagina, per_page=por_pagina, error_out=False)


def obtener(sku: str) -> Producto:
    producto = db.session.scalar(select(Producto).where(Producto.sku == sku))
    if producto is None:
        raise NoEncontrado(f"No existe el producto {sku}")
    return producto


def crear(datos: dict) -> Producto:
    existe = db.session.scalar(select(Producto.id).where(Producto.sku == datos["sku"]))
    if existe:
        raise Conflicto("Ya existe un producto con ese SKU")
    producto = Producto(**datos)
    db.session.add(producto)
    db.session.commit()
    return producto


def ajustar_stock(sku: str, delta: int) -> Producto:
    producto = obtener(sku)
    if producto.stock + delta < 0:
        raise ErrorDeNegocio("El stock no puede quedar negativo")
    producto.stock += delta
    db.session.commit()
    return producto

Fíjate en que ninguna función menciona peticiones, respuestas ni códigos de estado, salvo el atributo informativo de las excepciones. La regla de que el stock no puede ser negativo vive aquí, no en el endpoint. Si mañana añades una tarea programada o una herramienta de línea de comandos que ajuste inventario, reutilizarás la misma función con las mismas garantías.

En escenarios con mucha concurrencia, el ajuste de stock tal como está escrito puede perder actualizaciones si dos peticiones leen el mismo valor a la vez. Para un almacén real conviene usar una actualización atómica en la base, por ejemplo con una expresión que incremente la columna directamente, o un bloqueo de fila con la opción de selección para actualizar. Lo dejamos simple para centrarnos en la arquitectura, pero es un punto a vigilar.

Hash de contraseñas y tokens con PyJWT

Pasamos a la autenticación. Hay tres principios innegociables: nunca se almacenan contraseñas en claro, la comparación debe ser resistente a ataques de temporización y los tokens deben caducar. Usamos la librería bcrypt directamente, sin envoltorios adicionales, porque su interfaz es pequeña y estable.

# app/services/auth_service.py
import uuid
from datetime import datetime, timezone

import bcrypt
import jwt
from flask import current_app
from sqlalchemy import select

from ..extensions import db
from ..models import TokenRevocado, Usuario
from . import Conflicto, NoAutorizado


def registrar(correo: str, clave: str, es_admin: bool = False) -> Usuario:
    if db.session.scalar(select(Usuario.id).where(Usuario.correo == correo)):
        raise Conflicto("Ese correo ya está registrado")
    hash_clave = bcrypt.hashpw(clave.encode("utf-8"), bcrypt.gensalt())
    usuario = Usuario(correo=correo, hash_clave=hash_clave, es_admin=es_admin)
    db.session.add(usuario)
    db.session.commit()
    return usuario


def verificar_credenciales(correo: str, clave: str) -> Usuario:
    usuario = db.session.scalar(select(Usuario).where(Usuario.correo == correo))
    if usuario is None or not bcrypt.checkpw(clave.encode("utf-8"), usuario.hash_clave):
        raise NoAutorizado("Credenciales inválidas")
    return usuario

El mensaje de error es deliberadamente el mismo tanto si el correo no existe como si la clave es incorrecta. Distinguirlos permite a un atacante averiguar qué correos están registrados. Un matiz técnico de bcrypt: solo considera los primeros 72 bytes de la contraseña, y algunas versiones recientes de la librería rechazan entradas más largas, así que valida la longitud máxima en la capa de entrada.

Ahora la emisión y validación de tokens. PyJWT en su serie 2 devuelve cadenas desde encode, exige indicar explícitamente la lista de algoritmos permitidos al decodificar y, en versiones recientes, valida que el campo sub sea una cadena. Por eso convertimos el identificador numérico a texto.

def emitir_token(usuario: Usuario) -> str:
    ahora = datetime.now(timezone.utc)
    carga = {
        "sub": str(usuario.id),
        "jti": str(uuid.uuid4()),
        "adm": usuario.es_admin,
        "iat": ahora,
        "exp": ahora + current_app.config["JWT_DURACION"],
    }
    return jwt.encode(
        carga,
        current_app.config["SECRET_KEY"],
        algorithm=current_app.config["JWT_ALGORITMO"],
    )


def decodificar_token(token: str) -> dict:
    try:
        carga = jwt.decode(
            token,
            current_app.config["SECRET_KEY"],
            algorithms=[current_app.config["JWT_ALGORITMO"]],
            options={"require": ["exp", "sub", "jti"]},
        )
    except jwt.ExpiredSignatureError:
        raise NoAutorizado("El token ha expirado")
    except jwt.InvalidTokenError:
        raise NoAutorizado("Token inválido")
    if db.session.scalar(select(TokenRevocado.id).where(TokenRevocado.jti == carga["jti"])):
        raise NoAutorizado("El token fue revocado")
    return carga

La opción require obliga a que el token contenga los campos esenciales; sin ella, un token sin expiración sería aceptado como válido para siempre. Esa es una de las trampas más comunes al usar JWT. Tampoco debes aceptar nunca el algoritmo que indique la cabecera del propio token: la lista permitida la decide el servidor.

Una nota de diseño sobre HS256: es un algoritmo simétrico, adecuado cuando una única aplicación emite y valida. Si varios servicios deben verificar los tokens sin poder emitirlos, usa un algoritmo asimétrico como RS256 o EdDSA con una pareja de claves, de forma que solo el emisor posea la clave privada. Para conocer más prácticas de protección, conviene revisar con calma las prácticas de protección de sesiones y credenciales.

Cierre de sesión con una lista negra de tokens

Un JWT firmado es válido hasta que caduca, aunque el usuario haya cerrado sesión. Para poder invalidarlo antes necesitamos mantener una lista negra de tokens revocados y consultarla en cada petición. Es el precio de combinar tokens sin estado con la posibilidad de logout real.

def revocar_token(token: str) -> None:
    carga = decodificar_token(token)
    db.session.add(TokenRevocado(jti=carga["jti"]))
    db.session.commit()

La tabla crecería indefinidamente si no la limpiáramos. Como los tokens caducados ya son rechazados por su fecha de expiración, los registros antiguos de la lista negra dejan de aportar nada. Una tarea periódica puede borrar los anteriores a la duración máxima del token. Podemos exponerla como comando de la propia aplicación.

# fragmento para app/__init__.py, dentro de create_app
import click
from datetime import datetime, timezone
from sqlalchemy import delete

@app.cli.command("limpiar-tokens")
def limpiar_tokens():
    """Elimina revocaciones que ya no pueden afectar a ningún token."""
    from .models import TokenRevocado

    limite = datetime.now(timezone.utc) - app.config["JWT_DURACION"]
    resultado = db.session.execute(
        delete(TokenRevocado).where(TokenRevocado.revocado_en < limite)
    )
    db.session.commit()
    click.echo(f"Registros eliminados: {resultado.rowcount}")

Se invoca con flask limpiar-tokens y se programa con cron o con el planificador de tu plataforma. Si el tráfico es alto y no quieres una consulta a la base por petición, puedes mover la lista a una caché en memoria compartida con expiración automática por clave, algo que encaja muy bien con el campo de caducidad del token. Otra estrategia habitual es combinar tokens de acceso muy cortos con tokens de refresco de mayor duración, revocando solo estos últimos.

Controladores con Flask-RESTX: namespaces, modelos y validación

Ya tenemos la lógica; falta exponerla. Flask-RESTX organiza los endpoints en namespaces, describe los datos con modelos y genera la documentación interactiva automáticamente. Empezamos con el registro de la API y un manejador global para nuestras excepciones.

# app/api/__init__.py
from flask import Blueprint
from flask_restx import Api

from ..services import ErrorDeNegocio
from .auth import ns_auth
from .productos import ns_productos


def registrar_api(app):
    blueprint = Blueprint("api", __name__, url_prefix="/api/v1")
    api = Api(
        blueprint,
        title="API de inventario",
        version="1.0",
        description="Gestión de productos y stock de almacén",
        authorizations={
            "Bearer": {"type": "apiKey", "in": "header", "name": "Authorization"}
        },
    )
    api.add_namespace(ns_auth, path="/auth")
    api.add_namespace(ns_productos, path="/productos")

    @api.errorhandler(ErrorDeNegocio)
    def manejar_error_de_negocio(error):
        return {"mensaje": str(error)}, error.codigo_http

    app.register_blueprint(blueprint)

Un solo manejador convierte todas las excepciones de la capa de servicios en respuestas coherentes. Los controladores quedan libres de bloques de captura repetitivos.

Antes de los recursos, el decorador que protege rutas. Vive en un módulo propio porque lo usarán varios namespaces.

# app/api/seguridad.py
from functools import wraps

from flask import g, request

from ..services import NoAutorizado
from ..services.auth_service import decodificar_token


def _extraer_token() -> str:
    cabecera = request.headers.get("Authorization", "")
    partes = cabecera.split()
    if len(partes) != 2 or partes[0].lower() != "bearer":
        raise NoAutorizado("Falta la cabecera Authorization con esquema Bearer")
    return partes[1]


def token_requerido(funcion):
    @wraps(funcion)
    def envoltura(*args, **kwargs):
        g.token = _extraer_token()
        g.carga = decodificar_token(g.token)
        return funcion(*args, **kwargs)

    return envoltura


def admin_requerido(funcion):
    @wraps(funcion)
    @token_requerido
    def envoltura(*args, **kwargs):
        if not g.carga.get("adm"):
            raise NoAutorizado("Se requieren permisos de administrador")
        return funcion(*args, **kwargs)

    return envoltura

Los datos del token verificado se guardan en el objeto g, que Flask crea por cada petición, de modo que los recursos pueden leerlos sin volver a decodificar. Para devolver un 403 en lugar de un 401 cuando falta el permiso, puedes añadir una subclase de excepción con ese código; aquí mantenemos una sola para no alargar el ejemplo.

Ahora el namespace de autenticación.

# app/api/auth.py
from flask import g
from flask_restx import Namespace, Resource, fields

from ..services import auth_service
from .seguridad import token_requerido

ns_auth = Namespace("auth", description="Registro, acceso y cierre de sesión")

credenciales = ns_auth.model(
    "Credenciales",
    {
        "correo": fields.String(required=True, example="[email protected]"),
        "clave": fields.String(required=True, min_length=10, max_length=64),
    },
)

token_salida = ns_auth.model("Token", {"access_token": fields.String})


@ns_auth.route("/registro")
class Registro(Resource):
    @ns_auth.expect(credenciales, validate=True)
    @ns_auth.response(201, "Usuario creado")
    def post(self):
        datos = ns_auth.payload
        usuario = auth_service.registrar(datos["correo"], datos["clave"])
        return {"id": usuario.id, "correo": usuario.correo}, 201


@ns_auth.route("/acceso")
class Acceso(Resource):
    @ns_auth.expect(credenciales, validate=True)
    @ns_auth.marshal_with(token_salida)
    def post(self):
        datos = ns_auth.payload
        usuario = auth_service.verificar_credenciales(datos["correo"], datos["clave"])
        return {"access_token": auth_service.emitir_token(usuario)}


@ns_auth.route("/salida")
class Salida(Resource):
    @ns_auth.doc(security="Bearer")
    @token_requerido
    def post(self):
        auth_service.revocar_token(g.token)
        return {"mensaje": "Sesión cerrada"}

La opción validate hace que Flask-RESTX compruebe el cuerpo contra el modelo y devuelva un error 400 con el detalle si faltan campos o no cumplen los límites. Ten presente que la validación de los esquemas se apoya en JSON Schema y que no sustituye a las comprobaciones de negocio de los servicios.

Y el namespace de productos, con operaciones restringidas según el rol.

# app/api/productos.py
from flask import request
from flask_restx import Namespace, Resource, fields

from ..services import producto_service
from .seguridad import admin_requerido, token_requerido

ns_productos = Namespace("productos", description="Catálogo y stock")

producto = ns_productos.model(
    "Producto",
    {
        "sku": fields.String(required=True, max_length=40),
        "nombre": fields.String(required=True, max_length=120),
        "ubicacion": fields.String,
        "stock": fields.Integer(min=0, default=0),
        "precio": fields.Fixed(decimals=2, required=True),
    },
)

ajuste = ns_productos.model(
    "AjusteStock", {"delta": fields.Integer(required=True)}
)


@ns_productos.route("/")
class ListaProductos(Resource):
    @ns_productos.doc(security="Bearer")
    @token_requerido
    @ns_productos.marshal_list_with(producto)
    def get(self):
        pagina = request.args.get("pagina", 1, type=int)
        return producto_service.listar(pagina).items

    @ns_productos.doc(security="Bearer")
    @admin_requerido
    @ns_productos.expect(producto, validate=True)
    @ns_productos.marshal_with(producto, code=201)
    def post(self):
        return producto_service.crear(ns_productos.payload), 201


@ns_productos.route("/<string:sku>")
class DetalleProducto(Resource):
    @ns_productos.doc(security="Bearer")
    @token_requerido
    @ns_productos.marshal_with(producto)
    def get(self, sku):
        return producto_service.obtener(sku)


@ns_productos.route("/<string:sku>/stock")
class StockProducto(Resource):
    @ns_productos.doc(security="Bearer")
    @token_requerido
    @ns_productos.expect(ajuste, validate=True)
    @ns_productos.marshal_with(producto)
    def patch(self, sku):
        return producto_service.ajustar_stock(sku, ns_productos.payload["delta"])

El orden de los decoradores importa. El de seguridad va por fuera para rechazar la petición antes de procesar nada más, y el de serialización queda más cerca de la función para transformar su resultado. Al arrancar con flask run y abrir la raíz de la API en el navegador verás la interfaz Swagger con todos los endpoints, los modelos y el botón para introducir el token.

Para probar rápidamente desde la terminal puedes usar curl.

curl -s -X POST localhost:5000/api/v1/auth/registro \
  -H "Content-Type: application/json" \
  -d '{"correo": "[email protected]", "clave": "una-clave-bien-larga"}'
{"id": 1, "correo": "[email protected]"}

Pruebas automatizadas con pytest

Una API sin pruebas se rompe en silencio. Con pytest, la clave está en los fixtures: funciones que preparan y limpian el contexto de cada prueba. Aprovechamos la fábrica para crear una aplicación con la configuración de pruebas y una base de datos efímera que existe solo mientras dura cada test.

# tests/conftest.py
import pytest

from app import create_app
from app.extensions import db
from app.services import auth_service


@pytest.fixture()
def app():
    app = create_app("testing")
    with app.app_context():
        db.create_all()
        yield app
        db.session.remove()
        db.drop_all()


@pytest.fixture()
def cliente(app):
    return app.test_client()


@pytest.fixture()
def cabecera_admin(app):
    usuario = auth_service.registrar("[email protected]", "clave-de-admin-123", es_admin=True)
    token = auth_service.emitir_token(usuario)
    return {"Authorization": f"Bearer {token}"}

Dos observaciones. Para las pruebas creamos las tablas directamente con create_all porque lo que importa es el comportamiento de la API; las migraciones se pueden verificar en un trabajo aparte de integración continua. Y el fixture del administrador usa el servicio directamente, sin pasar por HTTP, lo que acelera las pruebas y las hace más independientes.

Primero las pruebas de autenticación.

# tests/test_auth.py
import time


def _registro(cliente, correo="[email protected]", clave="una-clave-bien-larga"):
    return cliente.post("/api/v1/auth/registro", json={"correo": correo, "clave": clave})


def test_registro_y_acceso(cliente):
    assert _registro(cliente).status_code == 201
    respuesta = cliente.post(
        "/api/v1/auth/acceso",
        json={"correo": "[email protected]", "clave": "una-clave-bien-larga"},
    )
    assert respuesta.status_code == 200
    assert "access_token" in respuesta.get_json()


def test_registro_duplicado_devuelve_conflicto(cliente):
    _registro(cliente)
    assert _registro(cliente).status_code == 409


def test_clave_incorrecta(cliente):
    _registro(cliente)
    respuesta = cliente.post(
        "/api/v1/auth/acceso",
        json={"correo": "[email protected]", "clave": "otra-clave-distinta"},
    )
    assert respuesta.status_code == 401


def test_logout_revoca_el_token(cliente):
    _registro(cliente)
    token = cliente.post(
        "/api/v1/auth/acceso",
        json={"correo": "[email protected]", "clave": "una-clave-bien-larga"},
    ).get_json()["access_token"]
    cabecera = {"Authorization": f"Bearer {token}"}

    assert cliente.post("/api/v1/auth/salida", headers=cabecera).status_code == 200
    assert cliente.get("/api/v1/productos/", headers=cabecera).status_code == 401


def test_token_expirado(cliente):
    _registro(cliente)
    token = cliente.post(
        "/api/v1/auth/acceso",
        json={"correo": "[email protected]", "clave": "una-clave-bien-larga"},
    ).get_json()["access_token"]
    time.sleep(6)
    respuesta = cliente.get(
        "/api/v1/productos/", headers={"Authorization": f"Bearer {token}"}
    )
    assert respuesta.status_code == 401

La prueba de expiración usa la duración de cinco segundos de la configuración de pruebas. Si te molesta esa espera, otra opción es fijar el reloj con una biblioteca de congelación de tiempo o generar directamente un token con fecha de expiración pasada.

Y ahora las de productos, que cubren permisos y reglas de negocio.

# tests/test_productos.py
NUEVO = {"sku": "TOR-001", "nombre": "Tornillo M6", "stock": 100, "precio": "0.15"}


def test_solo_admin_crea_productos(cliente, cabecera_admin):
    assert cliente.post("/api/v1/productos/", json=NUEVO).status_code == 401
    respuesta = cliente.post("/api/v1/productos/", json=NUEVO, headers=cabecera_admin)
    assert respuesta.status_code == 201
    assert respuesta.get_json()["sku"] == "TOR-001"


def test_sku_duplicado(cliente, cabecera_admin):
    cliente.post("/api/v1/productos/", json=NUEVO, headers=cabecera_admin)
    respuesta = cliente.post("/api/v1/productos/", json=NUEVO, headers=cabecera_admin)
    assert respuesta.status_code == 409


def test_stock_no_puede_ser_negativo(cliente, cabecera_admin):
    cliente.post("/api/v1/productos/", json=NUEVO, headers=cabecera_admin)
    respuesta = cliente.patch(
        "/api/v1/productos/TOR-001/stock", json={"delta": -500}, headers=cabecera_admin
    )
    assert respuesta.status_code == 400


def test_validacion_de_entrada(cliente, cabecera_admin):
    respuesta = cliente.post(
        "/api/v1/productos/", json={"nombre": "Sin SKU"}, headers=cabecera_admin
    )
    assert respuesta.status_code == 400

Se ejecutan todas con un comando, y la salida indica de un vistazo el estado.

pytest -q
.........                                                                [100%]
9 passed in 6.41s

Cuando el conjunto crezca, añade la medición de cobertura y ejecuta las pruebas en cada commit mediante integración continua. Además, escribe pruebas unitarias directas de los servicios: son más rápidas que las de extremo a extremo y señalan con más precisión dónde está el fallo.

Errores frecuentes y cómo resolverlos

Algunos problemas aparecen una y otra vez en proyectos con esta arquitectura, y conocerlos ahorra horas de depuración.

El primero es el error de contexto de aplicación, que Flask comunica con un mensaje sobre trabajar fuera de ese contexto. Ocurre cuando usas la sesión de base de datos en un script o un hilo sin haber entrado en el contexto. La solución es envolver el código con el gestor de contexto de la aplicación, como hacen los fixtures de pruebas.

El segundo es que flask db migrate no detecte tus modelos y genere un script vacío. Casi siempre significa que los modelos no se importaron antes de ejecutar el comando. Verifica que la fábrica importe el paquete de modelos, como hicimos.

El tercero es el import circular, que suele delatarse con un error de nombre no definido al arrancar. Mantén las extensiones en su módulo sin dependencias internas y haz los imports de las partes de la API dentro de la fábrica si hace falta.

El cuarto es olvidar la lista de algoritmos al decodificar un token, o confiar en que la firma basta sin exigir expiración. Revisa que decodificar siempre reciba los algoritmos permitidos y los campos obligatorios.

El quinto afecta a las pruebas: si una prueba depende del orden de ejecución o de datos que dejó otra, tendrás fallos intermitentes. Los fixtures que crean y destruyen el esquema por prueba evitan este tipo de contaminación, a costa de algo de velocidad. Si el tiempo se vuelve un problema, puedes envolver cada prueba en una transacción que se revierte al final.

El sexto es mezclar zonas horarias. SQLite no conserva la zona de las fechas, y al compararlas con fechas con zona obtendrás errores. Normaliza todo a UTC en la entrada y trátalo así de forma consistente, convirtiendo a la zona local solo al mostrar datos al usuario.

Buenas prácticas de seguridad y rendimiento

Más allá de lo implementado, hay medidas que elevan notablemente la solidez del servicio.

En seguridad, limita los intentos de acceso. Un atacante puede probar millones de contraseñas contra el endpoint de acceso, y una extensión de limitación de peticiones por dirección o por cuenta reduce mucho el riesgo. Sirve siempre la API por HTTPS y configura las cabeceras de seguridad en el proxy inverso. No registres tokens ni contraseñas en los logs, ni siquiera en depuración. Rota la clave secreta con un plan: si la cambias de golpe, todos los tokens vigentes se invalidan, y si la filtras, es exactamente lo que necesitas hacer.

Define también una política para las contraseñas: longitud mínima razonable, bloqueo de las más comunes y ningún límite artificial bajo, salvo el técnico de bcrypt. Y revisa periódicamente las dependencias con herramientas de auditoría, porque las librerías de criptografía y de tokens reciben correcciones de seguridad con frecuencia, razón de más para fijar rangos y actualizar con calma.

En rendimiento, el primer cuello de botella suele ser la base de datos. Añade índices a las columnas por las que filtras, como hicimos con el SKU y el correo. Pagina siempre los listados, como en el servicio de productos, para no devolver miles de filas. Evita el problema de consultas N más uno cargando relaciones con las estrategias de carga de SQLAlchemy cuando introduzcas tablas relacionadas, como movimientos de stock por producto.

Para ejecutar en producción no uses el servidor de desarrollo de Flask. Emplea un servidor WSGI como Gunicorn o uWSGI con varios procesos de trabajo, detrás de un proxy inverso. La fábrica de aplicaciones lo facilita, porque el servidor solo necesita una referencia a la función que crea la aplicación.

gunicorn --workers 4 --bind 0.0.0.0:8000 "app:create_app('production')"

Para empaquetarlo todo y desplegarlo con garantías, consulta la guía sobre desarrollo y despliegue de aplicaciones web Flask en la nube, que complementa muy bien lo visto aquí.

Alternativas a Flask-RESTX y cuándo elegirlas

Flask-RESTX cumple su cometido y sigue publicando versiones, pero su ritmo de desarrollo es moderado y conviene saber qué otras opciones existen, sobre todo si vas a empezar un proyecto nuevo con vida larga.

Flask-Smorest se apoya en marshmallow para esquemas y en apispec para generar la especificación OpenAPI. Es una buena elección si ya usas marshmallow o si valoras una documentación estándar, con una integración cuidada de la paginación y los errores. APIFlask añade al propio Flask validación, serialización y documentación con una interfaz muy cercana al estilo original, con la ventaja de que puedes migrar un proyecto existente de forma gradual. Y si tus necesidades lo permiten, FastAPI ofrece tipado y validación con Pydantic, documentación automática y soporte asíncrono de primera clase, aunque supone abandonar Flask.

Una regla práctica: si ya tienes mucho código en Flask y quieres mantener la estructura de este tutorial, quédate con Flask-RESTX o evalúa Flask-Smorest. Si empiezas de cero y la API es el núcleo del producto, compara con FastAPI antes de decidir. En cualquier caso, la separación en controladores, servicios y modelos que hemos aplicado es independiente de la librería de documentación: migrar solo afectaría a la capa de controladores, que es justo la ventaja de haber dividido las responsabilidades.

Otro punto a revisar es la gestión de tokens. Bibliotecas integradas como Flask-JWT-Extended resuelven muchas de estas tareas, incluida la revocación y los tokens de refresco, con una interfaz ya probada. Escribir el servicio a mano, como hicimos, ayuda a entender qué ocurre por debajo y da control total, pero en un proyecto crítico puede ser más prudente apoyarse en una extensión con años de uso y auditoría.

Conclusiones

Hemos construido una API de inventario con una arquitectura que escala sin dolor: una fábrica de aplicaciones que permite instanciar la app con distintas configuraciones, clases de configuración por entorno que mantienen los secretos fuera del código, modelos con el estilo tipado de SQLAlchemy 2, migraciones gestionadas con el comando flask db y una capa de servicios que concentra las reglas de negocio con independencia del protocolo.

En seguridad aplicamos hash con bcrypt, tokens firmados con PyJWT con campos obligatorios y algoritmos explícitos, y una tabla de revocación que hace posible un cierre de sesión real. La suite de pytest, apoyada en fixtures y en la fábrica, verifica registro, acceso, permisos, validaciones y reglas de stock sin depender del orden de ejecución.

Los siguientes pasos naturales son añadir movimientos de stock con su historial, limitar la tasa de peticiones, fijar la integración continua para ejecutar las pruebas y las migraciones en cada cambio, y contenerizar el servicio para desplegarlo. Antes de ello, recuerda comprobar en PyPI las versiones vigentes de cada dependencia, porque este ecosistema se mueve con rapidez y los rangos que fijamos hoy conviene revisarlos de forma periódica.