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 para la tienda.
Inventario: calcula el stock sumando movimientos —nunca lo fija a mano— y registra ajustes y mermas.
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 verificando stock; al confirmar, lo descuenta y congela el precio en cada línea.
Facturación: emite boleta/factura a SUNAT y notas de crédito; registra pagos con Yape, Plin, tarjeta o transferencia.
Autenticación: POST /auth/login, /auth/refresh, /auth/logout. Tokens JWT con el rol del usuario.
Integraciones: SUNAT para comprobantes, pasarela de pagos local y courier (Olva) para envíos.
Limitaciones y restricciones
Limitación de tasa: Máximo de 100 peticiones por minuto e IP, como protección frente a ataques de denegación de servicio.
Tiempos límite: Las operaciones largas (reportes) se limitan a 30 segundos; lo más pesado se delega en tareas asíncronas.
Concurrencia: Dos pedidos simultáneos podrían provocar condiciones de carrera sobre el stock, mitigadas con bloqueos.
Coste computacional: Los reportes muy grandes pueden saturar la CPU; sus resultados se cachean.
Dependencia externa: Si SUNAT o la pasarela de pagos caen, no se pueden completar pedidos. Hay reintentos pero requiere intervención manual.
Propósito del componente
Actuar como intermediario entre el frontend (tienda y panel) y los datos: aplicar reglas, validar operaciones y coordinar integraciones. Una API bien diseñada permite que la tienda y el panel deleguen toda la lógica y se limiten a presentar la información.
Por qué: Django es maduro y seguro. DRF agiliza construir APIs. PostgreSQL maneja datos relacionales complejos. Redis para cache y colas. Celery para tareas asincrónicas (envío de facturas). Gunicorn como servidor WSGI. Docker para deployment reproducible.
Información técnica adicional
Arquitectura: Patrón MVC con modelos normalizados. Serializers para validar la entrada y ViewSets para el CRUD repetitivo.
Seguridad: CORS restringido a dominios autorizados, tokens CSRF, prevención de inyección SQL mediante el ORM y contraseñas con hash.
Monitorización: Logs centralizados, alertas si la tasa de error supera el 1% y endpoint de health check.
Versionado: /api/v1/pedidos, /api/v2/pedidos permite evolucionar sin romper la tienda ni el panel.
Documentación: Generada automáticamente con Swagger/OpenAPI; permite probar los endpoints desde la interfaz.
Métricas importantes
Tiempo de respuesta: P95 < 200 ms, P99 < 500 ms; ningún endpoint debería superar los 5 s.
Disponibilidad: 99,9%. Es el cuello de botella: si cae, nada funciona.
Tasa de error: < 0,5%. Los errores 5xx son críticos y se alertan de inmediato.
Rendimiento (throughput): Capacidad de procesar al menos 500 peticiones por segundo sin degradación.
Precisión de datos: Transacciones ACID garantizadas; no se pierden pedidos.
El motor es la pieza más crítica del sistema: un defecto aquí corrompe datos y una caída detiene todo. Conviene invertir en pruebas, monitorización y documentación. La velocidad de procesamiento incide directamente en la experiencia del cliente.