Vouchers / Gift Cards

Catálogo global de vouchers y gift cards. Listar países, marcas, ofertas y comprar.

Catálogo de vouchers y gift cards distribuido por país y marca. Es el flujo único para tarjetas de regalo (Amazon, Apple, Spotify, Steam, etc.) — los productos se descubren navegando por país y marca.

`GET /store/voucher-catalog`

Endpoint multimodo. El modo se determina por los query params presentes.

Autenticación

No requiere autenticación (endpoint público). Rate limit: 30 req/min por IP.

Modos

Modo	Query	Devuelve
Destacados	`?featured`	Top 12 marcas globales por cantidad de ofertas
Países	`?countries`	Lista de países con vouchers disponibles
Marcas	`?country=XX`	Marcas disponibles para un país (acepta `&q=...` para búsqueda)
Ofertas	`?country=XX&brand=Nombre`	Ofertas de una marca en un país

Modo destacados

curl -X GET "https://api.qvapay.com/store/voucher-catalog?featured"

{
  "featured": [
    {
      "brand": "Amazon",
      "slug": "amazon",
      "country": "US",
      "logo_url": "https://...",
      "offer_count": 12,
      "country_meta": { "name": "Estados Unidos", "flag": "🇺🇸" }
    }
  ]
}

Modo países

curl -X GET "https://api.qvapay.com/store/voucher-catalog?countries"

{
  "countries": [
    { "code": "US", "offer_count": 230, "name": "Estados Unidos", "flag": "🇺🇸" },
    { "code": "ES", "offer_count": 45, "name": "España", "flag": "🇪🇸" }
  ]
}

Modo marcas (por país)

curl -X GET "https://api.qvapay.com/store/voucher-catalog?country=US&q=amazon"

Parámetro	Tipo	Requerido	Descripción
`country`	string (ISO-2)	Sí	Código de país
`q`	string	No	Búsqueda parcial por nombre de marca

{
  "country": { "name": "Estados Unidos", "flag": "🇺🇸" },
  "brands": [
    {
      "brand": "Amazon",
      "slug": "amazon",
      "country": "US",
      "logo_url": "https://...",
      "bg_color": "#FF9900",
      "offer_count": 5,
      "sample_price": 10.00
    }
  ]
}

Modo ofertas

curl -X GET "https://api.qvapay.com/store/voucher-catalog?country=US&brand=Amazon"

Parámetro	Tipo	Requerido	Descripción
`country`	string (ISO-2)	Sí	Código de país
`brand`	string	Sí	Nombre de marca (URL-encoded)

{
  "country": { "name": "Estados Unidos", "flag": "🇺🇸" },
  "brand": "Amazon",
  "brand_logo_url": "https://...",
  "offers": [
    {
      "source": "global",
      "offer_id": "OFFER_ABC123",
      "name": "Amazon Gift Card $10",
      "notes": "Amazon Gift Card $10",
      "sent_benefits": "Código digital",
      "send": { "currency": "USD", "value": 10.00 },
      "sub_type": "DIGITAL",
      "price_type": "FIXED",
      "price": 10.50
    },
    {
      "source": "global",
      "offer_id": "OFFER_XYZ789",
      "name": "Amazon Gift Card (variable)",
      "notes": null,
      "sent_benefits": "Código digital",
      "sub_type": "DIGITAL",
      "price_type": "RANGE",
      "price_min": 5.00,
      "price_max": 500.00,
      "service_fee_pct": 5.0
    }
  ]
}

Notas

Para ofertas FIXED, el campo price ya incluye impuestos. No se expone base_price ni tax_pct.
Para ofertas RANGE, se expone service_fee_pct para que el cliente pueda calcular el total: total = amount + (amount * service_fee_pct / 100).
El offer_id es el identificador requerido por el endpoint de compra.
sent_benefits describe lo que el destinatario recibe (ej: "60 UC", "12,000 UC + 4,200 Free"). Puede ser null si la oferta no provee descripción específica.
send contiene el valor monetario que se entrega al destinatario ({ currency, value }). Útil cuando sent_benefits viene vacío y el voucher representa un monto fijo en USD/etc. — el cliente puede mostrar ese valor al usuario para transparencia.

`POST /store/voucher/purchase`

Compra un voucher. El monto total (base + impuesto) se descuenta del balance del usuario autenticado.

Autenticación

Bearer Token (header Authorization: Bearer <token>). Rate limit: 1 req/10s por usuario.

Request

curl -X POST https://api.qvapay.com/store/voucher/purchase \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "OFFER_ABC123",
    "country": "US",
    "brand": "Amazon",
    "amount": 25
  }'

Parámetros (body)

Parámetro	Tipo	Requerido	Descripción
`offer_id`	string	Sí	ID de la oferta obtenido del catálogo
`country`	string (ISO-2)	Sí	Código de país de la oferta
`brand`	string	Sí	Nombre de la marca
`amount`	integer	Condicional	Monto deseado en USD, entero (sin decimales). Requerido solo para ofertas con `price_type: "RANGE"`

Response

{
  "message": "Tarjeta solicitada",
  "transaction_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "buyedService_id": "123"
}

Recuperar el código del voucher

La compra queda en pending hasta que se procesa la entrega. Para obtener el código/PIN/URL de canje una vez procesada, consulta GET /store/my/{buyedService_id} usando el buyedService_id devuelto aquí — el código vive en data.service_data.receipt. Ver Mis Compras.

Notas

La compra valida la oferta contra el catálogo en vivo (el precio puede haber cambiado entre la consulta del catálogo y la compra).
El impuesto se aplica según el override de la oferta o el tax/tax_gold (si el usuario es golden) del service GIFT_CARD configurado para la marca.
La compra queda en estado pending hasta que se procesa la entrega.
Para ofertas RANGE, amount debe ser un entero (sin decimales) dentro del rango [price_min, price_max] retornado por el catálogo.

Errores

Código	Descripción
`400`	Request inválido (faltan campos o formato incorrecto)
`400`	`country` no coincide con la oferta
`400`	Categoría de oferta inválida (no es `VOUCHER`)
`400`	Precio de oferta inválido
`400`	`amount` requerido para ofertas `RANGE`
`400`	`amount` fuera del rango permitido o con decimales
`400`	Saldo insuficiente
`401`	No autorizado
`404`	Oferta no disponible o deshabilitada
`429`	Rate limit excedido
`500`	Error al procesar la compra

On this page