Ferramentas · Reservas e Agendamento

O módulo Reservas e o Agendamento pelo assistente: buscar salas e horários livres (com o custo em créditos e o seu saldo), reservar, remarcar, cancelar, marcar ausência, baixar o convite de calendário, cadastrar salas e mesas, bloquear horários, definir preços e aprovar agendas de membros. Os dois módulos usam as mesmas ferramentas de reserva; as de Agendamento são as cinco últimas.

Cada ferramenta traz um selo: Só consulta não muda nada, Altera cria ou muda algo na hora, e Pede confirmação só age depois do seu sim a um resumo. Ver Dinheiro e confirmação.

#Em resumo

"Equipe" é o proprietário, o administrador, o moderador e o financeiro. Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa conectada faria na tela.

Os espaços se criam com create_space e module: "bookings" ou "scheduling"; update_space muda só o que você mandar. O argumento bookings leva os padrões de toda sala (slot_minutes, min_duration_minutes, max_duration_minutes, min_notice_minutes, max_advance_days, show_booker_name e opening_hours, com as chaves mon a sun e períodos HH:MM); o scheduling leva os mesmos e mais offerers (ADMINS, TEAM ou MEMBERS), allow_paid_slots e require_listing_approval.

Horários. Os horários que você manda são sempre do relógio da comunidade ("2026-11-03T14:00", sem sufixo). Custos. Reservar, remarcar e cancelar mexem nos créditos: o assistente diz o custo e o saldo antes de reservar. Sem créditos suficientes, a resposta traz required, balance e shortfall; com o horário ocupado, traz os próximos horários livres.

#Buscar e consultar

#search_booking_rooms

Só consulta

O que atende ao pedido. Dê um início exato (starts_at) ou uma janela do dia (date com from e to), mais duração, capacidade e comodidades. Devolve só os recursos que atendem, com os horários de início livres, o custo em créditos, canAfford e o seu saldo, ordenados pelo mais cedo e depois pela menor capacidade; quando nada serve, next_slots lista os próximos horários para o mesmo pedido.

Peça assim: "Preciso de uma sala para 6 pessoas amanhã das 14h às 16h, com projetor."

#check_availability

Só consulta

Livre e ocupado. Os horários de um dia (ou de até 7), calculados do horário semanal, dos bloqueios e das reservas, cada livre com creditCost e canAfford. Nunca diz quem reservou, a menos que o espaço mostre o nome.

#list_booking_resources

Só consulta

As salas. Salas, mesas, estações e agendas do espaço. O membro vê só as listadas, ativas e abertas para reserva; a equipe vê todas. Parâmetros: space (obrigatório), kind, host_profile_id, page, limit.

#list_booking_amenities

Só consulta

O catálogo de comodidades que a comunidade aceita (projetor, TV, quadro branco, Wi-Fi…). Uma chave fora do catálogo é recusada. Sem parâmetros.

#get_booking_resource

Só consulta

Uma sala com as regras efetivas já combinadas com os padrões do espaço (horário, intervalo, limites de duração, antecedência, janela de cancelamento). Parâmetro: resource_id.

#Reservar

#create_booking

Altera

Reservar para você. Reserva na hora (já confirmada) e debita os seus créditos no mesmo passo. Antes, o assistente diz o custo e o saldo. Para reservar em nome de outro membro, use create_booking_for_member. A cortesia (waive_credits com waive_reason) é só do proprietário e do administrador. O e-mail de confirmação com o convite de calendário entra na fila. Devolve creditCost e balanceAfter.

Peça assim: "Reserve a Sala 2 amanhã das 14h às 16h para 6 pessoas."

#create_booking_for_member

Pede confirmação

Reservar em nome de um membro. Debita os créditos dele (ou sai grátis como cortesia, só proprietário e administrador, com waive_reason) e ele recebe o e-mail com o convite. Antes de agir, mostra um resumo com o membro e o saldo dele e só repete a chamada depois do seu sim. Mesmos parâmetros e mesmas respostas de create_booking, mais profile_id. Papel mínimo: moderador (ou financeiro).

Peça assim: "Reserve a Sala 1 na sexta, às 10h, em nome da Maria."

#list_my_bookings

Só consulta

As suas reservas, ou, com as_host, as que as pessoas fizeram na agenda que você oferece. Filtros: space, resource_id, status (lista, ex. CONFIRMED,NO_SHOW), from, to, order, page, limit. Cada uma traz canCancel.

#list_bookings

Só consulta

Todas as reservas da comunidade, com os mesmos filtros. Papel mínimo: moderador (ou financeiro).

#get_booking

Só consulta

Uma reserva: sala, pessoa, horários, situação, custo em créditos, se foi cortesia ou cancelamento tardio e o que quem pergunta pode fazer. Só o dono, o anfitrião e a equipe; outra pessoa recebe 404. Parâmetro: booking_id.

#Mudar uma reserva

#cancel_booking

Pede confirmação

Cancelar. O dono que cancela depois da janela (24 h por padrão) tem o cancelamento marcado como tardio e pode perder os créditos; dentro da janela, ou quando a equipe ou o anfitrião cancela, o estorno é por inteiro. A pessoa recebe o e-mail e o evento é cancelado na agenda dela. Uma reserva que já começou não se cancela (use a ausência). Mostra um resumo e só age depois do seu sim.

#reschedule_booking

Pede confirmação

Remarcar. Muda o horário na mesma sala (o que você não mandar fica, e a duração se mantém). Mexe nos créditos: um horário mais caro debita a diferença (sem saldo, a resposta traz shortfall), um mais barato estorna, uma cortesia não toca no livro. O convite é atualizado e a pessoa recebe um e-mail. Mostra o resumo e devolve charged, refunded e balanceAfter.

#mark_booking_no_show

Altera

Marcar a ausência. Só para reserva confirmada que já começou. A comunidade decide se os créditos se perdem; a resposta diz quantos foram devolvidos. Equipe e anfitrião. Parâmetro: booking_id.

#get_booking_ics

Só consulta

O convite de calendário, o mesmo arquivo do e-mail de confirmação, devolvido como texto em ics com o nome do arquivo (uma reserva cancelada devolve o cancelamento). Parâmetro: booking_id.

#Salas, bloqueios e preços

#create_booking_resource

Altera

Criar uma sala, mesa ou agenda. kind é ROOM, DESK, STATION ou OTHER (proprietário e administrador); no Agendamento, PERSON: quem pode criar a agenda de uma pessoa é decidido pelo offerers do espaço (um membro cria só a sua). O tipo não muda depois. Sem faixa de preço, é grátis.

#update_booking_resource

Altera

Editar. Muda só o que você mandar; troca a foto com image_url ou image_base64 e remove com remove_image. As reservas existentes mantêm o preço. Parâmetro resource_id mais os campos acima. No Agendamento, quem oferece edita a própria agenda, menos listed.

#delete_booking_resource

Pede confirmação

Excluir. Com reservas futuras ativas, a resposta é 409 listando-as; com cancel_bookings: true, cancela todas (estorno por inteiro e e-mail para cada pessoa) e exclui. Proprietário ou administrador.

#list_availability_exceptions

Só consulta

Bloqueios (CLOSED) e horários extras (OPEN) de uma sala daqui para frente. Parâmetros: resource_id, from.

#create_availability_exception

Altera

Bloquear ou abrir um período. kind é CLOSED (padrão: manutenção, feriado) ou OPEN (extra). Um bloqueio com reservas ativas é recusado com 409 listando-as: para cancelá-las, use cancel_bookings_for_closure. Salas: a equipe; agendas de pessoas: quem oferece e o proprietário e o administrador.

#cancel_bookings_for_closure

Pede confirmação

Bloquear cancelando. Bloqueia o período e cancela toda reserva ativa dentro dele: cada uma é estornada por inteiro, cada pessoa recebe o e-mail e o evento é cancelado na agenda. Diz quantas foram canceladas. Use depois que create_availability_exception respondeu 409 e a pessoa concordou. Parâmetros: resource_id, starts_at, ends_at, reason.

#delete_availability_exception

Pede confirmação

Remover um bloqueio ou horário extra. As reservas que o bloqueio já cancelou não voltam. Parâmetros: resource_id, exception_id.

#list_price_rules

Só consulta

As faixas de preço de uma sala (a única fonte de preço; sem faixa, é grátis). Vale a primeira que se encaixa: data específica, depois dia da semana, depois o padrão; o custo é por bloco, e cada bloco usa a faixa em que começa. Proprietário ou administrador. Parâmetro: resource_id.

#create_price_rule

Altera

Criar uma faixa. Por exemplo, 3 créditos a cada 30 minutos. Um horário oferecido por membro é sempre grátis; no Agendamento, uma faixa paga precisa de Permitir horários pagos no espaço (409). Cobrança em dinheiro ainda não é feita.

#update_price_rule

Altera

Editar uma faixa (resource_id, rule_id, e só o que mudar). As reservas já feitas mantêm o preço.

#delete_price_rule

Pede confirmação

Remover uma faixa. Sem nenhuma, a sala fica grátis; as reservas já feitas mantêm o preço. Parâmetros: resource_id, rule_id.

#Agendamento

#get_scheduling_config

Só consulta

As regras do espaço: quem oferece (offerers), allowPaidSlots, requireListingApproval, se você pode oferecer agora, as suas agendas e, para o proprietário e o administrador, quantas ofertas esperam aprovação. O horário de membro é sempre grátis. Parâmetro: space.

#search_scheduling_hosts

Só consulta

Pessoas com horário livre. Cada uma vem com as agendas, quantos horários livres tem e os próximos 3 (grátis ou o custo em créditos, com canAfford) e o seu saldo. Quando ninguém tem horário, sugere os mais próximos. Para marcar, use create_booking.

#get_scheduling_host

Só consulta

A página de uma pessoa, com a grade de horários livres por dia (1 a 7 dias). Uma pessoa sem agenda listada, que perdeu o papel ou de outra comunidade responde 404. Parâmetros: space, profile_id, date, days, duration_minutes.

#list_pending_scheduling_offers

Só consulta

Agendas esperando aprovação, cada uma com o dono e se ele ainda cumpre a regra de quem oferece. Proprietário ou administrador. Parâmetro: space.

#set_booking_resource_listing

Altera

Aprovar ou retirar uma agenda. listed: true aprova (a agenda aparece aos membros); false retira (não cancela nenhuma reserva já feita, só impede as novas). Reversível, sem confirmação. Proprietário ou administrador. Parâmetros: resource_id, listed.

#Relacionados

• Reservas
• Agendamento
• Ferramentas · Créditos
• Ferramentas
• Dinheiro e confirmação
• Receitas