eSIM de viaje
Consultar el catálogo de planes de datos eSIM por destino, comprar una eSIM y recuperar el QR/código de activación.
Planes de datos eSIM en más de 190 países, comprables con saldo QvaPay. El flujo completo es: catálogo → compra → polling del detalle → activación. La eSIM se entrega como un string LPA (el contenido del QR de instalación) junto a los datos de activación manual (dirección SM-DP+, código de activación e ICCID).
Los planes son de precio fijo (price_type: FIXED). El precio devuelto por el catálogo es el precio final a pagar — no hay fees ocultos al momento de la compra.
GET /store/esim-catalog
Catálogo navegable de planes eSIM. 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 |
|---|---|---|
| Destinos | ?countries | Lista de destinos con planes disponibles |
| Planes | ?country=XX | Planes de un destino, ordenados por precio |
Modo destinos
curl -X GET "https://api.qvapay.com/store/esim-catalog?countries"{
"countries": [
{ "code": "US", "offer_count": 24, "price_from": 4.5, "name": "Estados Unidos", "flag": "🇺🇸" },
{ "code": "ES", "offer_count": 18, "price_from": 3.9, "name": "España", "flag": "🇪🇸" },
{ "code": "XX", "offer_count": 40, "price_from": 9.0, "name": "Global / Regional", "flag": "🌐" }
]
}| Campo | Tipo | Descripción |
|---|---|---|
code | string | Código ISO-2 del destino. XX agrupa los planes regionales/globales (Europa, Latam, mundo) |
offer_count | number | Cantidad de planes disponibles |
price_from | number | null | Precio del plan más barato (USD) |
name / flag | string | Nombre y bandera para mostrar |
Modo planes (por destino)
curl -X GET "https://api.qvapay.com/store/esim-catalog?country=ES"{
"country": { "code": "ES", "name": "España", "flag": "🇪🇸" },
"offers": [
{
"offer_id": "ESIM-ES-5GB-30D",
"name": "5 GB · 30 días",
"sent_benefits": "5 GB · 30 días",
"region": "Europe",
"sub_type": "DATA",
"price_type": "FIXED",
"price": 8.5
}
]
}| Campo | Tipo | Descripción |
|---|---|---|
offer_id | string | ID del plan. Úsalo en POST /store/esim/purchase |
name | string | Título del plan (datos · duración · cobertura) |
region | string | null | Región de cobertura (en planes regionales) |
sub_type | string | Tipo de plan (DATA, etc.) |
price | number | Precio final a pagar (USD) |
POST /store/esim/purchase
Compra un plan eSIM. Debita el saldo inmediatamente y encola la emisión (asíncrona, normalmente menos de un minuto). Devuelve el buyedService_id con el que harás polling del detalle para recuperar el QR.
Autenticación
Dos opciones:
- Usuario: Bearer Token (header
Authorization: Bearer <token>). - App: headers
app-idyapp-secret. Con app auth, la compra se debita del saldo de la cuenta dueña de la app.
Rate limit: 1 req/10s por usuario.
Request
curl -X POST "https://api.qvapay.com/store/esim/purchase" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "offer_id": "ESIM-ES-5GB-30D", "country": "ES" }'Parámetros
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
offer_id | string | Sí | ID del plan (del catálogo) |
country | string | Sí | Código ISO-2 del destino del plan (usa XX para planes globales/regionales) |
Response
{
"message": "eSIM solicitada",
"transaction_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"buyedService_id": "456"
}Errores
| Código | Descripción |
|---|---|
400 | Body inválido, país no coincide con el plan, precio inválido o saldo insuficiente |
401 | Autenticación inválida o ausente |
403 | La cuenta no tiene permitido gastar saldo |
404 | Plan no disponible (deshabilitado o retirado del catálogo) |
429 | Rate limit excedido |
503 | eSIM temporalmente no disponible |
Si la emisión falla del lado del operador, la compra pasa a cancelled y el saldo se reembolsa automáticamente (verás una transacción de reembolso en la cuenta).
Recuperar el QR y los datos de activación
La entrega se recupera con GET /store/my/:id usando el buyedService_id de la compra. Haz polling (cada 10–15s) hasta que status sea paid; entonces service_data.esim trae los datos de activación:
curl -X GET "https://api.qvapay.com/store/my/456" \
-H "Authorization: Bearer <token>"{
"message": "Purchase details",
"data": {
"id": "456",
"status": "paid",
"amount": 8.5,
"service": { "name": "eSIM · 5 GB · 30 días", "logo": null },
"transaction": { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" },
"service_data": {
"brand": "",
"country": "ES",
"plan": "5 GB · 30 días",
"receipt": { "voucherId": "", "voucher": "", "confirmationNumber": "", "redemptionUrl": "", "epin": "" },
"esim": {
"iccid": "8944500000000000000",
"activationCode": "K2-1ABCDE-2FGHIJ",
"confirmationCode": "0000",
"smdpAddress": "rsp.example.com",
"lpa": "LPA:1$rsp.example.com$K2-1ABCDE-2FGHIJ",
"instructions": "Install before arrival. Enable data roaming on the eSIM line."
}
}
}
}Objeto esim
| Campo | Tipo | Descripción |
|---|---|---|
lpa | string | Contenido del QR de instalación (formato estándar LPA:1$<smdp>$<matchingId>). Genera un código QR con este string tal cual y el teléfono lo instala al escanearlo |
smdpAddress | string | Dirección SM-DP+ para activación manual |
activationCode | string | Código de activación (matching ID) para activación manual — es el mismo valor que va dentro del lpa |
confirmationCode | string | Código de confirmación del carrier (p. ej. 0000). Solo hay que introducirlo si el teléfono lo pide durante la instalación; vacío cuando no aplica |
iccid | string | ICCID de la eSIM emitida (identificador; útil para soporte) |
instructions | string | Instrucciones adicionales del plan (cuando aplica) |
La mayoría de las eSIM solo pueden instalarse una vez. Muestra el QR/códigos únicamente al comprador y adviértele que no borre la eSIM del teléfono si piensa seguir usándola. Mientras status sea pending o processing, el objeto esim viene con campos vacíos.