Service Properties

This document defines the structure of the service entity, including required properties and their descriptions.

🔹 Core Properties

Property	Type	Required	Description	Example
id	string	Yes	Unique identifier for the service	"550e8400-e29b-41d4-a716-446655440000"
name	string	Yes	The name of the service	"Standard Consultation"
duration	number	Yes	Duration of appointments in minutes	60
timeBetween	number	Yes	Buffer time between appointments in minutes	15

⏰ Scheduling Constraints

Property	Type	Required	Description	Example
minTimeToSchedule	number	Yes	Minimum days in advance required for booking	1
maxTimeToSchedule	number	Yes	Maximum days in advance allowed for booking	120
incrementTime	number	Yes	Time slot increment in minutes	15
deniedMultipleAppointment	boolean	No	Prevents multiple bookings for the same client	true

📋 Additional Settings

Property	Type	Required	Description	Example
extraFields	object	No	Custom fields for the service	{"requiredDocuments": ["id"]}
image	string	No	URL for the service image	"https://example.com/img.jpg"
userGroupId	string	No	Associated user group ID	"550e8400-e29b-41d4-a716-446655440000"
organizationId	string	No	Organization ID	"550e8400-e29b-41d4-a716-446655440000"

---

🧩 Example Entry

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Standard Consultation",
  "duration": 60,
  "timeBetween": 15,
  "minTimeToSchedule": 1,
  "maxTimeToSchedule": 120,
  "incrementTime": 15,
  "deniedMultipleAppointment": true,
  "extraFields": {
    "requiredDocuments": ["id", "insurance"],
    "location": "Virtual"
  },
  "image": "https://example.com/service-image.jpg"
}

---

🔍 Related Entities

Calendar Association

A service can be associated with one or more calendars. Each association includes:

• calendarId: The ID of the associated calendar
• active: Whether the calendar is active for this service
• restrictionDates: Custom date restrictions for this calendar

Weekly Schedule

Services can have associated weekly schedules that define:

• Regular availability windows
• Recurring time slots
• Day-specific settings

---

📝 Notes

• incrementTime affects the granularity of available time slots
• extraFields can be used to add custom requirements or information
• Time-related properties (duration, timeBetween, incrementTime) are all in minutes
• Scheduling window properties (minTimeToSchedule, maxTimeToSchedule) are in days

Calendars

The calendars property is an array within a service payload. Each item defines calendar-based restrictions or availability settings tied to external resources, such as agents, assets, or other schedulable entities.

---

🔹 Structure

Each object in the calendars array includes the following fields:

Field	Type	Required	Description
calendarId	string	Yes	Identifier of the linked calendar.
active	boolean	No	Whether this calendar is currently active.
restrictionDates	object	No	Defines time-based restrictions.
├─ exclude	array	No	List of date-time range arrays to exclude from availability.
├─ include	array	No	List of date-time range arrays to explicitly include.
timezone	string	No	Timezone (IANA format) used to interpret the date-time values.
type	string	No	Type of entity the calendar applies to (e.g., "asset").
name	string	No	Human-readable name of the related resource.

---

🧩 Example Entry

{
  "calendarId": "2c4331e6-c164-40ec-b66b-d453d26434ee",
  "active": true,
  "restrictionDates": {
    "exclude": [
      [
        "2025-05-22T08:21:00.000Z",
        "2025-05-25T08:21:00.000Z"
      ]
    ],
    "include": []
  },
  "timezone": "Europe/Madrid",
  "type": "asset",
  "name": "CUPRA TAVASCAN"
}

---

🔍 Interpretation

• The calendar entry is active, meaning the restrictions apply.
• It blocks availability from May 22, 2025, 08:21 UTC to May 25, 2025, 08:21 UTC.
• The timezone (Europe/Madrid) is used to interpret all date-time values.
• The calendar is related to an asset named "CUPRA TAVASCAN".
• The include array is empty, meaning no override periods are defined to explicitly open availability during blocked times.

---

✅ Use Cases

• 🔧 Maintenance Windows: Block bookings during asset maintenance.
• 🚗 Vehicle Sharing Platforms: Disable availability when a vehicle is reserved or under service.
• 🗓 Dynamic Scheduling: Apply temporary restrictions on services based on third-party calendar events.
• 🌐 Timezone-Aware Availability: Ensure restrictions are respected in the appropriate local context.

---

📘 Notes

• Exclusion precedence: Times listed in exclude are treated as unavailable, regardless of general availability rules elsewhere in the system.
• Inclusion override: The include array can be used to re-allow specific times that may fall within exclusion ranges (if supported by the system logic).
• Timezone importance: Always ensure timezone is properly set, as it affects the interpretation of all restrictionDates.
• Extensibility: This structure allows associating multiple external calendars with a single service, supporting complex scenarios like multi-resource scheduling.

---