POST/v1/flights/order/required-fields/:gdsprovider/:offerId

Consultar campos requeridos para reservar vuelo

Devuelve los campos dinámicos de pasajero, documentos e identidad necesarios para completar la reserva de una oferta de vuelo seleccionada.

Endpoint

Método	Ruta	Auth
`POST`	`/v1/flights/order/required-fields/: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í	Accepted values: `0`, `1`
`offerId`	`string`		Sí	-

Esquema del cuerpo de la petición

Propiedad	Tipo	Detalles	Requerido	Notas
`offerId`	`string`		Sí	Selected offer id
`passengers`	`array`		Sí	-
`passengers[]type`	`enum`	`adultchildinfant_without_seat`	Sí	-

Respuesta exitosa

Devuelve required field definitions for the offer.

Esquema del cuerpo de la respuesta

Propiedad	Tipo	Requerido	Notas
`holder`	`object`	Sí	-
`holderphone`	`boolean`	Sí	Cuando sea true, envia `passengers[0].phone_number` en formato E.164 para flujos que consumen datos de contacto del titular
`holderemail`	`boolean`	Sí	Cuando sea true, envia `passengers[0].email` para flujos que consumen email del titular
`holdercountryCode`	`boolean`	Sí	No existe un campo separado en `create-order`. En flujos gdsprovider=1 se deriva de `passengers[0].phone_number` en formato E.164
`passengers`	`array`	Sí	-
`passengers[]idx`	`number`	Sí	Indice del pasajero en la respuesta de required-fields
`passengers[]title`	`boolean`	Sí	Mapea a `passengers[].title`
`passengers[]type`	`boolean`	Sí	Mapea a `passengers[].type`
`passengers[]name`	`boolean`	Sí	Mapea a `passengers[].firstName`
`passengers[]lastName`	`boolean`	Sí	Mapea a `passengers[].lastName`
`passengers[]age`	`boolean`	Sí	Solo informativo. No existe campo directo en `create-order` y actualmente es false en flujos publicos de vuelos
`passengers[]nationality`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].country`
`passengers[]gender`	`boolean`	Sí	Mapea a `passengers[].gender`
`passengers[]phone`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].phone_number`
`passengers[]email`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].email`. Algunos flujos gdsprovider=1 solo consumen el email del primer pasajero
`passengers[]address`	`boolean`	Sí	Solo informativo. No existe campo directo en `create-order` y actualmente es false en flujos publicos de vuelos
`passengers[]city`	`boolean`	Sí	Solo informativo. No existe campo directo en `create-order` y actualmente es false en flujos publicos de vuelos
`passengers[]postalCode`	`boolean`	Sí	Solo informativo. No existe campo directo en `create-order` y actualmente es false en flujos publicos de vuelos
`passengers[]bornDate`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].bornDate`
`passengers[]documentIdentifier`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].identity_documents[].unique_identifier`
`passengers[]documentType`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].identity_documents[].type` cuando se usa un objeto de documento
`passengers[]documentIssuedAt`	`boolean`	Sí	Solo informativo. No existe campo directo en `create-order` y actualmente es false en flujos publicos de vuelos
`passengers[]documentExpiresAt`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].identity_documents[].expires_on`
`passengers[]documentCountryCode`	`boolean`	Sí	Cuando sea true, mapea a `passengers[].identity_documents[].issuing_country_code`
`passengers[]allowedDocuments`	`array`	Nulable	Valores permitidos para el flujo de documentos de reserva: `passport`, `tax_id`, `known_traveler_number`, `passenger_redress_number`, `dni`. Si `dni` esta permitido, tambien recoge `passengers[].NationalID` porque la respuesta actual no expone un flag dedicado `nationalId`

Notas operativas

Prefiere este endpoint POST porque acepta contexto de pasajeros en el cuerpo de la peticion.
GET /v1/flights/order/required-fields/:gdsprovider/:offerId existe por compatibilidad, pero las integraciones deberian usar POST.
El contrato real de respuesta es holder mas passengers[]; no es un wrapper requiredFields[].
Usa la respuesta para decidir si antes de reservar debes recoger identity_documents, NationalID, nacionalidad o vencimiento de documento.
allowedDocuments limita los valores validos de passengers[].identity_documents[].type. Si incluye dni, recoge tambien passengers[].NationalID, aunque la respuesta actual no exponga un boolean dedicado nationalId.
En flujos gdsprovider=1, holder.countryCode no corresponde a un campo separado de reserva. Se satisface con passengers[0].phone_number en formato E.164.
En flujos gdsprovider=1, passengers[].email puede aparecer como requerido aunque solo el email del primer pasajero se consuma como email del titular.

Ejemplo

bash

curl -X POST https://api.sandbox.travelandz.com/v1/flights/order/required-fields/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 '{"offerId":"offer_123","passengers":[{"type":"adult"}]}'

Cuerpo de la petición - Ejemplo

json

{
  "offerId": "offer_123",
  "passengers": [
    {
      "type": "adult"
    }
  ]
}

Respuestas

Código	Descripción
`200`	Campos requeridos de reserva resueltos correctamente.
`400`	Solicitud inválida: payload no válido.
`401`	No autorizado: credenciales inválidas o ausentes.
`403`	Prohibido: credenciales inválidas.
`500`	Error interno del servidor

200 Cuerpo de la respuesta

Tipo de contenido: application/json

json

{
  "holder": {
    "phone": true,
    "email": true,
    "countryCode": true
  },
  "passengers": [
    {
      "idx": 0,
      "title": true,
      "type": true,
      "name": true,
      "lastName": true,
      "age": false,
      "nationality": true,
      "gender": true,
      "phone": true,
      "email": true,
      "address": false,
      "city": false,
      "postalCode": false,
      "bornDate": true,
      "documentIdentifier": true,
      "documentType": true,
      "documentIssuedAt": false,
      "documentExpiresAt": true,
      "documentCountryCode": true,
      "allowedDocuments": [
        "passport",
        "dni"
      ]
    }
  ]
}