Solicitações de reserva

Um visitante de um dos seus mapas publicados pode enviar à sua empresa uma solicitação sobre um local do mapa: uma reserva em um estabelecimento, uma visita a um imóvel, um horário em uma loja, uma coleta em uma parada. A solicitação chega à caixa de entrada da sua organização no Kaleidr Booking, em booking.kaleidr.com, por e-mail se você quiser, e aos seus próprios sistemas por webhooks. Você a responde pela caixa de entrada.

Uma solicitação é uma solicitação, não uma reserva confirmada. Nada é reservado, bloqueado nem pago: sua empresa a confirma, por e-mail ou como costuma fazer.

Ativar as solicitações

1. No Kaleidr Booking, abra Configurações, Geral e ative Aceitar solicitações. Enquanto estiver desativado, nenhum visitante pode enviar uma solicitação à sua organização, e os botões de solicitação não aparecem.
2. No Kaleidr Studio, adicione uma ação de solicitação a uma coleção: abra a coleção, Cartão e filtros, Ações do local, e adicione Solicitação. O rótulo dela é o botão que os visitantes veem; cada kit começa com o seu:

Tipo de coleção	Rótulo padrão	O visitante pede
Lojas	Request an Appointment	Um horário, uma retirada ou a resposta a uma pergunta
Anúncios	Schedule a Tour	Uma visita presencial ou por vídeo, ou mais informações
Estabelecimentos	Reserve	Uma reserva ou a resposta a uma pergunta
Paradas	Request Pickup	Uma coleta, uma encomenda antecipada ou um aviso

3. Publique um mapa que mostre a coleção. Os cartões de local, os layouts de locais e os locais das respostas do Ask Kaleidr passam então a exibir o botão.

• Uma ação de solicitação por coleção. Adicioná-la ativa as solicitações para todos os locais da coleção. Uma nova coleção de Estabelecimentos começa com Reserve, e uma nova coleção de Paradas com Request Pickup.
• Coleções de Veículos e Personalizadas não aceitam solicitações.
• Locais do chat. A configuração Solicitações de um mapa no Studio, Aceitar Solicitações para Qualquer Lugar, também permite que os visitantes enviem uma solicitação sobre um local que a Kaleidr AI cita nas respostas, como um restaurante perto do seu hotel. Ela fica desativada por padrão. Essa solicitação identifica o local pelo nome e endereço. Só leva uma posição no mapa quando o endereço foi encontrado nos dados de endereços próprios da Kaleidr.
• A Kaleidr AI pode preencher um formulário, nunca enviá-lo. Quando alguém pede "reserve uma mesa para quatro às 19h", o painel Ask Kaleidr prepara o formulário com o que o visitante disse e mostra Revisar e Enviar. O visitante revisa, adiciona os próprios dados e envia. A Kaleidr AI nunca vê o nome, o e-mail nem o telefone de um visitante.

O formulário

O visitante vê o formulário sobre o mapa: os campos do kit da coleção, o nome, o e-mail e um telefone opcional, uma mensagem e a linha de consentimento. Enviar solicitação fica desativado até que os campos obrigatórios sejam preenchidos e a caixa de consentimento seja marcada. Depois do envio, o visitante vê Solicitação enviada e uma referência como K-7XQ2MD. Sobre o formulário em si, consulte O formulário de solicitação.

No Kaleidr Booking, Configurações, Formulários de solicitação tem uma aba por kit. Para cada campo, você escolhe se ele aparece, se é obrigatório e o rótulo, e pode adicionar até cinco perguntas próprias. A pré-visualização ao lado mostra o formulário como os visitantes vão vê-lo.

Kit	Campos padrão
Lojas	O motivo da solicitação, data, período do dia, itens
Anúncios	O motivo da solicitação, visita presencial ou por vídeo, até três datas, período do dia, financiamento
Estabelecimentos	O motivo da solicitação, data, horário, número de pessoas (1 a 50), noites (1 a 60)
Paradas	O motivo da solicitação, coleta, destino, data, horário, número de pessoas (1 a 20), itens

Coleta e destino são texto que o visitante digita. No layout ao vivo, uma coleção de Paradas cuja ação de solicitação deixa os visitantes escolhê-los adiciona os dois pontos, encontrados por uma busca de endereço ou um toque no mapa. Eles são o que o visitante escolheu para você atender.

Bots. Um visitante que não entrou na Kaleidr passa por uma breve verificação humana antes de a solicitação ser enviada.

A caixa de entrada

Solicitações no Kaleidr Booking é um quadro com as colunas Nova, Aceita, Concluída e Recusada. Arraste um cartão para mudar o status, ou use o menu Mover para. Mostrar spam mostra as solicitações marcadas como spam. Filtre por mapa, local, kit e data, ou pesquise por referência, nome, e-mail ou local.

Abra uma solicitação para ver os dados e as respostas do visitante, o consentimento que ele deu, o local em um mapa e o histórico da solicitação. A partir daí:

Ação	O que faz
Aceitar, Recusar, Marcar como concluída, Marcar como spam, Reabrir	Muda o status. Uma solicitação nova pode ser aceita, recusada ou marcada como spam; uma aceita pode ser marcada como concluída ou recusada; uma recusada ou marcada como spam pode ser reaberta. Concluída é definitivo.
Resposta	Envia sua resposta ao visitante por e-mail. A resposta dele chega ao seu próprio endereço de e-mail.
Adicionar nota	Uma nota só para sua equipe. Nunca é enviada.
Atribuir a	Entrega a solicitação a um membro da sua organização.
Apagar solicitante	Exclui todas as solicitações desse endereço de e-mail na sua organização. Consulte Retenção e apagamento.

Quem pode fazer o quê segue os papéis da sua organização: proprietários, administradores, membros e leitores podem ler as solicitações; proprietários, administradores e membros podem alterá-las, respondê-las e atribuí-las; proprietários e administradores gerenciam as configurações, os formulários, os webhooks e as notificações, excluem e apagam solicitações e as exportam em CSV.

E-mail. Em Configurações, Notificações, Avisar novas solicitações por e-mail envia um e-mail aos membros ativados em Equipe quando chega uma solicitação. O e-mail indica o local e o tipo de solicitação e leva até ela; não contém nenhum dado do visitante. Enviar confirmações envia ao visitante uma cópia com a referência.

Solicitações de teste. Uma solicitação que você mesmo envia pelo Studio é marcada como Teste e não conta para o limite do seu plano.

Consentimento

A linha de consentimento do formulário diz: "Concordo que sua empresa use estes dados para responder à minha solicitação. A Kaleidr os trata em nome de sua empresa.", com o nome da sua empresa no lugar de sua empresa: o Nome da empresa em Configurações, Geral, ou então o nome da sua organização. Defina o Link da Política de Privacidade com um endereço https:// da sua própria política, e a linha passa a apontar para ele. A caixa começa desmarcada, e uma solicitação sem ela é recusada. Cada solicitação guarda a versão da linha que o visitante aceitou e quando.

Retenção e apagamento

• Manter solicitações por exclui uma solicitação depois desse tempo sem atividade: 365 dias, a menos que você mude, de 30 a 730 dias. Uma solicitação marcada como spam é excluída após 30 dias.
• Apagar solicitante exclui todas as solicitações de um endereço de e-mail na sua organização, junto com os e-mails enviados sobre elas. Use quando uma pessoa pedir que você exclua os dados dela.
• Excluir uma solicitação a exclui junto com os e-mails enviados sobre ela.
• Quando uma pessoa exclui a conta Kaleidr, as solicitações dela são excluídas em todas as organizações.
• Quando sua organização é excluída, as solicitações dela são excluídas junto.

Webhooks

Um webhook envia cada evento de solicitação a um endereço seu assim que acontece, para que seu sistema de reservas, seu CRM ou a automação da sua planilha possa agir. Adicione um no Kaleidr Booking em Configurações, Webhooks. Os webhooks estão disponíveis nos planos Pro e Enterprise.

• O endereço precisa ser https na porta 443, e todos os endereços para os quais o nome dele resolve precisam ser públicos. Qualquer outra porta, ou um endereço privado, é recusado ao salvar e novamente em cada entrega.
• O segredo é mostrado uma vez, quando você adiciona o webhook. Trocar segredo gera um novo; o antigo continua assinando por 24 horas para você fazer a troca.
• Enviar teste envia um evento webhook.test.

Evento	Enviado quando
request.created	Um visitante envia uma solicitação.
request.status_changed	O status de uma solicitação muda. data.from_status contém o anterior.
request.replied	Alguém responde ao visitante. data.reply contém { body, created_at }.
webhook.test	Você escolhe Enviar teste.

Cada entrega é um POST com um corpo JSON e estes cabeçalhos:

Cabeçalho	Valor
Kaleidr-Signature	t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
Kaleidr-Event-Id	O id do evento, o mesmo em cada nova tentativa. Use-o para ignorar uma repetição.
Kaleidr-Event-Type	O evento, como na tabela acima.
Kaleidr-Delivery-Attempt	De 1 a 7.

{
  "id": "8a1c2b9e-0000-4000-8000-000000000001",
  "type": "request.created",
  "api_version": "2026-10-22",
  "created_at": "2026-10-22T15:04:05Z",
  "org_id": "…",
  "data": {
    "request": {
      "id": "…",
      "ref": "K-7XQ2MD",
      "kit": "venues",
      "status": "new",
      "place": { "name": "Sample Venue", "line": "…", "lat": 40.7411, "lng": -73.9897 },
      "requester": { "name": "…", "email": "…", "phone": null, "locale": "en", "signed_in": false },
      "fields": { "kind": "reservation", "date": "2026-10-30", "time": "19:00", "party_size": 4 },
      "message": "…"
    }
  }
}

Uma solicitação sobre um local do chat cujo endereço não foi encontrado nos dados de endereços próprios da Kaleidr tem place.lat e place.lng definidos como null.

Verificar a assinatura

Verifique o corpo bruto antes de analisá-lo, e recuse um carimbo de data e hora com mais de cinco minutos. Durante uma troca de segredo, o cabeçalho traz um segundo v1=, assinado com o segredo anterior; aceite qualquer um dos dois.

import hashlib, hmac, time

def verify(header: str, secret: str, body: bytes, tolerance: int = 300) -> bool:
    parts = [p.split("=", 1) for p in header.split(",")]
    t = next((v for k, v in parts if k == "t"), "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)

Teste seu código com este vetor:

Entrada	Valor
segredo	whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
t	1761091200
corpo	{"id":"8a1c2b9e-0000-4000-8000-000000000001","type":"webhook.test"}
v1	3e55a2f93ac990282b95fd9140f8290ffaddc5d41969831e4234b164d613bd72

Entrega e novas tentativas

• Responda com qualquer status 2xx em até 10 segundos. Redirecionamentos não são seguidos.
• Pelo menos uma vez. Uma entrega que falha é tentada de novo após 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas: sete tentativas em cerca de 32 horas. O mesmo evento pode chegar duas vezes; ignore um Kaleidr-Event-Id que você já viu.
• O corpo é a solicitação como está no momento do envio, então uma nova tentativa traz o estado mais recente. Uma solicitação apagada nesse meio-tempo não é enviada.
• Dez entregas seguidas em que todas as tentativas falham desativam o webhook. Reativá-lo zera a contagem.
• Entregas, em cada webhook, lista as tentativas dos últimos 30 dias com status, código de resposta e tempo, sem os corpos. Tentar novamente reenvia uma que falhou.

Limites

Limite	Free	Pro	Enterprise
Solicitações por mês	50	1.000	Definido no seu contrato
Webhooks	Nenhum	5	Definido no seu contrato

Um mês é o período de faturamento da sua organização. Solicitações de teste não contam. No limite, novas solicitações são recusadas até o próximo período, e o formulário mostra no lugar o telefone ou o link do local, quando houver.

Relacionado

• O formulário de solicitação
• Biblioteca de locais
• Referência do Viewer: layouts de locais
• Rastreamento ao vivo