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

Para a integração com BestBuy Travel, o pagamento é sempre processado no gateway de pagamento da sua agência (via PIX, cartão de crédito ou boleto configurado na Moblix). A BestBuy não processa pagamentos diretamente dos clientes.

Modos de Emissão

Ao configurar as credenciais da BestBuy no painel, você pode escolher entre dois modos de emissão:

Modo Automático (Faturamento)

Cliente paga → Sistema cria reserva automaticamente na BestBuy → Faturamento

✅ Quando usar: Para vendas onde você quer emissão imediata e faturamento automático com o fornecedor
⚡ A reserva é criada automaticamente na BestBuy assim que o pagamento é confirmado
💰 Você é faturado automaticamente pela BestBuy pela reserva criada
📧 Cliente recebe confirmação imediata com voucher

Modo Manual (Confirmação posterior)

Cliente paga → Pedido interno criado → Agente confirma manualmente → Reserva na BestBuy

✅ Quando usar: Para cotações ou quando você quer decidir se/quando emitir no fornecedor
⏸️ A reserva fica como "Pendente de Confirmação" após o pagamento
🔒 Você decide manualmente quando confirmar no fornecedor pelo painel
💰 Só é faturado quando você confirmar manualmente

O modo de emissão é configurado em Configurações → Integrações → Provedores de Hotéis no painel da Moblix.

Fluxo de Faturamento

Cliente paga na sua agência (via gateway Moblix)
Você recebe o valor integral do cliente
Fornecedor fatura você pela reserva (apenas no modo automático ou após confirmação manual)
Você é responsável por pagar o fornecedor conforme contrato comercial

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

Hotéis (Hotels)

Fluxo Completo

Buscar Destinos (Autocomplete)

Query Parameters

Exemplo de Requisição

Resposta

Campos da Resposta

Buscar Hotéis

Parâmetros

Exemplo de Requisição

Resposta

Estrutura da Resposta

Hotel

Location

Price

Availability

Summary

Modos de Emissão e Pagamento

Como funciona o pagamento

Modos de Emissão

Modo Automático (Faturamento)

Modo Manual (Confirmação posterior)

Fluxo de Faturamento

Notas Importantes

Rate Limit

On this page