Consulta el consumo y añade una recarga
Usa esta guía para añadir datos a una eSIM existente. Necesitas permiso para leer la eSIM y comprar un paquete, además de fondos suficientes en la cartera. La disponibilidad de recargas depende del perfil, los paquetes existentes y la oferta seleccionada.
1. Consulta los paquetes activos
Abre el perfil desde eSIMs y revisa Data packages. Con API, lista los paquetes de la eSIM y consulta su estado, vencimiento y saldo.
balance.total_bytes es la cantidad de datos comprada. Si used_bytes, remaining_bytes o used_percent es null, no hay medición disponible. Mantén esos valores como desconocidos en tu aplicación.
Lee el campo balance_reporting de la eSIM para decidir qué mostrar. Si es unavailable, muestra la cantidad comprada sin presentarla como datos restantes medidos. Si es available, el consumo puede seguir siendo desconocido hasta que llegue un informe. El historial de uso diario es independiente y no está disponible en este momento.
Usa balance.as_of para la hora de la última actualización de saldo; antes de que se informe el consumo, puede ser la hora de entrega del paquete. balance.observed_at es la hora de medición de la red cuando se proporciona. Muestra la marca de tiempo junto con el uso medido para que el cliente pueda reconocer un informe retrasado.
2. Listar ofertas compatibles
Selecciona Top up en la eSIM, o llama a Listar ofertas compatibles para ese perfil. Usa una oferta devuelta en lugar de elegir del catálogo general. Que la cobertura incluya el mismo país no garantiza compatibilidad.
Si no hay un top-up disponible, lee available_actions en la eSIM para conocer el motivo. Un pedido sin finalizar o el límite de paquetes puede impedir otra compra. Resuelve el pedido existente antes de volver a intentarlo. Actualiza las ofertas compatibles antes de enviar: una oferta puede dejar de estar disponible entre la selección y la compra.
Una eSIM en expired está inactiva y puede volver a active tras completar un top-up compatible. Comprueba la acción disponible y las ofertas compatibles antes de decidir que el perfil instalado necesita reemplazo.
3. Revisar las condiciones efectivas
Muestra la cantidad, cobertura, precio publicado con moneda y validez de la oferta seleccionada. Compara la validez del nuevo paquete con el límite de servicio active_until de la eSIM cuando esté presente. Si ese límite acortaría la validez comprada, el pedido devuelve 409 con la validez efectiva. Muestra el período más corto y obtén la aceptación antes de establecer acknowledge_shortened_validity: true.
Una recarga crea un paquete adicional. No modifica el saldo de un paquete existente ni extiende su fecha de vencimiento. Comprueba la activación y el vencimiento del nuevo paquete tras la entrega.
4. Aprobar y dar seguimiento al pedido
Confirma la compra en el panel. Con la API, crea un pedido usando el esim_id existente, el offer_id seleccionado, el revision de la oferta como offer_revision y su pricing.price como expected_price. Omite subscriber_id; un top-up conserva la asignación existente. Guarda el ID del pedido y un Idempotency-Key para reintentos.
Si el precio aceptado o la revisión cambiaron, obtén la oferta actual y confirma los nuevos términos antes de enviar otra compra. Copia el importe y la moneda devueltos sin conversión ni redondeo.
Da seguimiento al pedido en Orders, o consulta el pedido a través de API. Revisa status después de ambas respuestas 201 y 202. Si la respuesta se pierde, reintenta la misma solicitud con la misma clave; no crees una compra de reemplazo mientras el resultado sea incierto.
5. Verificar el paquete resultante
Cuando el pedido esté en completed, usa su package_id para obtener el nuevo paquete. Confirma que la eSIM de destino, la cobertura y la cantidad coinciden con la compra. El top-up usa el perfil instalado; no necesitas instalar una nueva eSIM. Un paquete pendiente de primer uso puede no tener aún marca de tiempo de activación ni de expiración.
Solución de problemas
Si el pedido está completo pero el saldo sigue siendo desconocido, compara el estado del paquete y las marcas de tiempo de los reportes. Los reportes pueden retrasarse respecto al consumo del dispositivo; hacer otro pedido no resuelve ese retraso. Si una compra falla, revisa los detalles del fallo y cualquier referencia de crédito antes de reintentar.
Próximos pasos
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.