Bookings

Returns a paginated list of business bookings. Supports filtering.

List bookings

GET /v1/bookings

Success: 200 OK

{
  "total": 42,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "startTime": "2026-03-05 10:00:00",
      "endTime": "2026-03-05 11:00:00",
      "status": "confirmed",
      "internalNote": null,
      "clientNote": null,
      "paymentStatus": null,
      "isFromWeb": false,
      "isFromAgent": false,
      "amount": 50.0,
      "clientId": "660e8400-e29b-41d4-a716-446655440001",
      "locationId": "770e8400-e29b-41d4-a716-446655440002",
      "serviceId": "880e8400-e29b-41d4-a716-446655440003",
      "personId": "990e8400-e29b-41d4-a716-446655440004",
      "paymentId": null,
      "businessAccountId": "aa0e8400-e29b-41d4-a716-446655440005",
      "location": { "id": "770e8400-e29b-41d4-a716-446655440002", "name": "Sede Principal" },
      "person": { "id": "990e8400-e29b-41d4-a716-446655440004", "firstname": "María", "lastname": "García", "email": "maria@example.com", "status": "active", "phone": "+593991234567" },
      "service": { "id": "880e8400-e29b-41d4-a716-446655440003", "name": "Corte de cabello", "duration": 60, "domiciliary": false, "virtual": false, "status": "active", "price": 50.0, "categoryId": "bb0e8400-e29b-41d4-a716-446655440006", "description": null, "sessions": null, "simultaneous": 1 },
      "client": { "id": "660e8400-e29b-41d4-a716-446655440001", "firstname": "Juan", "lastname": "Pérez", "email": "juan@example.com", "phone": "+593991234568" },
      "notifyClient": true,
      "repeatGroupId": null,
      "answers": null,
      "questionaryId": null,
      "createdAt": "2026-03-01 15:30:00"
    }
  ]
}

Get booking

GET /v1/bookings/{id}

Parameter	Type	Description
`id`	`string` (UUID)	Booking ID

Success: 200 OK — Single Booking object.

Error: 404 Not Found — { "message": "Booking not found." }

Create booking

POST /v1/bookings

Field	Type	Required	Description
`startTime`	`string`	Yes	Start date/time ISO 8601. e.g. `2026-03-05T10:00:00Z`
`endTime`	`string`	Yes	End date/time ISO 8601. Must be after `startTime`
`status`	`string`	Yes	Status: `reserved`, `pending`, `confirmed`, `no_show`, `completed`, `cancelled`
`internalNote`	`string`	No	Internal note
`amount`	`number`	Yes	Booking amount (>= 0)
`clientId`	`string` (UUID)	Yes	Client UUID
`locationId`	`string` (UUID)	Yes	Location UUID
`serviceId`	`string` (UUID)	Yes	Service UUID
`personId`	`string` (UUID)	No	Professional UUID
`notifyClient`	`boolean`	No	Notify client (default: `true`)

Example: (same JSON as in Spanish docs)

Success: 201 Created — { "id": "cc0e8400-e29b-41d4-a716-446655440007" }

Update booking (partial)

PUT /v1/bookings/{id}

Parameter	Type	Description
`id`	`string` (UUID)	Booking ID

Allows partial update of an existing booking. Only the fields sent will be modified; omitted fields keep their current value.

Note: Origin fields (isFromWeb, isFromAgent, isFromApi) cannot be modified.

Body (all fields optional):

Field	Type	Description
`startTime`	`string` (ISO 8601)	Start date/time
`endTime`	`string` (ISO 8601)	End date/time
`status`	`string`	Status: `reserved`, `pending`, `confirmed`, `no_show`, `completed`, `cancelled`
`internalNote`	`string`	Internal note
`amount`	`number`	Amount (≥ 0)
`clientId`	`string` (UUID)	Client ID
`locationId`	`string` (UUID)	Location ID
`serviceId`	`string` (UUID)	Service ID
`personId`	`string` (UUID)	Professional ID
`notifyClient`	`boolean`	Notify client (default: `true`)

Example — update status only:

{
  "status": "confirmed"
}

Example — update time and amount:

{
  "startTime": "2026-04-01T14:00:00Z",
  "endTime": "2026-04-01T15:00:00Z",
  "amount": 75.00
}

Success: 204 No Content

Error if booking does not exist: 422 Unprocessable Entity

Delete booking

DELETE /v1/bookings/{id}

Performs a soft-delete of the booking.

Success: 204 No Content

Check availability

GET /v1/bookings/availability

Returns available time slots for a service at a location.

Parameter	Type	Required	Description
`locationId`	`string` (UUID)	Yes	Location UUID
`serviceId`	`string` (UUID)	Yes	Service UUID
`startDate`	`string`	No	Start date (`YYYY-MM-DD`). Default: today
`endDate`	`string`	No	End date (`YYYY-MM-DD`). Default: startDate + 30 days
`professionalId`	`string` (UUID)	No	Filter by specific professional

Success: 200 OK — (same slots JSON as in Spanish docs)

Field	Type	Description
`days`	`string[]`	Dates with availability (`YYYY-MM-DD`)
`professionals`	`Professional[]`	Professionals with at least one slot
`slots`	`Slot[]`	Available time slots
`slots[].startTime` / `slots[].endTime`	`string`	Slot start/end (`YYYY-MM-DD HH:mm:ss`)
`limitExceeded`	`boolean`	`true` if range exceeded schedule window