Vitrina pública

Endpoints públicos del marketplace: índice de tiendas, detalle de una tienda, catálogo de productos y ficha de producto. Sin autenticación.

Superficie pública y de solo lectura del marketplace — la contraparte JSON de la web (/store) pensada para apps móviles e integraciones. Ningún endpoint de esta página requiere autenticación; todos limitan por IP (60 req/min) y solo exponen tiendas aprobadas (status: active) y productos activos.

Las respuestas se cachean brevemente (60–120s), por lo que precio y stock pueden tener hasta un minuto de desfase; el checkout siempre revalida contra datos frescos.

`GET /market/stores`

Índice de tiendas aprobadas, ordenadas por destacadas primero y luego por ventas. Cada tienda incluye su conteo de productos activos y hasta 4 imágenes de sus productos más vendidos (para pintar tarjetas con mosaico).

Request

curl https://api.qvapay.com/market/stores?category=fashion&page=1&take=20

Query params

Parámetro	Tipo	Requerido	Descripción
`category`	string	No	Filtra por categoría de la tienda. Slugs válidos: `electronics`, `fashion`, `home`, `beauty`, `food`, `sports`, `gaming`, `books`, `digital`, `services`, `other`
`page`	number (1-100)	No	Página (default 1)
`take`	number (1-50)	No	Tiendas por página (default 20)

Response

{
  "stores": [
    {
      "uuid": "a1b2c3d4-...",
      "slug": "ecoflow",
      "name": "EcoFlow",
      "description": "Productos sostenibles",
      "logo": "https://media.qvapay.com/...",
      "banner": null,
      "country": "CU",
      "category": "home",
      "socials": null,
      "accept_reviews": true,
      "returns_policy": null,
      "status": "active",
      "featured": false,
      "sales_count": 128,
      "rating_avg": 4.8,
      "created_at": "2026-06-08T12:00:00.000Z",
      "product_count": 42,
      "product_images": ["https://media.qvapay.com/...", "https://media.qvapay.com/..."]
    }
  ],
  "total": 1,
  "page": 1,
  "take": 20
}

Errores

Código	Descripción
`400`	Parámetros inválidos
`429`	Demasiadas solicitudes (rate limit)

`GET /market/stores/{slug}`

Detalle público de una tienda aprobada por su slug (el mismo de la URL /store/{slug}). Incluye el rating real del vendedor (promedio + cantidad de calificaciones) y los primeros 12 productos (los más recientes) embebidos, para pintar la pantalla en un solo request. El resto del catálogo se pagina con GET /market/catalog?shop={slug}.

Las tiendas pending, suspended o eliminadas responden 404 igual que las inexistentes — el estado de moderación no se filtra.

Request

curl https://api.qvapay.com/market/stores/ecoflow

Response

{
  "store": {
    "uuid": "a1b2c3d4-...",
    "slug": "ecoflow",
    "name": "EcoFlow",
    "description": "Productos sostenibles",
    "logo": "https://media.qvapay.com/...",
    "banner": null,
    "country": "CU",
    "category": "home",
    "socials": null,
    "accept_reviews": true,
    "returns_policy": null,
    "status": "active",
    "featured": false,
    "sales_count": 128,
    "rating_avg": 4.8,
    "rating_count": 37,
    "product_count": 42,
    "created_at": "2026-06-08T12:00:00.000Z"
  },
  "products": [
    {
      "uuid": "p1q2r3...",
      "slug": "camiseta-de-algodon",
      "title": "Camiseta de algodón",
      "description": "100% algodón orgánico",
      "main_image": "https://media.qvapay.com/...",
      "images": [],
      "kind": "physical",
      "price": 19.99,
      "currency": "USD",
      "stock": 50,
      "track_inventory": true,
      "active": true,
      "featured": false,
      "category": null,
      "sku": null,
      "option_axes": ["Color", "Talla"],
      "ship_to": null,
      "sales_count": 12,
      "created_at": "2026-06-08T12:00:00.000Z",
      "variants": [
        { "uuid": "v1a2...", "sku": "CAM-R-M", "options": { "Color": "Rojo", "Talla": "M" }, "price": 21.99, "stock": 10, "image": null, "sort": 0 }
      ],
      "variant_count": 1,
      "price_min": 21.99,
      "price_max": 21.99
    }
  ]
}

Errores

Código	Descripción
`404`	Tienda no encontrada (inexistente, pendiente, suspendida o eliminada)
`429`	Demasiadas solicitudes (rate limit)

`GET /market/catalog`

Catálogo público cross-tienda: productos comprables (con imagen y stock) de tiendas aprobadas, con búsqueda, filtros y orden. Con el filtro shop sirve como paginación del catálogo completo de una tienda (continuación de los 12 productos embebidos en el detalle).

Request

curl "https://api.qvapay.com/market/catalog?shop=ecoflow&sort=newest&page=2"

Query params

Parámetro	Tipo	Requerido	Descripción
`shop`	string (slug)	No	Solo productos de esa tienda
`q`	string (2-80)	No	Búsqueda por título
`category`	string	No	Categoría efectiva del producto (la del producto, o la de su tienda). Mismos slugs que en tiendas
`kind`	`physical` \| `digital` \| `service` \| `giftcard`	No	Tipo de producto
`country`	string (ISO-2)	No	Solo productos que envían a ese país
`min` / `max`	number	No	Rango de precio
`sort`	string	No	`relevance` (default), `newest`, `bestselling`, `price_asc`, `price_desc`
`page`	number (1-500)	No	Página (default 1)
`take`	number (1-48)	No	Items por página (default 24)

Con ?counts (sin más parámetros) responde en su lugar el conteo de productos elegibles por categoría: { "counts": { "fashion": 12, "home": 30 } } — útil para pills/facetas.

Response

Proyección compacta de tile — price_min/price_max resumen el rango de las variantes activas (igual al price si no hay variantes):

{
  "products": [
    {
      "uuid": "p1q2r3...",
      "slug": "camiseta-de-algodon",
      "title": "Camiseta de algodón",
      "main_image": "https://media.qvapay.com/...",
      "kind": "physical",
      "price": 19.99,
      "price_min": 19.99,
      "price_max": 21.99,
      "currency": "USD",
      "stock": 50,
      "track_inventory": true,
      "featured": false,
      "category": "fashion",
      "ship_to": null,
      "sales_count": 12,
      "variant_count": 2,
      "created_at": "2026-06-08T12:00:00.000Z",
      "shop": { "slug": "ecoflow", "name": "EcoFlow", "logo": "https://media.qvapay.com/...", "rating_avg": 4.8 }
    }
  ],
  "total": 42,
  "page": 2,
  "take": 24
}

Errores

Código	Descripción
`400`	Parámetros inválidos / rango de precio inválido (`min` > `max`)
`429`	Demasiadas solicitudes (rate limit)

`GET /market/products/{uuid}`

Ficha pública de un producto: el producto completo con sus variantes activas más los datos públicos de su tienda. Solo productos activos de tiendas aprobadas; cualquier otro caso responde 404.

El entregable de los productos digitales (digital_payload) nunca viaja por esta ruta — solo lo ve el vendedor y el comprador tras la compra.

Request

curl https://api.qvapay.com/market/products/p1q2r3...

Response

{
  "product": {
    "uuid": "p1q2r3...",
    "slug": "camiseta-de-algodon",
    "title": "Camiseta de algodón",
    "description": "100% algodón orgánico",
    "main_image": "https://media.qvapay.com/...",
    "images": [],
    "kind": "physical",
    "price": 19.99,
    "currency": "USD",
    "stock": 50,
    "track_inventory": true,
    "active": true,
    "featured": false,
    "category": null,
    "sku": null,
    "option_axes": ["Color", "Talla"],
    "ship_to": { "US": null, "CU": ["LHA", "MTZ"] },
    "sales_count": 12,
    "created_at": "2026-06-08T12:00:00.000Z",
    "variants": [
      { "uuid": "v1a2...", "sku": "CAM-R-M", "options": { "Color": "Rojo", "Talla": "M" }, "price": 21.99, "stock": 10, "image": null, "sort": 0 }
    ],
    "variant_count": 1,
    "price_min": 21.99,
    "price_max": 21.99
  },
  "shop": {
    "uuid": "a1b2c3d4-...",
    "slug": "ecoflow",
    "name": "EcoFlow",
    "logo": "https://media.qvapay.com/...",
    "country": "CU",
    "status": "active",
    "sales_count": 128,
    "rating_avg": 4.8,
    "created_at": "2026-06-08T12:00:00.000Z"
  }
}

Errores

Código	Descripción
`404`	Producto no encontrado (inexistente, inactivo, eliminado o de tienda no aprobada)
`429`	Demasiadas solicitudes (rate limit)

On this page