Compras

A API de compras oferece acesso a tarifas ativas e disponibilidade para 700 mil acomodações no mundo todo.

Visão geral

A API de compras retorna tarifas e disponibilidade de todos os tipos de quarto das propriedades especificadas, com um máximo de 250 propriedades por solicitação. A resposta inclui detalhes da tarifa, como as promoções, se a tarifa é reembolsável, as multas por cancelamento e os detalhes de preço para atender aos requisitos de exibição de preço no seu mercado.

Vários quartos do mesmo tipo podem ser solicitados ao incluir várias instâncias do parâmetro occupancy. Se a mesma ocupação for solicitada várias vezes na mesma solicitação, a resposta vai conter apenas um único conjunto de tarifas para essa ocupação. Podem ser solicitados, no máximo, 8 quartos por vez. Se você precisar reservar mais de 8 quartos por vez, consulte o seu gerente de contas sobre a nossa parceria para reservas de grupo.

Alterações na exibição de preços

Fique por dentro das próximas mudanças, devido à regulamentação de exibição de preços da Price Display Regulation (Berman Law) da Califórnia, que entra em vigor a partir de 1º de julho de 2024.

O que diz a lei?

A lei proíbe anunciar, exibir ou oferecer uma tarifa de quarto que não inclua todas as taxas ou cobranças exigidas para se hospedar em uma acomodação por curta duração, exceto impostos e taxas governamentais sobre a estadia. A lei também exige que a hospedagem de curta duração inclua no preço total a ser pago, antes que o consumidor reserve a estadia, todos os impostos e taxas governamentais incidentes sobre a estadia. "Hospedagem de curta duração" significa qualquer hotel, motel, pousada e outras acomodações temporárias, incluindo aluguéis por temporada de curta duração ou uma propriedade residencial locada para um visitante por 30 dias consecutivos ou menos. Para saber mais, consulte California Assembly Bill 537 ("Lei da Assembleia da Califórnia 537", em inglês).

O Expedia Group está fazendo alterações na API para permitir que parceiros da API exibam preços de várias maneiras. Em última análise, no entanto, cada parceiro que usa a API do Expedia Group é responsável por garantir que a maneira como exibe as informações e preços de viagem da Expedia esteja em conformidade com a lei.

Quais são as próximas mudanças?

A Expedia está melhorando a Rapid API para adicionar um novo campo property_inclusive com o preço total, que inclui a tarifa padrão e todas as taxas e impostos cobrados pela Expedia e pela propriedade por toda a estadia. Uma versão riscada desse preço total também vai estar disponível em um novo campo property_inclusive_strikethrough. Além dos novos campos de exibição que incluem a propriedade, estamos reorganizando a forma como as taxas e os impostos são detalhados na resposta da API. Todas as taxas cobradas pela Expedia vão fazer parte do tipo de detalhamento de preço nightly e stay da property_fee, e todos os impostos cobrados pela Expedia vão fazer parte do tipo de detalhamento de preço tax_and_service_fee por nightly e stay.

Como essa vai ser uma mudança global implementada em todas as propriedades, a data de lançamento foi remarcada para 29 de maio de 2024 para garantir que a adoção e a compreensão das alterações ocorram da melhor maneira. Entre em contato com o gerente de contas se tiver mais dúvidas sobre as alterações.

Pontos de fidelidade

As propriedades com programas de fidelidade que participam do programa de tarifas corporativas da Expedia oferecem a viajantes de negócios a oportunidade de ganhar pontos de fidelidade pelas suas estadias em hotéis. Parceiros podem usar o nó de comodidades da resposta de compras para identificar e mostrar a qualificação para o programa de fidelidade antes da captura dos detalhes de associação do viajante.

Parceiros também podem pesquisar tarifas corporativas qualificadas do programa de fidelidade usando o filtro de valor loyalty nas solicitações da API de compras.

Observação: o recebimento de pontos de fidelidade só está disponível em tarifas corporativas quando o hotel já possui um programa de fidelidade.

Exemplo:

Tarifas corporativas de hotel que acumulam pontos de fidelidade vão ter o seguinte parâmetro na resposta de busca do nó amenities:

{
  "id": "2096",
  "name": "Eligible for hotel loyalty points"
}

Incentivos de comissão

Como parceiro da Rapid API, você tem acesso a incentivos de comissão adicionais que oferecem margens mais altas em propriedades para um determinado período de reserva e estadia. Para identificar propriedades com incentivo de comissão ativo, basta usar o valor rooms.rates.marketing_fee_incentives para o parâmetro include na sua solicitação da API de compras da Rapid. Tarifas com incentivos de comissão para todo ou parte do período de estadia solicitado vão ter detalhes adicionais, incluindo a fonte do incentivo e a parte da estadia afetada, no objeto marketing_fee_incentives na resposta da API de compras. Você pode considerar isso e o campo marketing_fee existente, que é uma estimativa da taxa de marketing que inclui todos os incentivos disponíveis, no seu processo de classificação e seleção de inventário.

Exemplo

A propriedade 19248 oferece margens mais altas para estadias em dezembro. Você faz uma solicitação de API de compras para a propriedade 19248 para uma estadia de 22 de dezembro a 5 de janeiro. No objeto marketing_fee_incentives da resposta da API de compras, você vai ver que há um incentivo disponível para uma parte da estadia solicitada, de 22 de dezembro a 31 de dezembro, o que representa 10 das 14 diárias da estadia.

Exemplo de solicitação

curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-01-05\
&currency=USD\
&country_code=US\
&language=en-US\
&occupancy=2\
&property_id=19248\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only\
&include=rooms.rates.marketing_fee_incentives\
&travel_purpose=leisure" \
 -H "accept: application/json, application/json"\
 -H "accept-encoding: gzip"\
 -H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
 -H "user-agent: TravelNow/3.30.112"

Exemplo de resposta

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "marketing_fee_incentives": [
              {
                "source": "property",
                "start": "2023-12-22",
                "end": "2023-12-31"
              }
            ],
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": { ... },
                  "strikethrough": { ... },
                  "marketing_fee": {
                    "billable_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    },
                    "request_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    }
                  },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

Motivo da viagem

O parâmetro travel_purpose permite que você defina a sua viagem como negócios ou lazer. A partir de 1º de abril de 2024, os parceiros qualificados para comprar com tarifas corporativas vão precisar usar travel_purpose=business na solicitação de compras para receber essas tarifas na resposta. Se nenhum parâmetro travel_purpose for fornecido na solicitação, o motivo vai ser definido como lazer e nenhuma tarifa corporativa vai ser retornada.

Exemplo

Para especificar que um cliente pretende viajar a negócios, basta adicionar 24 caracteres à solicitação da API de disponibilidade.

&travel_purpose=business

Preço riscado

• O campo strikethrough fornece o preço total sem impostos antes da aplicação de descontos financiados pelo hotel. Esse campo deve ser usado em localidades como os Estados Unidos, que, em geral, mostram o preço base sem impostos e taxas nos resultados da pesquisa.
• O campo inclusive_strikethrough apresenta o preço total, antes dos descontos, com impostos e taxas incluídos. Esse campo foi criado para permitir que você mostre com mais clareza o desconto aplicável em localidades que apresentam preços com tudo incluído, ou seja, base, impostos e taxas. O campo retorna o valor nas moedas de cobrança e na solicitada.

Exemplo

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": {
                    "billable_currency": {
                      "value": "726.63",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "549.60",
                      "currency": "USD"
                    }
                  },
                  "strikethrough": {
                    "billable_currency": {
                      "value": "650.00",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "491.64",
                      "currency": "USD"
                    }
                  },
                  "marketing_fee": { ... },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

Exibição de valor de oferta e desconto

Ao exibir um valor de desconto com base em uma oferta ou aviso fornecido nas APIs de disponibilidade e verificação de preços, determinados pontos de venda exigem que sejam fornecidos detalhes sobre o preço da tarifa padrão (por exemplo, o preço no qual o desconto é calculado). Consulte as declarações abaixo sobre qual terminologia usar.

UE: informe com clareza qual é o preço da tarifa padrão. Por exemplo, "Este preço é a tarifa padrão informada pela propriedade com base na sua busca".

Itália: use este texto: "Questo prezzo è basato sulla tariffa generalmente applicabile fornita dalla struttura per questa camera e per queste date".

Motivo de indisponibilidade

O recurso unavailable_reason permite solicitar informações práticas sobre a razão pela qual uma propriedade está totalmente indisponível para uma estadia definida (datas da estadia e ocupação). O parâmetro de solicitação opcional include=unavailable_reason deve ser incluído ao comprar para receber essa informação na resposta. Mas, nem todas as propriedades indisponíveis tem um motivo prático para não serem reservadas. Essas propriedades não vão ser apresentadas na resposta.

A resposta da compra pode incluir tanto propriedades disponíveis como indisponíveis. As propriedades indisponíveis vão incluir uma seção property_id, scoree unavailable_reason que inclui um code com uma breve explicação do porquê a propriedade está indisponível (em inglês) e data com informações adicionais que podem ser ajustadas na solicitação para disponibilizar propriedade/quartos/planos tarifários. Por exemplo, se um unavailable_reason code fosse adults_exceed_threshold, o 2 em data significaria que 2 adultos é o número máximo permitido para aquele quarto/tarifa e qualquer ocupação maior que 2 retornaria um erro.

Observação: várias restrições podem ser aplicadas a uma propriedade, mas apenas um unavailable_reason será retornado.

Exemplo

[
  {
    "property_id": "824739",
    "score": 12345,
    "unavailable_reason": {
      "code": "adults_exceed_threshold",
      "data": "2"
    }
  }
]

Veja aqui a lista completa de códigos retornados.

Filtros de comodidades

Como opção, você pode filtrar as propriedades retornadas na resposta da compra da Rapid usando o parâmetro de solicitação amenity_category junto de uma ou mais comodidades específicas.

Consulte a seção relativa às categorias de comodidades das Listas de referência de conteúdo aqui para ver uma lista de comodidades que podem ser usadas para filtrar a resposta.

Exemplos

Filtro de comodidade único:

&amenity_category=free_breakfast

Filtros de comodidade variados:

&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casino

Limitação de taxa

A otimização do tráfego é alcançada aplicando limites de taxa aos parceiros. Esses limites de taxa garantem a entrega contínua de um serviço estável e sustentável aos parceiros, garantindo também o uso eficiente dos sistemas do Expedia Group. Para o tráfego de compra, os fatores significativos para determinar a carga são o número de propriedades, o número de quartos e a duração das estadias que são buscadas em cada solicitação.

Consulte aqui mais informações sobre a limitação de taxa.

Verificação de preço

Confirma o preço apresentado pela resposta de compra. Use esta API para conferir se uma tarifa selecionada mais cedo ainda está válida antes iniciar a reserva. Se houver correspondência de preço, a resposta mostrará um link para solicitar uma reserva. Se houve uma mudança de preço, você recebe os novos detalhes do preço e um link para iniciar a reserva com o preço atualizado. Se a tarifa não estiver mais disponível, a resposta vai mostrar um novo link de solicitação de compra para buscar novas tarifas.

Pode haver uma pequena variação de aproximadamente 0,1% por quarto, por pessoa, por diária no valor de cobrança exibido no PriceCheck para totals.property_fees e fees em comparação com a resposta de compra anterior. Essa possível discrepância nas taxas da propriedade pode surgir somente quando request_currency e billable_currency forem diferentes para as tarifas Expedia Collect. A API vai funcionar sem erros nessa circunstância.

Opções de pagamento

Retorna as opções de pagamento. Use esta API para alimentar a sua página de pagamento e mostrar as formas de pagamento para uma reserva mais simples. As tarifas oferecidas como Property Collect vão retornar os tipos de cartão aceitos pela propriedade. Todos os outros tipos de tarifa informam as opções de pagamento aceitas pela Expedia.

Observações importantes

• language só usa pares hifenizados de dois dígitos para códigos de idiomas e de países. Consulte os idiomas compatíveis antes de integrar códigos.
• Os códigos de dois dígitos de country definem o ponto de venda do viajante, mas não afetam o conteúdo localizado.
• Dados estáticos (nomes, classificações por estrela, informações geográficas etc.) não são retornados. Apenas os dados de disponibilidade e tarifas são apresentados.
• Links de solicitação com token vão expirar após um breve período. Se um link de token retornar um erro HTTP 503, é porque o link deve ter expirado. Faça uma nova verificação de preço ou link de depósito de uma nova resposta de compra e tente de novo. Não armazene valores de link para reutilização em longo prazo.
• A Rapid API permite que propriedades atualizem o próprio conteúdo a qualquer momento. Solicitamos que você colabore em disponibilizar informações atualizadas a clientes. A API de compras oferece informações atualizadas sobre quartos e tarifas disponíveis. Para mais informações sobre o nível da propriedade, do quarto e da tarifa não encontradas nessa resposta, use a nossa API de conteúdo da propriedade.
• As APIs oferecem preços com base em apenas um quarto e a reserva de vários quartos exige um cálculo a mais por sua conta. Como parte dos requisitos de lançamento, a sua integração deve mostrar o detalhamento dos preços para os usuários finais em diferentes passos da reserva. O detalhamento pode ser encontrado neste link de documentação segura.

Para fazer solicitações de teste neste serviço, consulte a nossa documentação sobre solicitação de teste.

Detalhes da API

Explore as definições dos pontos de extremidade relacionados a compras nesta página e use o API Explorer ou outro software de teste para comparar os exemplos e as definições de esquemas com o resultado real.

Recursos adicionais

Não importa se deseja testar todos os pontos de extremidade da Rapid API, ou baixar a especificação OpenAPI ou a nossa coleção Postman Collection, você pode contar conosco.

Acessar API Explorer