Configuração da API

Esta seção aborda os passos essenciais para uma integração bem-sucedida com nossas APIs. Quer você queira receber notificações push via Webhooks ou extrair dados de nossos endpoints, nós temos a solução ideal para você.

• API Push: Ideal para parceiros TAAP e White Label Travel Platform, os eventos push entregam atualizações near-real-time diretamente para o seu sistema. Aprenda como configurar assinaturas, gerenciar autenticação e lidar com novas tentativas.
• API Pull: Projetada para parceiros de Plataforma de Viagens White Label, permite que você solicite dados quando precisar deles. Explicaremos como configurar a autenticação token-based para acesso seguro.

Siga as orientações abaixo para garantir uma integração tranquila e uma transmissão de dados segura.

Entrega Push-based

Isso pode ser relevante para você se for um parceiro TAAP ou de uma Plataforma de Viagens White Label interessado em dados de itinerários. Os eventos push são entregues via Webhook e serão enviados como uma mensagem HTTP POSTpara um URL que você fornecer.

Para começar a receber eventos, você precisará se inscrever em um tipo de evento e autenticar a Expedia como remetente.

Assinaturas e eventos

Nossa API de Assinaturas permite que você crie e gerencie os eventos que deseja receber por meio do nosso serviço de entrega push-based. Atualmente, você pode criar e gerenciar assinaturas para eventos de atualização de itinerários, e adicionaremos mais opções conforme forem disponibilizadas.

Você precisará de um ID e uma chave secreta do cliente da API, que seu contato comercial pode fornecer.

Acessando a API de Assinaturas

Você deverá incluir um token de acesso específico para sua empresa em todas as suas solicitações de API. Solicite este token usando suas credenciais de API por meio do mecanismo de autenticação básica HTTP.

1. Adicione um cabeçalho de Autorização com uma string codificada em Base64 contendo o ID e o segredo do seu cliente de API ao endpoint de token https://analytics.ean.com/*/v1/oauth/token. Substitua o *no URL por templateou taap, dependendo da sua parceria.
2. O endpoint de token retornará um token de acesso que você usará em solicitações de API subsequentes. Para obter mais detalhes, consulte os detalhes da API de Assinaturas .
3. Inclua o valor do token de acesso em futuras solicitações ao endpoint da API.

Exemplo de cabeçalho de autorização inicial

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

Exemplo de solicitação de token

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

Exemplo de cabeçalho de autorização autenticado

Authorization: Bearer {access-token}

Gerenciando suas assinaturas

Após autenticar-se na API de Assinaturas, você poderá gerenciar suas assinaturas, incluindo criar uma lista das assinaturas existentes, criar novas e excluir aquelas que não são mais relevantes.

Criar assinaturas

Ao criar uma assinatura, você precisará especificar:

• O URL do ponto de extremidade onde você deseja receber eventos.
• O tipo de evento ao qual você deseja se inscrever, incluindo o indicador de sua parceria: taap.itinerary.changeou template.itinerary.change.

Observação: Embora seja possível criar várias assinaturas, assinaturas duplicadas resultarão em entregas de eventos duplicadas. Para evitar isso, liste suas assinaturas existentes antes de criar novas.

Ao criar uma assinatura, você receberá uma chave secreta exclusiva para validar o HMAC (código de autenticação de mensagem hash-based) incluído nas entregas de eventos.

Para listar ou excluir assinaturas, use os endpoints HTTP GET /subscriptionsou HTTP DELETE /subscriptions/{subscription_id}, respectivamente. Você deve usar um token válido.

Para obter detalhes adicionais, consulte os detalhes da API de Assinaturas .

Autenticando a Expedia como remetente

Enviaremos notificações push para o endpoint que você fornecer, e cada notificação incluirá uma assinatura HMAC no cabeçalho de autorização. Você deve validar esta assinatura usando o segredo compartilhado que forneceremos para garantir a transmissão segura e confiável dos dados.

Exemplo de cabeçalho de autorização

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

Etapa 1: Configurar validação

Adicione estas configurações HMAC ao seu endpoint de API push:

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

Etapa 2: Adicionar módulo de validação

Valide a assinatura HMAC adicionando este código de classe pública ao endpoint:

@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
    }
}

Etapa 3: Implementar a lógica de validação

A lógica para validação de assinatura deve seguir estes passos:

1. Analise o cabeçalho de autorização para extrair os componentes.
2. Gere uma assinatura HMAC usando os componentes extraídos e sharedSecretKey.
3. Compare a assinatura gerada com a assinatura presente no cabeçalho de autorização.

Exemplo 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);
    }
}

Tentando novamente falhas de eventos

Se um evento falhar, o sistema tentará novamente usando um padrão de espera exponencial ao longo de 7 dias: primeiro em 5 minutos, depois em 60 minutos e, a partir daí, a cada 12 horas. Tentaremos novamente qualquer falha causada por:

• Um código de status HTTP diferente de 200
• Um tempo limite
• Uma exceção do seu endpoint

Detalhes da API de Assinaturas

Para obter mais detalhes sobre a API de Assinaturas, faça o download da especificação OpenAPI.

Entrega Pull-based

Se você possui um site de Plataforma de Viagens White Label, pode implementar a entrega pull-based para dados de Itinerários e Acúmulo de Pontos de Fidelidade, dependendo das APIs que estiver utilizando.

Para obter acesso aos endpoints de Acúmulo de Pontos de Fidelidade e Itinerários, você precisará de um ID e um segredo de cliente da API, que podem ser obtidos com seu contato comercial. Você deverá incluir um token de acesso específico para sua empresa em todas as suas solicitações de API. Solicite este token usando suas credenciais de API por meio do mecanismo de autenticação básica HTTP.

1. Adicione um cabeçalho de Autorização com uma string codificada em Base64 contendo o ID e o segredo do seu cliente de API ao endpoint de token.https://analytics.ean.com/template/v1/oauth/token .
2. O endpoint de token retornará um token de acesso que você usará em solicitações de API subsequentes. Para mais detalhes, consulte a especificação OpenAPI.
3. Inclua o valor do token de acesso em futuras solicitações ao endpoint da API.

Exemplo de cabeçalho de autorização inicial

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

Exemplo de solicitação de token

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

Exemplo de cabeçalho de autorização autenticado

Authorization: Bearer {token}

Após receber seu token, você poderá começar a fazer solicitações para qualquer um dos endpoints de Acúmulo de Pontos de Fidelidade ou Itinerários.

Ao solicitar o serviço, você precisará especificar a versão da sua API. Use oservers.url Valor encontrado na parte superior dos nossos arquivos de especificação OpenAPI para download. Sempre corresponderá ao número da versão do serviço de API que você está testando.

A URL deve seguir esta estrutura:

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

Você pode alternar entre endpoints substituindo o caminho, mas certifique-se de manter o protocolo, a designação de domínio, o produto e o número da versão da API conforme definido na especificação OpenAPI.

Exemplos de endpoints

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

Para explorar o escopo dos dados e as configurações da API, consulte os esquemas de entrega da API:
Entrega de API de itinerários
Entrega da API de Acúmulo de Fidelidade