Integra la API de eSIM

Usa la API de eSIM para comprar paquetes de datos y entregar los detalles de instalación desde tu aplicación. Necesitas un espacio de trabajo, una clave API y fondos en la billetera de la organización para compras en producción. Sigue la autenticación y usa la región API correspondiente a tu clave.

Asigna a la clave esim:read para inspeccionar ofertas y recursos, y esim:write para comprar o gestionar el servicio. Las credenciales de instalación tienen permisos separados: esim_credentials:read para consultarlas y esim_credentials:write para crear o enviar enlaces de instalación. Mantén la clave API en tu aplicación de servidor.

1. Elige una oferta

Lista las ofertas para el destino y luego consulta la oferta seleccionada. Revisa zone.countries, la capacidad y validez en pricing, las condiciones de velocidad y cualquier servicio telefónico incluido. Para una eSIM existente, usa Listar ofertas compatibles; la disponibilidad en el catálogo general no garantiza compatibilidad para recarga.

Consulta los requisitos de identificación de la oferta antes de recopilar información del suscriptor. La respuesta contiene un esquema JSON por cada país de cobertura, que exige nombre, apellido y correo electrónico, además de los campos adicionales que apliquen. Activa la validación de formato de correo electrónico y fecha. Tú recopilas y validas esta información; la API de eSIM no recibe ni verifica las respuestas, y una validación exitosa no autoriza una compra.

Para una eSIM nueva, consulta las opciones de pago. Muestra el precio único devuelto o la cotización recurrente disponible antes de aceptar la compra. Los precios de pago son antes de impuestos. La renovación tiene su propio precio y cadencia; sigue paquetes recurrentes cuando el cliente la elija.

Para el ejemplo de compra única a continuación, instala curl y jq. Establece BIRD_API_URL con tu URL base regional, BIRD_API_KEY con tu clave y ESIM_OFFER_ID con el ID de la oferta seleccionada:

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Revisa el precio y las condiciones de la oferta antes de continuar. La cotización no reserva disponibilidad.

2. Crea la compra

Crea una orden con offer_id. Omite esim_id para un perfil nuevo; inclúyelo para una recarga. Para una compra única, envía offer_revision y expected_price de la cotización aceptada. Estos campos rechazan condiciones modificadas con 409 antes de cobrar; consulta y revisa una cotización nueva antes de aceptar un precio modificado.

Establece ESIM_ORDER_KEY con un valor único para esta compra y guárdalo junto con la solicitud. Este ejemplo compra una eSIM nueva, sin asignar, y copia el precio publicado sin modificar su monto ni su moneda:

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Para asignar un perfil nuevo cuando la entrega se complete, incluye un subscriber_id de espacio de trabajo; sigue la configuración de suscriptor. Una recarga conserva la asignación existente, así que omite subscriber_id cuando envíes esim_id. Envía los detalles de instalación por separado después de la entrega.

Guarda el ID de orden devuelto. Inspecciona status incluso después de HTTP 201, que puede contener una orden completada o fallida. HTTP 202 significa que el procesamiento continúa. Consulta la orden hasta que sea completed o failed. Una orden completada identifica esim_id y package_id; la instalación en el dispositivo sigue siendo un paso separado.

3. Proporciona los datos de instalación

Después de la compra, lee las credenciales de instalación, crea un enlace de instalación alojado o envía un enlace por correo electrónico o SMS. Mantén los detalles de activación y los enlaces de instalación fuera de analíticas y registros públicos.

Para un enlace enviado, guarda el ID de entrega y consulta el historial de entrega. Una respuesta 202 confirma la aceptación para el envío; delivered confirma la entrega del mensaje, y la instalación en el dispositivo requiere su propia comprobación. Sigue la guía de instalación para métodos compatibles, expiración del enlace y recuperación.

4. Recupera una compra interrumpida

Si la respuesta de creación se perdió o devolvió 503, repite la solicitud guardada con su Idempotency-Key original; consulta solicitudes idempotentes. Si tienes el ID de la orden, lee esa orden primero. Crear otra compra mientras el resultado es incierto puede provocar otro cargo.

Para una orden en charging, inspecciona funding y el saldo de tu billetera. funding.required_amount es el saldo total necesario, impuestos incluidos; compáralo con los fondos existentes antes de añadir dinero. Las órdenes de pago único reintentan la financiación automáticamente. Si una compra recurrente inicial es rechazada por fondos insuficientes, añade fondos y reintenta explícitamente la misma solicitud de creación con su clave original.

Comprueba el estado actual de la orden incluso después de funding.lapses_at: esa marca de tiempo no garantiza la cancelación. Una orden aún puede completarse si recibe fondos antes de que un intento posterior por fondos insuficientes la haga fallar.

Para detener una compra no financiada no deseada, cancela la orden. Una cancelación exitosa sin financiación devuelve status: failed y failure_code: canceled. Una orden de pago único ya financiada devuelve 409 y continúa. En una compra recurrente inicial, un pago recuperado durante la cancelación puede dejar la compra pagada en curso mientras la renovación futura se detiene. Inspecciona la orden y la suscripción devueltas antes de informar una cancelación o un reembolso.

Para una compra fallida, inspecciona failure_code y failure_reason. Cualquier cargo se acredita automáticamente; refund_transaction_id identifica un crédito emitido. Conserva el ID de la orden para soporte si el pago, la entrega o el crédito queda sin resolver.

5. Muestra saldos y estado del servicio

Obtén la eSIM para consultar el estado, el estado de instalación, los paquetes y available_actions. Muestra la cantidad de datos, el consumo y la fecha y hora de la medición del paquete usando la guía de uso. El consumo desconocido debe permanecer como desconocido en tu aplicación.

Vuelve a comprobar la disponibilidad de la acción cuando el cliente actúe; la operación verifica permisos y estado de nuevo. Usa la guía de operaciones para investigar compras incompletas, problemas de instalación o fallos de conectividad.

Próximos pasos

• Elige un paquete de viaje.
• Prepara la instalación en el dispositivo.
• Gestiona paquetes recurrentes.