Órdenes
Listar compras y gestionar una venta: marcar entregada, agregar tracking, reembolsar y calificar.
Listado y acciones sobre órdenes existentes. El comprador lista sus compras y califica tras recibir; el vendedor gestiona la entrega y el reembolso.
GET /market/orders
Compras del usuario autenticado en el marketplace (como comprador), de la más reciente a la más antigua. Sin cache: el estado (fulfilled, tracking) siempre se ve fresco.
Autenticación
Bearer Token. Rate limit: 30 req/min por usuario.
Request
curl "https://api.qvapay.com/market/orders?status=paid&page=1&take=20" \
-H "Authorization: Bearer <token>"Query params
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
status | paid | fulfilled | cancelled | refunded | No | Filtra por estado |
page | number (1-500) | No | Página (default 1) |
take | number (1-50) | No | Órdenes por página (default 20) |
Response
Proyección del comprador: no incluye el entregable digital (se sirve en el detalle de la compra) ni la economía del vendedor. product sale del snapshot de la compra si el producto original ya no existe.
{
"orders": [
{
"uuid": "o1r2d3...",
"status": "fulfilled",
"quantity": 2,
"unit_price": 19.99,
"subtotal": 39.98,
"gift_card_amount": 0,
"total": 39.98,
"tracking_code": "1Z999AA10123456784",
"note": null,
"delivered_at": "2026-06-08T13:00:00.000Z",
"created_at": "2026-06-08T12:00:00.000Z",
"product": { "uuid": "p1q2r3...", "slug": "camiseta-de-algodon", "title": "Camiseta de algodón", "main_image": "https://media.qvapay.com/...", "kind": "physical" },
"variant": { "options": { "Color": "Rojo", "Talla": "M" }, "sku": "CAM-R-M" },
"shop": { "name": "EcoFlow", "slug": "ecoflow", "logo": "https://media.qvapay.com/..." }
}
],
"total": 1,
"page": 1,
"take": 20
}gift_card_amount es la porción del total pagada con una gift card de la tienda; total es lo efectivamente debitado del saldo.
Errores
| Código | Descripción |
|---|---|
401 | No autenticado |
400 | Parámetros inválidos |
429 | Demasiadas solicitudes (rate limit) |
PATCH /market/orders/{uuid}
El vendedor marca la orden como entregada y/o agrega un código de tracking. Solo el dueño de la venta.
Autenticación
Bearer Token. Solo el vendedor de la orden.
Request
curl -X PATCH https://api.qvapay.com/market/orders/o1r2d3... \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "fulfill": true, "tracking_code": "1Z999AA10123456784" }'Parámetros (body)
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
fulfill | boolean | No | Si es true y la orden está paid, pasa a fulfilled y registra la fecha de entrega |
tracking_code | string (≤160) | null | No | Código de seguimiento |
Al marcar entregada, se notifica al comprador (Telegram, si está vinculado).
Response
{ "order": { "uuid": "o1r2d3...", "status": "fulfilled", "tracking_code": "1Z999AA10123456784", "delivered_at": "2026-06-08T13:00:00.000Z" } }Errores
| Código | Descripción |
|---|---|
404 | Orden no encontrada o no es del vendedor |
409 | La orden no admite cambios (cancelada o reembolsada) |
400 | Datos inválidos / nada que actualizar |
POST /market/orders/{uuid}/refund
Reembolsa una venta. Lo puede iniciar el vendedor dueño de la orden o un administrador. Revierte el dinero de forma atómica (comprador recupera el total, el vendedor devuelve su neto, la plataforma su comisión) y repone el inventario — en la variante comprada si la orden fue de una variante con stock finito, o en el producto en caso contrario.
Autenticación
Bearer Token. Vendedor dueño o admin/moderador. Sin body.
Request
curl -X POST https://api.qvapay.com/market/orders/o1r2d3.../refund \
-H "Authorization: Bearer <token>"Response
{ "order": { "uuid": "o1r2d3...", "status": "refunded" } }Se notifica al comprador (email + Telegram). Para productos digitales, el entregable deja de mostrarse tras el reembolso.
Errores
| Código | Descripción |
|---|---|
403 | No autorizado (no eres el vendedor ni admin) |
404 | Orden no encontrada |
409 | La orden ya fue reembolsada/cancelada o no admite reembolso |
500 | Error al procesar el reembolso |
POST /market/orders/{uuid}/rate
El comprador califica al vendedor tras recibir la compra. Solo una vez por orden, y solo si la orden está fulfilled.
Autenticación
Bearer Token. Solo el comprador de la orden.
Request
curl -X POST https://api.qvapay.com/market/orders/o1r2d3.../rate \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"rating": 5,
"comment": "Excelente, llegó rápido",
"tags": ["entrega_rapida", "producto_como_descrito"]
}'Parámetros (body)
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
rating | number (1-5) | Sí | Calificación |
comment | string (≤300) | No | Comentario |
tags | string[] | No | producto_como_descrito, entrega_rapida, buena_comunicacion |
Response 201
{ "success": true, "rating": { "rating": 5, "comment": "Excelente, llegó rápido" } }Errores
| Código | Descripción |
|---|---|
404 | Orden no encontrada o no eres el comprador |
409 | La compra no está entregada, o ya la calificaste |
400 | Datos inválidos |