Configuração da API

Esta seção aborda as etapas essenciais para uma integração bem-sucedida com nossas APIs. Não importa se você deseja receber eventos push via Webhooks ou extrair dados de nossos endpoints, nós podemos ajudar.

• Push API: Ideal para parceiros de modelos TAAP e White Label, os eventos push fornecem atualizações quase em tempo real diretamente para seu sistema. Aprenda a configurar assinaturas, gerenciar autenticação e lidar com novas tentativas.
• Pull API: Projetada para parceiros de modelos de marca branca, ela permite que você solicite dados quando precisar. Orientaremos você na configuração da autenticação baseada em token para acesso seguro.

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

Entrega baseada em push

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

Para começar a receber eventos, você precisará se inscrever em um tipo de evento e autenticar o 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 baseado em push. Atualmente, você pode criar e gerenciar assinaturas para eventos de atualização de itinerários, e adicionaremos mais conforme estiverem disponíveis.

Você precisará de um ID de cliente de API e um segredo, que seu contato comercial pode fornecer.

Acessando a API de Assinaturas

Você incluirá um token de acesso específico para seu negócio 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 do ID do cliente da sua API e segredo ao ponto de extremidade do tokenhttps://analytics.ean.com/*/v1/oauth/token. Substitua * na URL por template ou taap, dependendo da sua parceria.
2. O ponto de extremidade do token retornará um token de acesso que você usará para solicitações de API subsequentes. Para mais detalhes, consulte os Detalhes da API de assinaturas.
3. Inclua o valor do token de acesso em futuras solicitações de ponto de extremidade 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 a autenticação na API de assinatura, você pode gerenciar suas assinaturas, incluindo fazer uma lista das suas assinaturas existentes, criar novas e excluir aquelas que não são mais aplicáveis.

Criando assinaturas

Ao criar uma assinatura, você precisará especificar:

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

Observação: embora você possa criar várias assinaturas, assinaturas duplicadas resultarão em entregas de eventos duplicadas. Para evitar isso, liste suas assinaturas existentes antes de criar novas.

Quando uma assinatura é criada, você receberá uma chave secreta exclusiva para validar o HMAC (código de autenticação de mensagens baseado em hash) incluído nas entregas de eventos.

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

Para obter detalhes adicionais, consulte os Detalhes da API de assinaturas.

Autenticação da Expedia como remetente

Enviaremos eventos push para o endpoint fornecido, com cada evento incluindo uma assinatura HMAC no cabeçalho de autorização. Você deve validar esta assinatura usando o segredo compartilhado que forneceremos para garantir uma transmissão de dados segura e confiável.

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 do HMAC ao seu ponto de extremidade da 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 ponto de extremidade:

@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 lógica de validação

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

1. Analise o cabeçalho de autorização para extrair componentes.
2. Gere uma assinatura HMAC usando os componentes extraídos e sharedSecretKey.
3. Compare a assinatura gerada com a que está 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 a cada 5 minutos, depois a cada 60 minutos e, depois disso, a cada 12 horas. Tentaremos novamente qualquer falha devido a:

• Um código de status HTTP não-200
• Um tempo limite
• Uma exceção do seu ponto de extremidade

Detalhes da API de assinaturas

Para obter detalhes adicionais sobre a API de Assinaturas, baixe a especificação OpenAPI.

Entrega baseada em pull

Se você tiver um site de modelo de marca branca, poderá implementar a entrega baseada em pull para dados de itinerários e ganhos de fidelidade, dependendo das APIs que estiver usando.

Para ter acesso aos endpoints do Loyalty Earn e Itinerários, você precisará de um ID de cliente de API e um segredo, que pode ser obtido com seu contato comercial. Você incluirá um token de acesso específico para seu negócio 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 do ID do cliente da API e do segredo ao ponto de extremidade do tokenhttps://analytics.ean.com/template/v1/oauth/token .
2. O ponto de extremidade do token retornará um token de acesso que você usará para 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 de ponto de extremidade 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ê pode começar a fazer solicitações para qualquer um dos endpoints de Fidelidade ou Itinerários.

Ao solicitar o serviço, você precisará especificar sua versão da API. Use oservers.url valor encontrado no topo dos nossos arquivos de especificação OpenAPI para download. Ele 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 os pontos de extremidade 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 estabelecido 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 de dados e as configurações da API, consulte os esquemas para entrega da API:
Entrega de API de itinerários
Entrega da API Loyalty Earn