Gestionar paquetes eSIM recurrentes

Usa una suscripción recurrente para comprar paquetes de datos en un calendario de facturación. Necesitas permiso para comprar servicio eSIM, fondos en la billetera de la organización y un suscriptor para la persona que usa la eSIM. La disponibilidad depende de la oferta y el perfil seleccionados.

Esta guía cubre compras nuevas e inscripción en una eSIM existente. La eSIM API no ofrece una operación para cambiar una suscripción activa a otro plan.

1. Revisa las condiciones recurrentes

Para una eSIM nueva, obtén las opciones de compra. Ofrece renovación automática cuando recurrence.available sea true y usa su quote para los términos aceptados. Si no está disponible, inspecciona unavailable_reason y ofrece una opción de compra compatible.

Para una eSIM existente, lista las ofertas compatibles con recurring_only=true y luego obtén los términos recurrentes de la oferta seleccionada. La inscripción vuelve a verificar la compatibilidad antes de aceptar la compra.

Muestra el precio recurrente, la moneda publicada, la cadencia y el modo de entrega antes de la aceptación. La cotización es antes de impuestos; el historial de períodos registra el total cobrado y el impuesto. calendar_month sigue meses calendario; fixed_days usa el número indicado de días de 24 horas. La billetera de la organización paga el servicio; el suscriptor no tiene una billetera separada.

Verifica si el paquete cubre el intervalo pagado (exact_period) o si cada renovación compra un paquete estándar (recurring_top_up). Con recargas recurrentes, la activación y la expiración siguen los términos del paquete y pueden diferir de los límites de facturación. No prometas datos ininterrumpidos solo porque la renovación está programada.

2. Asigna el suscriptor

En el panel, abre el perfil desde eSIMs, abre More eSIM actions, selecciona Assign person, elige el contacto y confirma Assign person. No puedes cambiar la persona asignada después.

Con la API, crea un suscriptor usando el contact_id de un contacto en tu espacio de trabajo. Esto requiere email_marketing:read para Contacts y esim:write. La respuesta devuelve el suscriptor existente cuando el contacto ya tiene uno.

Crear la asociación impide la eliminación del contacto, incluso después de que la eSIM finalice. Las asociaciones de suscriptor no pueden eliminarse, desvincularse ni anonimizarse actualmente. Decide si esa retención se ajusta a tu proceso de cliente antes de crear una.

Para un perfil existente, asigna la eSIM usando subscriber_id. Repetir la misma asignación devuelve el registro existente; asignar una persona diferente devuelve 409. Para un perfil nuevo, incluye subscriber_id en la compra para que la asignación se complete con la entrega.

La asignación no otorga acceso al espacio de trabajo ni permiso para leer credenciales de instalación. Gestiona la recopilación de identificación por separado usando los requisitos de la oferta y la guía de integración.

3. Inscribe y verifica la entrega

En una eSIM asignada existente en el panel, abre Automatic renewal y selecciona Set up renewal. Elige un Package, selecciona Check recurring price y revisa el precio, la cadencia y las condiciones de entrega del paquete. Selecciona Buy first package and renew para comprar el primer período y activar la renovación.

Para una eSIM nueva a través de API, crea un pedido con el offer_id seleccionado, el subscriber_id del espacio de trabajo y estas condiciones de compra aceptadas:

• Establece offer_revision en recurrence.quote.offer_revision.
• Establece recurrence.recurrence_revision en recurrence.quote.recurrence_revision.
• Establece recurrence.accepted_price en el objeto recurrence.quote.price completo.

Envía un Idempotency-Key; omite esim_id y expected_price para esta compra. Guarda el ID del pedido y su recurring_subscription_id. El primer período de facturación comienza cuando se fondea el pago. Sigue el pedido hasta que se complete o falle, usando los pasos de recuperación de compra si es necesario.

Para una eSIM asignada existente, crea una suscripción recurrente con esim_id, offer_id, el revision de la oferta como offer_revision, y el revision de las condiciones recurrentes como recurrence_revision. Envía el price completo de las condiciones recurrentes como accepted_price. Se requiere un Idempotency-Key; reutilízalo con la misma solicitud para recuperar la inscripción. La inscripción compra el primer período de inmediato; no espera a que un paquete existente se agote.

Obtén la suscripción y lista sus períodos. Confirma el pago y la entrega del paquete por separado. Para una eSIM nueva, entrega los datos de instalación después de que se complete su pedido.

4. Supervisa la renovación

Abre Subscriptions para revisar las condiciones aceptadas, el estado y la próxima renovación. En API, lee next_renewal_at, stop_reason y el historial de períodos. Un cambio en el precio publicado requiere nueva aceptación; una renovación sin fondos detiene las compras futuras.

Si status es needs_attention, revisa el último período y el pedido asociado. Una entrega no resuelta puede permanecer como pagadera y bloquea una nueva inscripción. Contacta a soporte con esas referencias antes de comprar un reemplazo.

5. Detén la renovación futura

En la sección Automatic renewal de la eSIM, selecciona Cancel renewal. Revisa la fecha de fin del período pagado actual y luego confirma Cancel renewal en el diálogo. Verifica la suscripción actualizada para consultar su fecha de cancelación.

Con API, cancela la suscripción y vuelve a leerla. Verifica cancel_at_period_end, cancellation_effective_at y next_renewal_at para confirmar cuándo termina la renovación. Un período ya comprometido sigue siendo pagadero. Los paquetes entregados conservan su propia validez y el perfil instalado se preserva.

Eliminar el perfil del teléfono no cancela la renovación. Liberar una eSIM la retira permanentemente, pierde los datos restantes y no genera reembolso. Usa las acciones de servicio cuando quieras modificar la conectividad además de la renovación.

Solución de problemas

Añadir fondos a la billetera no reinicia automáticamente una suscripción detenida. Comprueba stop_reason y el estado final del servicio anterior antes de aceptar una nueva inscripción. Una entrega pagada fallida y su crédito tienen resultados independientes: inspecciona order_status y refund_transaction_id en el historial de períodos.

Verifica el recorrido del cliente

Confirma que el cliente puede encontrar la cantidad de datos adquirida, la caducidad del paquete, la próxima renovación, la fecha de cancelación y el contacto de soporte. Verifica la entrega del primer paquete y prueba los datos móviles en un dispositivo compatible. Comprueba el pago y la entrega de un período posterior por separado respecto a su fecha de renovación programada.

Próximos pasos

• Consulta saldos y compra una recarga única.
• Prepara la instalación en el dispositivo.
• Investiga problemas de pago o entrega.