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 precisar reservar mais de 8 quartos de uma só vez, entre em contato com seu gerente de conta. Estamos trabalhando para expandir as reservas em grupo, e compartilhar suas necessidades nos ajudará a definir nossa solução.
Alterações na exibição de preços
Informamos que, devido a alterações recentes na legislação local:
- Regulamento de Exibição de Preços da Califórnia (Projeto de Lei 537 da Assembleia da Califórnia) que entra 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 a partir de 2025-01-01
Esperamos que outras regulamentações sejam implementadas e não atualizaremos esta página para cada uma delas; estes são apenas dois exemplos.
Por que as mudanças?
Algumas jurisdições estão implementando leis que determinam como as tarifas são exibidas para os viajantes. Cada lei é ligeiramente diferente, porém, a forma como implementamos as alterações permitirá o cumprimento individualizado.
A Expedia Group fez alterações em sua API para permitir que os parceiros de API exibam os preços de diversas maneiras. Em última análise, porém, cada parceiro que utiliza a API do Expedia Group é responsável por garantir que a forma como exibe as informações de viagens 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 cobrados pela Expedia e propriedade para toda a estadia. Uma versão riscada 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 forma como os impostos e taxas são discriminados na resposta da API. Todas as taxas cobradas pela Expedia estão incluídas no detalhamento de preços por noite e estadia, e todos os impostos cobrados pela Expedia estão incluídos no detalhamento de preços por noite e estadia.property_fee``tax_and_service_fee
Para tarifas Expedia Collect, o billable_currencydos campos property_inclusivee property_inclusive_strikethroughestará na moeda especificada no contrato de Expedia Group com o provedor, que geralmente é a moeda local de 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 tarifas do Expedia Collect será o mesmo que o request_currency.
A resposta da Loja pode ter os valores coletados propriedade agrupados de forma diferente do valor apresentado na resposta do Conteúdo. Os totais ainda devem coincidir corretamente.
Essa foi uma mudança global implementada em todas as propriedades. Para mais informações sobre as alterações, entre em contato com seu gerente de conta.
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 de dezembro a 31 de dezembro, 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_purposepermite que você classifique seu viajante como negócios ou lazer. Todos os parceiros da Rapid podem usar o parâmetro travel_purposepara ajudar as propriedades a reconhecer e atender melhor os viajantes corporativos.
Para os parceiros elegíveis para comparar tarifas comerciais, será necessário usar travel_purpose=businessna solicitação de comparação para receber as tarifas comerciais na resposta da comparação. 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=businessMerchandising
Fizemos as seguintes alterações na API de Compras para dar suporte aos fluxos de merchandising e tornar a sua integração com a API de Merchandising perfeita:
- Os parceiros podem usar o novo filtro
dealdisponível no endpoint de Disponibilidade de Compras Rápidas para receber apenas tarifas que apresentem promoções ativas. Isso dá aos parceiros a flexibilidade de criar uma solicitação de compras com foco exclusivo em merchandising e garantir que todas as taxas retornadas tenham um atributodeal. - Um novo cabeçalho de solicitação chamado
Campaign-Idestá disponível no endpoint de Disponibilidade de Compras da Rapid para que você possa indicar que a chamada específica à API de Disponibilidade de Compras que você está fazendo não é uma chamada regular e, na verdade, se deve aos seus esforços promocionais de merchandising (em outras palavras, isso significará que uma solicitação à API de Disponibilidade de Compras foi feita quando o viajante entrou na experiência de compra devido à promoção da campanha). Aceitaremos apenas um ID de campanha por chamada à API de Compras.
Preç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 de preços e maior flexibilidade.
As três opções são:
refundablenon_refundablepartially_refundable
O que significa parcialmente reembolsável?
O termo "parcialmente reembolsável" refere-se a tarifas em que:
- A penalidade de cancelamento é maior que 0, mas menor que o valor total da reserva.
e/ou
- Existem intervalos de datas non-refundable dentro do período de permanência.
**Como aproveitar o campo ** current_refundability é melhor do que usar apenas o indicador booleano de reembolso?
Orefundable Um indicador booleano mostra se uma tarifa é totalmente reembolsável ou não, mas retorna um valor.false resultado para tarifas parcialmente reembolsáveis, o que é enganoso para os viajantes. Ocurrent_refundability O campo oferece uma opção mais detalhada que fornece informações mais precisas sobre a reembolsabilidade das tarifas.
Como os parceiros podem receber o current_refundability ** campo na resposta da Loja?**
Os parceiros precisam solicitar ocurrent_refundability campo sob oinclude parâmetro na 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"
}
}
]Ver a lista completa de códigos retornada .
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.
Leia mais sobre taxa de limitação
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 ligeira variação de aproximadamente 0,1% (por quarto × pessoa × noite) no valor faturável exibido.PriceCheck paratotals.property_fees efees Em comparação com a resposta anterior da loja, que poderia incluir um ajuste do valor para zero. A discrepância nas taxas devidas no propriedade surge quando orequest_currency ebillable_currency As tarifas do Expedia Collect variam. A funcionalidade da API não será afetada por essa discrepância.
Pausar e Continuar
Alguns itens do estoque não são elegíveis para reserva e retomada. Parceiros que utilizam o recurso de retenção e retomada podem acessar essas taxas incrementais adotando o indicador de comparação de taxas non-holdable. Mais detalhes podem ser encontrados aqui .
Opções de pagamento
Retorna as opções de pagamento aceitas nos casos em que a Expedia recebe 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. A análise detalhada pode ser encontrada abaixo. link para 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órias 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 de acordo com a atividade in-stay ou impostos de hospedagem variáveis em alguns mercados, como o Japão e a Colômbia. Informações sobre como esses impostos e taxas variáveis são calculados estarão disponíveis na API de Conteúdo. Esta informação deve ser exibida de forma 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.