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 de uma vez, entre em contato com seu gerente de conta. Estamos trabalhando para expandir as reservas de grupos e compartilhar suas necessidades ajudará a informar nossa solução.
Alterações na exibição de preços
Informamos que sobre as mudanças recentes devido às regulamentações locais:
- Regulamento de Exibição de Preços da Califórnia (Projeto de Lei 537 da Assembleia da Califórnia) em vigor a partir de 2024-07-01
- Regulamento de Exibição de Preços de Minnesota (Capítulo 111--H.F.No. 3438) que entra em vigor em 2025-01-01
Esperamos que outras regulamentações sejam implementadas e não atualizaremos esta página para cada uma delas. Esses são apenas dois exemplos.
Por que as mudanças?
Certas jurisdições estão implementando leis que determinam como as tarifas são exibidas para os viajantes. Cada lei é um pouco diferente, no entanto, a maneira como implementamos as mudanças permitirá o cumprimento individualizado.
Expedia Group fez alterações em sua API para permitir que os parceiros da API exibam preços de diversas maneiras. No entanto, em última análise, cada parceiro que usa a API do Expedia Group é responsável por garantir que a maneira como ela exibe as informações de viagem e os preços da Expedia esteja em conformidade com a lei.
Quais são as mudanças?
A Expedia aprimorou o Rapid API para incluir um novo campo property_inclusive contendo o preço total que inclui a tarifa base e todas as taxas e impostos coletados pela Expedia e propriedade para toda a estadia. Uma versão tachada deste preço total também está disponível em um novo campo property_inclusive_strikethrough. Além dos novos campos de exibição inclusivos propriedade, realinhamos a maneira como impostos e taxas são discriminados na resposta da API. Todas as taxas coletadas pela Expedia fazem parte do tipo de detalhamento de preço por noite e estadia property_fee, e todos os impostos coletados pela Expedia fazem parte do tipo de detalhamento de preço por noite e estadia tax_and_service_fee.
Para tarifas do Expedia Collect, o billable_currencydos campos property_inclusivee property_inclusive_strikethroughestará na moeda especificada no contrato do Expedia Group com o provedor, que geralmente é a moeda local do propriedade. Isso é independente do request_currency, porque os campos property_inclusivee property_inclusive_strikethroughpodem incluir taxas cobradas no propriedade na moeda local. Esse comportamento difere dos campos inclusivee inclusive_strikethrough, onde o billable_currencypara as taxas do Expedia Collect será o mesmo que o request_currency.
A resposta da Loja pode ter os valores coletados de propriedade agrupados de forma diferente do valor apresentado na resposta de Conteúdo. Os totais ainda devem corresponder corretamente.
Esta foi uma mudança global implementada em todas as propriedades. Entre em contato com seu gerente de conta para quaisquer dúvidas adicionais 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. Faça uma solicitação à API de compras para Propriedade 19248 para uma estadia de 22 de dezembro a 5 de janeiro. No objeto marketing_fee_incentivesda resposta da API de compras , você verá que há um incentivo disponível para uma parte da estadia solicitada de 22 a 31 de dezembro, o que representa 10 das 14 noites de estadia.
Exemplo de solicitação
curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-01-05\
¤cy=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=businessPreço riscado
- O campo
strikethroughfornece 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_strikethroughapresenta 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".
Opções de reembolso
O campo current_refundabilitypermite que os parceiros exibam todas as opções de reembolso, oferecendo aos viajantes transparência nas tarifas e maior flexibilidade.
As três opções são:
refundablenon_refundablepartially_refundable
O que significa parcialmente reembolsável?
Parcialmente reembolsável refere-se a tarifas onde:
- A penalidade de cancelamento é maior que 0, mas menor que o valor total da reserva.
e/ou
- Há intervalos de datas non-refundable dentro do período de estadia.
**Como aproveitar o campo ** current_refundability é melhor do que usar apenas o sinalizador booleano reembolsável?
O sinalizador booleano refundableindica se uma tarifa é totalmente reembolsável ou não, mas retorna um resultado falsepara tarifas parcialmente reembolsáveis, o que é enganoso para os viajantes. O campo current_refundabilityoferece uma opção mais detalhada que fornece informações mais precisas sobre a possibilidade de reembolso das taxas.
**Como os parceiros podem receber o campo ** current_refundability na resposta da Loja?
Os parceiros precisam solicitar o campo current_refundabilityno parâmetro includena solicitação da Loja.
Exemplo
"property_id": "23060",
"status": "available".
"rates": [
{
"id": "201392692",
"status": "available",
...
...
...
...
"current_refundability": partially_refundable,
"cancel_penalties":[
{
"start": "2024-10-08T23:59:00.000+02:00",
"end": "2024-10-09T23:59:00.000+02:00",
"nights":"1",
"currency": "EUR"
}
]
}
]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_breakfastFiltros de comodidade variados:
&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casinoLimitaçã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 × pessoa × noite) no valor faturável exibido em PriceCheckpara totals.property_feese feesem comparação com a resposta anterior da Loja, o que pode incluir um valor ajustado para zero. A discrepância nas taxas devidas no propriedade surge quando request_currencye billable_currencydiferem nas taxas do Expedia Collect. A função da API não será afetada por essa discrepância.
Pausar e Continuar
Alguns estoques não são elegíveis para retenção e retomada. Os parceiros que usam retenção e retomada podem acessar essas taxas incrementais adotando o indicador de compras de taxas non-holdable. Mais detalhes podem ser encontrados aqui .
Opções de pagamento
Retorna as opções de pagamento aceitas onde a Expedia está recebendo o pagamento do viajante final (EPS MOR). Use esta API para alimentar a sua página de pagamento e mostrar as formas de pagamento para uma reserva sem percalços.
Observações importantes
languagesó 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
countrydefinem 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.
Impostos e taxas variáveis
Pode haver impostos e taxas obrigatórios que não estão incluídos no preço total porque não podem ser calculados no momento da reserva, por exemplo, taxas que variam com base na atividade in-stay ou impostos de acomodação variáveis em alguns mercados, como Japão e Colômbia. Informações sobre como esses impostos e taxas variáveis são calculados estarão disponíveis na API de conteúdo. Essas informações devem ser exibidas em local visível aos viajantes.
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.