Productos

Gestión del catálogo de una tienda. Soporta tres tipos (kind): physical (físico, con envío), digital (entrega un payload al comprar) y service. El inventario es opcional por producto.

POST /market/productsCopy Anchor Link

Crea un producto en una tienda propia. La tienda puede estar pending; el catálogo se puede preparar antes de la aprobación.

AutenticaciónCopy Anchor Link

Bearer Token. La tienda (shop_uuid) debe pertenecer al usuario.

RequestCopy Anchor Link

curl -X POST https://api.qvapay.com/market/products \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_uuid": "a1b2c3d4-...",
    "title": "Camiseta de algodón",
    "description": "100% algodón orgánico",
    "kind": "physical",
    "price": 19.99,
    "stock": 50,
    "track_inventory": true,
    "main_image": "https://media.qvapay.com/market/<uuid>/product-1.webp"
  }'

Parámetros (body)Copy Anchor Link

Formato de ship_to — objeto cuyas claves son países ISO-2 y cuyos valores son null (todo el país) o un array de códigos de provincia/estado:

{ "US": null, "CU": ["LHA", "MTZ"] }

Solo los países con datos de subdivisiones (por ahora US — estados USPS — y CU — 16 provincias con códigos de 3 letras: PRI, ART, LHA, MAY, MTZ, CFG, VCL, SSP, CAV, CMG, LTU, HOL, GRA, SCU, GTM, IJV) aceptan restricción por provincia; el resto solo admite null (todo el país). El checkout rechaza compras cuya dirección de envío quede fuera de estos destinos.

Response 201Copy Anchor Link

Proyección del dueño (incluye digital_payload):

{
  "product": {
    "uuid": "p1q2r3...",
    "slug": "camiseta-de-algodon",
    "title": "Camiseta de algodón",
    "kind": "physical",
    "price": 19.99,
    "currency": "USD",
    "stock": 50,
    "track_inventory": true,
    "active": true,
    "featured": false,
    "sales_count": 0,
    "created_at": "2026-06-08T12:00:00.000Z"
  }
}

ErroresCopy Anchor Link

GET /market/products/{uuid}/variantsCopy Anchor Link

Ejes de opciones y variantes de un producto propio (incluye inactivas).

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño (vía la tienda).

ResponseCopy Anchor Link

{
  "option_axes": ["Color", "Talla"],
  "variants": [
    { "uuid": "v1a2...", "sku": "CAM-R-M", "options": { "Color": "Rojo", "Talla": "M" }, "price": 21.99, "price_override": 21.99, "stock": 10, "image": null, "sort": 0, "active": true },
    { "uuid": "v3b4...", "sku": "CAM-R-L", "options": { "Color": "Rojo", "Talla": "L" }, "price": 19.99, "price_override": null, "stock": null, "image": null, "sort": 1, "active": true }
  ]
}

price es siempre el precio efectivo (el de la variante, o el del producto si no define uno); price_override distingue si la variante tiene precio propio (null = hereda).

PUT /market/products/{uuid}/variantsCopy Anchor Link

Sincroniza el set completo de variantes con el estado enviado: las filas con uuid se actualizan, las filas sin uuid se crean, y las variantes existentes que no aparezcan en el payload se eliminan. Idempotente — pensado para guardar la matriz completa del editor de una vez.

{ "option_axes": [], "variants": [] } elimina todas las variantes del producto.

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño.

RequestCopy Anchor Link

curl -X PUT https://api.qvapay.com/market/products/p1q2r3.../variants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "option_axes": ["Color", "Talla"],
    "variants": [
      { "options": { "Color": "Rojo", "Talla": "M" }, "sku": "CAM-R-M", "price": 21.99, "stock": 10 },
      { "options": { "Color": "Rojo", "Talla": "L" }, "sku": "CAM-R-L", "price": null, "stock": null }
    ]
  }'

Parámetros (body)Copy Anchor Link

El stock de la variante se descuenta atómicamente en cada compra (track_inventory del producto debe estar activo) y se repone en reembolsos.

ErroresCopy Anchor Link

POST /market/products/bulkCopy Anchor Link

Alta masiva de productos en una tienda propia, pensada para cargar un catálogo completo de una vez (importación desde CSV/Excel). Cada fila se valida y se crea de forma independiente: un error en una fila no detiene el resto. La tienda puede estar pending.

AutenticaciónCopy Anchor Link

Bearer Token. La tienda (shop_uuid) debe pertenecer al usuario. Rate limit más estricto que el alta unitaria (token bucket: 1 cada 60s, ráfaga de 2).

RequestCopy Anchor Link

curl -X POST https://api.qvapay.com/market/products/bulk \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_uuid": "a1b2c3d4-...",
    "products": [
      { "title": "Camiseta de algodón", "kind": "physical", "price": 19.99, "stock": 50, "image_url": "https://ejemplo.com/camiseta.jpg" },
      { "title": "Curso de diseño", "kind": "digital", "price": 9.99, "digital_payload": "https://drive.example.com/curso" }
    ]
  }'

Parámetros (body)Copy Anchor Link

Cada fila de products acepta los mismos campos que POST /market/products (sin shop_uuid), con coerción tolerante de tipos (números y booleanos pueden venir como texto, p. ej. "true", "50"). En lugar de main_image, usa:

Response 201Copy Anchor Link

Resumen agregado más el detalle por fila. index es la posición (base 0) dentro del array enviado.

{
  "created": 1,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "product": { "uuid": "p1q2r3...", "slug": "camiseta-de-algodon", "title": "Camiseta de algodón", "price": 19.99 },
      "warning": "No se pudo descargar la imagen"
    },
    { "index": 1, "ok": false, "error": "price: Precio inválido" }
  ]
}

ErroresCopy Anchor Link

GET /market/products?shop={uuid}Copy Anchor Link

Lista los productos de una tienda propia (incluye inactivos; oculta los eliminados).

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño de la tienda.

Query paramsCopy Anchor Link

ResponseCopy Anchor Link

{ "products": [ { "uuid": "...", "title": "...", "price": 19.99, "stock": 50, "active": true } ], "total": 1, "page": 1, "take": 50 }

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

Edita un producto propio. El kind es inmutable.

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño (vía la tienda).

Parámetros (body)Copy Anchor Link

Todos opcionales: title (3-300), description (≤5000), price (>0), currency, stock (≥0 o null), track_inventory, digital_payload, main_image, images, category, sku, ship_to, active, featured. Si track_inventory se pone en false, el stock pasa a null (ilimitado). Los ejes de opciones (option_axes) no se editan aquí: usa PUT /market/products/{uuid}/variants.

ResponseCopy Anchor Link

{ "product": { "uuid": "...", "title": "...", "..." : "..." } }

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

Baja lógica del producto (soft delete). Deja de aparecer en la tienda.

AutenticaciónCopy Anchor Link

Bearer Token. Solo el dueño.

ResponseCopy Anchor Link

{ "success": true }

ErroresCopy Anchor Link