Skip to content

Home

Jump to bottom
Camilo edited this page Oct 13, 2026 · 48 revisions

Documentación de la API Backend LaSobremesa

Documentación técnica de los servicios, endpoints, modelos y contratos de la API Backend del ecommerce LaSobremesa.

Esta Wiki tiene como objetivo centralizar la documentación de la API y facilitar el desarrollo, integración y mantenimiento de los distintos servicios del proyecto.

Sobre el proyecto

LaSobremesa es un ecommerce orientado a la comercialización de productos artesanales provenientes de proveedores locales.

El backend expone una API REST organizada en distintos dominios de negocio, incluyendo catálogo, usuarios y proveedores, carrito y pedidos, checkout, autenticación y cuenta, comunidad y fidelización, y logística.

Servicios

Catálogo

Servicios relacionados con los productos disponibles en la tienda.

Usuarios y proveedores

Servicios relacionados con los usuarios del sistema, proveedores locales y sus direcciones.

Carrito y pedidos

Servicios relacionados con el proceso de compra y gestión de pedidos.

  • Carrito
  • Ítems del carrito
  • Pedidos
  • Detalle de pedidos
  • Estados de pedidos
  • Historial de pedidos

Checkout

Servicios relacionados con el proceso de finalización de compra.

Autenticación y cuenta

Servicios relacionados con autenticación, registro y gestión de cuentas.

  • Autenticación
  • Cuenta
  • Registro
  • Recuperación de contraseña
  • Verificación de correo electrónico

Comunidad y fidelización

Servicios relacionados con la interacción de los usuarios y su relación con el ecommerce.

Logística

Servicios relacionados con la gestión y seguimiento del despacho de los pedidos.

  • Despacho
  • Métodos de entrega
  • Tiempo de entrega
  • Seguimiento de despacho
  • Zonas de despacho

Relación con el Sitemap y Wireframes

La definición de los dominios y servicios del backend se realizó considerando el Sitemap general del proyecto y el nivel de detalle presente en los wireframes.

El Sitemap representa la estructura general de navegación, mientras que los wireframes detallan las funcionalidades asociadas a cada sección. Por este motivo, algunas funcionalidades del backend pueden no aparecer explícitamente en el Sitemap, pero sí estar representadas en los wireframes.

La siguiente tabla muestra la relación entre las secciones del Sitemap, las funcionalidades identificadas, los dominios del backend y los servicios correspondientes.

Sección del Sitemap Funcionalidad Dominio Servicio
Productos Catálogo (Lista de productos) Catálogo Productos
Productos Catálogo (Lista de productos) Catálogo Categorías
Productos Catálogo (Lista de productos) Catálogo Stock
Productos Detalle del producto Catálogo Productos
Productos Reseñas del producto Comunidad y fidelización Reseñas
Historias Productores Usuarios y proveedores Proveedores
Historias Perfil de cada productor Usuarios y proveedores Proveedores
Suscripción Planes Comunidad y fidelización Suscripciones
Cuenta Mis datos Autenticación y cuenta Usuarios
Cuenta Mis datos (Direcciones) Usuarios y proveedores Direcciones
Cuenta Mis pedidos Carrito y pedidos Pedidos
Cuenta Mis pedidos Carrito y pedidos Detalle de pedidos
Cuenta Mis pedidos Carrito y pedidos Estados de pedidos
Cuenta Mis pedidos Carrito y pedidos Historial de pedidos
Cuenta Mi suscripción Comunidad y fidelización Suscripciones
Cuenta Favoritos Catálogo Favoritos
Cuenta Tarjetas Usuarios y proveedores Tarjetas
Cuenta Autenticación Autenticación y cuenta Autenticación
Cuenta Registro Autenticación y cuenta Registro
Cuenta Recuperación de contraseña Autenticación y cuenta Recuperación de contraseña
Cuenta Verificación de correo electrónico Autenticación y cuenta Verificación de correo electrónico
Carrito Carrito Carrito y pedidos Carrito
Carrito Carrito Carrito y pedidos Ítems del carrito
Carrito Checkout Checkout Checkout
Carrito Checkout Checkout Datos de despacho
Carrito Checkout Checkout Métodos de entrega
Carrito Checkout Checkout Tiempo de entrega
Carrito Checkout Checkout Datos de facturación
Carrito Checkout Checkout Métodos de pago
Carrito Compra exitosa Checkout Confirmación de compra
Ayuda Envíos Logística Despacho
Ayuda Envíos Logística Seguimiento de despacho
Ayuda Envíos Logística Zonas de despacho

Organización de la API

La API está organizada en dominios funcionales, los cuales agrupan los distintos servicios del ecommerce.

Dominio Servicios
Catálogo Productos, Categorías, Favoritos, Stock
Usuarios y proveedores Usuarios, Proveedores, Direcciones, Tarjetas
Carrito y pedidos Carrito, Ítems del carrito, Pedidos, Detalle de pedidos, Estados de pedidos, Historial de pedidos
Checkout Checkout, Datos de despacho, Datos de facturación, Métodos de pago, Confirmación de compra
Autenticación y cuenta Autenticación, Cuenta, Registro, Recuperación de contraseña, Verificación de correo electrónico
Comunidad y fidelización Suscripciones, Reseñas
Logística Despacho, Métodos de entrega, Tiempo de entrega, Seguimiento de despacho, Zonas de despacho

Estado de los servicios

El estado de cada servicio refleja su avance de implementación para el Hito 2. Los servicios implementados utilizan comportamiento simulado y no necesariamente cuentan con persistencia ni lógica de negocio completa.

Dominio Servicio Estado
Catálogo Productos 🟢 Implementado (simulado)
Catálogo Categorías 🟡 En desarrollo
Catálogo Favoritos 🟢 Implementado (simulado)
Catálogo Stock 🟡 En desarrollo
Usuarios y proveedores Usuarios 🟡 En desarrollo
Usuarios y proveedores Proveedores 🟢 Implementado (simulado)
Usuarios y proveedores Direcciones 🟡 En desarrollo
Usuarios y proveedores Tarjetas 🟢 Implementado (simulado)
Carrito y pedidos Carrito 🟡 En desarrollo
Carrito y pedidos Ítems del carrito 🟡 En desarrollo
Carrito y pedidos Pedidos 🟡 En desarrollo
Carrito y pedidos Detalle de pedidos 🟡 En desarrollo
Carrito y pedidos Estados de pedidos 🟡 En desarrollo
Carrito y pedidos Historial de pedidos 🟡 En desarrollo
Checkout Checkout 🟢 Implementado (simulado)
Checkout Datos de despacho 🟡 En desarrollo
Checkout Datos de facturación 🟢 Implementado (simulado)
Checkout Métodos de pago 🟡 En desarrollo
Checkout Confirmación de compra 🟢 Implementado (simulado)
Autenticación y cuenta Autenticación 🟢 Implementado (simulado)
Autenticación y cuenta Cuenta 🟡 En desarrollo
Autenticación y cuenta Registro 🟢 Implementado (simulado)
Autenticación y cuenta Recuperación de contraseña 🟡 En desarrollo
Autenticación y cuenta Verificación de correo electrónico 🟡 En desarrollo
Comunidad y fidelización Suscripciones 🟡 En desarrollo
Comunidad y fidelización Reseñas 🟢 Implementado (simulado)
Logística Despacho 🟡 En desarrollo
Logística Métodos de entrega 🟡 En desarrollo
Logística Tiempo de entrega 🟡 En desarrollo
Logística Seguimiento de despacho 🟡 En desarrollo
Logística Zonas de despacho 🟡 En desarrollo

Los estados corresponden al avance actual del proyecto y pueden cambiar durante el desarrollo.

Flujo de ramas

El proyecto utiliza una estrategia de ramas para organizar el desarrollo, integrar las funcionalidades y mantener estable la versión principal.

  • main: rama principal y estable del proyecto.
  • develop: rama de integración donde se incorporan y validan las funcionalidades desarrolladas por el equipo.
  • feature/*: ramas de trabajo para implementar funcionalidades específicas.

Flujo de trabajo

  1. Crear una rama feature/* a partir de develop.
  2. Desarrollar y probar los cambios en la rama correspondiente.
  3. Crear un Pull Request (PR) desde feature/* hacia develop.
  4. Revisar y aprobar el PR antes de integrar los cambios en develop.
  5. Validar la integración de las funcionalidades en develop.
  6. Crear un Pull Request desde develop hacia main cuando la versión esté lista.
  7. Revisar y aprobar el PR para incorporar los cambios en main.

Este flujo permite integrar y validar el trabajo del equipo antes de incorporarlo a la rama principal estable.

Rama principal

La rama main contiene el código estable del proyecto y no se utiliza para desarrollar directamente.

Ramas de funcionalidades

Cada servicio o funcionalidad se desarrolla en una rama independiente utilizando la siguiente nomenclatura:

feature/<nombre-del-servicio>

Ejemplos:

  • feature/productos
  • feature/categorias
  • feature/direcciones
  • feature/usuarios
  • feature/proveedores

Pull Requests

Una vez finalizado el desarrollo de una funcionalidad, se crea un Pull Request desde la rama feature/* correspondiente hacia develop.

Los cambios deben ser revisados antes de realizar el merge.

Convenciones de la API

La API utiliza una arquitectura REST y sigue las siguientes convenciones:

Métodos HTTP

Método Uso
GET Consultar recursos
POST Crear recursos
PUT Actualizar completamente un recurso
PATCH Actualizar parcialmente un recurso
DELETE Eliminar recursos

Parámetros

  • Los identificadores de recursos se utilizan como parámetros de ruta.
  • Los filtros de búsqueda se envían mediante query parameters.
  • Los datos para crear o actualizar recursos se envían mediante Request Body.

Respuestas

Las respuestas exitosas utilizan códigos HTTP según la operación realizada.

Código Uso
200 OK Operación exitosa
201 Created Recurso creado correctamente
204 No Content Operación exitosa sin contenido
400 Bad Request Datos o parámetros inválidos
404 Not Found Recurso no encontrado
409 Conflict Conflicto con el estado actual del recurso

Documentación de cada servicio

Cada página de servicio contiene:

  • Descripción del servicio.
  • Endpoints disponibles.
  • Modelos utilizados.
  • DTOs de entrada y salida.
  • Parámetros de ruta.
  • Query parameters.
  • Request Bodies.
  • Ejemplos de respuestas.
  • Códigos HTTP.
  • Respuestas de error.

Contratos de la API

Los contratos de los endpoints se documentan utilizando Swagger/OpenAPI.

La documentación incluye:

  • Parámetros de entrada.
  • DTOs.
  • Tipos de respuesta.
  • Códigos HTTP.
  • Ejemplos de datos.
  • Respuestas de error.

La documentación Swagger sirve como referencia técnica complementaria a esta Wiki.

Alcance del Hito 1

Durante el Hito 1 se define la estructura inicial del backend y los principales contratos de la API.

Entre los aspectos considerados se encuentran:

  • Definición de los principales dominios del sistema.
  • Identificación de los servicios necesarios para el ecommerce.
  • Definición de entidades y modelos.
  • Definición de DTOs.
  • Diseño de endpoints REST.
  • Definición de parámetros de entrada.
  • Definición de respuestas de la API.
  • Documentación de los endpoints mediante Swagger.
  • Documentación técnica de los servicios mediante esta Wiki.
  • Definición de responsabilidades dentro del equipo.

Alcance del Hito 2

El Hito 2 tiene como objetivo avanzar desde la definición de los contratos de la API hacia una primera implementación funcional del backend, manteniendo la coherencia entre los endpoints, los DTOs, las validaciones y la documentación.

Implementaciones realizadas

  • Servicios REST: implementación inicial de endpoints para los servicios asignados, utilizando respuestas simuladas cuando la lógica de negocio o la persistencia aún no están disponibles.
  • DTOs: definición de objetos para estructurar los datos de entrada y salida de los endpoints.
  • Validaciones: incorporación de validaciones para los datos recibidos mediante DTOs y mecanismos de validación de NestJS.
  • Documentación Swagger: documentación de los endpoints, parámetros, DTOs, validaciones y respuestas HTTP.
  • Trazabilidad de solicitudes: incorporación de un identificador único por solicitud, disponible en el encabezado de respuesta x-request-id.
  • Registro de solicitudes: registro de información relevante para el seguimiento de las solicitudes, incluyendo identificador, fecha y hora, método HTTP, ruta, duración y código de respuesta.
  • Manejo de errores: incorporación de excepciones y filtros para estandarizar las respuestas de error HTTP.
  • Configuración del entorno: documentación de las variables de entorno necesarias para ejecutar la aplicación.
  • Contenedorización: incorporación de Docker para facilitar la ejecución del backend y su entorno local.

Alcance y limitaciones

La implementación de este hito constituye una primera versión funcional de la API. Algunos endpoints utilizan datos y respuestas simuladas, por lo que no representan necesariamente operaciones persistentes ni procesos de negocio completos.

La persistencia definitiva, el modelo físico de la base de datos y la integración completa de los procesos de negocio se desarrollarán según el alcance de las siguientes etapas del proyecto.

Servicios definidos

A continuación se indican los endpoints actualmente definidos para cada servicio.

Productos

  • GET /productos - Obtener lista de productos con filtros opcionales
  • GET /productos/top-ventas - Obtener productos más vendidos
  • GET /productos/{id} - Obtener producto por ID
  • POST /productos - Crear producto
  • PATCH /productos/{id} - Actualizar producto
  • DELETE /productos/{id} - Eliminar producto

Categorías

  • GET /categorias - Obtener lista de categorías con filtro opcional por nombre
  • GET /categorias/top - Obtener categorías más utilizadas
  • GET /categorias/{id} - Obtener categoría por ID
  • POST /categorias - Crear categoría
  • PATCH /categorias/{id} - Actualizar categoría
  • DELETE /categorias/{id} - Eliminar categoría

Stock

  • GET /stock/{productoId} - Obtener stock de un producto
  • POST /stock - Crear registro de stock
  • PATCH /stock/{productoId} - Actualizar stock de un producto
  • DELETE /stock/{productoId} - Eliminar registro de stock

Usuarios

  • GET /usuarios - Obtener lista de usuarios
  • GET /usuarios/{id} - Obtener usuario por ID
  • POST /usuarios - Crear usuario
  • PATCH /usuarios/{id} - Actualizar usuario
  • DELETE /usuarios/{id} - Eliminar usuario

Proveedores

  • GET /proveedores - Obtener lista de proveedores
  • GET /proveedores/{id} - Obtener proveedor por ID
  • POST /proveedores - Crear proveedor
  • PATCH /proveedores/{id} - Actualizar proveedor
  • DELETE /proveedores/{id} - Eliminar proveedor

Direcciones

  • GET /direcciones - Obtener lista de direcciones
  • GET /direcciones/{id} - Obtener dirección por ID
  • POST /direcciones - Crear dirección
  • PATCH /direcciones/{id} - Actualizar dirección
  • DELETE /direcciones/{id} - Eliminar dirección

Carrito

  • GET /carrito - Obtener información del carrito
  • POST /carrito/items - Agregar un producto al carrito
  • PUT /carrito/items/{itemId} - Actualizar la cantidad de un producto
  • DELETE /carrito/items/{itemId} - Eliminar un producto del carrito
  • DELETE /carrito - Vaciar el carrito completo

Pedidos

  • GET /pedidos - Obtener lista de pedidos
  • GET /pedidos/{id} - Obtener pedido por ID
  • POST /pedidos - Crear pedido
  • PATCH /pedidos/{id}/estado - Actualizar estado del pedido

Reseñas

  • GET /resenas - Obtener lista de reseñas con filtros opcionales.
  • GET /resenas/{id} - Obtener reseña por ID.
  • POST /resenas - Crear reseña.
  • PATCH /resenas/{id} - Actualizar parcialmente una reseña.
  • DELETE /resenas/{id} - Eliminar reseña.

Suscripciones

  • GET /suscripciones - Obtener suscripciones
  • POST /suscripciones - Crear suscripción
  • PATCH /suscripciones/{id} - Modificar suscripción
  • PUT /suscripciones/{id} - Modificar datos de suscripción
  • DELETE /suscripciones/{id} - Deshabilitar suscripción

Checkout

  • POST /checkout - Iniciar el proceso de compra (simulado).

Autenticación

  • POST /autenticacion/registro - Registrar un usuario (simulado).
  • POST /autenticacion/login - Iniciar sesión (simulado).

Despacho

  • GET (/shipping) - Obtener despachos
  • POST (/shipping) - crear nuevo despacho
  • PUT(/shipping/{id}) - Modificar totalmente despacho
  • PATCH (/shipping/{id}) - Modificar parcialmente despacho
  • DELETE (/shipping/{id}) - Eliminar despacho

Datos de facturación

  • POST /datos-facturacion - Ingresar datos de facturación (simulado).

Confirmación de compra

  • POST /confirmacion-compra - Generar una confirmación de compra simulada.

Tarjetas

  • POST /tarjetas - Simular el procesamiento de una tarjeta.

Favoritos

  • GET /favoritos - Obtener la lista de productos favoritos.
  • POST /favoritos/{productoId} - Agregar un producto a favoritos.
  • DELETE /favoritos/{productoId} - Eliminar un producto de favoritos.

Clone this wiki locally