Hotéis (Hotels)

Busque hotéis e hospedagens com disponibilidade e preços em tempo real.

Fluxo Completo

Para realizar uma reserva de hotel via API, siga este fluxo:

Buscar destinos — Use o autocomplete para encontrar o código da cidade
Buscar hotéis — Pesquise hotéis disponíveis com o código da cidade e datas
Criar reserva — Use os dados do hotel retornado na busca para criar a reserva via API de Reservas

Os resultados da busca têm validade limitada (~20 minutos). Crie a reserva logo após a busca para garantir preço e disponibilidade.

Buscar Destinos (Autocomplete)

GET /api/public/hotels/destinations

Busca cidades/destinos disponíveis por nome. Este endpoint é público e não requer autenticação. O código da cidade retornado (code) deve ser usado como cityCode na busca de hotéis.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`q`	string	Sim	Termo de busca (mínimo 2 caracteres). Ex: `rio de janeiro`, `paris`
`limit`	number	Não	Máximo de resultados (padrão: 10, máx: 50)

Exemplo de Requisição

curl -X GET "https://app.moblix.co/api/public/hotels/destinations?q=rio+de+janeiro&limit=5"

const response = await fetch(
  'https://app.moblix.co/api/public/hotels/destinations?q=rio+de+janeiro&limit=5'
);

const data = await response.json();
console.log(data.destinations);

import requests

response = requests.get(
    'https://app.moblix.co/api/public/hotels/destinations',
    params={'q': 'rio de janeiro', 'limit': 5}
)

data = response.json()
print(data['destinations'])

Resposta

{
  "destinations": [
    {
      "code": "75",
      "label": "Rio de Janeiro, Brasil",
      "city": "Rio de Janeiro",
      "country": "Brasil",
      "countryCode": "BR",
      "value": "75 - Rio de Janeiro"
    },
    {
      "code": "1234",
      "label": "Rio Branco, Brasil",
      "city": "Rio Branco",
      "country": "Brasil",
      "countryCode": "BR",
      "value": "1234 - Rio Branco"
    }
  ],
  "count": 2,
  "query": "rio de janeiro"
}

Campos da Resposta

Campo	Tipo	Descrição
`code`	string	Código da cidade (usar como `cityCode` na busca)
`label`	string	Nome formatado para exibição
`city`	string	Nome da cidade
`country`	string	Nome do país
`countryCode`	string	Código do país (ISO 2)
`value`	string	Valor combinado código + nome

Buscar Hotéis

POST /api/v1/hotels/search

Realiza uma busca de hotéis disponíveis para as datas especificadas.

Parâmetros

{
  "cityCode": "75",
  "checkIn": "2026-03-15",
  "checkOut": "2026-03-20",
  "adults": 2,
  "children": 0,
  "rooms": 1,
  "nationality": "BR"
}

Campo	Tipo	Obrigatório	Descrição
`cityCode`	string	Sim	Código da cidade (obtido via autocomplete de destinos)
`checkIn`	string	Sim	Data de entrada no formato YYYY-MM-DD
`checkOut`	string	Sim	Data de saída no formato YYYY-MM-DD
`adults`	number	Sim	Número total de adultos (1-9)
`children`	number	Não	Número total de crianças (padrão: 0)
`rooms`	number	Não	Número de quartos (1-5, padrão: 1)
`nationality`	string	Não	Nacionalidade dos hóspedes, código ISO 2 letras (padrão: BR)

O campo cityCode é um código numérico do fornecedor, não o nome da cidade. Use o endpoint de Buscar Destinos para obter o código correto.

Exemplo de Requisição

curl -X POST https://app.moblix.co/api/v1/hotels/search \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "cityCode": "75",
    "checkIn": "2026-03-15",
    "checkOut": "2026-03-20",
    "adults": 2,
    "rooms": 1
  }'

const response = await fetch('https://app.moblix.co/api/v1/hotels/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cityCode: '75',
    checkIn: '2026-03-15',
    checkOut: '2026-03-20',
    adults: 2,
    rooms: 1
  })
});

const data = await response.json();
console.log(data.hotels);

import requests

response = requests.post(
    'https://app.moblix.co/api/v1/hotels/search',
    headers={
        'Authorization': 'Bearer mbx_live_sua_chave_aqui',
        'Content-Type': 'application/json'
    },
    json={
        'cityCode': '75',
        'checkIn': '2026-03-15',
        'checkOut': '2026-03-20',
        'adults': 2,
        'rooms': 1
    }
)

data = response.json()
print(data['hotels'])

Resposta

{
  "data": {
    "hotels": [
      {
        "id": "bestbuy:12345",
        "name": "Copacabana Palace",
        "location": {
          "address": "Av. Atlântica, 1702 - Copacabana",
          "city": "75",
          "country": "BR",
          "coordinates": {
            "latitude": -22.9671,
            "longitude": -43.1795
          }
        },
        "rating": 5,
        "stars": 5,
        "images": [
          "https://images.example.com/hotel/main.jpg",
          "https://images.example.com/hotel/thumb.jpg"
        ],
        "amenities": [],
        "price": {
          "amount": 900.00,
          "currency": "BRL",
          "perNight": true,
          "total": 4500.00
        },
        "availability": {
          "checkIn": "2026-03-15",
          "checkOut": "2026-03-20",
          "nights": 5,
          "roomsAvailable": 3
        },
        "description": "Hotel de luxo à beira-mar",
        "provider": "BestBuy",
        "offersCount": 3,
        "searchSessionId": "uuid-da-sessao"
      }
    ],
    "summary": {
      "totalResults": 45,
      "minPrice": 250.00,
      "maxPrice": 2400.00,
      "duration": 3500
    },
    "searchSessionId": "uuid-da-sessao",
    "meta": {
      "searchParams": {
        "cityCode": "75",
        "checkIn": "2026-03-15",
        "checkOut": "2026-03-20",
        "adults": 2,
        "children": 0,
        "rooms": 1,
        "nationality": "BR"
      },
      "teamId": "uuid-do-time"
    }
  },
  "timestamp": "2026-01-26T10:30:00Z"
}

Estrutura da Resposta

Hotel

Campo	Tipo	Descrição
`id`	string	ID único no formato `provider:hotelId`
`name`	string	Nome do hotel
`location`	Location	Endereço e coordenadas
`rating`	number	Categoria em estrelas (1-5)
`stars`	number	Estrelas do hotel (1-5)
`images`	string[]	URLs das imagens do hotel
`amenities`	string[]	Lista de comodidades (pode estar vazia)
`price`	Price	Informações de preço
`availability`	Availability	Disponibilidade e datas
`description`	string	Descrição ou observações do hotel
`provider`	string	Nome do fornecedor
`offersCount`	number	Número de ofertas/quartos disponíveis
`searchSessionId`	string	ID da sessão de busca

Location

Campo	Tipo	Descrição
`address`	string	Endereço do hotel
`city`	string	Código da cidade
`country`	string	Código do país
`coordinates`	object	`latitude` e `longitude`

Price

Campo	Tipo	Descrição
`amount`	number	Preço por diária (melhor oferta)
`currency`	string	Moeda (BRL)
`perNight`	boolean	Sempre `true` — indica que `amount` é por diária
`total`	number	Preço total da estadia (melhor oferta)

Availability

Campo	Tipo	Descrição
`checkIn`	string	Data de check-in
`checkOut`	string	Data de check-out
`nights`	number	Número de diárias
`roomsAvailable`	number	Quantidade de ofertas disponíveis

Summary

Campo	Tipo	Descrição
`totalResults`	number	Total de hotéis encontrados
`minPrice`	number	Menor preço por diária
`maxPrice`	number	Maior preço por diária
`duration`	number	Tempo da busca em milissegundos

Notas Importantes

A busca de hotéis retorna apenas propriedades com disponibilidade para as datas especificadas. Os preços exibidos são da melhor oferta (menor preço) de cada hotel.

Os preços podem variar dependendo da demanda. A sessão de busca (searchSessionId) expira em aproximadamente 20 minutos. Crie a reserva dentro desse período.

Rate Limit

Endpoint	Limite
`/hotels/search`	30 req/min

Hotéis

On this page