Hotéis (Hotels)

Busque hotéis e hospedagens com disponibilidade e preços em tempo real, e crie reservas com pagamento integrado.

Fluxo Completo

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

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
Detalhes do hotel (opcional) — Obtenha descrição completa, fotos, facilidades
Pré-reservar (Prebook) — Valide a oferta e reserve temporariamente por 20 minutos
Confirmar reserva (Book) — Envie os dados dos hóspedes e pagamento para criar a reserva

GET  /api/v1/hotels/destinations        →  cityCode
POST /api/v1/hotels/search              →  hotels[] com ofertas
POST /api/v1/hotels/details             →  detalhes, fotos, facilidades
POST /api/v1/hotels/prebook             →  prebook_token (20 min)
POST /api/v1/hotels/book                →  booking + pagamento

Os resultados da busca têm validade limitada (~20 minutos). Complete o fluxo de prebook e book dentro desse período para garantir preço e disponibilidade.

1. Buscar Destinos (Autocomplete)

GET /api/v1/hotels/destinations

Busca cidades/destinos disponíveis por nome. Retorna códigos de cidade que devem ser usados como cityCode na busca de hotéis.

Autenticação obrigatória: Requer API key no header Authorization.

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.net/api/v1/hotels/destinations?q=rio+de+janeiro&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.moblix.net/api/v1/hotels/destinations?q=rio+de+janeiro&limit=5',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

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

import requests

response = requests.get(
    'https://app.moblix.net/api/v1/hotels/destinations',
    params={'q': 'rio de janeiro', 'limit': 5},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

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

Resposta

{
  "data": {
    "destinations": [
      {
        "code": "1650",
        "label": "Rio De Janeiro, Brasil",
        "city": "Rio De Janeiro",
        "country": "Brasil",
        "countryCode": "BR",
        "value": "1650 - Rio De Janeiro"
      },
      {
        "code": "2933",
        "label": "Rio De Janeiro-galeao Airport, Brasil",
        "city": "Rio De Janeiro-galeao Airport",
        "country": "Brasil",
        "countryCode": "BR",
        "value": "2933 - Rio De Janeiro-galeao Airport"
      }
    ],
    "count": 2,
    "query": "Rio de Janeiro"
  },
  "timestamp": "2026-02-19T15:50:18.451Z"
}

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

2. Buscar Hotéis

POST /api/v1/hotels/search

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

Parâmetros

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

Campo	Tipo	Obrigatório	Descrição
`cityCode`	string	Condicional	Código da cidade (obtido via autocomplete de destinos). Obrigatório se `hotelIds` não for informado
`hotelIds`	string[]	Condicional	Lista de IDs de hotéis para busca específica (máx. 500). Obrigatório se `cityCode` não for informado
`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)

Pelo menos um de cityCode ou hotelIds deve ser informado. O 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. O hotelIds aceita IDs de hotéis do provedor (campo hotelId da resposta do search).

Exemplo de Requisição

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

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

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

import requests

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

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

Resposta

{
  "data": {
    "hotels": [
      {
        "id": "bestbuy:6931",
        "name": "BELMOND COPACABANA PALACE",
        "hotelId": "6931",
        "hotelSearchCode": "20608180/3661045776465014655/1022",
        "location": {
          "address": "COPACABANA",
          "city": "Rio De Janeiro",
          "country": "Brasil",
          "countryCode": "BR",
          "coordinates": {
            "latitude": -22.967413,
            "longitude": -43.178798
          }
        },
        "rating": 5,
        "stars": 5,
        "images": [
          "https://i.travelapi.com/lodging/1000000/10000/7200/7130/b2fc212d_b.jpg",
          "https://i.travelapi.com/lodging/1000000/10000/7200/7130/b2fc212d_t.jpg"
        ],
        "amenities": [],
        "price": {
          "amount": 4081.00,
          "currency": "BRL",
          "perNight": true,
          "total": 12243.00
        },
        "availability": {
          "checkIn": "2026-03-15",
          "checkOut": "2026-03-18",
          "nights": 3,
          "roomsAvailable": 1
        },
        "description": "IF YOU FAIL TO CHECK-IN FOR THIS RESERVATION...",
        "provider": "BestBuy Travel",
        "offersCount": 1,
        "offers": [
          {
            "hotelSearchCode": "20608180/3661045776465014655/1022",
            "roomBasis": "BB",
            "rooms": ["Superior City View Room"],
            "totalPrice": 12243.00,
            "netPrice": 11243.00,
            "currency": "BRL",
            "nonRefundable": false,
            "cancellationDeadline": "2026-03-13"
          }
        ],
        "searchSessionId": "a8ee0a39-24f5-4e9c-a622-6fc80101fb4e",
        "netPrice": 11243.00
      }
    ],
    "summary": {
      "totalResults": 167,
      "minPrice": 482.33,
      "maxPrice": 4870.00,
      "duration": 16077
    },
    "searchSessionId": "a8ee0a39-24f5-4e9c-a622-6fc80101fb4e",
    "meta": {
      "searchParams": {
        "cityCode": "1650",
        "checkIn": "2026-03-15",
        "checkOut": "2026-03-18",
        "adults": 2,
        "children": 0,
        "rooms": 1,
        "nationality": "BR"
      },
      "teamId": "uuid-do-time"
    }
  },
  "timestamp": "2026-02-19T15:51:00.000Z"
}

Use o campo hotelSearchCode do hotel ou de uma oferta específica para obter detalhes (endpoint details) e para criar a pré-reserva (endpoint prebook). Cada hotel pode ter múltiplas ofertas com diferentes tipos de quarto e regime alimentar.

Estrutura da Resposta

Hotel

Campo	Tipo	Descrição
`id`	string	ID único no formato `provider:hotelId`
`name`	string	Nome do hotel
`hotelId`	string	ID do hotel no provedor
`hotelSearchCode`	string	Código da melhor oferta (usar no prebook e details)
`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 (thumbnail e imagem principal). Para galeria completa, use o endpoint Details
`amenities`	string[]	Lista de comodidades (pode estar vazia na busca). Para lista completa, use o endpoint Details
`price`	Price	Informações de preço da melhor oferta
`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
`offers`	Offer[]	Lista de todas as ofertas disponíveis para este hotel
`searchSessionId`	string	ID da sessão de busca (usar no prebook)
`netPrice`	number	Preço de custo da melhor oferta (antes do markup)

Location

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

Offer

Campo	Tipo	Descrição
`hotelSearchCode`	string	Código da oferta (usar no prebook para esta oferta específica)
`roomBasis`	string	Regime alimentar: `RO` (Room Only), `BB` (Bed & Breakfast), `HB` (Half Board), `FB` (Full Board), `AI` (All Inclusive)
`rooms`	string[]	Tipos de quarto disponíveis
`totalPrice`	number	Preço total da estadia (com markup)
`netPrice`	number	Preço de custo (antes do markup)
`currency`	string	Moeda
`nonRefundable`	boolean	Se a oferta é não-reembolsável
`cancellationDeadline`	string\|null	Data limite para cancelamento gratuito (YYYY-MM-DD)

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

3. Detalhes do Hotel (Details)

POST /api/v1/hotels/details

Retorna informações detalhadas de um hotel específico, incluindo descrição completa, galeria de fotos, facilidades do hotel e do quarto, e breakdown de preços.

Este endpoint é opcional mas recomendado. Use-o para montar a página de detalhes do hotel antes do usuário selecionar uma oferta para reservar.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`hotel_search_code`	string	Sim	Código da oferta retornado na busca (`hotelSearchCode`)
`hotel_id`	string	Não	ID do hotel no provedor (para informações adicionais)
`language`	string	Não	Idioma da resposta (padrão: `pt`). Opções: `pt`, `en`, `es`

Exemplo de Requisição

curl -X POST https://app.moblix.net/api/v1/hotels/details \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "hotel_search_code": "HSC-ABCDEF123456",
    "hotel_id": "12345",
    "language": "pt"
  }'

const response = await fetch('https://app.moblix.net/api/v1/hotels/details', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    hotel_search_code: 'HSC-ABCDEF123456',
    hotel_id: '12345',
    language: 'pt'
  })
});

const data = await response.json();
console.log(data.data.hotel_name);
console.log(data.data.pictures);       // Galeria de fotos
console.log(data.data.facilities);     // Facilidades do hotel
console.log(data.data.description);    // Descrição completa

import requests

response = requests.post(
    'https://app.moblix.net/api/v1/hotels/details',
    headers={
        'Authorization': 'Bearer mbx_live_sua_chave_aqui',
        'Content-Type': 'application/json'
    },
    json={
        'hotel_search_code': 'HSC-ABCDEF123456',
        'hotel_id': '12345',
        'language': 'pt'
    }
)

data = response.json()
print(data['data']['hotel_name'])
print(data['data']['pictures'])
print(data['data']['facilities'])

Resposta

{
  "data": {
    "hotel_name": "Copacabana Palace, A Belmond Hotel, Rio de Janeiro",
    "hotel_id": "6931",
    "address": "Avenida Atlantica, 1702, Rio de Janeiro, BR",
    "city_code": "1650",
    "phone": "55-21-25487070",
    "stars": 5,
    "description": "Property Location Copacabana Palace, A Belmond Hotel ficará numa localização central em Rio de Janeiro, a poucos passos de Praia de Copacabana...",
    "facilities": [
      "Piscina ao ar livre",
      "Spa com serviço completo",
      "Restaurante",
      "Bar/lounge",
      "Centro de fitness",
      "Wi-fi grátis",
      "Estacionamento (sobretaxa)",
      "Serviço de quarto 24 horas",
      "Concierge"
    ],
    "room_facilities": [
      "Ar condicionado",
      "Televisor LCD",
      "Cofre no quarto",
      "Mini bar",
      "Secador de cabelo",
      "Toalhas fornecidas",
      "Roupão de banho"
    ],
    "pictures": [
      "https://i.travelapi.com/lodging/1000000/10000/7200/7130/b2fc212d_b.jpg",
      "https://i.travelapi.com/lodging/1000000/10000/7200/7130/667c0367_b.jpg",
      "https://i.travelapi.com/lodging/1000000/10000/7200/7130/dd513758_b.jpg",
      "https://i.travelapi.com/lodging/1000000/10000/7200/7130/abc12345_b.jpg",
      "..."
    ],
    "coordinates": null,
    "price_breakdown": {
      "HotelName": "Copacabana Palace, A Belmond Hotel",
      "Room": { "...": "detalhamento por diária" }
    }
  },
  "timestamp": "2026-02-19T15:52:00.000Z"
}

As coordenadas geográficas são retornadas no endpoint de busca (search). No endpoint de detalhes, coordinates pode ser null dependendo do provedor. Use as coordenadas obtidas na busca para posicionar o hotel no mapa.

Campos da Resposta

Campo	Tipo	Descrição
`hotel_name`	string	Nome do hotel
`hotel_id`	string	ID do hotel no provedor
`address`	string	Endereço completo
`city_code`	string	Código da cidade
`phone`	string	Telefone do hotel
`stars`	number	Classificação em estrelas (1-5)
`description`	string	Descrição detalhada do hotel (texto limpo, sem HTML)
`facilities`	string[]	Lista de facilidades/amenidades do hotel
`room_facilities`	string[]	Lista de facilidades do quarto
`pictures`	string[]	URLs das fotos do hotel (galeria completa)
`coordinates`	object\|null	`latitude` e `longitude`. Pode ser `null` — use as coordenadas do endpoint de busca quando disponíveis
`price_breakdown`	object	Detalhamento de preços por diária

Erros Possíveis

HTTP	Erro	Descrição
400	Validation error	Campos obrigatórios faltando
400	Provider credentials not configured	Credenciais não configuradas
401	Unauthorized	API key inválida
500	Provider password not found	Erro ao decriptar senha

4. Pré-reservar Hotel (Prebook)

POST /api/v1/hotels/prebook

Valida a disponibilidade de uma oferta de hotel e a reserva temporariamente por 20 minutos. Retorna um prebook_token que deve ser usado no próximo passo para confirmar a reserva.

O prebook_token expira em 20 minutos. Após esse prazo, será necessário criar um novo prebook.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`hotel_search_code`	string	Sim	Código da oferta retornado na busca (campo `hotelSearchCode` da oferta)
`search_session_id`	string	Não	ID da sessão de busca (`searchSessionId` da resposta do search)
`check_in`	string	Sim	Data de check-in (YYYY-MM-DD)
`check_out`	string	Sim	Data de check-out (YYYY-MM-DD)
`adults`	number	Sim	Número de adultos (1-9)
`children`	number	Não	Número de crianças (padrão: 0)
`rooms`	number	Não	Número de quartos (1-5, padrão: 1)
`room_basis`	string	Não	Tipo de quarto (retornado na oferta)
`hotel_name`	string	Sim	Nome do hotel
`hotel_id`	string	Não	ID do hotel (campo `id` da resposta do search)
`unit_price`	number	Sim	Preço total da estadia (campo `price.total` do search)
`currency`	string	Não	Moeda, 3 caracteres (padrão: BRL)
`net_price`	number	Não	Preço de custo/net (para cálculo de markup)

Exemplo de Requisição

curl -X POST https://app.moblix.net/api/v1/hotels/prebook \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "hotel_search_code": "HSC-ABCDEF123456",
    "search_session_id": "uuid-da-sessao",
    "check_in": "2026-03-15",
    "check_out": "2026-03-20",
    "adults": 2,
    "rooms": 1,
    "hotel_name": "Copacabana Palace",
    "hotel_id": "bestbuy:12345",
    "unit_price": 4500.00,
    "currency": "BRL"
  }'

const response = await fetch('https://app.moblix.net/api/v1/hotels/prebook', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    hotel_search_code: 'HSC-ABCDEF123456',
    search_session_id: 'uuid-da-sessao',
    check_in: '2026-03-15',
    check_out: '2026-03-20',
    adults: 2,
    rooms: 1,
    hotel_name: 'Copacabana Palace',
    hotel_id: 'bestbuy:12345',
    unit_price: 4500.00,
    currency: 'BRL'
  })
});

const data = await response.json();
const prebookToken = data.data.prebook_token;
// Salve este token para usar no próximo passo (book)

import requests

response = requests.post(
    'https://app.moblix.net/api/v1/hotels/prebook',
    headers={
        'Authorization': 'Bearer mbx_live_sua_chave_aqui',
        'Content-Type': 'application/json'
    },
    json={
        'hotel_search_code': 'HSC-ABCDEF123456',
        'search_session_id': 'uuid-da-sessao',
        'check_in': '2026-03-15',
        'check_out': '2026-03-20',
        'adults': 2,
        'rooms': 1,
        'hotel_name': 'Copacabana Palace',
        'hotel_id': 'bestbuy:12345',
        'unit_price': 4500.00,
        'currency': 'BRL'
    }
)

data = response.json()
prebook_token = data['data']['prebook_token']
# Salve este token para usar no próximo passo (book)

Resposta de Sucesso (201 Created)

{
  "data": {
    "prebook_token": "pbk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hotel_name": "Copacabana Palace",
    "check_in": "2026-03-15",
    "check_out": "2026-03-20",
    "nights": 5,
    "unit_price": 4500.00,
    "currency": "BRL",
    "expires_at": "2026-01-26T10:50:00Z"
  },
  "timestamp": "2026-01-26T10:30:00Z"
}

Campos da Resposta

Campo	Tipo	Descrição
`prebook_token`	string	Token para usar no endpoint de book (válido por 20 min)
`hotel_name`	string	Nome do hotel
`check_in`	string	Data de check-in
`check_out`	string	Data de check-out
`nights`	number	Número de diárias
`unit_price`	number	Preço total confirmado
`currency`	string	Moeda
`expires_at`	string	Data/hora de expiração do token (ISO 8601)

Erros Possíveis

HTTP	Erro	Descrição
400	Validation error	Campos obrigatórios faltando ou inválidos
400	check_in must be before check_out	Datas inválidas
400	Provider credentials not configured	Credenciais do provedor não configuradas
401	Unauthorized	API key inválida

5. Confirmar Reserva (Book)

POST /api/v1/hotels/book

Cria a reserva de hotel definitiva a partir de um prebook_token, com dados dos hóspedes e pagamento integrado.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`prebook_token`	string	Sim	Token obtido no prebook
`customer_id`	string (UUID)	Sim	ID do cliente cadastrado na sua equipe
`guests`	array	Sim	Lista de hóspedes (mín. 1)
`payment`	object	Sim	Dados de pagamento
`notes`	string	Não	Observações internas
`special_requests`	string	Não	Solicitações especiais (ex: "check-in tardio")

Hóspedes (`guests`)

Campo	Tipo	Obrigatório	Descrição
`first_name`	string	Sim	Nome
`last_name`	string	Sim	Sobrenome
`document_type`	string	Não	Tipo: `cpf`, `passport`, `rg`
`document_number`	string	Não	Número do documento
`email`	string	Não	E-mail do hóspede
`phone`	string	Não	Telefone
`birth_date`	string	Não	Data de nascimento (YYYY-MM-DD)

Pagamento (`payment`)

Campo	Tipo	Obrigatório	Descrição
`method`	string	Sim	Método: `pix`, `credit_card`, `boleto`
`installments`	number	Não	Parcelas (1-12, apenas cartão de crédito)
`credit_card`	object	Condicional	Obrigatório quando `method` = `credit_card`
`credit_card_holder_info`	object	Não	Endereço do titular (recomendado para cartão)

Cartão de Crédito (`payment.credit_card`)

Campo	Tipo	Obrigatório	Descrição
`holder_name`	string	Sim	Nome impresso no cartão
`number`	string	Sim	Número do cartão
`expiry_month`	string	Sim	Mês de validade (2 dígitos, ex: `"03"`)
`expiry_year`	string	Sim	Ano de validade (4 dígitos, ex: `"2028"`)
`ccv`	string	Sim	Código de segurança (3-4 dígitos)

Endereço do Titular (`payment.credit_card_holder_info`)

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo do titular
`email`	string	Sim	E-mail do titular
`cpf_cnpj`	string	Sim	CPF ou CNPJ do titular
`postal_code`	string	Sim	CEP (8 dígitos)
`address_number`	string	Sim	Número do endereço
`phone`	string	Não	Telefone
`address_street`	string	Não	Rua
`address_complement`	string	Não	Complemento
`address_neighborhood`	string	Não	Bairro
`address_city`	string	Não	Cidade
`address_state`	string	Não	Estado (UF)

Exemplo: Reserva com PIX

curl -X POST https://app.moblix.net/api/v1/hotels/book \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "prebook_token": "pbk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "uuid-do-cliente",
    "guests": [
      {
        "first_name": "João",
        "last_name": "Silva",
        "document_type": "cpf",
        "document_number": "12345678900",
        "email": "joao@example.com",
        "phone": "+5511999999999"
      },
      {
        "first_name": "Maria",
        "last_name": "Silva",
        "document_type": "cpf",
        "document_number": "98765432100"
      }
    ],
    "payment": {
      "method": "pix"
    },
    "special_requests": "Check-in após as 18h"
  }'

const response = await fetch('https://app.moblix.net/api/v1/hotels/book', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prebook_token: 'pbk_a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    customer_id: 'uuid-do-cliente',
    guests: [
      {
        first_name: 'João',
        last_name: 'Silva',
        document_type: 'cpf',
        document_number: '12345678900',
        email: 'joao@example.com',
        phone: '+5511999999999'
      },
      {
        first_name: 'Maria',
        last_name: 'Silva',
        document_type: 'cpf',
        document_number: '98765432100'
      }
    ],
    payment: {
      method: 'pix'
    },
    special_requests: 'Check-in após as 18h'
  })
});

const data = await response.json();
console.log('Reserva:', data.data.booking.booking_number);
console.log('PIX:', data.data.payment.pix_code);

import requests

response = requests.post(
    'https://app.moblix.net/api/v1/hotels/book',
    headers={
        'Authorization': 'Bearer mbx_live_sua_chave_aqui',
        'Content-Type': 'application/json'
    },
    json={
        'prebook_token': 'pbk_a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        'customer_id': 'uuid-do-cliente',
        'guests': [
            {
                'first_name': 'João',
                'last_name': 'Silva',
                'document_type': 'cpf',
                'document_number': '12345678900',
                'email': 'joao@example.com',
                'phone': '+5511999999999'
            },
            {
                'first_name': 'Maria',
                'last_name': 'Silva',
                'document_type': 'cpf',
                'document_number': '98765432100'
            }
        ],
        'payment': {
            'method': 'pix'
        },
        'special_requests': 'Check-in após as 18h'
    }
)

data = response.json()
print('Reserva:', data['data']['booking']['booking_number'])
print('PIX:', data['data']['payment']['pix_code'])

Exemplo: Reserva com Cartão de Crédito

{
  "prebook_token": "pbk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "uuid-do-cliente",
  "guests": [
    {
      "first_name": "João",
      "last_name": "Silva",
      "document_type": "cpf",
      "document_number": "12345678900"
    }
  ],
  "payment": {
    "method": "credit_card",
    "installments": 3,
    "credit_card": {
      "holder_name": "JOAO SILVA",
      "number": "4111111111111111",
      "expiry_month": "12",
      "expiry_year": "2028",
      "ccv": "123"
    },
    "credit_card_holder_info": {
      "name": "João Silva",
      "email": "joao@example.com",
      "cpf_cnpj": "12345678900",
      "postal_code": "22041080",
      "address_number": "1702",
      "phone": "+5511999999999"
    }
  }
}

Resposta de Sucesso (201 Created)

Resposta com PIX

{
  "data": {
    "booking": {
      "id": "uuid-da-reserva",
      "booking_number": "BK-1234567890",
      "locator": "ABC123",
      "status": "pending",
      "total_amount": 4500.00,
      "currency": "BRL"
    },
    "payment": {
      "id": "uuid-do-pagamento",
      "method": "pix",
      "amount": 4500.00,
      "status": "pending",
      "pix_qr_code": "data:image/png;base64,...",
      "pix_code": "00020126580014br.gov.bcb.pix...",
      "expires_at": "2026-01-26T11:30:00Z"
    }
  },
  "timestamp": "2026-01-26T10:30:00Z"
}

Resposta com Cartão de Crédito

{
  "data": {
    "booking": {
      "id": "uuid-da-reserva",
      "booking_number": "BK-1234567890",
      "locator": "ABC123",
      "status": "confirmed",
      "total_amount": 4500.00,
      "currency": "BRL"
    },
    "payment": {
      "id": "uuid-do-pagamento",
      "method": "credit_card",
      "amount": 4500.00,
      "status": "paid"
    }
  },
  "timestamp": "2026-01-26T10:30:00Z"
}

Pagamentos com cartão de crédito são confirmados imediatamente (status: "confirmed"). Para PIX e boleto, a reserva fica como pending até o pagamento ser confirmado via webhook.

Campos da Resposta

Booking

Campo	Tipo	Descrição
`id`	string	UUID da reserva
`booking_number`	string	Número da reserva (ex: BK-1234567890)
`locator`	string	Localizador da reserva (código curto)
`status`	string	`pending` (aguardando pagamento) ou `confirmed` (pago)
`total_amount`	number	Valor total
`currency`	string	Moeda

Payment

Campo	Tipo	Descrição
`id`	string	UUID do pagamento
`method`	string	Método utilizado
`amount`	number	Valor cobrado
`status`	string	`pending` ou `paid`
`pix_qr_code`	string	QR Code PIX em base64 (apenas para PIX)
`pix_code`	string	Código PIX copia-e-cola (apenas para PIX)
`boleto_url`	string	URL do boleto PDF (apenas para boleto)
`payment_url`	string	URL de pagamento (quando disponível)
`expires_at`	string	Expiração do pagamento (ISO 8601)

Erros Possíveis

HTTP	Erro	Descrição
400	Validation error	Campos obrigatórios faltando ou inválidos
400	credit_card data is required	Faltam dados do cartão
400	Prebook token already used	Token já foi utilizado
400	No payment provider configured	Nenhum gateway suporta o método
404	Prebook token not found	Token não encontrado
404	Customer not found	Cliente não pertence ao time
410	Prebook token expired	Token expirou (criar novo prebook)

Fluxo Completo — Exemplo Passo a Passo

Aqui está um exemplo completo de integração, do início ao fim:

const API_URL = 'https://app.moblix.net';
const API_KEY = 'mbx_live_sua_chave_aqui';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Passo 1: Buscar código da cidade
const destResult = await fetch(
  `${API_URL}/api/v1/hotels/destinations?q=rio+de+janeiro`,
  { headers }
).then(r => r.json());

const cityCode = destResult.data.destinations[0].code; // "1650"

// Passo 2: Buscar hotéis disponíveis
const searchResult = await fetch(`${API_URL}/api/v1/hotels/search`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    cityCode,
    checkIn: '2026-03-15',
    checkOut: '2026-03-20',
    adults: 2,
    rooms: 1
  })
}).then(r => r.json());

const hotel = searchResult.data.hotels[0];
// hotel.hotelSearchCode → código para usar no details e prebook
// hotel.offers → lista de todas as ofertas disponíveis

// Passo 3 (opcional): Obter detalhes completos do hotel
const details = await fetch(`${API_URL}/api/v1/hotels/details`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    hotel_search_code: hotel.hotelSearchCode,
    hotel_id: hotel.hotelId,
    language: 'pt'
  })
}).then(r => r.json());

console.log('Fotos:', details.data.pictures);
console.log('Facilidades:', details.data.facilities);

// Passo 4: Pré-reservar o hotel (escolha uma oferta específica ou use a melhor)
const selectedOffer = hotel.offers[0]; // ou hotel.hotelSearchCode para a melhor
const prebook = await fetch(`${API_URL}/api/v1/hotels/prebook`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    hotel_search_code: selectedOffer.hotelSearchCode,
    search_session_id: hotel.searchSessionId,
    check_in: '2026-03-15',
    check_out: '2026-03-20',
    adults: 2,
    rooms: 1,
    hotel_name: hotel.name,
    hotel_id: hotel.id,
    unit_price: selectedOffer.totalPrice
  })
}).then(r => r.json());

// Passo 5: Confirmar reserva com pagamento
const booking = await fetch(`${API_URL}/api/v1/hotels/book`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    prebook_token: prebook.data.prebook_token,
    customer_id: 'uuid-do-cliente',
    guests: [
      {
        first_name: 'João',
        last_name: 'Silva',
        document_type: 'cpf',
        document_number: '12345678900',
        email: 'joao@example.com'
      }
    ],
    payment: { method: 'pix' }
  })
}).then(r => r.json());

console.log('Reserva criada:', booking.data.booking.booking_number);
console.log('PIX para pagamento:', booking.data.payment.pix_code);

Cliente paga → Sistema cria reserva automaticamente na BestBuy → Faturamento

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

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

Consultar e Gerenciar Reservas

Após criar uma reserva de hotel, você pode consultá-la e gerenciá-la pela API de Reservas:

Listar reservas — GET /api/v1/bookings?type=hotel
Buscar por ID — GET /api/v1/bookings/:id
Atualizar — PATCH /api/v1/bookings/:id
Cancelar — DELETE /api/v1/bookings/:id

Rate Limit

Endpoint	Limite
`/hotels/search`	30 req/min
`/hotels/details`	60 req/min
`/hotels/prebook`	60 req/min
`/hotels/book`	30 req/min

Hotéis

On this page