Configuración de la API

En esta sección te explicamos los pasos básicos para integrar con éxito nuestras API. Tanto si quieres recibir notificaciones push a través de Webhooks como si quieres recuperar datos de nuestros puntos de conexión, tenemos la solución que necesitas.

• API Push:. Ideal para socios de TAAP y de plataformas de viajes de marca blanca, los eventos push te envían actualizaciones real-time directamente a tu sistema. Aprende a configurar suscripciones, gestionar la autenticación y gestionar 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 instrucciones que te damos a continuación para garantizar una integración sin problemas y una transmisión segura de los datos.

Push-based entrega

Esto podría interesarte si eres socio de TAAP o de una plataforma de viajes de marca blanca y te interesan los datos sobre itinerarios. Los eventos push se envían a través de Webhook y se enviarán como un mensaje « HTTP POST » a la URL que nos facilites.

Para empezar a recibir eventos, tendrás que suscribirte a un tipo de evento y autenticar 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 envío « push-based ». Ahora mismo puedes crear y gestionar suscripciones a los eventos de actualización de itinerarios, y iremos añadiendo más a medida que estén disponibles.

Vas a necesitar un ID de cliente y una clave secreta de la API, que te puede facilitar tu persona de contacto comercial.

Cómo acceder a la API de suscripciones

Tendrás que incluir un token de acceso específico para tu empresa en todas tus solicitudes 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 un encabezado «Authorization» con una cadena codificada en Base64 que contenga tu ID de cliente y tu clave secreta de la API al punto final del token https://analytics.ean.com/*/v1/oauth/token. Sustituye « * » en la URL por « template » o « taap », según tu acuerdo de colaboración.
2. El punto final de tokens te devolverá un token de acceso que usarás para las siguientes solicitudes a la API.
3. Incluye el valor del token de acceso en las próximas solicitudes al punto final de la API.

>> Más información sobre el token de acceso

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

Una vez que te hayas autenticado en la API de suscripciones, podrás gestionar tus suscripciones, lo que incluye ver una lista de las que ya tienes, crear otras nuevas y eliminar las que ya no te interesen.

Crear suscripciones

Al crear una suscripción, tendrás que indicar:

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

Nota: Aunque puedes crear varias suscripciones, si hay suscripciones duplicadas, se enviarán los eventos por duplicado. Para evitarlo, haz una lista de las suscripciones que ya tienes antes de crear otras nuevas.

Cuando se cree una suscripción, recibirás una clave secreta única para validar el HMAC (código de autenticación de mensajes «hash-based ») que se incluye en los mensajes de eventos.

Para ver o eliminar suscripciones, usa los puntos finales HTTP GET /subscriptionso HTTP DELETE /subscriptions/{subscription_id}, respectivamente. Tienes que usar un token válido.

>> Más información sobre las suscripciones

Autenticación de Expedia como remitente

Te enviaremos notificaciones push al punto de conexión que nos facilites; cada notificación incluirá una firma HMAC ( hash-based ) en el encabezado de autorización. Deberías validar esta firma para garantizar una transmisión de datos segura y fiable 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 punto final que recibe eventos push. Así te asegurarás de que los eventos que recibas procedan de Expedia y de que no hayan sido alterados 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: Analizar el encabezado de autorización

Extrae la información necesaria del encabezado 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: Comprueba que tengas todos los componentes necesarios

Comprueba que los componentes necesarios ts (marca de tiempo), nonce, bodyhashy macestén presentes y tengan el formato correcto.

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: Genera y valida el hash del cuerpo del mensaje

Genera el hash del cuerpo de la solicitud utilizando HMAC SHA-256 y el sharedSecretKey, y comprueba que coincida 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 solicitud, el dominio del servidor, el puerto y el hash del cuerpo generado, y compárala con el valor recibido en el encabezado 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 los eventos fallidos

Si un evento falla, el sistema lo volverá a intentar siguiendo un patrón de retroceso exponencial durante 7 días: primero cada 5 minutos, luego cada 60 minutos y, a partir de ahí, cada 12 horas. Volveremos a intentarlo si se produce un error por:

• Un código de estado HTTP que no sea 200
• Un tiempo muerto
• Una excepción de tu punto final

Detalles de la API de suscripciones

Si quieres más detalles sobre la API de suscripciones, descárgate la especificación OpenAPI.

Pull-based entrega

Si tienes una plataforma de viajes de marca blanca, puedes implementar la entrega de datos a través de « pull-based » para los itinerarios y los puntos de fidelidad, dependiendo de las API que utilices.

Para poder acceder a los puntos finales «Loyalty Earn» e «Itineraries», necesitarás un ID de cliente y una clave secreta de la API, que puedes pedirle a tu contacto comercial. Tendrás que incluir un token de acceso específico para tu empresa en todas tus solicitudes 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 un encabezado «Authorization» con una cadena codificada en Base64 que contenga tu ID de cliente y tu clave secreta de la API al punto final del token https://analytics.ean.com/template/v1/oauth/token.
2. El punto final de tokens te devolverá un token de acceso que usarás para las siguientes solicitudes a la API. Para más detalles, consulta la especificación OpenAPI.
3. Incluye el valor del token de acceso en las próximas solicitudes 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}

En cuanto hayas recibido tu token, ya puedes empezar a enviar solicitudes a cualquiera de los puntos finales de «Loyalty Earn» o «Itineraries».

Cuando solicites el servicio, tendrás que indicar tu versión de la API. Usa el valor « servers.url » que aparece en la parte superior de nuestros archivos de especificaciones OpenAPI descargables. Siempre coincidirá 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 punto final 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 indican 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 conocer el alcance de los datos y las configuraciones de la API, echa un vistazo a los esquemas de la API:
>> Más información sobre la API de itinerarios
>> Descubre cómo funciona la API de Loyalty Earn