Preguntas frecuentes

¿Se pueden vender tarjetas físicas?

No. La API pública vende únicamente eSIM.

¿Tengo que elegir proveedor o tipo de tarjeta?

No. La disponibilidad te devuelve directamente el plan eSIM más barato que cubre tu búsqueda, con un token; el prebooking necesita ese token y el número de eSIM que quieres.

¿El precio es por eSIM o por la venta?

La disponibilidad devuelve el precio de una eSIM: el pricePerDay (por día) y el totalPrice (toda la duración). El prebooking, donde eliges cuántas eSIM, devuelve el pricePerCard (una eSIM, el mismo totalPrice de la disponibilidad) y el totalPrice de la reserva (pricePerCard por cardsNumber), y la confirmación devuelve el totalPrice de la venta, siempre con impuestos, dos decimales y la currency (EUR). El importe de la venta es el del prebooking mientras el precio no cambie; si cambiara entre la disponibilidad y el prebooking, lo verás en el prebooking, antes de confirmar.

¿Puedo consultar la disponibilidad sin indicar fecha o duración?

No, startDate y days son obligatorios: la respuesta es siempre el precio de una duración concreta.

¿Puedo vender para el mismo día?

Sí: startDate puede ser hoy. Solo se rechazan las fechas pasadas.

¿Qué es el token de la disponibilidad y cuánto dura?

Es lo que recuerda tu búsqueda (plan, precio, países, fecha y duración) para que no tengas que repetirla en el prebooking. No caduca por sí mismo, pero el prebooking calcula siempre el precio y comprueba el plan en ese momento: si cambiaron los países, las fechas o la duración, repite la búsqueda y usa el token nuevo. Si el token no es uno devuelto por la disponibilidad, el prebooking responde 400 INVALID_TOKEN.

¿Cuánto dura una reserva (prebooking)?

No hay un plazo garantizado: confirma cuanto antes tras el prebooking. Si la confirmación falla porque las eSIM ya no están disponibles (409 CARDS_NUMBER_MISMATCH), repite el prebooking.

¿Qué pasa si la confirmación da un timeout?

Repite la llamada con el mismo prebookingId. Recibirás la misma respuesta y no se duplicará la venta.

¿Puedo volver a descargar el voucher?

Sí, cuando quieras: consulta el detalle de la reserva y abre su voucherUrl, con las mismas credenciales.

¿Cómo sé si una venta está cancelada o si la eSIM ya se activó?

Consulta el detalle de la reserva: el status de la venta es CONFIRMED o CANCELLED (con su cancellationDate), y cada eSIM de cards lleva su propio status: PENDING_ACTIVATION, ACTIVATED o CANCELLED.

¿Puedo abrir el voucherUrl en el navegador?

Sí. El navegador te pedirá tu usuario y secreto y descargará el PDF. Solo puedes descargar los vouchers de las ventas que hayas confirmado tú: el de cualquier otra venta responde 404.

¿Puedo cancelar una venta desde la API?

No. La API pública no cancela ventas: si hay que cancelar una, contacta con tu gestor de WelcomeSims. Cuando se cancele, el detalle de la reserva mostrará la venta como CANCELLED, con su cancellationDate.

¿Me avisáis cuando el viajero activa la eSIM o se cancela una venta?

No hay avisos automáticos (webhooks). Si necesitas conocer el estado, consulta el detalle de la reserva: hazlo cuando lo necesites, sin consultas continuas.

¿Puedo listar mis ventas?

No hay un endpoint para listarlas: guarda el locator que devuelve la confirmación, porque es lo que necesitas para consultar cada venta.

¿En qué zona horaria vienen las fechas con hora?

Con su zona horaria incluida, en formato RFC 3339: hoy en UTC, por lo que terminan en Z. Las fechas de cobertura (startDate, endDate) son días de calendario, sin hora.

¿Hay un límite de peticiones?

Todavía no hay un límite definido. Haz un uso razonable (por ejemplo, guarda en caché la lista de países) y te avisaremos si llega a aplicarse alguno.

¿Esta documentación es pública?

Sí. Lo que no es público son tus credenciales: no las compartas.

Algo no funciona, ¿a quién acudo?

Contacta con tu gestor de WelcomeSims indicando el entorno, el momento aproximado de la llamada, el code del error y, si la tienes, la referencia de tu venta (agencyReference). Nunca incluyas el secreto.