Для вашого сайту

Інтеграції для Beauty Studio

Додайте онлайн-запис віджетом або підключіть власну серверну інтеграцію через API.

Віджет запису для вашого сайту

Великий і компактний віджети доступні на тарифах Pro та Pro+. Вставте готовий код у HTML свого сайту — клієнт пройде весь запис, не залишаючи сторінку.
Pro
Готовий код Переглянути віджет 
<iframe data-vuzol-booking-widget="large" src="https://vzl.one/embed/book/demo-business" title="Онлайн-запис — Beauty Studio" loading="lazy" style="width:100%;min-height:720px;border:0;border-radius:24px;"></iframe>
<script async src="https://vzl.one/static/booking-widget-loader.js"></script>
Готовий код Переглянути віджет 
<iframe data-vuzol-booking-widget="compact" src="https://vzl.one/embed/book/demo-business/compact" title="Онлайн-запис — Beauty Studio" loading="lazy" style="width:100%;min-height:360px;border:0;border-radius:20px;"></iframe>
<script async src="https://vzl.one/static/booking-widget-loader.js"></script>

API-токени

Створюйте окремий токен для кожного сайту або серверної інтеграції.
Активних API-токенів ще немає.
API v1

Безпечна інтеграція запису

API навмисно має вузький доступ і прив'язане до вибраного бізнесу.

  • Можна отримати послуги, команду й вільний час та створити запис.
  • Немає доступу до списку клієнтів, CRM або історії записів.
  • Викликайте API лише зі свого сервера — не вставляйте токен у JavaScript сайту.
PUBLIC API · V1

Документація Booking API

Повний довідник для серверної інтеграції онлайн-запису: від отримання послуг і вільного часу до безпечного створення запису та обробки помилок.

REST JSON Bearer token HTTPS
Базова адреса https://vzl.one/api/v1/booking
Формат обміну JSON у запитах і відповідях
Ліміт запитів 120 GET / 30 POST за 60 с
01
Рекомендований порядок інтеграції

Перед створенням запису завжди отримуйте актуальні ідентифікатори та доступний час із API.

  1. 1
    Отримайте послугиПокажіть клієнту активні послуги та збережіть service_id.
  2. 2
    Оберіть спеціалістаВідфільтруйте команду за service_id та збережіть employee_id.
  3. 3
    Перевірте часОтримайте свіжий список слотів безпосередньо перед підтвердженням.
  4. 4
    Створіть записПередайте точне значення starts_at із відповіді availability.
02
Авторизація для кожного запиту

Додайте Bearer-токен до заголовка Authorization. Кожен токен прив’язаний до одного бізнесу.

Лише server-to-server
HTTP-заголовки 
Authorization: Bearer $VUZOL_API_TOKEN
Accept: application/json

Для кожного токена діє ліміт: до 120 запитів читання та до 30 запитів запису за 60 секунд. Відповідь 429 містить заголовок Retry-After з кількістю секунд до повторної спроби.

03
Помилки та безпечне відновлення

API повертає стандартний HTTP-статус і поле detail з поясненням. Не створюйте запис повторно без перевірки причини помилки.

401
Токен відсутній або недійсний

Немає Bearer-токена, токен відкликано або передано з помилкою. Створіть новий токен чи перевірте заголовок Authorization.

403
Бізнес недоступний

Бізнес видалено, вимкнено або він більше не належить власнику токена.

404
Ресурс не знайдено

Послуга, співробітник або бізнес із переданим ідентифікатором не існує чи недоступний для онлайн-запису.

409
Конфлікт під час створення запису

Слот уже зайнятий, закритий, минув або став недоступним через зміну графіка, перерву, вихідний, закриту дату чи тимчасове закриття бізнесу.

422
Некоректні дані

Відсутнє обов’язкове поле, значення порожнє, телефон некоректний або query-параметр не відповідає формату чи дозволеному діапазону.

429
Забагато запитів

Ліміт для токена вичерпано. Зачекайте час із заголовка Retry-After, а потім повторіть запит.

Що робити, якщо слот уже закритий або зайнятий

Availability показує стан на момент перевірки. Інший клієнт або адміністратор може зайняти чи закрити цей час до POST-запиту, тому фінальним підтвердженням завжди є відповідь 201 від appointments.

  1. Повторно викличте availability з тим самим service_id та employee_id.
  2. Покажіть клієнту оновлений список і попросіть обрати інший starts_at.
  3. Повторіть POST лише з новим значенням starts_at; не надсилайте старий слот у циклі.
HTTP/1.1 409 Conflict
Content-Type: application/json

{"detail":"Цей слот вже недоступний. Оберіть інший час."}
Формат помилки У більшості відповідей detail — це текст. Для помилок перевірки FastAPI поле detail може містити масив із назвою поля та причиною.
04
Endpoints і приклади

Усі секції відкриті: параметри, готові curl-запити, приклади відповідей і помилки можна переглянути без додаткових кліків.

Усі секції відкриті
GET/api/v1/booking/businessПублічні дані цього бізнесу

Повертає дані бізнесу, до якого прив’язаний токен, включно з публічною адресою сторінки запису.

ПараметриДодаткові параметри не потрібні.
Приклад запиту
curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  https://vzl.one/api/v1/booking/business
200 · Відповідь
{
  "data": {
    "id": "business_01",
    "name": "Vuzol Studio",
    "slug": "vuzol-studio",
    "phone": "+380501112233",
    "address": "Kyiv",
    "logo_url": "https://cdn.example.com/logo.png",
    "booking_url": "https://vzl.one/book/vuzol-studio"
  }
}
Можливі помилки401 Токен відсутній, недійсний або відкликаний.403 Бізнес для цього токена недоступний.429 Ліміт запитів вичерпано; врахуйте Retry-After.
GET/api/v1/booking/servicesПослуги, доступні для онлайн-запису

Повертає лише активні послуги, які можна записати онлайн. Використовуйте id послуги в наступних запитах.

ПараметриДодаткові параметри не потрібні.
Приклад запиту
curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  https://vzl.one/api/v1/booking/services
200 · Відповідь
{
  "data": [
    {
      "id": "service_01",
      "name": "Consultation",
      "category": "Services",
      "description": "60-minute consultation",
      "duration_minutes": 60,
      "price": 900.0
    }
  ]
}
Можливі помилки401 Токен відсутній, недійсний або відкликаний.403 Бізнес для цього токена недоступний.429 Ліміт запитів вичерпано; врахуйте Retry-After.
GET/api/v1/booking/teamСпівробітники для вибраної послуги

Повертає активних співробітників бізнесу. Якщо передати service_id, список буде обмежений спеціалістами, призначеними на цю послугу.

ПолеОбов’язковістьОпис
service_idstring · queryНеобов’язковоID послуги з /services. Якщо не передавати, API поверне всю доступну команду.
Приклад запиту
curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  "https://vzl.one/api/v1/booking/team?service_id=SERVICE_ID"
200 · Відповідь
{
  "data": [
    {
      "id": "employee_01",
      "full_name": "Iryna Kovalenko",
      "role": "Specialist",
      "photo_url": "https://cdn.example.com/iryna.jpg"
    }
  ]
}
Можливі помилки404 Переданий service_id не знайдено.422 Query-параметр має неправильний формат або довжину.429 Ліміт запитів вичерпано; врахуйте Retry-After.
GET/api/v1/booking/availabilityДоступні дати й часові слоти

Розраховує доступний час з урахуванням тривалості послуги, графіка, перерв, відпусток, закритих дат, уже створених записів і статусу бізнесу.

ПолеОбов’язковістьОпис
service_idstring · queryОбов’язковоID активної онлайн-послуги з /services.
employee_idstring · queryНеобов’язковоID конкретного спеціаліста з /team. Без нього повертаються слоти всіх доступних співробітників.
start_datedate · YYYY-MM-DDНеобов’язковоПерший день пошуку. За замовчуванням — поточна дата сервера.
daysinteger · 1–31Необов’язковоКількість календарних днів для пошуку. За замовчуванням 7, дозволено від 1 до 31.

Для POST /appointments передавайте starts_at без змін саме з цього списку. Самостійно сформований час може не збігатися з кроком календаря або графіком.

Приклад запиту
curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  "https://vzl.one/api/v1/booking/availability?service_id=SERVICE_ID&employee_id=EMPLOYEE_ID&start_date=2026-09-10&days=7"
200 · Відповідь
{
  "data": [
    {
      "employee_id": "employee_01",
      "employee_name": "Iryna Kovalenko",
      "starts_at": "2026-09-10T14:00",
      "date": "2026-09-10",
      "time": "14:00"
    }
  ],
  "meta": {
    "service_id": "service_01",
    "employee_id": "employee_01",
    "start_date": "2026-09-10",
    "days": 7
  }
}
Можливі помилки404 Послугу або співробітника не знайдено.422 Query-параметр має неправильний формат або довжину.429 Ліміт запитів вичерпано; врахуйте Retry-After.
POST/api/v1/booking/appointmentsСтворити новий онлайн-запис

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

ПолеОбов’язковістьОпис
service_idstring · max 100Обов’язковоID послуги, для якої було отримано слот.
employee_idstring · max 100Обов’язковоID співробітника з вибраного слота.
starts_atstring · ISO 8601Обов’язковоТочне ISO-значення starts_at із відповіді /availability. Не переформатовуйте і не округлюйте його.
client_namestring · max 120Обов’язковоІм’я клієнта, яке буде показано в календарі та CRM.
client_phonestring · max 40Обов’язковоДійсний контактний номер клієнта. Використовується для пошуку або створення картки клієнта.
notesstring · max 2000Необов’язковоНеобов’язковий коментар до запису. Якщо приміток немає, передайте порожній рядок або не додавайте поле.
Приклад запиту
curl -X POST https://vzl.one/api/v1/booking/appointments \
  -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "SERVICE_ID",
    "employee_id": "EMPLOYEE_ID",
    "starts_at": "2026-09-10T14:00",
    "client_name": "Iryna Kovalenko",
    "client_phone": "+380501112233",
    "notes": "First visit"
  }'
201 · Відповідь
{
  "data": {
    "booking_id": "appointment_01",
    "status": "booked",
    "service_id": "service_01",
    "employee_id": "employee_01",
    "starts_at": "2026-09-10T14:00",
    "ends_at": "2026-09-10T15:00",
    "receipt_url": "https://vzl.one/book/vuzol-studio/appointments/PUBLIC_TOKEN"
  }
}
Можливі помилки409 Слот уже зайнятий або більше недоступний; послуга чи співробітник також могли бути деактивовані.422 Обов’язкові дані порожні, телефон некоректний або поле не відповідає схемі.429 Ліміт запитів вичерпано; врахуйте Retry-After.