API для внешних систем управления

1. Возможности API

С помощью API-ключа вы можете из своего программного обеспечения читать и записывать данные в календарь ваших объектов:

• получать информацию об объектах и площадках с их идентификаторами, необходимыми для всех остальных запросов;
• получать список бронирований за определенный период, по объекту или отдельной площадке для синхронизации с вашей базой данных;
• создавать бронирования из внешних систем (например, когда клиент бронирует на вашем сайте) с теми же проверками на наложение броней и закрытие площадок;
• изменять или отменять существующие бронирования (перенос времени или площадки, оплата, примечания, отмена);
• получать информацию о доступности площадки на определенный день: уже занятые слоты, часы работы и внеплановые закрытия, чтобы предлагать свободные слоты без необходимости дублировать правила на вашей стороне;
• получить прайс-лист площадки для отображения цен конечному клиенту.

В этот API не входят запросы организаторов на использование площадок в турнирах (они одобряются в приложении), создание объектов и площадок, сохранение расписания, закрытий и прайс-листа: это операции панели управляющего.

2. Требования и активация

1. Аккаунт управляющего площадками VolleyFriends как минимум с одним объектом и одной площадкой.
2. Действующая подписка с тарифом, включающим функцию «API для внешних систем управления». Вся v1 — даже операции только для чтения — зарезервирована для тех, у кого есть эта функция: это платная функция, а не бесплатное дополнение к панели.
3. API-ключ, сгенерированный в панели управления: admin.volleyfriends.com → Настройки → API-ключи → Новый ключ.

Ключ имеет формат vfk_, за которым следуют 40 шестнадцатеричных символов (всего 44 символа), и отображается только один раз, сразу после создания: в базе данных сохраняется только его хэш sha256, поэтому восстановить его невозможно. Если вы его потеряете, отзовите его и создайте новый. В списке на панели управления видны только префикс (например, vfk_9f2c), дата создания и дата последнего использования.

3. Аутентификация

Каждый запрос должен быть аутентифицирован с помощью заголовка X-Api-Key. Токены, логины, сроки действия или продления не требуются: ключ остается действительным, пока вы его не отзовете.

# Ключи на этой странице приведены для примера: замените их своим собственным.
curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: vfk_9f2c41a7b83d05e6c19af4728b60d35e1c9a7f42"

В следующих примерах ключ считывается из переменной окружения VF_API_KEY, как это рекомендуется делать и в рабочей среде.

Заголовок отсутствует, короче 12 символов, неизвестен или относится к отозванному ключу: возвращается ответ 401 со следующим телом.

{
  "error": "invalid_key",
  "message": "Chiave API mancante o non valida (header X-Api-Key)."
}

4. Базовый URL

https://www.volleyfriends.com/api

Пути, описанные ниже, должны добавляться к базовому URL. Префикс /api относится к обратному прокси-серверу, поэтому полный адрес конечной точки выглядит, например, так:

GET https://www.volleyfriends.com/api/manager-api/v1/availability

Все ответы возвращаются в формате application/json с кодировкой UTF-8. Запросы с телом (POST, PATCH) должны содержать заголовок Content-Type: application/json.

5. Ограничение частоты запросов

Лимит составляет 120 запросов в минуту на один API-ключ (скользящее окно в 1 минуту). Подсчет ведется по ключу, а не по IP-адресу: системы управления часто находятся за одним и тем же адресом провайдера, и лимит по IP нанесет ущерб разным операторам, размещенным на одной инфраструктуре. Если заголовок X-Api-Key полностью отсутствует, подсчет переносится на IP-адрес.

Каждый ответ содержит состояние счетчика в заголовках x-ratelimit-limit, x-ratelimit-remaining и x-ratelimit-reset (секунд до сброса). При превышении лимита также добавляется заголовок retry-after.

Ответ при превышении лимита — 429

{
  "error": "rate_limited",
  "message": "Limite di 120 richieste al minuto superato per questa chiave API."
}

6. Эндпоинты

Шесть эндпоинтов, все по пути /manager-api/v1. Каждый вызов проходит через одну и ту же цепочку проверок в следующем порядке: валидный API-ключ → функция «API для внешних систем управления» включена в тариф → rate limit → валидация параметров → проверка принадлежности ресурса вам.

6.1 Объекты и площадки

Возвращает список ваших объектов, каждый со своими вложенными площадками. Это базовый вызов: идентификаторы id площадок (courtId) требуются для всех остальных эндпоинтов. Объекты отсортированы по названию, площадки — по названию.

Параметры

Нет.

Пример запроса

curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: $VF_API_KEY"

Пример ответа — 200

{
  "venues": [
    {
      "id": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "name": "Centro Sportivo Aurora",
      "city": "Verona",
      "address": "Via delle Palestre 12",
      "verified": true,
      "courts": [
        {
          "id": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 1",
          "surface": "parquet",
          "indoor": true,
          "lighting": true
        },
        {
          "id": "e2a71f64-9c03-4bd8-b512-38f6cd90a7e1",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 2 beach",
          "surface": "sabbia",
          "indoor": false,
          "lighting": true
        }
      ]
    }
  ]
}

Поля ответа

Если у аккаунта еще нет площадок, ответ будет {"venues": []}.

Специфические ошибки

Отсутствуют, кроме общих.

6.2 Список бронирований

Возвращает бронирования ваших площадок, отсортированные по возрастанию времени начала. Список является постраничным: максимум limit строк на запрос (по умолчанию 500, лимит 1000) — если вы получаете ровно limit строк, сделайте повторный запрос с увеличенным значением offset для перехода на следующую страницу. В рабочей среде всегда фильтруйте данные как минимум по диапазону дат.

Параметры (строка запроса)

Пример запроса

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "from=2026-08-01"   --data-urlencode "to=2026-08-31"

Пример ответа — 200

{
  "bookings": [
    {
      "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
      "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
      "courtName": "Campo 1",
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "customerName": "Marta Bellini",
      "customerPhone": "+39 340 1122334",
      "customerEmail": "marta.bellini@example.com",
      "priceCents": 3000,
      "playersCount": null,
      "status": "confirmed",
      "paymentMethod": null,
      "paymentLink": null,
      "notes": "Prenotato dal sito della struttura",
      "source": "api",
      "recurrenceId": null,
      "createdAt": "2026-07-28T09:14:02.517Z",
      "updatedAt": "2026-07-28T09:14:02.517Z"
    }
  ],
  "limit": 500,
  "offset": 0
}

Поля бронирования

Эта же структура возвращается методами POST и PATCH (внутри ключа booking).

Специфические ошибки

6.3 Новое бронирование

Создает бронирование на вашей площадке. Бронирование создается с source: "api", чтобы в панели управления его можно было отличить от введенных вручную, а управляющий получает push-уведомление «Новое бронирование» в приложении.

Применяются те же правила, что и в панели управления, по порядку:

1. внеплановое закрытие спортивного объекта на дату начала → 409 venue_closed;
2. наложение на другое неотмененное бронирование той же площадки → 409 overlap;
3. цена отсутствует → рассчитывается по тарифной сетке площадки (null, если время начала не попадает ни в один интервал). Если для интервала установлена цена за человека, также требуется playersCount: без него запрос отклоняется с ошибкой 400 players_required (если только не указана явная цена priceCents).

Часы работы не блокируют создание: они носят информационный характер, управляющий остается полновластным хозяином своей площадки. Если вы хотите предотвратить бронирование во внерабочее время, самостоятельно проверьте hours, возвращаемые /availability, перед вызовом POST.

Тело запроса (JSON)

Пример запроса

curl -s -X POST https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "startsAt": "2026-08-12T18:00:00+02:00",
    "endsAt": "2026-08-12T19:30:00+02:00",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "notes": "Prenotato dal sito della struttura"
  }'

Пример ответа — 201

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T16:00:00.000Z",
    "endsAt": "2026-08-12T17:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "confirmed",
    "paymentMethod": null,
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T09:14:02.517Z"
  }
}

В примере параметр priceCents не был указан: 90 минут в интервале с тарифом 20,00 €/час дают 3000 центов (расчет пропорционален фактическим минутам по тарифу того интервала, в котором начинается бронирование).

Специфические ошибки

// 409 — пересечение
{ "error": "overlap", "message": "Il campo è già prenotato in quell'orario." }

// 409 — внеплановое закрытие (причина, если она указана администратором, содержится в сообщении)
{ "error": "venue_closed", "message": "Struttura chiusa in quella data (manutenzione)." }

6.4 Изменение бронирования

Обновляет существующее бронирование. Это частичное обновление: отправляйте только изменяемые поля, остальные останутся без изменений. Тело запроса должно содержать как минимум одно поле.

Эндпоинт для удаления отсутствует: чтобы отменить бронирование, установите значение status: "cancelled". История сохраняется в панели управления, а слот снова становится свободным (отмененные бронирования не занимают площадку и не вызывают ошибку overlap).

Параметр пути

Тело запроса (JSON)

Все поля являются необязательными. Поля с пометкой «с возможностью сброса» принимают значение null для очистки значения.

Пример запроса — перенос и выручка

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "startsAt": "2026-08-12T19:00:00+02:00",
    "endsAt": "2026-08-12T20:30:00+02:00",
    "status": "paid",
    "paymentMethod": "cash",
    "priceCents": 3000
  }'

Пример запроса — отмена

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{ "status": "cancelled" }'

Пример ответа — 200

Обновленное бронирование в том же формате, что и POST:

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T17:00:00.000Z",
    "endsAt": "2026-08-12T18:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "paid",
    "paymentMethod": "cash",
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T11:02:47.883Z"
  }
}

Специфические ошибки

6.5 Доступность корта на день

Возвращает для корта и дня занятые слоты, время работы в этот день недели и возможное внеплановое закрытие. Этот эндпоинт следует использовать для расчета свободных слотов на внешнем сайте без дублирования правил системы управления: вычтите бронирования из окна работы.

Перечислены все слоты, занимающие корт, в любом статусе, кроме cancelled: то есть включая запросы на онлайн-бронирование, которые все еще находятся в статусе pending. День определяется по местному итальянскому времени, а интервалы являются полуоткрытыми: бронирование, заканчивающееся ровно в полночь, относится к предыдущему дню. Бронирование, переходящее через полночь, отображается в обоих пересекаемых днях с его реальным временем (которое может выходить за пределы запрашиваемого дня).

Параметры (строка запроса)

Пример запроса

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/availability   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "date=2026-08-12"

Пример ответа — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
  "date": "2026-08-12",
  "timezone": "Europe/Rome",
  "hours": {
    "weekday": 2,
    "openMinute": 540,
    "closeMinute": 1380,
    "closed": false,
    "configured": true
  },
  "closure": null,
  "bookings": [
    {
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "status": "confirmed"
    },
    {
      "startsAt": "2026-08-12T18:00:00.000Z",
      "endsAt": "2026-08-12T19:00:00.000Z",
      "status": "paid"
    },
    {
      "startsAt": "2026-08-12T19:00:00.000Z",
      "endsAt": "2026-08-12T20:30:00.000Z",
      "status": "pending"
    }
  ]
}

Поля ответа

Специфические ошибки

6.6 Тарифная сетка площадки

Тарифная сетка площадки в режиме только для чтения: используется для отображения цен клиенту перед бронированием, с теми же интервалами, которые система управления использует для автоматического расчета цены. Интервалы можно изменить только в панели управления. Они отсортированы по возрастанию fromMinute.

Параметры (строка запроса)

Пример запроса

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/rates   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"

Пример ответа — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "rates": [
    {
      "id": "4a1e0b72-6d35-4c81-93af-0b7e2d5814c6",
      "label": "Mattina infrasettimanale",
      "daysMask": 31,
      "fromMinute": 480,
      "toMinute": 840,
      "pricePerHourCents": 1500,
      "pricingMode": "court",
      "minPlayers": null
    },
    {
      "id": "c07d9b31-8f42-4a05-b6e9-15d3c8017a2b",
      "label": "Serale",
      "daysMask": 127,
      "fromMinute": 1080,
      "toMinute": 1380,
      "pricePerHourCents": 600,
      "pricingMode": "person",
      "minPlayers": 10
    }
  ]
}

Поля ответа

Специфические ошибки

Площадка без прайс-листа возвращает 200 с "rates": [].

7. Соглашения о данных

7.1 Даты и время

• На входе значения времени представляют собой строки ISO 8601 с обязательным смещением: 2026-08-12T18:00:00+02:00 или 2026-08-12T18:00:00Z. Строка без смещения (2026-08-12T18:00:00) отклоняется с ошибкой 400: она была бы неоднозначной, а для календаря такая неоднозначность приводит к ошибкам в бронировании на один час.
• На выходе значения времени всегда нормализованы в UTC с суффиксом Z и миллисекундами: "2026-08-12T16:00:00.000Z". Преобразуйте их в местный часовой пояс перед отображением.
• Простые даты (date, closure.from, closure.to и from/to при использовании в формате дня) имеют формат AAAA-MM-GG и относятся к местному итальянскому времени.
• Интервалы являются полуоткрытыми [inizio, fine): 18:00–19:00 и 19:00–20:00 не конфликтуют друг с другом.

7.2 Часовой пояс

Бронирования хранятся как абсолютные моменты времени, но все правила календаря — день недели, интервалы прайс-листа, часы работы, даты закрытия, границы дня — оцениваются в часовом поясе Europe/Rome с автоматическим переходом на летнее время. Поле timezone в ответе /availability явно указывает на это. Если ваш сервер работает в UTC или другом часовом поясе, не конвертируйте минуты вручную: они уже выражены по местному итальянскому времени.

7.3 Минуты от полуночи

Время «по календарю» (openMinute, closeMinute, fromMinute, toMinute) представляет собой целые числа от 0 до 1440, обозначающие количество минут от местной полуночи. Преобразование: ore = ⌊m / 60⌋, minuti = m mod 60.

7.4 Суммы

Все суммы представляют собой целые числа в евроцентах (priceCents, pricePerHourCents): никаких значений с плавающей запятой, никаких символов валюты. 2000 = 20,00 €. В бронировании priceCents: null означает «цена не определена» и отличается от 0, что означает «бесплатно».

7.5 Статусы бронирования

7.6 Источник и способ оплаты

Оба поля являются текстовыми доменами: в будущем могут быть добавлены новые значения без изменения версии, поэтому ваш код не должен выдавать ошибку при встрече с незнакомым значением.

7.7 Персональные данные клиентов

Имя, телефон и email, которые вы передаете при бронировании, являются персональными данными ваших клиентов: вы являетесь оператором персональных данных, а VolleyFriends хранит их от вашего имени в качестве обработчика в соответствии со ст. 28 GDPR. Передавайте только те данные, которые необходимы для управления кортами, и информируйте своих клиентов. Подробная информация содержится в privacy policy.

8. Общие ошибки

Каждая ошибка имеет одинаковую структуру: стабильный код в error, предназначенный для вашего кода, и message на итальянском языке, предназначенный для людей. Принимайте решения на основе error и статуса HTTP, а не текста сообщения, который может измениться.

{
  "error": "overlap",
  "message": "Il campo è già prenotato in quell'orario."
}

Ошибки валидации добавляют issues, подробный список проблем по каждому полю:

{
  "error": "invalid_input",
  "message": "Dati non validi",
  "issues": [
    {
      "code": "invalid_string",
      "validation": "datetime",
      "path": ["startsAt"],
      "message": "Invalid datetime"
    }
  ]
}

Несуществующий путь под базовым URL возвращает 404; то же самое относится к непредусмотренному методу для существующего пути:

{
  "error": "not_found",
  "message": "Risorsa non trovata"
}

Ответы 502, 503 и 504 поступают от обратного прокси-сервера, когда API недоступен (перезапуск или обслуживание): в этих случаях тело ответа не обязательно будет в формате JSON. Рассматривайте их как временные ошибки и повторите попытку с экспоненциальной задержкой (backoff), не пытаясь прочитать содержимое.

9. Версии и совместимость

Версия указана в пути: /manager-api/v1. Нет необходимости указывать заголовки версии или даты релизов: единственная опубликованная на данный момент версия — v1.

Что мы можем изменить без предварительного уведомления

• Добавлять поля в существующие ответы.
• Добавлять необязательные параметры в запросы со значением по умолчанию, сохраняющим текущее поведение.
• Добавлять новые эндпоинты в /v1.
• Добавлять значения в открытые текстовые поля (source, paymentMethod, surface).
• Изменять формулировку message в ошибках, сохраняя коды error без изменений.

Что не меняется в рамках v1

• Ни одно поле не будет удалено или переименовано в ответах.
• Ни одно поле не изменит свой тип или значение.
• Ни один параметр, являющийся сейчас необязательным, не станет обязательным.
• Коды error и HTTP-статусы, документированные здесь, остаются прежними.

Любое изменение, нарушающее эти гарантии, будет выпущено под новым префиксом (/v2), при этом поддержка v1 продолжится, а администраторы, использующие её, будут предупреждены заранее.

Список изменений

10. Поддержка интеграции

По техническим вопросам, при неожиданном поведении или запросах эндпоинтов, которых здесь нет, пишите нам со страницы Контакты. Чтобы сразу перейти к делу, укажите в сообщении:

• endpoint и метод, который вы вызываете;
• дата и время вызова (с часовым поясом) и полученный HTTP-код;
• код error и сообщение ответа;
• префикс используемого ключа (например, vfk_9f2c).

Если вам нужно протестировать интеграцию, не затрагивая реальный календарь, создайте тестовую площадку с выделенным полем и используйте её: все вызовы ограничены площадками владельца ключа, поэтому остальная часть вашего аккаунта не будет затронута.