Paquetes de Teléfono

`GET /store/phone_package`

Retorna la lista de paquetes de teléfono activos disponibles para compra (datos, minutos, etc.).

Autenticación

No requiere autenticación (endpoint público).

Request

curl -X GET https://api.qvapay.com/store/phone_package

Response

{
  "phone_packages": [
    {
      "id": 1,
      "name": "Paquete 1GB + 20 min",
      "logo": "https://example.com/package.png",
      "details": [
        { "label": "Datos", "value": "1 GB" },
        { "label": "Minutos", "value": "20" }
      ],
      "price": 5.00,
      "gold_price": 4.50,
      "external": true,
      "external_amount": 100,
      "period": "30 días"
    }
  ]
}

Campos de respuesta

Campo	Tipo	Descripción
`id`	number	Identificador del paquete
`name`	string	Nombre del paquete
`logo`	string	URL del logo del paquete
`details`	array	Detalles del paquete (datos, minutos, SMS, etc.)
`price`	number	Precio regular en USD
`gold_price`	number	Precio para usuarios GOLD en USD
`external`	boolean	Indica si es un paquete externo
`external_amount`	number	Monto externo asociado
`period`	string	Período de validez del paquete

Errores

Código	Descripción
`429`	Demasiadas solicitudes
`500`	Error al obtener los paquetes

`POST /store/phone_package`

Compra un paquete de teléfono para un número cubano. El monto se descuenta del balance del usuario.

Autenticación

Bearer Token (header Authorization: Bearer <token>).

Request

curl -X POST https://api.qvapay.com/store/phone_package \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_package_id": 1,
    "phone_number": "+5350001234",
    "recipient_name": "María Pérez González"
  }'

Parámetros (body)

Parámetro	Tipo	Requerido	Descripción
`phone_package_id`	number	Sí	ID del paquete de teléfono a comprar
`phone_number`	string	Sí	Número de teléfono cubano del destinatario
`recipient_name`	string	Condicional	Nombre y apellidos de quien recibe la recarga. Obligatorio si el comprador es US person (ficha CIP); opcional para el resto. Mínimo nombre y un apellido, solo letras

Response

{
  "message": "Paquete de teléfono comprado correctamente",
  "transaction_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "buyedService": "123"
}

Recuperar el detalle de la compra

El paquete queda en pending hasta que se procesa la entrega. Para consultar su estado y los datos de entrega, usa GET /store/my/{buyedService} con el buyedService devuelto aquí. Ver Mis Compras.

Comisión

El precio varía según el tipo de usuario:

Usuarios regulares: se cobra el campo price del paquete.
Usuarios GOLD: se cobra el campo gold_price (precio reducido).

Rate Limiting

1 request cada 10 segundos por usuario.

Errores

Código	Descripción
`400`	Faltan `phone_package_id` o `phone_number`
`400`	Falta o es inválido `recipient_name` cuando el comprador es US person (`code: "RECIPIENT_NAME_REQUIRED"`)
`400`	El número de teléfono no es válido
`400`	Saldo insuficiente
`401`	No autorizado
`404`	El paquete no existe o no está activo
`429`	Demasiadas solicitudes
`500`	Error al crear la transacción

On this page