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 TAAP y de Plantillas de Marca Blanca, los eventos push envían actualizaciones de near-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 Plantilla 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 Plantillas 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 de 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 indiques, y cada evento incluirá una firma HMAC en la cabecera de autorización. Debes validar esta firma utilizando el secreto compartido que te proporcionaremos para garantizar una transmisión de datos segura y de confianza.

Ejemplo de encabezado de autorización

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

Paso 1: Configurar la validación

Añade estos ajustes de configuración HMAC a tu punto final de la API push:

hmac.validator.sharedSecretKey={mySecretKey}
hmac.validator.endpoint=https:{//example.com}
hmac.validator.methodType=POST

Paso 2: Añadir módulo de validación

Valida la firma HMAC añadiendo este código de clase pública al punto final:

@Component
public class HmacValidator {
    private static final String HMAC_SHA256 = "HmacSHA256";
    private static final String DEFAULT_PORT = "443";
    private final String sharedSecretKey;
    private final String endpoint;
    private final String methodType;

    // Constructor for initialization
    public HmacValidator(@Value("${hmac.validator.sharedSecretKey}") String sharedSecretKey,
                         @Value("${hmac.validator.endpoint}") String endpoint,
                         @Value("${hmac.validator.methodType:POST}") String methodType) {
        this.sharedSecretKey = sharedSecretKey;
        this.endpoint = endpoint;
        this.methodType = methodType; // Default to POST if not provided
    }

    public boolean validate(String signature) {
        //Validation logic here
    }
}

Paso 3: Implementar la lógica de validación

La lógica para la validación de la firma debe seguir los siguientes pasos:

1. Analiza la cabecera de autorización para extraer los componentes.
2. Genera una firma HMAC utilizando los componentes extraídos y sharedSecretKey.
3. Compara la firma generada con la de la cabecera de autorización.

Ejemplo de código

// Validate the signature
    public boolean validate(String signature) {
        Map<String, String> components = parseSignature(signature);
        if (components == null || components.isEmpty()) {
            return false; // Invalid format or empty signature
        }

        String generatedHmacSignature = generateHmacSignature(components);
        System.out.println("Generated HMAC Signature: " + generatedHmacSignature);
        System.out.println("Received HMAC Signature: " + components.get("mac"));
        return generatedHmacSignature.equals(components.get("mac"));
    }

    // Parse the signature into its components
    private Map<String, String> parseSignature(String signature) {
        // Define the pattern for each key-value pair in the format "key='value'"
        Pattern pattern = Pattern.compile("([a-zA-Z]+)='([^']*)'");
        Matcher matcher = pattern.matcher(signature);

        // Store results in a map
        Map<String, String> components = new HashMap<>();

        // Extract each key-value pair
        while (matcher.find()) {
            components.put(matcher.group(1), matcher.group(2));
        }
        return components;
    }

    // Generate the HMAC signature using components
    public String generateHmacSignature(Map<String, String> components) {
        try {
            URL url = new URL(endpoint);
            String signature = String.format("%s/n%s/n%s/n%s/n%s/n%s/n%s/n",
                    components.get("ts"),
                    components.get("nonce"),
                    methodType.toUpperCase(),
                    url.getPath(),
                    url.getHost(),
                    url.getPort() == -1 ? DEFAULT_PORT : String.valueOf(url.getPort()),
                    components.get("bodyhash"));

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

    // Calculate the HMAC from the signature string
    private String calculateHMAC(String signature) {
        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(signature.getBytes(StandardCharsets.UTF_8));
            return bytesToBase64(hmacBytes);
        } catch (Exception e) {
            throw new RuntimeException("Failed to calculate HMAC", e);
        }
    }

    // Convert byte array to Base64 string
    private String bytesToBase64(byte[] bytes) {
        return Base64.getEncoder().encodeToString(bytes);
    }
}

Reintentar fallos de eventos

Si un evento falla, 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 Plantilla de Marca Blanca, puedes implementar la entrega de pull-based para los datos de Itinerarios y 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. 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 Ganar Lealtad 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 de 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