5. Detalle de la reserva

`GET /v1/sales/{locator}`

Devuelve todo lo que sabemos de una venta que confirmaste tú: su estado, el titular, cada eSIM con su propio estado, el desglose del precio y la dirección del voucher. Úsalo cuando quieras saber si una venta sigue confirmada, si el viajero ya activó su eSIM o cómo se compuso el importe.

Petición

curl -s -u "mi-usuario:mi-secreto" \
  "https://pre-api.welcomesims.com/public-api/v1/sales/11346498"

El locator es el que devolvió la confirmación.

Respuesta `200`

{
  "locator": "11346498",
  "status": "CONFIRMED",
  "agencyReference": "REF-0001",
  "saleDate": "2026-10-29T10:15:30Z",
  "startDate": "2026-12-01",
  "endDate": "2026-12-15",
  "planName": "Japón 15 días",
  "countryName": "Japón",
  "cardsNumber": 2,
  "holder": {
    "name": "Test",
    "surname": "Prueba",
    "documentType": "DNI",
    "documentNumber": "TEST0001",
    "email": "test@example.com",
    "phone": "+34000000000"
  },
  "cards": [
    { "icc": "8934071100123456789", "status": "PENDING_ACTIVATION" },
    { "icc": "8934071100123456790", "status": "ACTIVATED", "activationDate": "2026-12-01T08:30:00Z" }
  ],
  "price": {
    "currency": "EUR",
    "totalPrice": "65.78",
    "vatPercentage": "21.00",
    "vatAmount": "11.42"
  },
  "voucherUrl": "https://pre-api.welcomesims.com/public-api/v1/sales/11346498/voucher"
}

Campo	Presencia	Descripción
`locator`	Siempre	Localizador de la venta. Es un número que la respuesta devuelve como texto.
`status`	Siempre	Estado de la venta: `CONFIRMED` o `CANCELLED`.
`cancellationDate`	Solo si está cancelada	Fecha y hora de la cancelación.
`agencyReference`	Puede faltar	Tu referencia interna, la que enviaste en la confirmación. No aparece si no enviaste ninguna.
`saleDate`	Siempre	Fecha y hora en que se confirmó la venta.
`startDate`, `endDate`	Siempre	Primer y último día de cobertura (`yyyy-MM-dd`).
`planName`, `countryName`	Siempre	Plan y país de la venta.
`cardsNumber`	Siempre	Número de eSIM de la venta (entero).
`holder`	Siempre	El titular: los datos que enviaste en la confirmación (ver abajo).
`cards`	Siempre	Lista de las eSIM de la venta (ver abajo).
`price`	Siempre	El desglose del importe (ver abajo).
`voucherUrl`	Puede faltar	Dirección para descargar el voucher. No aparece si la venta no tiene voucher.

El holder lleva los datos de la confirmación:

Campo	Presencia	Descripción
`name`, `surname`	Siempre	Nombre y apellidos.
`documentType`, `documentNumber`	Siempre	Tipo y número del documento.
`email`	Puede faltar	Correo, si lo enviaste.
`phone`	Puede faltar	Teléfono, si lo enviaste. Llega con su prefijo ya incluido, por ejemplo `+34000000000`.

Cada elemento de cards lleva:

Campo	Presencia	Descripción
`icc`	Siempre	Número de serie de la eSIM.
`status`	Siempre	Su estado (ver abajo).
`activationDate`	Solo si está activada	Fecha y hora de la activación.
`cancellationDate`	Solo si está cancelada	Fecha y hora de la cancelación.

Estados

La venta puede estar:

`status`	Significado
`CONFIRMED`	La venta está confirmada y en vigor.
`CANCELLED`	La venta se ha cancelado. La fecha está en `cancellationDate`.

Cada eSIM de cards tiene su propio estado:

`status`	Significado
`PENDING_ACTIVATION`	Todavía no se ha activado.
`ACTIVATED`	El viajero ya la activó. La fecha está en `activationDate`.
`CANCELLED`	Se ha cancelado. La fecha está en `cancellationDate`.

Fechas y horas

saleDate, cancellationDate y activationDate llevan su zona horaria en formato RFC 3339. Hoy van en UTC, así que terminan en Z (2026-10-29T10:15:30Z): conviértelas a la hora de tu cliente al mostrarlas, y no las trates como hora local. startDate y endDate son días de calendario (yyyy-MM-dd) sin hora ni zona.

El desglose del precio

Los cuatro campos vienen siempre. Todos los importes van en euros (currency), como texto con dos decimales:

Campo	Descripción
`totalPrice`	Importe de la venta, con impuestos. Es el mismo que devolvió la confirmación.
`vatPercentage`, `vatAmount`	Porcentaje y cuantía del IVA.

El voucher

La voucherUrl descarga un PDF con los datos de la eSIM y el código QR que el viajero escanea para activarla. Requiere las mismas credenciales que el resto de llamadas:

curl -s -u "mi-usuario:mi-secreto" \
  -o voucher.pdf \
  "https://pre-api.welcomesims.com/public-api/v1/sales/11346498/voucher"

También puedes pegarla en el navegador: te pedirá tu usuario y secreto y descargará el PDF. La respuesta es una descarga (Content-Disposition: attachment; filename="voucher-<localizador>.pdf") y lleva Cache-Control: no-store: no la guardes en cachés compartidas, porque contiene datos de activación personales. Puedes volver a pedirla cuando quieras.

Errores

Estado	`code`	Significado
`404`	`SALE_NOT_FOUND`	La venta no existe o no es de tu cuenta. Es la misma respuesta en los dos casos.
`404`	`VOUCHER_NOT_AVAILABLE`	Al pedir la `voucherUrl`: la venta es tuya pero no tiene voucher.