Послуги, слоти та майстри

Перед створенням запису потрібно отримати дані для форми бронювання: які послуги доступні, хто з майстрів працює, та які слоти вільні.

---

Інформація про бізнес

GET /v1/integration/business

Scope: business:read

Повертає публічну інформацію про ваш бізнес — назву, адресу, графік роботи, фото.

curl -H "X-API-Key: ВАШ_КЛЮЧ" \
  https://api.zapys24.com/v1/integration/business

Відповідь:

{
  "id": 1,
  "name": "Beauty Studio",
  "slug": "beauty-studio",
  "type": "beauty",
  "description": "Найкращий салон краси у Києві",
  "address": "вул. Хрещатик, 1",
  "city": "Київ",
  "phone": "+380991234567",
  "email": "[email protected]",
  "website": "https://beauty-studio.ua",
  "timezone": "Europe/Kyiv",
  "workingHours": {
    "monday": { "open": "09:00", "close": "20:00" },
    "tuesday": { "open": "09:00", "close": "20:00" },
    "sunday": null
  },
  "bookingSettings": {
    "allowClientCancellation": true,
    "cancellationMinAdvanceMinutes": 120,
    "maxAdvanceBookingDays": 30
  },
  "logoUrl": "https://cdn.zapys24.com/logo.jpg",
  "averageRating": 4.7,
  "reviewCount": 42,
  "photos": [
    {
      "id": 1,
      "url": "https://cdn.zapys24.com/photo1.jpg",
      "thumbnailUrl": "https://cdn.zapys24.com/photo1_thumb.jpg",
      "order": 0
    }
  ]
}

Корисні поля

• bookingSettings.maxAdvanceBookingDays — на скільки днів вперед можна записатись (наприклад, 30). Використовуйте для обмеження calendar picker.
• bookingSettings.allowClientCancellation — чи дозволено скасування через API.
• workingHours — дні з null означають вихідний.

---

Послуги

Список послуг

GET /v1/integration/services

Scope: services:read

Параметр	Тип	Опис
category	string	Фільтр за категорією
onlineOnly	boolean	Лише послуги, доступні для онлайн-запису

curl -H "X-API-Key: ВАШ_КЛЮЧ" \
  "https://api.zapys24.com/v1/integration/services?onlineOnly=true"

Відповідь:

[
  {
    "id": 1,
    "name": "Стрижка чоловіча",
    "description": "Класична чоловіча стрижка будь-якої складності",
    "duration": 60,
    "price": 50000,
    "category": "Перукарські послуги",
    "isOnline": true,
    "bufferTimeBefore": 0,
    "bufferTimeAfter": 10
  }
]

Поле	Опис
duration	Тривалість у хвилинах
price	Ціна у копійках (50000 = 500,00 ₴)
isOnline	Чи доступна для онлайн-бронювання
bufferTimeBefore / bufferTimeAfter	Буферний час до/після послуги (хвилини)

Отримати одну послугу

GET /v1/integration/services/:id

Scope: services:read

---

Майстри (співробітники)

Список майстрів

GET /v1/integration/staff

Scope: staff:read

Повертає лише активних та видимих майстрів.

curl -H "X-API-Key: ВАШ_КЛЮЧ" \
  https://api.zapys24.com/v1/integration/staff

Відповідь:

[
  {
    "id": 1,
    "firstName": "Олена",
    "lastName": "Коваль",
    "position": "Стиліст",
    "bio": "Досвід роботи 10 років",
    "avatarUrl": "https://cdn.zapys24.com/avatar.jpg",
    "rating": 4.8,
    "serviceIds": [1, 2, 3],
    "schedule": [
      {
        "dayOfWeek": "monday",
        "startTime": "09:00",
        "endTime": "18:00",
        "isWorkingDay": true
      },
      {
        "dayOfWeek": "sunday",
        "startTime": "00:00",
        "endTime": "00:00",
        "isWorkingDay": false
      }
    ]
  }
]

Поле	Опис
serviceIds	Масив ID послуг, які надає цей майстер. Використовуйте для фільтрації — якщо клієнт обрав послугу, покажіть лише відповідних майстрів
schedule	Робочий розклад. isWorkingDay: false — вихідний
rating	Середній рейтинг від клієнтів

Отримати одного майстра

GET /v1/integration/staff/:id

Scope: staff:read

---

Вільні слоти

Це ключовий ендпоінт для форми бронювання — він повертає доступний час для запису.

Слоти на конкретну дату

GET /v1/integration/slots

Scope: slots:read

Параметр	Тип	Обов'язково	Опис
serviceId	number	✅	ID послуги
staffId	number	—	ID майстра. Без нього — повертаються слоти всіх майстрів
date	string	✅	Дата у форматі YYYY-MM-DD

curl -H "X-API-Key: ВАШ_КЛЮЧ" \
  "https://api.zapys24.com/v1/integration/slots?serviceId=1&date=2026-03-15"

Відповідь:

{
  "date": "2026-03-15",
  "slots": [
    {
      "time": "09:00",
      "staffId": 1,
      "staffName": "Олена Коваль",
      "available": true
    },
    {
      "time": "10:00",
      "staffId": 1,
      "staffName": "Олена Коваль",
      "available": true
    },
    {
      "time": "11:00",
      "staffId": 2,
      "staffName": "Марія Петренко",
      "available": false
    }
  ]
}

Логіка вибору

Коли staffId не вказано, повертаються слоти від усіх кваліфікованих майстрів. Якщо один час доступний у кількох — повертається перший доступний.

Показуйте клієнту лише слоти з available: true.

Слоти за діапазоном дат

Для календарного вигляду — отримайте слоти одразу на кілька днів:

GET /v1/integration/slots/range

Scope: slots:read

Параметр	Тип	Обов'язково	Опис
serviceId	number	✅	ID послуги
staffId	number	—	ID майстра
from	string	✅	Початок діапазону YYYY-MM-DD
to	string	✅	Кінець діапазону YYYY-MM-DD

curl -H "X-API-Key: ВАШ_КЛЮЧ" \
  "https://api.zapys24.com/v1/integration/slots/range?serviceId=1&from=2026-03-15&to=2026-03-21"

Обмеження: максимум 14 днів у діапазоні. Минулі дати заборонені.

Відповідь: масив об'єктів — по одному на кожну дату з доступними слотами.

---

Відгуки

Список відгуків

GET /v1/integration/reviews

Scope: reviews:read

Параметр	Тип	За замовч.	Опис
page	number	1	Номер сторінки
limit	number	10	Кількість на сторінку (максимум 50)

curl -H "X-API-Key: ВАШ_КЛЮЧ" \
  "https://api.zapys24.com/v1/integration/reviews?limit=5"

Відповідь:

{
  "data": [
    {
      "id": 1,
      "rating": 5,
      "comment": "Чудовий сервіс!",
      "clientName": "Олена К.",
      "staffName": "Марія Петренко",
      "serviceName": "Стрижка жіноча",
      "createdAt": "2026-03-01T12:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 5
}

Використовуйте відгуки для підвищення довіри на вашому сайті — покажіть рейтинг та коментарі клієнтів поруч із формою бронювання.