Visión general

La API pública de WelcomeSims te permite vender eSIM de viaje desde tu propia plataforma: buscas el plan adecuado para el destino y las fechas del viaje, lo reservas, confirmas la venta, consultas su detalle y descargas el voucher con el QR que el viajero usa para activar la eSIM.

Qué cubre esta documentación

• Autenticación y entornos.
• Los cinco pasos del flujo de venta: países, disponibilidad, prebooking, confirmación y detalle de la reserva (con su voucher).
• Los errores que puedes recibir y cómo reaccionar.
• Las pruebas que recomendamos hacer antes de pasar a producción.

El flujo

 GET  /v1/countries            ──▶ id del país
 GET  /v1/availability         ──▶ plan eSIM más barato, su precio y un token
 POST /v1/prebooking           ──▶ prebookingId e importe (reserva las eSIM del token)
 POST /v1/booking              ──▶ locator e importe (confirma la venta)
 GET  /v1/sales/{locator}      ──▶ detalle de la venta: estado, eSIM, importes y voucherUrl (PDF con el QR)

Convenciones de los datos

Valen para todas las llamadas:

• Lo que no aplica no se envía. Un campo opcional sin valor no aparece en la respuesta: nunca llega como null. Cada guía indica qué campos vienen siempre y cuáles pueden faltar; programa tu cliente para tolerar la ausencia de los segundos, y para ignorar los campos que no conozca.
• Importes. Son texto con punto decimal y dos decimales ("32.89"), en euros (EUR) y con impuestos. Conviértelos a un tipo decimal exacto; no operes con ellos como números de coma flotante.
• Fechas. Los días (startDate, endDate) van como yyyy-MM-dd. Las fechas con hora (saleDate, activationDate…) llevan su zona horaria (RFC 3339, hoy UTC, terminadas en Z).
• Identificadores. Los id de país y de plan son enteros. El prebookingId es un UUID. El locator es un número que envías en la ruta y que las respuestas devuelven como texto.
• Codificación. JSON en UTF-8; las cabeceras de petición con cuerpo llevan Content-Type: application/json.

Cosas que conviene saber

• Solo eSIM. La API pública no vende tarjetas físicas.
• Un plan, un proveedor. No tienes que elegir proveedor ni tipo de tarjeta: al consultar la disponibilidad recibes directamente el plan más barato que cubre tu búsqueda.
• JSON y HTTPS. Las peticiones y respuestas son JSON (salvo el voucher, que es un PDF) y solo se admite HTTPS.
• Errores uniformes. Todos los errores tienen el mismo formato (application/problem+json) y un campo code estable que puedes usar en tu código. Consulta la referencia de errores.
• Reintentos seguros en la confirmación. Si la confirmación se corta por un timeout, puedes repetir la misma llamada con el mismo prebookingId: recibirás la misma respuesta sin duplicar la venta.