Pular para o conteúdo

Content Catalog

Endpoints de conteúdo estático. Atualizados diariamente. Use para conteúdo de hotéis, planos de refeições e catálogos de cidades adequados a cache.

Método Caminho Propósito
GET /content-catalog/hotels Lista todos os hotéis disponíveis (info básica)
GET /content-catalog/hotels/{hotelId} Detalhe completo de um hotel
GET /content-catalog/mealplans Todos os planos de refeições
GET /content-catalog/cities Todas as cidades

Todos exigem Authorization: Bearer <access_token>.


Retorna a lista de hotéis disponíveis para o seu channel.

{
"hotels": [
{
"id": 100007,
"name": "Beachscape Kin Ha Villas & Suites Cancún",
"giataId": "50540",
"hotelBedsID": "8540",
"expediaIDRapid": "895806"
}
],
"total": 2
}
  • Sincronizar o inventário de hotéis diariamente.
  • Cruzar IDs com Giata, HotelBeds, Expedia EPS Rapid.

Retorna o conteúdo completo do hotel.

Parâmetro Tipo Descrição
language string en-us (default), es-mx, es-co, pt-br
{
"id": 100010,
"name": "Aquamarina Beach",
"category": "3.0",
"address": "Blvr Kukulcán km 4.5 Zona Hotelera Cancun",
"idCity": 26,
"city": "Cancún",
"destination": "Cancún",
"countryA2": "MX",
"country": "Mexico",
"zipCode": "77500",
"totalRooms": 94,
"geolocationX": "-86.79060280323029",
"geolocationY": "21.146537512859727",
"hotelBedsID": "4001",
"expediaIDRapid": "895724",
"giataId": "391934",
"telHotel": "+52998849-4606",
"description": "...",
"checkIn": "15:00",
"checkOut": "11:00",
"alerts": [],
"photos": ["https://img.cdnpth.com/..."],
"services": [
{ "serviceId": 0, "name": "Children's pool", "hasExtraCharge": false }
],
"rooms": [
{
"roomID": 26888541,
"name": "Standard Run of House",
"amenities": [],
"picture": "",
"image": { "cloudUri": "", "photoId": 0 },
"maxOccupancy": 4,
"bedType": "Subject to availability",
"bathroomType": "Private bathroom",
"smokingPolicy": "Non-Smoking",
"checkIn": "15:00",
"checkOut": "11:00"
},
{
"roomID": 4198203,
"name": "SEA VIEW OR PARTIAL SEA VIEW",
"amenities": ["Shower", "Balcony", "Satellite TV ", "Smoking rooms"],
"picture": "",
"image": { "cloudUri": "", "photoId": 0 },
"maxOccupancy": 4,
"bedType": "King-size bed 150-183 width (x1) or Double bed 131-150 width (x1)",
"bathroomType": "Private bathroom",
"smokingPolicy": "Non-Smoking",
"checkIn": "15:00-15:00",
"checkOut": "11:00-11:00"
}
],
"attributes": [
{ "attributeId": 3, "title": "3 stars or more", "uri": "3-estrellas-mas" }
],
"gallery": [
{ "photoID": 0, "cloudUri": "https://img.cdnpth.com/..." }
]
}
Campo Notas
category Categoria em estrelas como string (“3.0”, “4.5”, “5.0”, etc.)
giataId / hotelBedsID / expediaIDRapid IDs de mapeamento para Giata, HotelBeds e Expedia EPS Rapid. São retornados por este endpoint de detalhe, não apenas por GET /content-catalog/hotels. Presentes nas três amostras verificadas.
geolocationX Longitude — note o nome de eixo incomum
geolocationY Latitude
countryA2 Código de país ISO 3166-1 alpha-2. Use-o para fazer match por país.
country Nome de exibição, não normalizado. Para fazer match por país, use countryA2. Ver Data quality.
zipCode Pode vir como string vazia ("") em vez de vir ausente.
description Pode conter HTML (<br />, <p>): observado com tags em uma amostra e como texto simples sem tags em outra. As quebras de linha podem ser \n ou \r\n. As tags nem sempre estão balanceadas. Sanitize antes de renderizar.
attributes[] Array de objetos com attributeId (int), title (string) e uri (string). Observado com 6 entradas em uma amostra e vazio nas outras duas. O uri é um slug em espanhol ("3-estrellas-mas", "plan-europeo", "plan-todo-incluido"), enquanto o title vem em inglês ("3 stars or more", "Without food", "All inclusive"), com language em seu valor padrão: o uri não segue o idioma da requisição. Classifique por attributeId, não pelo title nem pelo uri.
alerts[] Observado sempre vazio. A forma preenchida ainda não está documentada.
totalRooms Inteiro cuja semântica não está definida. Não coincide de forma consistente com rooms.length: coincidiu exatamente em duas amostras e difere em uma terceira (94 contra 77 entradas). Também não corresponde ao número de quartos do hotel: o texto de description dessa mesma propriedade menciona 169. Não o exiba ao viajante nem o use para dimensionar inventário.
checkIn / checkOut (nível hotel) Horário do dia, não uma data. O formato varia por hotel: foram observados HH:MM e HH:MM:SS. Ver Time formats.
services[].serviceId Observado como 0 em todos os serviços das três amostras. Não é utilizável como identificador.
services[].description Opcional e frequentemente ausente: presente em uma amostra, ausente nas outras duas, onde todos os serviços traziam apenas serviceId, name e hasExtraCharge.
rooms[].checkIn Opcional: pode vir ausente. Formas observadas: HH:MM, HH:MM:SS e o intervalo HH:MM-HH:MM (p. ex. "15:00-23:59", "15:00-00:00", "15:00-15:00"). O intervalo é uma janela, não um horário. Ver Time formats.
rooms[].checkOut Opcional: pode vir ausente. Formas observadas: HH:MM, HH:MM:SS e o intervalo HH:MM-HH:MM (p. ex. "11:00-11:00"). Os intervalos não são exclusivos de checkIn. Ver Time formats.
rooms[].roomID ID do catálogo de conteúdo. Não presuma que corresponde ao rooms[].id retornado por /1.0/hotels/rates.
rooms[].amenities[] Array de strings simples, não de objetos. Pode vir vazio ou com dezenas de entradas dependendo do hotel. As cadeias não estão normalizadas — ver Data quality.
rooms[].picture String simples com a URL da foto do quarto. Pode estar vazia (""). Campo distinto de rooms[].image.
rooms[].image Objeto com cloudUri (string) e photoId (int). Alternativa estruturada a rooms[].picture. Na prática ambos podem estar vazios.
rooms[].maxOccupancy Número máximo de hóspedes permitidos no quarto.
rooms[].bedType Texto livre, não normalizado. Observado: "Subject to availability", "2 Twin Beds", "KING SIZE BED", "Single bed 80-130 width (x2)".
rooms[].bathroomType Tipo de banheiro (p. ex. "Private bathroom").
rooms[].smokingPolicy Política de fumo (p. ex. "Non-Smoking").
gallery[].photoID Observado com um ID real em uma amostra e como 0 em todas as entradas das outras duas. Não é confiável para identificar uma foto.
gallery[].extension Opcional. Presente em uma amostra, ausente nas outras duas. Sua presença correlaciona com o esquema de URL da imagem: um esquema de armazenamento expõe o ID no path e o outro usa um GUID.
Campo Formas observadas
checkIn / checkOut (nível hotel) HH:MM (p. ex. "15:00"), HH:MM:SS (p. ex. "15:00:00")
rooms[].checkIn HH:MM, HH:MM:SS, o intervalo HH:MM-HH:MM (p. ex. "15:00-23:59", "15:00-00:00", "15:00-15:00"), ou ausente
rooms[].checkOut HH:MM, HH:MM:SS, o intervalo HH:MM-HH:MM (p. ex. "11:00-11:00"), ou ausente

Nenhuma forma predomina. Uma amostra não trazia segundos em nenhum nível; outra trazia HH:MM:SS. Espere que a forma varie por hotel e por entrada.

A forma de intervalo é uma janela, não um horário, e não é exclusiva de checkIn: em uma amostra, 68 de 77 quartos retornaram "11:00-11:00" em rooms[].checkOut. Seu limite superior não é estável — foram observados como fechamento "23:59", "00:00" e o próprio valor de início — e o intervalo pode ser degenerado ("15:00-15:00", "11:00-11:00"). O limite inferior é a única parte que se lê de forma consistente nos três casos, e é isso que sustenta tomá-lo.

Trate esses valores como strings opacas de exibição, a menos que precise calcular com eles. Se calcular: verifique a presença, faça match contra todas as formas acima e tome o limite inferior do intervalo.

rooms[] pode conter várias entradas que descrevem o mesmo quarto físico, cada uma com seu próprio roomID. Em um hotel, rooms[] tinha 98 entradas com 70 nomes distintos, onde "2 Twin Premium Oceanfront" aparece três vezes, com roomID 20133744, 20175437 e 27854023.

O conteúdo do hotel é composto por mais de uma fonte e as entradas não são deduplicadas na resposta. Hoje não existe um campo que indique de qual fonte vem cada entrada, portanto as duplicatas não podem ser reconciliadas a partir da resposta.

O padrão não é específico de uma propriedade nem de um país. Em um segundo hotel, as 63 entradas se agrupam em quatro blocos, distinguíveis apenas por diferenças incidentais de forma e vocabulário:

rooms[].checkIn Quartos Vocabulário de amenities
15:00 7 "Vanity mirror", "TV LCD"
(ausente) 6 nomes de quarto em espanhol
15:00-00:00 45 "King-size bed 150-183 width (x1)"
15:00-23:59 5 "Composting", "LED light bulbs"

As entradas também se repetem dentro de um mesmo bloco, não apenas entre blocos. Em uma terceira propriedade — 77 entradas em três blocos — "SEA VIEW OR PARTIAL SEA VIEW" aparece três vezes, com roomID 4198203, 8426536 e 8426554, as três com o mesmo formato de horário e o mesmo vocabulário de amenities; "DOUBLE SEA VIEW", "QUADRUPLE SEA VIEW" e "TRIPLE SEA VIEW" aparecem duas vezes cada um dentro desse mesmo bloco. A duplicação, portanto, não se explica apenas pela mistura de fontes.

Consequências ao mapear quartos:

  • rooms[] não é uma lista canônica de tipos de quarto.
  • rooms.length não equivale ao número de tipos nem ao de quartos físicos.
  • Fazer match por name colapsa roomIDs distintos; fazer match por roomID gera duplicatas no catálogo do parceiro.
  • O array não está ordenado por roomID. No segundo hotel os últimos cinco roomID quebram a ordem ascendente, e no terceiro quem a quebra são os dois últimos (22502906, 22502908), o que é consistente com entradas concatenadas bloco a bloco. Não presuma nenhuma ordem em rooms[].

photos[] e gallery[] transportam as mesmas imagens. A igualdade elemento por elemento — photos ser exatamente a lista de gallery[].cloudUri — foi verificada em duas amostras: 102 URLs em uma, 50 na outra.

Consuma gallery[] e ignore photos[]. gallery[] nunca traz menos, mas nem sempre traz mais: em duas amostras não acrescentou nada sobre photos[], porque extension não vinha e todos os photoID eram 0.

Essa duplicação é cerca de um quarto do peso da resposta (~98 KB na amostra maior) — leve isso em conta ao sincronizar catálogos grandes.

Os valores chegam das fontes de conteúdo com normalização limitada. Trate todo campo de texto como entrada não confiável.

Campo Valor observado Nota
rooms[].amenities[] "Electronic key " Espaço no final. Aplique trim.
rooms[].amenities[] "Satellite TV " Espaço no final, igual a "Electronic key ".
rooms[].amenities[] "($)Internet access" Marcador de custo embutido no texto.
rooms[].amenities[] "Base para iPod" Idioma misturado dentro de uma resposta em inglês.
rooms[].amenities[] "Number of bedrooms", "Smoking rooms" Rótulos de atributo sem valor associado, não amenities.
rooms[].bedType "Sujetas a disponibilidad" Idioma misturado: convive com "Subject to availability" na mesma resposta em inglês.
telHotel "++84 0297 3683999" Prefixo + duplicado.
telHotel "+52998891-5650" Código de país sem separação do número.
country "Viet nam" Nome de exibição não normalizado. Use countryA2 para fazer match por país.
address "KHU DU LICH BAI DAI " Espaços no final. Aplique trim.
zipCode "" Cadeia vazia em vez de campo ausente.
  • rooms[].amenities[]: não use a cadeia como chave nem presuma um vocabulário fechado. O conjunto de valores varia entre fontes de conteúdo.
  • telHotel: normalize antes de validar ou discar. O formato não é consistente entre hotéis.
Código HTTP Mensagem
1001 404 hotel not found
1002 400 hotelId must be an integer

Parâmetro Tipo Descrição
language string en-us (default), es-mx
{
"mealPlans": [
{ "code": "A", "description": "American breakfast" },
{ "code": "AA", "description": "Imperial Christmas and New Years Eve" },
{ "code": "AB", "description": "Romantic Getaway" }
],
"total": 3
}
Código Descrição (en-us)
E Room Only
L Breakfast
A American breakfast
B Buffet breakfast
F Breakfast & dinner included
G Breakfast, lunch & dinner included
I All Inclusive

(Os códigos variam por hotel — sempre cruze com GET /content-catalog/mealplans.)


{
"cities": [
{ "idCity": 1, "name": "Acapulco", "country": "Mexico", "countryA2": "MX" },
{ "idCity": 2, "name": "Aguascalientes", "country": "Mexico", "countryA2": "MX" }
],
"total": 2
}
  • Filtrar / segmentar hotéis por cidade.
  • Relacionar idCity com as respostas de detalhe de hotel.

Como os dados do Content Catalog são atualizados diariamente, faça cache das respostas por 24h:

  • /content-catalog/hotels — sincronização completa uma vez por dia.
  • /content-catalog/hotels/{id} — cache por hotel, atualize semanalmente salvo que se precise de conteúdo dinâmico.
  • /content-catalog/mealplans — cache por 7 dias.
  • /content-catalog/cities — cache por 30 dias.