Tiendas

Gestión de las tiendas de un vendedor. Crear una tienda requiere cuenta habilitada como vendedor y KYC. La tienda nace en estado pending y debe ser aprobada por un administrador antes de ser pública.

POST /market/shopsCopy Anchor Link

Abre una nueva tienda. Queda en estado pending hasta su aprobación.

AutenticaciónCopy Anchor Link

Bearer Token. Requiere cuenta habilitada como vendedor + KYC. Rate limit: 3 req/min por usuario.

RequestCopy Anchor Link

curl -X POST https://api.qvapay.com/market/shops \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EcoFlow",
    "description": "Productos sostenibles",
    "country": "CU",
    "logo": "https://media.qvapay.com/market/<uuid>/logo-123.webp"
  }'

Parámetros (body)Copy Anchor Link

Response 201Copy Anchor Link

{
  "shop": {
    "uuid": "a1b2c3d4-...",
    "slug": "ecoflow",
    "name": "EcoFlow",
    "description": "Productos sostenibles",
    "logo": "https://media.qvapay.com/...",
    "banner": null,
    "country": "CU",
    "status": "pending",
    "sales_count": 0,
    "rating_avg": null,
    "created_at": "2026-06-08T12:00:00.000Z"
  }
}

ErroresCopy Anchor Link

GET /market/shopsCopy Anchor Link

Lista las tiendas del usuario autenticado.

AutenticaciónCopy Anchor Link

Bearer Token.

Query paramsCopy Anchor Link

ResponseCopy Anchor Link

{
  "shops": [ { "uuid": "...", "slug": "ecoflow", "name": "EcoFlow", "status": "active", "..." : "..." } ],
  "total": 1,
  "page": 1,
  "take": 20
}

GET /market/shops/{uuid}Copy Anchor Link

Detalle de una tienda propia.

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño.

ResponseCopy Anchor Link

{ "shop": { "uuid": "...", "slug": "ecoflow", "name": "EcoFlow", "status": "active", "..." : "..." } }

ErroresCopy Anchor Link

PATCH /market/shops/{uuid}Copy Anchor Link

Edita una tienda propia. No permite cambiar el status (eso es exclusivo de administración).

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño.

RequestCopy Anchor Link

curl -X PATCH https://api.qvapay.com/market/shops/a1b2c3d4-... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "EcoFlow Store", "description": "Nueva descripción" }'

Parámetros (body)Copy Anchor Link

Todos opcionales (al menos uno requerido): name (3-60), description (≤2000), country (ISO-2), category (slug de categoría o null), logo (URL o null), banner (URL o null), shipping (config de zonas de envío o null).

shipping — zonas de envío de la tienda (obligatorias para vender productos físicos; sin ellas el checkout responde SHIPPING_NOT_CONFIGURED). Shape: { "zones": [ { "id", "name", "country", "provinces", "price", "free_over", "eta_min_days", "eta_max_days" } ] } (1–40 zonas).

Al cobrar, gana la zona más específica que cubra la dirección (provincias sobre país completo; a igualdad, la más barata). Enviar shipping: null desconfigura los envíos (los físicos dejan de ser comprables).

curl -X PATCH https://api.qvapay.com/market/shops/a1b2c3d4-... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "shipping": { "zones": [ { "id": "zone-lha-1", "name": "La Habana", "country": "CU", "provinces": ["LHA"], "price": 5.00, "free_over": 50.00, "eta_min_days": 1, "eta_max_days": 3 } ] } }'

ResponseCopy Anchor Link

{ "shop": { "uuid": "...", "name": "EcoFlow Store", "..." : "..." } }

ErroresCopy Anchor Link

DELETE /market/shops/{uuid}Copy Anchor Link

Elimina una tienda propia (baja lógica). Desactiva todo el catálogo, la vitrina deja de ser pública y el slug se libera para reutilizarlo. Las órdenes existentes se conservan y los reembolsos siguen disponibles.

Bloqueado si hay ventas pagadas sin entregar: entrégalas o reembólsalas primero.

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño.

ResponseCopy Anchor Link

{ "success": true }

ErroresCopy Anchor Link