Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MateoNavarroMN/Balsamoa-Backend/llms.txt

Use this file to discover all available pages before exploring further.

The Balsamoa Backend exposes a versioned REST API under the /api/v1/ prefix. All endpoints fall into one of two audience scopes: admin routes (/api/v1/admin/…) intended for back-office management tools, and public store routes (/api/v1/tienda/…) designed for the customer-facing storefront. Admin routes expose full product data including raw stock counts, variant IDs, and the activo flag. Public store routes filter out inactive products and replace numeric stock with a human-readable availability label so that inventory details are never leaked to shoppers.

​
Base URL

All requests are relative to the server root. No additional base path configuration is required beyond the prefix already embedded in each route. 
/api/v1/

​
Content Type

All request and response bodies use application/json. The single exception is the image upload endpoint, which expects a multipart/form-data body containing a field named imagen. 
Content-Type: application/json          ← all other endpoints
Content-Type: multipart/form-data       ← POST /api/v1/admin/imagenes/subir

​
Error Format

Every error response — regardless of HTTP status code — returns a JSON object with at least a mensaje field describing what went wrong. Some errors also include a detalle field with the raw database error message for debugging purposes. 
{
  "mensaje": "El precio es obligatorio y debe ser un número positivo"
}

{
  "mensaje": "Error al obtener productos",
  "detalle": "relation \"vista_catalogo_productos\" does not exist"
}

​
Endpoint Groups

Products — Admin CRUD

Full create, read, update, and delete operations for products. Includes variant and image management within each request. All responses include raw stock counts and the full variant matrix.

Images — Upload & Delete

Upload a single image file to disk and receive its public URL, or delete an image by ID removing both the database record and the file from disk. Use the upload endpoint before creating or updating a product.

Catalog Lookups

Read-only endpoints for the reference tables used in product variants: GET /api/v1/admin/categorias, GET /api/v1/admin/talles, and GET /api/v1/admin/colores. Use the returned IDs when building create/update payloads.

Public Store

Read-only endpoints for the storefront. Only active products are returned. Stock counts are replaced with a plain-language availability label (Disponible, Últimas unidades, or Agotado). Supports an optional ?destacados=true query parameter.

​
Full Endpoint Index

MethodPathDescription
POST/api/v1/admin/imagenes/subirUpload an image file; returns its public URL
DELETE/api/v1/admin/imagenes/:idDelete an image by ID from disk and database
GET/api/v1/admin/productosList all products with full variant and stock data
GET/api/v1/admin/productos/:idGet a single product by ID
POST/api/v1/admin/productosCreate a product with images and variants
PUT/api/v1/admin/productos/:idUpdate a product’s fields, images, and variants
PATCH/api/v1/admin/productos/:id/activarSet activo = true (re-activate a product)
PATCH/api/v1/admin/productos/:id/desactivarSet activo = false (soft-delete a product)
DELETE/api/v1/admin/productos/:idPermanently delete a product and its image files
GET/api/v1/admin/categoriasList all product categories
GET/api/v1/admin/tallesList all available sizes
GET/api/v1/admin/coloresList all available colors with hex codes
GET/api/v1/tienda/productosPublic product catalog (active only, censored stock)
GET/api/v1/tienda/productos/:idPublic single product (active only, censored stock)

Build docs developers (and LLMs) love

Get started for freeTalk to us