Portal do Desenvolvedor Hotel Bergsonne Allgäu — API de reservas, MCP e OpenAPI

Esta página é o ponto de entrada para agentes IA, chatbots e parceiros de integração. Todos os endpoints de leitura são públicos e sem autenticação; as reservas usam um caminho de escrita documentado.

Quando usar esta API

Consultar disponibilidade e tarifas em tempo real para datas concretas em Sonthofen, Allgäu.
Descrever tipos de quarto, ocupação, equipamento, acessibilidade e o quarto de cuidados.
Responder sobre horários de chegada, contactos e factos do hotel.
Iniciar uma reserva direta ou encaminhar o hóspede para o processo de reserva.

Quando não usar esta API

Para outros hotéis ou pesquisa multipropriedade: esta API descreve apenas o Hotel Bergsonne Allgäu.
Para cancelar ou alterar reservas existentes: por e-mail ou telefone.
Para processamento de pagamentos, dados de hóspedes ou sistemas internos.
Para consultas em massa sem intenção de viagem: aplica-se um limite de pedidos.

Início rápido

Três passos: ler dados do hotel, verificar disponibilidade, confirmar preço. Parâmetros sem distinção de maiúsculas, preços em EUR com IVA.

Hotel & room typeshttps://bergsonne-allgaeu.de/api/booking?action=hotel
Availabilityhttps://bergsonne-allgaeu.de/api/booking?action=availability&checkIn=2026-08-20&checkOut=2026-08-23&adults=2
Price quotehttps://bergsonne-allgaeu.de/api/booking?action=price-quote&roomId=KDZ&checkIn=2026-08-20&checkOut=2026-08-23&adults=2
Bookable extrashttps://bergsonne-allgaeu.de/api/booking?action=addons
Create booking (POST)https://bergsonne-allgaeu.de/api/booking?action=bookings

Autenticação

A leitura é aberta: hotel, fact-sheet, availability, price-quote, addons e discover-rooms não exigem token. A escrita (action=bookings) usa POST; detalhes OAuth 2.1 em /.well-known/oauth-protected-resource e /.well-known/auth.md.

Scopes e privilégio mínimo

Os scopes OAuth nomeados estão declarados de forma legível por máquina: scopes_supported em /.well-known/oauth-protected-resource (RFC 9728) e esquema de segurança OAuth em /api/openapi. Os agentes pedem apenas o scope mínimo.

hotel:readHotel metadata, room types, amenities, fact sheet, extras
booking:readAvailability, rates, price quotes
booking:writeCreate a reservation for a named human guest

Registo self-service sem formulário nem aprovação humana: POST /agent/auth devolve uma credencial bearer anónima com hotel:read e booking:read. booking:write usa o fluxo OAuth com PKCE (S256), porque a reserva é em nome de um hóspede identificado.

Sandbox e idempotência

Com "test": true no corpo da reserva o pedido corre em modo sandbox: validação e cálculo idênticos, sem reserva real e com um bookingId TEST. Uma "idempotencyKey" por tentativa evita duplicados.

POST https://bergsonne-allgaeu.de/api/booking?action=bookings
Content-Type: application/json

{
  "roomId": "KDZ",
  "rateId": "1",
  "checkIn": "2026-08-20",
  "checkOut": "2026-08-23",
  "adults": 2,
  "customer": {
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "max@example.com",
    "phone": "+49 170 1234567",
    "country": "DE"
  },
  "idempotencyKey": "8f1c0e2a-...",
  "test": true
}

Erros e limites de pedidos

Os erros são sempre JSON com os campos error, code, hint, docs e openapi. Uma ação desconhecida devolve HTTP 400 com code UNKNOWN_ACTION, um caminho /api/ desconhecido HTTP 404 com NOT_FOUND. Pedidos excessivos devolvem HTTP 429 com RATE_LIMITED.

INVALID_DATESHTTP 400
UNKNOWN_ACTIONHTTP 400
METHOD_NOT_ALLOWEDHTTP 405
FORBIDDEN_ORIGINHTTP 403
NOT_FOUNDHTTP 404
RATE_LIMITEDHTTP 429
UPSTREAM_ERRORHTTP 502

Ficheiros legíveis por máquina

Contacto técnico

Questões sobre integração, limites ou acesso de escrita: e-mail servus@bergsonne-allgaeu.de ou +49 8321 3360.