POST/v1/flights/order/:gdsprovider/:offerId

Crear orden de vuelo

Crea una reserva instantánea o una orden en hold desde una oferta seleccionada. Las reservas públicas resuelven el precio interno desde offerId o desde la oferta trackeada.

Endpoint

Método	Ruta	Auth
`POST`	`/v1/flights/order/:gdsprovider/:offerId`	API key requerida

Headers obligatorios:

Header	Descripción
`Authorization`	`Bearer <secret_key>`. The secret is shown only once when the credential is created.
`X-Travelandz-Id`	`<public_key>:<profile_code>`. The `profile_code` is the `dp_`-prefixed Developer Profile code shown in your dashboard. This binds the request to a profile and credential.
`Content-Type`	Use `application/json` for requests with a body.

Esquema de parámetros de la petición

Propiedad	Tipo	Detalles	Requerido	Notas
`gdsprovider`	`number`		Sí	-
`offerId`	`string`		Sí	-

Esquema del cuerpo de la petición

Propiedad	Tipo	Detalles	Requerido	Notas
`currency`	`enum`	`EURUSDCNY`	Sí	Moneda solicitada para la reserva publica. El precio interno se resuelve por offerId o por los datos de la oferta trackeada
`passengers`	`array`		Sí	-
`passengers[]id`	`string`		Sí	Id de pasajero de la oferta seleccionada. Para gdsprovider=1, reutiliza el valor vacio si la oferta envia un id vacio
`passengers[]type`	`enum`	`adultchildinfant_without_seat`	Sí	-
`passengers[]title`	`enum`	`mrmsmrsmiss`	Sí	-
`passengers[]phone_number`	`string`	`Format: E.164 phone number`	Sí	Satisface `passengers[].phone`. En flujos gdsprovider=1, `passengers[0].phone_number` tambien satisface `holder.phone` y deriva `holder.countryCode`
`passengers[]infant_passenger_id`	`string`		No	Requerido cuando el pasajero esta asociado a un infante
`passengers[]identity_documents`	`array`		No	Objetos de documento de identidad. Ejemplo: `[{ type, unique_identifier, issuing_country_code, expires_on }]`. Requeridos cuando la oferta o required-fields los solicite
`passengers[]firstName`	`string`		Sí	Satisface `passengers[].name` desde required-fields
`passengers[]lastName`	`string`		Sí	Satisface `passengers[].lastName` desde required-fields
`passengers[]gender`	`enum`	`mf`	Sí	-
`passengers[]email`	`string`		Sí	Satisface `passengers[].email`. Algunos flujos gdsprovider=1 solo consumen el email del primer pasajero como email principal del titular
`passengers[]bornDate`	`string`	`Format: YYYY-MM-DD`	Sí	-
`passengers[]country`	`string`		No	Codigo de pais ISO de 2 letras. Usalo cuando required-fields marque `nationality` como true
`passengers[]NationalID`	`string`		No	Usalo cuando el flujo seleccionado requiera numero de identidad nacional. En respuestas actuales de gdsprovider=1 puede estar implicito si `allowedDocuments` incluye `dni`, incluso sin un flag explicito `nationalId`
`passengers[]loyaltyProgrammeAccounts`	`array`		No	Objetos opcionales de cuenta de fidelidad. Ejemplo: `[{ airlineIataCode, accountNumber }]`. Usalos solo cuando supportedLoyaltyPrograms incluya el codigo de aerolinea

`totalSegments`	`array`		Sí	-
`totalSegments[]originCode`	`string`		Sí	Mapped from offer.slices[].segments[].departure.iataCode
`totalSegments[]destinationCode`	`string`		Sí	Mapped from offer.slices[].segments[].arrival.iataCode
`totalSegments[]flightNumber`	`string`		Sí	Mapped from offer.slices[].segments[].flightNumber
`totalSegments[]departureDate`	`string`	`Format: ISO 8601`	Sí	Mapped from offer.slices[].segments[].departure.departingAt

`holdId`	`string`		No	Solo para proveedores que soportan pago en hold
`type`	`enum`	`instanthold`	No	Por defecto es instant. hold solo aplica cuando el proveedor seleccionado lo soporta

Respuesta exitosa

Devuelve order identifiers, status and provider booking payload.

Esquema del cuerpo de la respuesta

Propiedad	Tipo	Detalles	Requerido	Notas
`orderId`	`string`		Sí	-
`holdExpiresAt`	`string`	`Format: ISO 8601`	No	-
`holdPriceGuaranteed`	`string`		No	-

Notas operativas

passengers[].id es el id del pasajero de la oferta seleccionada, no un identificador interno de usuario.
No envies identificadores internos de usuario; no forman parte del contrato publico de reserva.
No envies originalPrice en reservas publicas. La API resuelve precio y moneda internos desde offerId o desde la oferta trackeada. Si se envia originalPrice, la validacion publica rechaza la peticion por ser un campo no permitido.
Envia identity_documents[] cuando la oferta o el endpoint required-fields indiquen que se requieren documentos de identidad.
type=hold y holdId solo aplican cuando el flujo seleccionado soporta pago en hold. Las reservas publicas en hold requieren una oferta trackeada para el mismo profile, gdsprovider y offerId; sin ella la API devuelve Tracked flight offer is required to complete this public booking.
totalSegments[] solo es requerido cuando el flujo seleccionado necesita metadata de segmentos. Construyelo desde cada item de offer.slices[].segments[].

Mapeo de required-fields a create-order

Respuesta de required-fields	Campo de create-order	Notas
`passengers[].title`	`passengers[].title`	Coincidencia directa
`passengers[].type`	`passengers[].type`	Coincidencia directa
`passengers[].name`	`passengers[].firstName`	Renombrado en el body de reserva
`passengers[].lastName`	`passengers[].lastName`	Coincidencia directa
`passengers[].gender`	`passengers[].gender`	Coincidencia directa
`passengers[].bornDate`	`passengers[].bornDate`	Coincidencia directa
`passengers[].nationality`	`passengers[].country`	Usa codigo de pais ISO de 2 letras
`passengers[].phone`	`passengers[].phone_number`	Formato E.164
`passengers[].email`	`passengers[].email`	En flujos gdsprovider=1, solo el email del primer pasajero puede consumirse como email del titular
`passengers[].documentIdentifier`	`passengers[].identity_documents[].unique_identifier`	Solo cuando se requiere un objeto de documento
`passengers[].documentType`	`passengers[].identity_documents[].type`	Limitado por `allowedDocuments`
`passengers[].documentExpiresAt`	`passengers[].identity_documents[].expires_on`	Solo cuando es requerido
`passengers[].documentCountryCode`	`passengers[].identity_documents[].issuing_country_code`	Solo cuando es requerido
`passengers[].allowedDocuments`	`passengers[].identity_documents[].type`	Si incluye `dni`, tambien recoge `passengers[].NationalID`
`holder.phone`	`passengers[0].phone_number`	Algunos flujos derivan el contacto del titular desde el primer pasajero
`holder.email`	`passengers[0].email`	Algunos flujos derivan el contacto del titular desde el primer pasajero
`holder.countryCode`	derivado de `passengers[0].phone_number`	No existe un campo separado de reserva; usa el prefijo telefonico E.164

Los flags genericos age, address, city, postalCode y documentIssuedAt actualmente no mapean a campos publicos explicitos de reserva.

Payloads anidados de pasajero

json

{
  "identity_documents": [
    {
      "type": "passport",
      "unique_identifier": "X1234567",
      "issuing_country_code": "ES",
      "expires_on": "2030-12-31"
    }
  ],
  "loyaltyProgrammeAccounts": [
    {
      "airlineIataCode": "BA",
      "accountNumber": "123456789"
    }
  ]
}

Ejemplo de totalSegments

json

[
  {
    "originCode": "MAD",
    "destinationCode": "BCN",
    "flightNumber": "1234",
    "departureDate": "2026-08-20T08:15:00"
  }
]

`totalSegments`	Origen en `offer.slices[].segments[]`
`originCode`	`segment.departure.iataCode`
`destinationCode`	`segment.arrival.iataCode`
`flightNumber`	`segment.flightNumber`
`departureDate`	`segment.departure.departingAt`

Ejemplo

bash

curl -X POST https://api.sandbox.travelandz.com/v1/flights/order/0/offer_123 \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  -H "Content-Type: application/json" \
  -d '{"currency":"EUR","type":"instant","passengers":[{"id":"pas_0001","type":"adult","title":"mr","phone_number":"+34612345678","firstName":"John","lastName":"Doe","gender":"m","email":"john.doe@example.com","bornDate":"1990-01-15","country":"ES"}]}'