claude-plugins/wordpress/skills/mcp-fluent-booking/references/api-reference.md

FluentBooking — referência da REST API (confirmado em produção, 2026-08-19)

Namespace: fluent-booking/v2 (WP REST API real, wp-json/fluent-booking/v2/...). Auth: Basic Auth com Application Password — o permission_callback de cada rota é uma Policy que verifica current_user_can()/PermissionManager, não nonce de sessão. 100 rotas registadas entre free e Pro; este ficheiro documenta só as usadas pelo MCP.

Calendários (/calendars)

GET /calendars — lista todos, cada um com slots[] (event types) aninhados, incluindo settings.weekly_schedules completo por dia. GET /calendars/{id} — um só, mesma forma.

Campos relevantes de um calendar: id, title, slug, status (active/…), type (simple/…), visibility (public/…), author_timezone, public_url (https://descomplicar.pt/?fluent-booking=calendar&host=<slug>), author_profile (nome, avatar, telefone).

Event types (/events/{event_id}, aninhado em calendars[].slots[])

GET /events/{event_id} → {calendar_event: {...}}. Campos: id, calendar_id, duration (minutos), title, slug, description (HTML), settings.schedule_type (weekly_schedules/…), settings.weekly_schedules.<dia>.{enabled, slots:[{start,end}]}.

Gotcha de nomes: GET /calendars/event-lists (sem id) devolve sempre {"code":"plugin_exception", ...} em produção — não é um bug do MCP, o controller CalendarController@getCalendarEventLists está partido standalone nesta instalação. Não usar este endpoint; listar event types via fb_list_calendars/fb_get_calendar (já vêm aninhados).

Reservas (/schedules)

GET /schedules — parâmetros via filters[...] (bracket notation, o MCP trata isto automaticamente a partir de campos planos no input schema):

Filtro	Valores	Nota
filters[period]	upcoming (omissão), completed, cancelled, pending, no_show, latest_bookings, all	Valor fora da lista cai silenciosamente para upcoming
filters[author]	id numérico do calendário, me, all	Sem permissão "ver todas as reservas", o utilizador só vê as suas mesmo que peça all
filters[event]	id numérico do event type
filters[event_type]	single/group/…
filters[email]	email do convidado
filters[range]	[date_from, date_to]	Filtra por created_at, não pela hora da reunião
search	texto livre	nome/email do convidado
page	inteiro	paginação Laravel-style

Forma de uma reserva (schedules.data[]): id, hash, calendar_id, event_id, group_id (agrupa reservas de grupo), host_user_id, start_time/end_time (timezone do site), first_name/last_name/email/phone/message, location_details ({type, online_meeting_link} ou presencial), status (scheduled/completed/cancelled/rejected/no_show), payment_status, source_url (página onde o convidado marcou), custom_form_data (campos custom do formulário de marcação, por chave), calendar_event (event type completo aninhado, redundante mas presente sempre), happening_status, booking_status_text, reschedule_url.

GET /schedules/{id} — mesma forma para uma reserva.

PUT /schedules/{id} (fb_update_booking_status) — body {column:"status", value:<estado>, cancel_reason?, reject_reason?, refund_payment?}. Colunas válidas no controller real: internal_note, email, phone, first_name, last_name, status, payment_status — o MCP só expõe status deliberadamente (as outras deixam editar dados do convidado sem justificação de negócio clara; ver SKILL.md "Fora do âmbito"). Side-effects reais confirmados no código (SchedulesController::patchBooking):

• status=cancelled → Booking::cancelMeeting($reason, 'host', $userId) + email de cancelamento.
• status=rejected → Booking::rejectMeeting($reason, $userId).
• status=scheduled com payment_method+payment_order associados → marca a order como paid.
• Valor igual ao actual → 422 {"message":"No changes found"} (não é um bug, é a validação do próprio plugin — útil para testar o caminho de escrita sem mutar nada).

POST /schedules/{id}/send-confirmation-email (fb_send_confirmation_email) — sem body, envia email real.

Actividade (/schedules/{id}/activities, /reports/activities)

Mesma forma nos dois: {id, booking_id, parent_id, created_by, status, type, title, description, created_at, updated_at}. /reports/activities é o log do site inteiro (todas as reservas); /schedules/{id}/activities filtra a uma só.

Disponibilidade (/availability)

GET /availability — lista templates reutilizáveis ({id, host_name, title, usage_count, settings:{timezone, date_overrides[], weekly_schedules}}). GET /availability/{id} — um só, envelope {schedule: {...}} em vez de {availabilities: {data:[...]}}.

Reports (/reports, /reports/graph-reports)

GET /reports → {overview: [{title, period?, number, content, stat}], latest_books: [...]}. Métricas confirmadas: Total Bookings, Completed Bookings, Cancelled Bookings, Total Guests.

GET /reports/graph-reports?date_range[0]=YYYY-MM-DD&date_range[1]=YYYY-MM-DD → {booked_stats, completed_stats, cancelled_stats}, cada um {"YYYY-MM-DD": count}. Sem date_range, o controller usa uma janela por omissão (~7 dias, granularidade adaptada ao intervalo — dia/semana/mês).

Definições e equipa

GET /settings/general → {payments, emailing, administration} (moeda, remetente/rodapé de email, auto_cancel_timing, dia de início da semana). GET /admin/all-hosts → {hosts: [{id, name, label, avatar, calendar_id, deleted_user}]}. GET /settings/license (Pro) → {status, variation_title, expires, is_expired, activation_hash, renew_url, purchase_url}.