HotelRates
Endpoint
Seção intitulada “Endpoint”POST {base_url}/1.0/hotels/ratesRetorna disponibilidade e tarifas de um ou mais hotéis em um intervalo de datas.
Headers
Seção intitulada “Headers”| Header | Valor |
|---|---|
Authorization |
Bearer <access_token> |
Content-Type |
application/json |
Accept |
application/json |
Accept-Encoding |
gzip |
Query params
Seção intitulada “Query params”| Parâmetro | Obrigatório | Tipo | Notas |
|---|---|---|---|
language |
No | string | Idioma do conteúdo da resposta. Valores aceitos: en-us, es-mx. Default: en-us |
Seu channel tem um idioma padrão (inglês, salvo configuração diferente); para solicitar outro, use ?language= — ver Idiomas.
Corpo da requisição
Seção intitulada “Corpo da requisição”{ "checkIn": "2027-05-15", "checkOut": "2027-05-16", "roomCriteria": [ { "paxes": [ { "age": 30 } ] } ], "hotelIds": [100652], "hotelRateFilter": { "nonRefundable": false }, "market": "MX"}Campos do body
Seção intitulada “Campos do body”| Campo | Obrigatório | Tipo | Notas |
|---|---|---|---|
checkIn |
Yes | string (YYYY-MM-DD) | Não pode ser uma data passada |
checkOut |
Yes | string (YYYY-MM-DD) | Deve ser > checkIn |
roomCriteria[] |
Yes | array | Uma entrada por quarto solicitado |
roomCriteria[].paxes[] |
Yes | array | Lista de pax — exige ao menos um adulto (18+) |
roomCriteria[].paxes[].age |
Yes | int | Menor de 17 = menor de idade |
hotelIds[] |
Yes | array of int | Máximo de 50 IDs por chamada |
hotelRateFilter.nonRefundable |
No | bool | Filtro de tarifas. Em uma amostra de Integration, true e false retornaram as mesmas 19 tarifas — 7 não reembolsáveis e 12 reembolsáveis em ambas — portanto não dependa dele para reduzir resultados e verifique cancellationPolicies em cada tarifa. Default: false |
market |
No | string | Código de país ISO do catálogo de Market (p. ex. MX, IN, US, ES) |
Se você enviar name e surname em roomCriteria[].paxes[], não espere que o BookingGet os retorne — ver BookingGet. Para enviar os nomes dos hóspedes por quarto, use o BookingHold: ver Guest data in the hold.
Resposta (sucesso)
Seção intitulada “Resposta (sucesso)”{ "hotels": [ { "id": 100652, "name": "Ocean View Cancun Arenas", "rooms": [ { "id": 16370816, "name": "Standard", "rates": [ { "rateKey": "RMDsX5...AAB=", "clientCurrency": "USD", "cancellationPolicies": [ { "startDate": "2027-05-12T00:00:00Z", "endDate": "2027-05-15T23:59:59Z", "amount": 116.00, "currency": "USD" } ], "reservationPolicies": [ { "type": "MEAL_PLAN", "code": "I", "description": "All Inclusive" }, { "type": "RESERVATION", "code": "PREPAID", "description": "Prepaid" } ], "amount": 116.00, "publicAmount": 135.98, "taxes": { "total": 16.00, "details": [] }, "feesNotIncluded": { "total": 0, "details": [], "currency": "" } } ] } ] } ], "eventId": "93072334-e0f6-4abd-9c9c-02ffca872382"}Campos da resposta
Seção intitulada “Campos da resposta”| Campo | Tipo | Descrição |
|---|---|---|
hotels[].id |
int | Identificador do hotel |
hotels[].name |
string | Nome do hotel |
hotels[].rooms[].id |
int | ID do tipo de quarto |
hotels[].rooms[].name |
string | Nome do quarto |
hotels[].rooms[].rates[].rateKey |
string | Use para o CheckRates — válido 60 min |
hotels[].rooms[].rates[].clientCurrency |
string | Moeda dos preços exibidos |
hotels[].rooms[].rates[].amount |
decimal | Valor líquido que a agência paga |
hotels[].rooms[].rates[].publicAmount |
decimal | Preço de venda recomendado (inclui margem) |
hotels[].rooms[].rates[].cancellationPolicies |
array | Penalidade por intervalo de datas (UTC) |
hotels[].rooms[].rates[].reservationPolicies |
array | Plano de refeições + tipo de reserva |
hotels[].rooms[].rates[].taxes |
object | Obrigatórios + outros (informativo) |
hotels[].rooms[].rates[].feesNotIncluded |
object | Taxas cobradas no check-in do hotel |
eventId |
string | ID de rastreamento — inclua ao reportar problemas |
Como identificar tarifas não reembolsáveis
Seção intitulada “Como identificar tarifas não reembolsáveis”Uma tarifa é efetivamente não reembolsável quando:
cancellationPolicies[i].amount === rates.amountA penalidade iguala o preço da tarifa → penalidade de 100% → não há janela real de reembolso.
Erros específicos deste endpoint
Seção intitulada “Erros específicos deste endpoint”| Código | HTTP | Mensagem | Causa | O que fazer |
|---|---|---|---|---|
| 429 | 429 | Request rate limit exceeded | Muitas requisições em pouco tempo | Reduza o ritmo das requisições e tente novamente com espera |
| 1002 | 401 | agency configuration not Found | Channel/agência não provisionada | Contate a PriceTravel com a requisição, a resposta e o eventId |
| 1003 | 400 | Invalid agency templateId | Problema de configuração da agência na PT | Contate a PriceTravel com a requisição, a resposta e o eventId |
| 3001 | 400 | CheckIn can not be a past date | checkIn é anterior a hoje |
Envie um checkIn de hoje ou posterior |
| 3002 | 400 | CheckOut can not be earlier or equal to CheckIn | checkOut é igual ou anterior ao checkIn |
Envie um checkOut posterior ao checkIn |
| 3003 | 400 | Can’t quote more than 28 days | O intervalo solicitado excede 28 dias | Divida a estadia em requisições de 28 dias ou menos |
| 3004 | 400 | All rooms must contain at least one adult (18+) | Um quarto em roomCriteria não tem nenhum pax de 18 anos ou mais |
Inclua pelo menos um pax de 18 anos ou mais em cada quarto |
| 4001 | 500 | Invalid Channel Id on Rate Limiter | Interno | Contate a PriceTravel com a requisição, a resposta e o eventId |
| 5001 | 500 | Miss-match of channel Id | Divergência de channel | Contate a PriceTravel com a requisição, a resposta e o eventId |
Padrões de diagnóstico
Seção intitulada “Padrões de diagnóstico”| Sintoma | Causa provável |
|---|---|
hotels[] vazio mas sem erro |
Não há disponibilidade para essas datas/critérios |
| O mesmo hotel retorna tarifas em um minuto e no seguinte não | Flutuação de inventário em tempo real do fornecedor |
| 429 a cada retentativa | Rate limit do channel — recue e tente novamente com atraso |
Fees currency: "" |
O hotel não cobra taxas na chegada |

