Hotelumo Hotel Rooms & Operations

npx add-mcp 'https://mcp.hotelumo.com/mcp'

Dirija sua propriedade a partir do seu próprio código ou assistente de IA: uma API REST com chaves de escopo, webhooks assinados e um MCP somente leitura com escopo por locatário para operações hoteleiras seguras.

Chaves de API

Obtenha uma chave e autentique-se

A API REST do Hotelumo permite que um channel manager, um motor de reservas, um CRM ou seu próprio back office faça o que o painel faz: ler e escrever reservas e hóspedes, manter quartos e tipos de quarto sincronizados, publicar planos de tarifas e preços diários e consultar disponibilidade.

Crie uma chave de API no painel do Hotelumo. O segredo é exibido apenas uma vez, quando a chave é criada, e nunca mais — guarde-o em um local seguro. Uma chave sempre pertence a uma organização; ela pode adicionalmente ser vinculada a um único hotel, caso em que cada solicitação feita com ela fica restrita a esse hotel e o hotel nunca precisa ser enviado.

Autentique cada solicitação com autenticação HTTP Basic contendo apenas o segredo da chave, codificado em base64, no cabeçalho Authorization.

# The Authorization header is HTTP Basic auth carrying only the key secret,
# with no username and no colon.
Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)

Todo endpoint fica sob https://api.hotelumo.com. Solicitações feitas com uma chave são limitadas por chave; exceder o limite retorna 429.

Início rápido

Suas três primeiras chamadas

Leia as reservas de um hotel, verifique o que ainda pode ser reservado nas próximas duas semanas e depois envie preços de volta para um plano de tarifas.

# List the reservations of one of your hotels
curl "https://api.hotelumo.com/api/reservations?hotelId=HOTEL_ID&limit=20" \
  -H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)"

# Read the next two weeks of availability for that hotel
curl https://api.hotelumo.com/api/hotels/HOTEL_ID/availability \
  -H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)"

# Push prices back: a batch upsert keyed on (ratePlanId, date).
# price is in minor units of the rate plan's currency, so 12000 is 120.00.
curl -X POST https://api.hotelumo.com/api/dailyRates \
  -H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      { "ratePlanId": "RATE_PLAN_ID", "date": "2026-08-01", "price": 12000 },
      { "ratePlanId": "RATE_PLAN_ID", "date": "2026-08-02", "price": 13500 }
    ]
  }'

Consulte a referência completa da API — cada endpoint com seus parâmetros, corpo da solicitação, respostas e escopo necessário.

CLI

Interface de linha de comando

As mesmas reservas, hóspedes, quartos, planos de tarifas e disponibilidade estão disponíveis no seu terminal por meio do CLI do hotelumo. Instale-o globalmente com npm ou execute-o ad hoc com npx.

A autenticação é um único comando: hotelumo login abre seu navegador para entrar na sua conta Hotelumo e armazena uma sessão para comandos futuros — sem necessidade de colar chave de API. Para uso não assistido, exporte HOTELUMO_API_KEY e pule a etapa de login completamente.

# Install once, globally
npm install -g hotelumo
# or run it ad hoc without installing
npx hotelumo --help

# Log in — opens your browser to sign in and stores a session
hotelumo login

# Who is arriving this month?
hotelumo reservations list --stayDateFrom 2026-08-01 --stayDateTo 2026-08-31

# What is still bookable for a two-night stay?
hotelumo availability check HOTEL_ID --checkInDate 2026-08-10 \
  --checkOutDate 2026-08-12

# Publish prices for a date range. price is in minor units, so 12000 is 120.00
hotelumo daily-rates set --hotelId HOTEL_ID --ratePlanId RATE_PLAN_ID \
  --dateFrom 2026-08-01 --dateTo 2026-08-31 --price 12000 --availability 4

Todo subcomando aceita --json para saída analisável, e hotelumo schema imprime toda a árvore de comandos como JSON, para que um script nunca precise extrair texto de ajuda.

O CLI é open source em github.com/hotelumo/cli e publicado como hotelumo no npm. Execute qualquer comando com --help para ver suas opções.

Escopos

Menor privilégio por padrão

Cada chave carrega uma lista de escopos, para que uma integração que só precise ler suas reservas nunca tenha a capacidade de alterar seus preços. Novas chaves começam somente leitura; amplie-as explicitamente no painel. Uma solicitação cuja chave não tenha o escopo exigido por um endpoint é recusada com 403.

• reservations:readListar reservas e ler uma única com seus quartos.
• reservations:writeCriar, atualizar e excluir reservas.
• guests:readListar o diretório de hóspedes e ler um único hóspede.
• guests:writeCriar, atualizar e excluir hóspedes.
• rooms:readListar quartos e tipos de quarto.
• rooms:writeCriar quartos e tipos de quarto.
• rates:readListar planos de tarifas e tarifas diárias, e ler a disponibilidade de um hotel.
• rates:writeCriar planos de tarifas e atualizar preços diários em lote.

Uma reserva ou hóspede que pertença a outra organização responde 404 em vez de 403, para que um id não possa ser sondado quanto à existência.

Assistentes de IA

Operações hoteleiras por meio de MCP

Conecte ChatGPT, Claude, Cursor ou outro assistente compatível com MCP ao Hotelumo com um único endpoint hospedado. Entre com OAuth do Hotelumo; o conector tem escopo por locatário, é somente leitura e exige o escopo hotelumo:read. Não há segredo de API para colar no host.

{
  "mcpServers": {
    "hotelumo": {
      "type": "http",
      "url": "https://mcp.hotelumo.com/mcp"
    }
  }
}

• list_hotels · get_hotelResolva seus hotéis e leia metadados seguros da propriedade.
• get_hotel_availabilityEncontre ofertas reserváveis de tipos de quarto e planos de tarifas para uma estadia de até 30 noites.
• get_hotel_schedule_summaryRevise contagens agregadas de chegadas, partidas, estadias em casa e status por até 31 dias.
• list_room_types · get_room_type · list_roomsInspecione o catálogo seguro de quartos, capacidade e status operacional dos quartos.
• list_rate_plans · list_daily_rates · list_extrasRevise planos vendáveis, preços diários limitados e o catálogo de extras.
• show_hotel_overviewRenderize um cartão limitado de operações hoteleiras em hosts de IA compatíveis.

O conector público deliberadamente omite identidades de hóspedes e detalhes de contato, registros individuais de reservas e alocação de quartos, identificadores de ocupantes, notas, documentos, códigos de acesso, dados de pagamento, credenciais, configuração de integração e metadados arbitrários. Resultados de agenda são apenas contagens agregadas; o conector não pode criar reservas, alterar tarifas, receber pagamentos ou modificar registros do Hotelumo.

Disponibilidade e preços de catálogo são retornados em unidades monetárias menores: por exemplo, 12000 é 120,00 quando a moeda do hotel usa duas casas decimais. Resultados limitados que terminam com um sinal de mais são limites inferiores, não totais completos.

Use o endpoint MCP de produção ou conecte-se por meio da listagem do Hotelumo em um host de IA compatível após a publicação do diretório estar ativa.

Habilidades de Agente

Ensine seu agente de codificação sobre o Hotelumo

O Hotelumo inclui Habilidades de Agente — guias que seguem o padrão agentskills.io que ensinam agentes de codificação a executar operações hoteleiras com o CLI do hotelumo e o conector MCP, em vez de adivinhar comandos e ferramentas.

# Install the Hotelumo skills into your coding agent
npx skills add hotelumo/skills

Um único comando instala as habilidades no Claude Code, Cursor, Codex, Gemini CLI e qualquer outro agente que siga o padrão de Habilidades. O CLI também inclui os mesmos guias, com versão correspondente aos comandos que ele fornece: hotelumo skills get <name> imprime um sob demanda.

Os dois guias não são intercambiáveis. O guia do CLI cobre a API REST completa, incluindo escritas; o guia de operações hoteleiras cobre o conector MCP somente leitura e seu limite de privacidade.

As habilidades são open source em github.com/hotelumo/skills. Usuários de Claude também podem instalar o plugin Claude do Hotelumo, que agrupa o conector junto com a habilidade: github.com/hotelumo/claude-plugin.

Webhooks

Webhooks assinados

Adicione uma assinatura de webhook a um hotel e o Hotelumo envia por POST os eventos que você escolheu para o seu servidor conforme eles acontecem. Todo escritor emite: a API REST, o painel, a página pública de reservas e channel managers conectados.

• reservation.createdUma reserva foi criada — por meio da API, do painel, da página pública de reservas ou de um channel manager conectado.
• reservation.updatedUma reserva mudou, incluindo seu status e quartos.
• reservation.deletedUma reserva foi excluída.
• guest.createdUm hóspede foi adicionado.
• guest.updatedUm registro de hóspede foi editado.
• guest.deletedUm hóspede foi excluído.

POST https://your-server.com/hotelumo-webhook

{
  "event": "reservation.created",
  "timestamp": 1719000000,
  "data": { "...": "..." }
}

Verifique a assinatura

Cada entrega carrega um cabeçalho X-Hotelumo-Signature no formato t=timestamp,v1=assinatura, onde a assinatura é um HMAC-SHA256 de timestamp.corpo com chave no segredo da assinatura mostrado a você uma vez quando a assinatura foi criada. Recalcule-o sobre o corpo bruto e compare antes de confiar no payload.

import crypto from 'node:crypto'

// body must be the RAW request body, byte for byte
function verify(header, body, secret) {
  const [t, v1] = (header || '').split(',').map(part => part.split('=')[1])
  if (!t || !v1) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(\`${t}.${body}\`)
    .digest('hex')

  // timingSafeEqual throws on a length mismatch, so a malformed signature
  // has to be rejected before the comparison rather than by it.
  if (v1.length !== expected.length) return false

  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

A entrega é uma única tentativa de melhor esforço com timeout de cinco segundos e sem novas tentativas, então responda 2xx rapidamente e faça o trabalho de forma assíncrona. Um endpoint que falha vinte vezes seguidas é desabilitado automaticamente e precisa ser reabilitado no painel.

Comece a construir