Backend · documento oficial
Contrato vigente de la API. Refleja el modelo de Las tablas del negocio.
El motor (Django + Django REST Framework) expone una API REST en JSON. La tienda y el panel son clientes ligeros: solo solicitan y presentan; todas las reglas —descontar stock, calcular el costo en soles, emitir a SUNAT— residen aquí. Cada recurso de la API corresponde a una tabla del modelo.
/api/v1/. La versión en la ruta permite evolucionar sin romper a la tienda.JSON. Fechas en ISO 8601, montos como número.JWT en la cabecera Authorization: Bearer …. El catálogo público es de solo lectura sin token.?page=), con ?buscar= y filtros (?categoria=, ?estado=).200/201 bien, 400 datos inválidos, 401/403 sin permiso, 409 conflicto (p. ej. sin stock).| Endpoint | Qué hace y reglas |
|---|---|
POST /auth/login { email, password } → { token } | Valida credenciales y devuelve un token JWT con el rol dentro. |
POST /auth/refresh | Renueva el token antes de que caduque, sin volver a pedir contraseña. |
POST /auth/logout | Invalida el token actual. |
GET /auth/yo | Devuelve el usuario en sesión y su rol. Apunta a usuario. |
| Endpoint | Qué hace y reglas |
|---|---|
GET /productos ?buscar=&categoria=&page= | Lista productos activos con sus variantes. Usa pg_trgm de Postgres para el buscar. Apunta a producto. |
GET /productos/{id} | Detalle del producto con sus variantes, imágenes y stock de cada una. |
POST /productos | Crea un producto. Solo abastecimiento/admin. |
GET /variantes/{id} | La versión real (el SKU). Es lo que se compra, vende y cuenta. Apunta a variante. |
PATCH /variantes/{id} | Edita SKU, código de barras, atributos o si sigue activa. |
GET /categorias | Árbol de categorías (con padre_id). Apunta a categoria. |
| Endpoint | Qué hace y reglas |
|---|---|
GET /variantes/{id}/stock | Devuelve el stock disponible calculado sumando movimiento_inventario, por almacén. Nunca es un valor escrito a mano. |
GET /movimientos ?variante=&almacen=&tipo= | El historial de entradas y salidas. Auditable: de dónde salió cada unidad. |
POST /movimientos | Registra un ajuste o merma a mano. Las compras y ventas generan su movimiento automáticamente, no por aquí. |
GET /almacenes | Las zonas físicas. Apunta a almacen. |
| Endpoint | Qué hace y reglas |
|---|---|
GET /proveedores | Fábricas y mayoristas. Apunta a proveedor. |
POST /ordenes-compra | Crea un pedido a un proveedor con sus líneas. Guarda tipo_cambio para calcular el costo real en soles. |
PATCH /ordenes-compra/{id} | Avanza el estado (pedido → producción → en tránsito → recibido). |
POST /ordenes-compra/{id}/recibir | Genera las entradas de stock de las variantes recibidas, en un solo paso atómico. |
GET /embarques/{id}/costo-real | Reparte flete, aduana y seguro (costo_importacion) entre las unidades para saber cuánto costó de verdad cada una. |
GET /muestras | Control de calidad previo. Apunta a muestra. |
| Endpoint | Qué hace y reglas |
|---|---|
GET /clientes | Personas y empresas. El doc_tipo (DNI/RUC) decide boleta o factura. Apunta a cliente. |
POST /pedidos | Crea una venta con sus líneas. Verifica stock antes de confirmar; si falta, responde 409. |
POST /pedidos/{id}/confirmar | Descuenta el stock como salida y deja el pedido listo para cobro y comprobante. Todo en una transacción. |
GET /pedidos/{id} | Detalle con líneas, envío, pagos y comprobante asociado. Apunta a pedido. |
POST /cotizaciones Fase posterior | Propuesta de precio a un mayorista antes de confirmar. Apunta a cotizacion. |
POST /envios | Registra el despacho (courier, tracking, costo). Apunta a envio_cliente. |
| Endpoint | Qué hace y reglas |
|---|---|
POST /comprobantes | Emite boleta o factura de un pedido. Encola el envío a SUNAT (Celery); responde 202 con estado pendiente. Apunta a comprobante. |
GET /comprobantes/{id} | Estado SUNAT (aceptado/rechazado/pendiente) y enlaces al XML y CDR. |
POST /notas-credito | Devolución o anulación que referencia al comprobante original. Apunta a nota_credito. |
POST /pagos | Registra el cobro (Yape, Plin, tarjeta, transferencia) con su voucher. Apunta a pago. |
POST /pagos/{id}/confirmar | Marca el pago confirmado y, si cubre el total, pasa el pedido a pagado. |
| Endpoint | Qué hace y reglas |
|---|---|
GET /reportes/ventas ?desde=&hasta= | Ventas agregadas por día/mes. Resultado cacheado en Redis. |
GET /reportes/stock-bajo | Variantes por debajo del mínimo, para reponer. |
GET /salud | Health check: responde que el motor y la base están vivos. |
POST /tareas (interno) | No es un endpoint público: emisión a SUNAT, envío de avisos y recálculos corren como tareas de Celery encoladas en Redis. |
Tres reglas atraviesan toda la API: el stock se calcula (nunca se fija por endpoint), confirmar pedido y emitir comprobante son transacciones que no dejan estados a medias, y lo lento (SUNAT, avisos) es asíncrono vía Celery. El detalle de cada tabla está en Las tablas del negocio; el panorama de componentes, en El motor.