Introducción
Marketplace de vendedores de QvaPay. Crea tiendas, publica productos o servicios, vende y cobra dentro del saldo QvaPay.
El Marketplace permite que un usuario verificado abra su propia tienda, publique productos o servicios, gestione inventario, venda y reciba los pagos directamente en su saldo QvaPay. El comprador paga con su saldo y el vendedor recibe el neto al instante.
Conceptos
| Recurso | Descripción |
|---|---|
Tienda (shop) | La vitrina de un vendedor. Tiene slug público (/store/{slug}), logo, descripción y un status. Un usuario puede tener varias tiendas. |
Producto (product) | Un ítem listado por una tienda. kind puede ser physical, digital o service. Maneja precio, inventario, SKU, destinos de envío (ship_to) y, para digitales, un entregable. |
Variante (variant) | Una combinación de opciones de un producto (ej. Color: Rojo · Talla: M) con SKU, precio, stock e imagen propios. Hasta 3 ejes de opciones por producto. |
Orden (order) | Una venta concreta (de un producto o de una variante específica). Mueve el saldo (comprador → vendedor + comisión a la plataforma) de forma atómica. |
Quién puede vender
Crear y operar tiendas requiere:
- Cuenta habilitada como vendedor (rollout gradual; actualmente limitado a cuentas autorizadas).
- KYC completado.
Una tienda recién creada queda en estado pending y no es pública ni puede vender hasta que un administrador la aprueba (active). Comprar es abierto para cualquier usuario autenticado.
Modelo de comisión
El comprador paga el precio publicado, sin recargo. La comisión del marketplace se descuenta del payout del vendedor:
comprador paga: subtotal (precio × cantidad)
vendedor recibe: subtotal − comisión
plataforma: comisión (subtotal × tasa de la tienda)La comisión es variable por tienda (típicamente entre 3% y 5%). Cada tienda puede tener su propia tasa configurada por un administrador; si no, se aplica un default global (4%). Los vendedores Gold pagan 1% menos sobre la tasa de su tienda (mínimo 0%).
Ejemplo: tienda con 4% de comisión, venta de $100 → el comprador paga $100, el vendedor recibe $96 y la plataforma $4. Si el vendedor es Gold: recibe $97 y la plataforma $3.
Estados
Tienda (status): pending → active → suspended
Orden (status):
| Estado | Significado |
|---|---|
paid | Pagada. Físico/servicio: esperando gestión del vendedor. |
fulfilled | Entregada. Los productos digitales pasan a fulfilled automáticamente al comprar. |
refunded | Reembolsada (revierte el dinero y repone inventario). |
cancelled | Cancelada. |
Autenticación
Los endpoints de gestión (vender, comprar, órdenes) usan Bearer Token (header Authorization: Bearer <token>); el token se obtiene del login. La vitrina pública (índice de tiendas, detalle de tienda, catálogo y ficha de producto) no requiere autenticación.
URL base
https://api.qvapay.comEndpoints
| Recurso | Endpoints |
|---|---|
| Tiendas | Crear, listar, ver y editar tiendas |
| Productos | CRUD de productos e inventario |
| Vitrina pública | Índice de tiendas, detalle de tienda, catálogo y ficha de producto (sin auth) |
| Comprar | Crear una orden (compra) |
| Órdenes | Listar compras, entrega, tracking, reembolso y calificación |
| Imágenes | Subir logos e imágenes de producto |