Saltearse al contenido

Reservas y Citas — Guía de Desarrollo y Admin UI

Ventana de terminal
pnpm add @vicacha-devs/strapi-plugin-calendar @vicacha-devs/strapi-plugin-bookings

2. Configuración del Servidor (config/plugins.ts)

Sección titulada «2. Configuración del Servidor (config/plugins.ts)»

Agregue la configuración del plugin en el archivo config/plugins.ts de su aplicación Strapi v5:

config/plugins.ts
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({
"bookings": {
enabled: true,
config: {
defaultTimezone: env("CALENDAR_DEFAULT_TIMEZONE", "UTC"),
defaultSlotDurationMinutes: 60,
},
},
});

Reservas y Citas — Strapi v5 Settings Panel

3. Recorrido por la Interfaz de Administración (Strapi v5 Admin UI)

Sección titulada «3. Recorrido por la Interfaz de Administración (Strapi v5 Admin UI)»

Una vez habilitado, el plugin registra su espacio de trabajo y ajustes dentro del panel de administración de Strapi v5 utilizando Strapi Design System v2:

Reservas y Citas — Strapi v5 Admin UI

Etiquetas Localizadas de la Interfaz (Español)

Sección titulada «Etiquetas Localizadas de la Interfaz (Español)»
Clave de Traducción Texto en Interfaz
settings.theme.breeze.label Brisa (Cielo y Pizarra — Predeterminado)
bookings.settings.theme.breeze.label Brisa (Cielo y Pizarra — Predeterminado)
settings.theme.breeze.description Cuadrícula azul cielo y pizarra de alto contraste con insignias Hijri en ámbar cálido
bookings.settings.theme.breeze.description Cuadrícula azul cielo y pizarra de alto contraste con insignias Hijri en ámbar cálido
settings.theme.emerald.label Mezquita Esmeralda (Verde Azulado y Oro)
bookings.settings.theme.emerald.label Mezquita Esmeralda (Verde Azulado y Oro)
settings.theme.emerald.description Encabezados verde esmeralda islámico con resaltados dorados para el calendario secundario
bookings.settings.theme.emerald.description Encabezados verde esmeralda islámico con resaltados dorados para el calendario secundario

4. Entidades Content-Type, Ubicación y Esquemas (strapi.documents)

Sección titulada «4. Entidades Content-Type, Ubicación y Esquemas (strapi.documents)»

Registers two relational Collection Types (plugin::bookings.resource one-to-many plugin::bookings.booking). Resources define weekly/seasonal availability windows, slot duration, buffers, and capacity; Bookings store individual customer reservations, party size, status transitions, and hashed self-service cancellation tokens. Supports runtime schemaExtensions (resource, booking) and customFields in config/plugins.ts.

Dónde Encontrar las Entidades Content-Type en Strapi v5

Sección titulada «Dónde Encontrar las Entidades Content-Type en Strapi v5»
  • Content Manager: /admin/content-manager/collection-types/plugin::bookings.resource & /admin/content-manager/collection-types/plugin::bookings.booking (visible: true)
  • Content-Type Builder: /admin/plugins/content-type-builder under Collection Types (Booking Resource & Booking)
  • Plugin Workspace & Settings: /admin/plugins/bookings (Reservations & Resources manager) and /admin/settings/bookings
  • Database Tables: booking_resources and bookings

Reservation, appointment, or resource slot booking

Kind: collectionType · DB Table: bookings · Admin Location: /admin/content-manager/collection-types/plugin::bookings.booking · Draft & Publish: No · i18n: No

Atributo Tipo en Strapi Requerido Restricciones / Relación
bookingCode string Yes max: 48
title string No max: 200
resource relation No target: plugin::bookings.resource
customerName string Yes max: 120
customerEmail email Yes —
customerPhone string No max: 40
organization string No max: 160
startDate datetime Yes —
endDate datetime Yes —
slotLabel string No max: 80
timezone string No max: 64; default: "UTC"
partySize integer Yes default: 1
status enumeration Yes enum: pending, confirmed, completed, cancelled, no_show; default: "pending"
preferredLanguage string No max: 16
assignedHost string No max: 120
notes text No max: 2000
internalNotes text No max: 2000; private: true
cancelTokenHash string No max: 128; private: true
sourceCollection string No default: "plugin::bookings.booking"
metadata json No —

plugin::bookings.resource — Booking Resource

Sección titulada «plugin::bookings.resource — Booking Resource»

Bookable service, appointment type, room, staff member, or equipment schedule

Kind: collectionType · DB Table: booking_resources · Admin Location: /admin/content-manager/collection-types/plugin::bookings.resource · Draft & Publish: No · i18n: No

Atributo Tipo en Strapi Requerido Restricciones / Relación
name string Yes max: 160
slug uid Yes —
resourceType enumeration Yes enum: service, appointment, room, staff, equipment, other; default: "service"
description text No —
color string No max: 32; default: "#0d9488"
timezone string No max: 64; default: "UTC"
slotDurationMinutes integer Yes default: 60
bufferBeforeMinutes integer No default: 0
bufferAfterMinutes integer No default: 0
capacityPerSlot integer Yes default: 1
maxPartySize integer No default: 50
minLeadTimeHours integer No default: 2
maxAdvanceDays integer No default: 90
requiresApproval boolean No default: false
weeklySchedule json No —
seasonalSchedules json No —
holidayRules json No —
blackoutDates json No —
recurrenceRule string No —
supportedLanguages json No —
assignedHosts json No —
location string No max: 240
price decimal No default: 0
currency string No max: 10; default: "USD"
isActive boolean No default: true
metadata json No —
bookings relation No target: plugin::bookings.booking

Integración con el Content Manager de Strapi v5 (/admin/content-manager)

Sección titulada «Integración con el Content Manager de Strapi v5 (/admin/content-manager)»

Grupo en la Barra Lateral del Content Manager: Events, Scheduling & Bookings

Entidades y Componentes en el Content Manager

Sección titulada «Entidades y Componentes en el Content Manager»
  • plugin::bookings.resource (Booking Resource — /admin/content-manager/collection-types/plugin::bookings.resource)
  • plugin::bookings.booking (Booking — /admin/content-manager/collection-types/plugin::bookings.booking)

Reservas y Citas — Vista de Entidades en el Content Manager de Strapi v5

Por Qué Este Plugin Crea e Integra Entidades en el Content Manager

Sección titulada «Por Qué Este Plugin Crea e Integra Entidades en el Content Manager»

@vicacha-devs/strapi-plugin-bookings registers both Booking Resource (plugin::bookings.resource) and Booking (plugin::bookings.booking) with pluginOptions['content-manager'].visible = true so teams can combine the operational slot-availability engine in /admin/plugins/bookings with Strapi v5’s native Content Manager relational modeling and schema extensibility:

  • Relational Linking to Host Entities (api::*): Link a Booking Resource directly to a Staff, Scholar & Author (api::leader.leader) record, room media gallery, or department via schemaExtensions.resource in config/plugins.ts.
  • Custom Intake Attributes (customFields & schemaExtensions.booking): Inspect and edit custom reservation fields (such as organizationName, cateringRequired, or equipmentNotes) alongside native Strapi audit columns (createdBy, updatedBy).
  • Advanced Filtering & Bulk Operations: Filter hundreds of historical reservations by status, startAt, resource, or customerEmail using Content Manager’s multi-condition filter builder and bulk-delete test records.
  • Cross-Plugin Side-Panel Ecosystem: Attach internal staff handoff notes via @vicacha-devs/strapi-plugin-notes in the Content Manager right sidebar or jump straight to a booking via Cmd+K (@vicacha-devs/strapi-plugin-global-search).

Cómo Usarlo en el Content Manager de Strapi (Paso a Paso)

Sección titulada «Cómo Usarlo en el Content Manager de Strapi (Paso a Paso)»
  1. Open in Content Manager: In the left sidebar, click Content Manager -> Collection Types -> Events, Scheduling & Bookings and select Booking Resource (/admin/content-manager/collection-types/plugin::bookings.resource) or Booking (/admin/content-manager/collection-types/plugin::bookings.booking).
  2. Configure Bookable Resources: Click + Create new entry in Booking Resource to define name, slug, resourceType (room, counselor, equipment, service, appointment), capacity, slotDurationMinutes, bufferBeforeMinutes, bufferAfterMinutes, and weeklySchedule JSON rules.
  3. Manage & Link Reservations: Open any Booking entry to inspect or update bookingCode, startAt, endAt, partySize, status, the linked resource relation, and any custom fields registered under config.schemaExtensions.booking.
  4. Workspace vs. Content Manager: Use Content Manager for structured resource setup, relational linking, and bulk filtering; use the Bookings Workspace (/admin/plugins/bookings) for 1-click status transitions (confirmed, completed, no_show) and availability slot testing.

Sincronización entre el Content Manager y el Espacio del Plugin

Sección titulada «Sincronización entre el Content Manager y el Espacio del Plugin»

Casos de Uso en el Content Manager y Flujos Editoriales

Sección titulada «Casos de Uso en el Content Manager y Flujos Editoriales»

Content Manager Use Case 1 — Linking Counselors & Imams (api::leader.leader) to Bookable Resources

Sección titulada «Content Manager Use Case 1 — Linking Counselors & Imams (api::leader.leader) to Bookable Resources»
  • Para qué sirve y por qué usarlo: Connect each appointment or counseling resource in plugin::bookings.resource to an institutional profile in api::leader.leader and a Media Library cover photo.
  • Cómo ejecutarlo en el Content Manager: Extend resource via schemaExtensions in config/plugins.ts, open /admin/content-manager/collection-types/plugin::bookings.resource, select the assigned scholar/counselor relation, and save.

Content Manager Use Case 2 — Auditing & Bulk-Filtering Reservations with Editorial Notes

Sección titulada «Content Manager Use Case 2 — Auditing & Bulk-Filtering Reservations with Editorial Notes»
  • Para qué sirve y por qué usarlo: Filter pending or high-capacity room bookings in Content Manager and attach internal preparation checklists in the right sidebar.
  • Cómo ejecutarlo en el Content Manager: Open /admin/content-manager/collection-types/plugin::bookings.booking, apply a filter on status = pending or partySize > 20, open the entry, and add a pinned note in the Notes side panel.

Use Case 1 — Public Self-Service Slot Discovery & Reservation

Sección titulada «Use Case 1 — Public Self-Service Slot Discovery & Reservation»
  • What it is for: Allow website visitors to query available time slots for a room, counselor, imam, or equipment resource and book a slot without double-booking.
  • How it works: Query GET /api/bookings/available-slots?resourceSlug=main-conference-hall&date=2026-05-15, then submit POST /api/bookings/reserve to create a plugin::bookings.booking entity and receive a one-time cancellation token.

Bookings & Reservations — Strapi v5 Admin Workspace

Use Case 2 — Multi-Host Appointment & Buffer Enforcement

Sección titulada «Use Case 2 — Multi-Host Appointment & Buffer Enforcement»
  • What it is for: Manage 1-on-1 consultations or guided tours with automatic pre/post buffer windows (bufferBeforeMinutes, bufferAfterMinutes), minimum lead time (minLeadTimeHours), and host assignment (assignedHost).
  • How it works: Configure weeklySchedule, seasonalSchedules, and blackoutDates on plugin::bookings.resource; staff approve or mark completed / no_show via PUT /bookings/bookings/{documentId}/status.

Bookings & Reservations — Strapi v5 Settings Panel

Use Case 3 — Tokenized Self-Service Rescheduling & Cancellation

Sección titulada «Use Case 3 — Tokenized Self-Service Rescheduling & Cancellation»
  • What it is for: Let customers reschedule or cancel their reservation from an email link without requiring a Strapi account.
  • How it works: Pass the customer’s bookingCode and plaintext cancelToken (verified against cancelTokenHash) to POST /api/bookings/reschedule or POST /api/bookings/cancel.

Bookings & Reservations — Strapi v5 Content Manager Entities

Use Case 4 — Unified Calendar & iCal Feed Synchronization

Sección titulada «Use Case 4 — Unified Calendar & iCal Feed Synchronization»
  • What it is for: Project all confirmed and pending reservations into the FullCalendar workspace and external Google/Apple Calendar clients.
  • How it works: At bootstrap, bookings registers plugin::bookings.booking with strapi.plugin('calendar').service('registry') and exposes GET /api/bookings/feed.ics.
Método Ruta del Endpoint Ámbito Controlador Autenticación
GET /bookings/settings admin admin.getSettings Bearer JWT
PUT /bookings/settings admin admin.updateSettings Bearer JWT
GET /bookings/schemas admin admin.discoverSchemas Bearer JWT
GET /bookings/resources admin admin.listResources Bearer JWT
POST /bookings/resources admin admin.saveResource Bearer JWT
GET /bookings/calendar admin admin.getCalendar Bearer JWT
POST /bookings/bookings admin admin.createBooking Bearer JWT
PUT /bookings/bookings/{documentId}/status admin admin.updateBookingStatus Bearer JWT
POST /bookings/bookings/reschedule admin admin.rescheduleBooking Bearer JWT
GET /bookings/export.csv admin admin.exportCsv Bearer JWT
GET /bookings/export.ics admin admin.exportICal Bearer JWT
GET /api/bookings/resources content-api content-api.listPublicResources Bearer JWT
GET /api/bookings/available-slots content-api content-api.getAvailableSlots Bearer JWT
POST /api/bookings/reserve content-api content-api.createReservation Bearer JWT
POST /api/bookings/reschedule content-api content-api.rescheduleReservation Bearer JWT
POST /api/bookings/cancel content-api content-api.cancelReservation Bearer JWT
GET /api/bookings/feed.ics content-api content-api.getICalFeed Bearer JWT

7. Uso Programático en el Servidor (strapi.plugin y strapi.documents)

Sección titulada «7. Uso Programático en el Servidor (strapi.plugin y strapi.documents)»
// Registered services on plugin "bookings": "settings", "availability", "reservation"
const pluginService = strapi.plugin("bookings")?.service("availability");
// Querying records via the Strapi v5 Document Service API
const records = await strapi.documents("plugin::bookings.booking").findMany({
limit: 25,
sort: "createdAt:desc",
});
  • Cambios no visibles en el panel Admin: Ejecute pnpm strapi build después de editar config/plugins.ts.
  • Aislamiento de dependencias peer: Mantenga hoistPattern: ["*", "!@strapi/*"] en pnpm-workspace.yaml para evitar colisiones de contexto en React.
  • Verificación estricta de TypeScript: Ejecute pnpm check para validar admin/tsconfig.json y server/tsconfig.json.