Skip to main content

​
Endpoint

GET /api/reservations/availability

​
Description

Retrieves available time slots for a professional on a specific date. This endpoint considers existing reservations and the professional’s work schedule to return only available times. See implementation in server/src/modules/reservations/reservations.controller.ts:129-143.

​
Authentication

This endpoint requires Bearer token authentication. Include your access token in the Authorization header.

​
Query Parameters

​
date
string
required
The date to check availability in YYYY-MM-DD formatExample: 2026-03-15
​
professional_id
string
required
The unique identifier of the professionalExample: prof456

​
Response

The response structure depends on the service implementation. Typically returns available time slots for the specified date.
​
data
array
Array of available time slots

​
Example Request

curl -X GET "https://your-domain.com/api/reservations/availability?date=2026-03-15&professional_id=prof456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

​
Example Response

{
  "status": 200,
  "data": [
    {
      "start_time": "2026-03-15T09:00:00Z",
      "end_time": "2026-03-15T10:00:00Z",
      "available": true
    },
    {
      "start_time": "2026-03-15T10:00:00Z",
      "end_time": "2026-03-15T11:00:00Z",
      "available": false
    },
    {
      "start_time": "2026-03-15T11:00:00Z",
      "end_time": "2026-03-15T12:00:00Z",
      "available": true
    }
  ]
}

​
Error Responses

​
Bad Request

{
  "statusCode": 400,
  "message": "Error al obtener la disponibilidad",
  "error": "Bad Request"
}

​
Invalid Date Format

{
  "statusCode": 400,
  "message": "Formato de fecha inválido. Use YYYY-MM-DD",
  "error": "Bad Request"
}

​
Unauthorized

{
  "statusCode": 401,
  "message": "Token inválido o expirado",
  "error": "Unauthorized"
}

​
How It Works

  1. The endpoint retrieves the professional’s settings (work hours, session duration)
  2. Generates possible time slots based on the work schedule
  3. Checks existing reservations for the specified date
  4. Returns only the available time slots

​
Use Cases

  • Display available appointment times to clients
  • Build a booking interface with real-time availability
  • Prevent double-booking
  • Show professionals when they have free slots

​
Notes

  • Date must be in YYYY-MM-DD format
  • Availability is calculated based on:
    • Professional’s work hours
    • Session duration settings
    • Existing reservations
    • Reservation window (how far in advance bookings are allowed)
  • Times are returned in ISO 8601 format with timezone
  • To create a reservation, use Create Without Payment or Create With Payment

Build docs developers (and LLMs) love

Get started for freeTalk to us