Intro
Bienvenido a la documentación de OrionStore, diseñada para contener todo lo relacionado a la API interna de la tienda.
La API controla todo lo relacionado a:
- Productos: Su creación, control, precio, stock, disponibilidad, entre otros.
- Ordenes: Rastreo de paquetes, impresión de etiquetas, control de pedidos.
- Usuarios: Control de roles (RBAC), cuentas de usuario.
Todos los endpoints están protegidos bajo OAuth o API KEY.
Requisitos
El proyecto está construido con Node.JS 24+ y Yarn 1.x.
Se necesita una instancia de MongoDB, se puede solicitar la creación de una instancia stage a Grapes. Los tests con Jester se realizan in-memory.
Una cuenta en Cloudinary para la subida de imagenes.
Configuración de entorno
Todas las variables de configuración se almacenan en un .env, las siguientes variables son necesarias:
# Cloudinary
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=
# Server
PORT=3000
NODE_ENV=development
Configuración de entorno - MongoDB
MongoDB tiene 2 formas de configurarse (ref):
Opción A
Usar una string de conexión completa:
MONGO_URI=mongodb://<user>:<encoded_password>@host:port
Si usas una URI completa, asegúrate de que el usuario y la contraseña estén codificados porcentualmente (percent encoding), especiamente si los valores tienen carácteres como @, /, #, %, ?, !, lo cuál es probable al ser el estándar de seguridad.
Si no están condificados correctamente, la conexión a Mongo fallará. Usa encodeURIComponent() si planeas usar esta opción.
Opción B Partir la URL por propiedades.
DB_USER=
DB_PASS= # Se puede usar la contraseña sin modificar
DB_HOST=
DB_PORT=
Esta es la opción recomendada, pues el sistema automáticamente codificará los valores. Está opción está garantizada a funcionar, pero puede traer problemas con URI's ambiguas.
Para el desarrolo local, puedes usar MongoDB Compass, crear una DB con MongoDB Atlas o usar una base de datos de stageging dada por Grapes.
Las pruebas usan Jest, ts-jest y supertest. Crean un MongoDB en memoria, por lo que están aisladas.
Instalación
La instalación es tan simple como clonar el repositorio usando Git:
git clone https://github.com/GrapesMaster98/oriapi.git
E instalar las dependencias en la carpeta raíz:
yarn install
Comandos de utilidad
Iniciar el servidor en modo dev:
yarn dev
Correr tests:
yarn tests
Buildear para producción e iniciar el servidor:
yarn build
yarn start
Es buena idea correr los tests de Jest al modificar la API, pues los tests crean una base de datos en memoria, simulan todo el CRUD y luego elimina la información, dejando logs de todo lo realizado.
Es importante saber que al proponer PR's, GH Actions correrá estos mismos tests y rechazará cambios que tengan problemas.
Endpoints - Resumen
POST /products
Crear producto (se permiten datos multipart/form-data)
GET /products
Listar productos (query: page, limite)
GET /products/ID
Obtén un producto en específico
PUT /products/ID
Reemplaza un producto (se permite multipart/form-data)
PATCH /products/ID
Actualización parcial (multipart/form-data)
DELETE /products/ID
Borra algún producto.
DELETE también borra las imagenes de Cloudinary, toma en cuenta eso al mandar solicitudes localmente o en producción.
Solicitudes de ejemplo
POST /products
curl -X POST "https://api.orionstore.local/products"
-F "name=Llavero Miku"
-F "price=19.99"
-F "stock=10"Troubleshooting tips
-F "isAvailable=true"
-F "readyToShip=true"
-F "image=@/path/to/image.jpg"
Respuesta si se crea el producto:
{
"name": "Llavero Miku",
"price": 19.99,
"stock": 10,
"isAvailable": true,
"readyToShip": true,
"imageUrl": "res.cloudinary.com/image-uploaded-to-cdn.jpg"
}
El controlador valida primero los campos que no son imágenes (los preprocesos de Zod permiten la conversión de string --> número/booleano para multipart).
Si la validación es correcta y hay un archivo de imagen, el servidor lo sube a Cloudinary y almacena imageUrl y imagePublicId en Mongo.
Si tienes problemas, abre un issue en GitHub.