Configuración de la API

Esta sección cubre los pasos esenciales para integrarse con éxito con nuestras API. Tanto si quieres recibir eventos push mediante Webhooks como si quieres extraer datos de nuestros puntos finales, te tenemos cubierto.

• API Push: Ideal para socios de TAAP y de la Plataforma de Viajes de Marca Blanca, los eventos push envían actualizaciones de real-time directamente a tu sistema. Aprende a configurar suscripciones, gestionar la autenticación y manejar los reintentos.
• API Pull: Diseñada para los socios de la Plataforma de Viajes de Marca Blanca, te permite solicitar datos cuando los necesites. Te explicaremos cómo configurar la autenticación token-based para un acceso seguro.

Sigue las siguientes pautas para garantizar una integración sin problemas y una transmisión de datos segura.

Push-based entrega

Esto podría ser relevante para ti si eres un TAAP o un socio de una Plataforma de Viajes de Marca Blanca interesado en los datos de Itinerarios. Los eventos Push se entregan mediante Webhook y se enviarán como un mensaje HTTP POSTa una URL que tú proporciones.

Para empezar a recibir eventos, tendrás que suscribirte a un tipo de evento y autentificar Expedia como remitente.

Suscripciones y eventos

Nuestra API de Suscripciones te permite crear y gestionar los eventos que te gustaría recibir a través de nuestro servicio de entrega push-based. Actualmente puedes crear y gestionar suscripciones para los eventos de actualización de Itinerarios, e iremos añadiendo más a medida que estén disponibles.

Necesitarás un identificador y un secreto de cliente API, que tu contacto comercial puede proporcionarte.

Acceder a la API de suscripciones

Incluirás un token de acceso específico para tu empresa en todas tus peticiones a la API. Solicita este token utilizando tus credenciales de la API a través del mecanismo de autenticación básica HTTP.

1. Añade una cabecera de Autorización con una cadena codificada en Base64 de tu ID de cliente API y tu secreto al punto final del token https://analytics.ean.com/*/v1/oauth/token. Sustituye el *de la URL por templateo taap, según tu asociación.
2. El punto final del token devolverá un token de acceso que utilizarás para las siguientes peticiones a la API. Para más información, consulta los detalles de la API de suscripciones .
3. Incluye el valor del token de acceso en futuras peticiones al punto final de la API.

Ejemplo de encabezado de autorización inicial

Authorization: Basic base64.b64encode({client-id}:{client-secret})

Ejemplo de solicitud de token

securitySchemes:
  oauth:
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: https://analytics.ean.com/taap/v1/oauth/token

Ejemplo de encabezado de autorización autenticada

Authorization: Bearer {access-token}

Gestionar tus suscripciones

Después de autenticarte con la API de Suscripción, puedes gestionar tus suscripciones, incluyendo hacer una lista de tus suscripciones existentes, crear otras nuevas y eliminar las que ya no sirven.

Crear suscripciones

Al crear una suscripción tendrás que especificar:

• La URL del punto final donde quieres recibir los eventos.
• El tipo de evento al que quieres suscribirte, incluyendo el indicador de tu asociación: taap.itinerary.changeo template.itinerary.change.

Nota: Aunque puedes crear varias suscripciones, las suscripciones duplicadas darán lugar a entregas de eventos duplicadas. Para evitarlo, haz una lista de tus suscripciones existentes antes de crear otras nuevas.

Cuando se crea una suscripción, recibirás una clave secreta única para validar el HMAC (código de autenticación de mensajeshash-based ) incluido en los envíos de eventos.

Para listar o eliminar suscripciones, utiliza los puntos finales HTTP GET /subscriptionso HTTP DELETE /subscriptions/{subscription_id}, respectivamente. Debes utilizar un token válido.

Para más información, consulta los detalles de la API de suscripciones .

Autentificar Expedia como remitente

Enviaremos eventos push al punto final que nos proporciones, y cada evento incluirá una firma de código de autenticación de mensaje hash-based (HMAC) en la cabecera de autorización. Debes validar esta firma para garantizar una transmisión de datos segura y de confianza utilizando el secreto compartido que te proporcionaremos cuando crees una suscripción.

Ejemplo de encabezado de autorización

"authorization": "MAC ts='1731524372777',nonce='f88e57ed-aaf5-4edd-8e58-9105817fb4cb',bodyhash='8YLHy71r5dx3PQjdcOkRuVYXaakjhbJSROEnlreQEIA=',mac='bDxvx41INtDxtkbZwTmAMADZGiFl6/xyXC1lE5ixPuY='"

Valida la firma HMAC añadiendo la siguiente lógica a tu endpoint que recibe eventos push. Esto garantizará que los eventos que recibes proceden de Expedia y no han sido manipulados durante la transmisión.

Nota: Este ejemplo muestra cómo implementar esta lógica de validación en Java. Puedes adaptar la lógica a tu lenguaje de programación preferido, pero los pasos básicos seguirán siendo los mismos.

Paso 1: Analiza la cabecera de autorización

Extrae la información necesaria de la cabecera de autorización analizando la cadena en sus componentes básicos.

Ejemplo de código

/**
 * Parse the signature string into components
 * @param signature The signature string in format "MAC ts='...', nonce='...', bodyhash='...', mac='...'"
 * @return Map of signature components
 */
private Map<String, String> parseSignature(String signature) {
    // Pattern for key='value' or key="value"
    Pattern pattern = Pattern.compile("([a-zA-Z]+)=['"]([^'"]*)['"]");
    Matcher matcher = pattern.matcher(signature);

    Map<String, String> components = new HashMap<>();
    while (matcher.find()) {
        components.put(matcher.group(1), matcher.group(2));
    }
    return components;
}

Paso 2: Validar los componentes necesarios

Comprueba que los componentes necesarios ts (marca de tiempo), nonce, bodyhash, y macestán presentes y correctamente formateados.

Ejemplo de código

private Boolean validateSignatureComponents(Map<String, String> components) {
    if (components.isEmpty()) {
        return false;
    }

    return components.containsKey("ts") &&
            components.containsKey("nonce") &&
            components.containsKey("bodyhash") &&
            components.containsKey("mac");
}

Paso 3: Generar y validar el hash del cuerpo

Genera el hash del cuerpo utilizando HMAC SHA-256 y el sharedSecretKeyy confirma que coincide con el hash del cuerpo de la solicitud para garantizar la integridad de los datos.

Ejemplo de código

/**
 * Compute body hash (HMAC-SHA256 of the request body)
 * @param body The raw request body
 * @return Base64 encoded body hash
 */
private String computeBodyHash(String body) {
    try {
        Mac mac = Mac.getInstance(HMAC_SHA256);
        SecretKeySpec secretKeySpec = new SecretKeySpec(
                sharedSecretKey.getBytes(StandardCharsets.UTF_8),
                HMAC_SHA256);
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(body.getBytes(StandardCharsets.UTF_8));
        return bytesToBase64(hmacBytes);
    } catch (Exception e) {
        throw new RuntimeException("Failed to compute body hash", e);
    }
}

private Boolean validateBodyHash(String requestBody, String bodyHashFromHeader) {
    String computedBodyHash = computeBodyHash(requestBody != null ? requestBody : "");
    return computedBodyHash.equals(components.get('bodyhash'));
}

Paso 4: Generar y validar la firma HMAC

Genera la firma HMAC incluyendo la marca de tiempo, el nonce, el método HTTP, la ruta de la petición, el dominio del host, el puerto y el hash del cuerpo generado, y valídala contra el valor recibido en la cabecera para garantizar la autenticidad.

Ejemplo de código

/**
 * Generate HMAC signature using the provided components
 * @param components Parsed signature components
 * @param computedBodyHash Computed body hash
 * @param method HTTP method (e.g., "POST", "GET")
 * @param path Request path (e.g., "/api/webhooks/events")
 * @param host Host name (e.g., "api.example.com")
 * @param port Port number
 * @return Base64 encoded HMAC signature
 */
private String generateHmacSignature(Map<String, String> components, String computedBodyHash,
                                     String method, String path, String host, int port) {
    try {
        // Normalize port (use 443 for standard HTTPS ports)
        String portString = (port == 80 || port == 443) ? DEFAULT_PORT : String.valueOf(port);

        // Build signature string with newline-delimited components
        String signatureString = String.format("%s\n%s\n%s\n%s\n%s\n%s\n%s\n",
                components.get("ts"),
                components.get("nonce"),
                method.toUpperCase(),
                path,
                host,
                portString,
                computedBodyHash);

        return calculateHMAC(signatureString);
    } catch (Exception e) {
        throw new RuntimeException("Failed to generate HMAC signature", e);
    }
}

/**
 * Calculate HMAC-SHA256
 * @param data Data to hash
 * @return Base64 encoded HMAC
 */
private String calculateHMAC(String data) {
    try {
        Mac mac = Mac.getInstance(HMAC_SHA256);
        SecretKeySpec secretKeySpec = new SecretKeySpec(
                sharedSecretKey.getBytes(StandardCharsets.UTF_8),
                HMAC_SHA256);
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        return bytesToBase64(hmacBytes);
    } catch (Exception e) {
        throw new RuntimeException("Failed to calculate HMAC", e);
    }
}

private Boolean validateHmacSignature(Map<String, String> components, String computedBodyHash,
                                      String method, String path, String host, int port) {
    String generatedHmacSignature = generateHmacSignature(components, computedBodyHash, method, path, host, port);
    return generatedHmacSignature.equals(components.get("mac"));
}

Reintentar fallos de eventos

Si falla un evento, el sistema lo reintentará utilizando un patrón de reintento exponencial durante 7 días: primero a los 5 minutos, luego a los 60 minutos y, a partir de entonces, cada 12 horas. Reintentaremos cualquier fallo debido a:

• Un código de estado HTTP no-200
• Un tiempo de espera
• Una excepción de tu punto final

Detalles de la API de suscripciones

Para más detalles sobre la API de Suscripciones, descarga la especificación OpenAPI.

Pull-based entrega

Si tienes un sitio de Plataforma de Viajes de Marca Blanca, puedes implementar la entrega pull-based para los Itinerarios y los datos de Ganar fidelidad, dependiendo de las API que utilices.

Para acceder a los puntos finales Ganar fidelidad e Itinerarios, necesitarás un identificador y un secreto de cliente API, que puedes obtener de tu contacto comercial. Incluirás un token de acceso específico para tu empresa en todas tus peticiones a la API. Solicita este token utilizando tus credenciales de la API a través del mecanismo de autenticación básica HTTP.

1. Añade una cabecera de Autorización con una cadena codificada en Base64 de tu ID de cliente API y tu secreto al punto final del token https://analytics.ean.com/template/v1/oauth/token.
2. El punto final del token devolverá un token de acceso que utilizarás para las siguientes peticiones a la API. Para más detalles, consulta la especificación OpenAPI.
3. Incluye el valor del token de acceso en futuras peticiones al punto final de la API.

Ejemplo de encabezado de autorización inicial

Authorization: Basic base64.b64encode({client-id}:{client-secret})

Ejemplo de solicitud de token

securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://analytics.ean.com/template/v1/oauth/token

Ejemplo de encabezado de autorización autenticada

Authorization: Bearer {token}

Una vez que hayas recibido tu token, puedes empezar a hacer solicitudes contra cualquiera de los puntos finales de Fidelidad Ganar o Itinerarios.

Cuando solicites el servicio, tendrás que especificar tu versión de API. Utiliza el valor servers.urlque se encuentra en la parte superior de nuestros archivos descargables de especificaciones OpenAPI. Siempre se corresponderá con el número de versión del servicio API que estés probando.

La URL debe seguir esta estructura:

https://analytics.ean.com/[product]/[API version]/[path]

Puedes cambiar de un punto final a otro sustituyendo la ruta, pero asegúrate de mantener el protocolo, la designación del dominio, el producto y el número de versión de la API tal y como se establece en la especificación OpenAPI.

Ejemplos de puntos finales

https://analytics.ean.com/template/v1/loyalty/earn/last_update
https://analytics.ean.com/template/v1/itineraries

Para explorar el alcance de los datos y las configuraciones de la API, consulta los esquemas para la entrega de la API:
Itinerarios Entrega de API
Fidelización Ganar entrega API