API backend que implementa las reglas de negocio y coordina la tienda, el panel, las bases de datos y los servicios externos. Toda operación pasa por aquí.
Esta página describe el componente. El contrato completo de la API, endpoint por endpoint, está en el documento oficial: La API del motor →
¿Qué es?
Es una API REST construida con Django y Django REST Framework. Recibe peticiones del catálogo público y del panel de gestión, aplica las reglas de negocio, consulta las bases de datos e interactúa con servicios externos. Responde siempre en JSON.
Funciones principales
Catálogo: producto y variante (el SKU), con búsqueda (pg_trgm), filtros y paginación.
Inventario: calcula el stock sumando movimientos —nunca lo fija a mano— y registra ajustes y mermas (ver Cómo se deriva el stock).
Compras / importación: órdenes a proveedores con su tipo de cambio; al recibir, suma stock y reparte flete/aduana en el costo real.
Ventas: crea pedidos; al confirmar, verifica y descuenta stock, y congela el precio en cada línea.
Facturación: registra boleta/factura y encola su emisión a SUNAT (hoy simulada, ver Servicios externos); registra pagos con Yape, Plin, tarjeta, transferencia o efectivo.
Autenticación: POST /auth/login, /auth/refresh, /auth/logout. Tokens JWT con el rol del usuario, más una sesión Django compartida (SSO) para Documentation.
Equipo: autoregistro (POST /auth/registro) con la cuenta bloqueada hasta que un admin la aprueba desde la intranet (/equipo/{id}/aprobar), con aviso por correo best-effort.
Fotos de producto: sube el original y encola la conversión real a WebP (miniatura/media/original) con Pillow.
Limitaciones y restricciones
Sin límite de tasa (rate limiting): no hay throttling configurado en DRF hoy; no hay protección explícita frente a abuso por IP.
Concurrencia: confirmar pedido y recibir orden son transacciones atómicas que verifican stock antes de escribir, pero no hay bloqueo pesimista explícito sobre la fila de la variante.
Sin caché de reportes: cada consulta de Reportes recalcula desde cero (agregaciones SQL), no hay resultados cacheados.
Dependencia externa real: hoy ninguna integración externa puede "caerse" porque ninguna está conectada de verdad (SUNAT es un simulacro; no hay pasarela de pagos ni courier con API). Es una limitación en sí misma: no hay facturación electrónica legal real todavía.
Propósito del componente
Actuar como intermediario entre los clientes (intranet, tienda pública) y los datos: aplicar reglas, validar operaciones y coordinar lo asíncrono. Una API bien diseñada permite que los frontends deleguen toda la lógica y se limiten a presentar la información.
Por qué: Django + DRF para la API. simplejwt para el login por token. django-filter para los filtros de cada listado. Redis + Celery para lo asíncrono (fotos, emisión simulada de SUNAT). Pillow procesa las imágenes de verdad. Gunicorn sirve la app en producción, Docker empaqueta cada servicio.
Información técnica adicional
Arquitectura: Serializers para validar la entrada, ViewSets para el CRUD, y services.py para las reglas de negocio (confirmar pedido, recibir orden) que no encajan en un serializer.
Tres bases de datos: leon_principal, leon_fotos y leon_facturas, enrutadas por LeonRouter según la app. Sin FK entre ellas.
Seguridad: CORS restringido por variable de entorno, contraseñas con hash (Django), inyección SQL prevenida por el ORM.
Monitorización: endpoint /salud de health check. Sin dashboards de métricas ni alertas configuradas para el backend en sí.
Versionado:URLPathVersioning de DRF está activo, pero solo existe /api/v1/ — no hay una v2 todavía.
Documentación de la API: este mismo documento (La API del motor), escrito a mano. No hay Swagger/OpenAPI autogenerado.
El motor es la pieza más crítica del sistema: un defecto aquí corrompe datos y una caída detiene todo. El detalle completo de cada endpoint está en La API del motor.