Аутентифікація

Усі запити до Zapys24 API повинні містити ваш API-ключ. Без ключа або з невалідним ключем ви отримаєте 401 Unauthorized.

Як передати API-ключ

Є два способи. Рекомендуємо перший:

Спосіб 1: Заголовок X-API-Key (рекомендований)

curl -H "X-API-Key: crm_live_a1b2c3d4e5f6..." \
  https://api.zapys24.com/api/v1/integration/services

Спосіб 2: Bearer token

curl -H "Authorization: Bearer crm_live_a1b2c3d4e5f6..." \
  https://api.zapys24.com/api/v1/integration/services

Base URL

Усі ендпоінти починаються з:

https://api.zapys24.com/v1/integration

---

Дозволи (Scopes)

При створенні API-ключа ви обираєте, до яких ресурсів він матиме доступ. Давайте ключу мінімально необхідні дозволи.

Scope	Що дозволяє	Потрібен для
business:read	Інформація про ваш бізнес	Показати назву, адресу, графік роботи на сайті
services:read	Список ваших послуг	Каталог послуг у віджеті
staff:read	Список майстрів	Вибір майстра при бронюванні
slots:read	Вільні слоти	Показати доступний час для запису
bookings:read	Перегляд існуючих записів	Перевірити статус бронювання
bookings:write	Створення та скасування записів	Форма онлайн-запису
reviews:read	Відгуки клієнтів	Показати відгуки на сайті
webhooks:manage	Управління вебхуками	Налаштувати сповіщення про події

Типові набори дозволів

Віджет бронювання на сайті:

services:read, staff:read, slots:read, bookings:write

Відображення інформації (без бронювання):

business:read, services:read, staff:read, reviews:read

Повна інтеграція з CRM:

business:read, services:read, staff:read, slots:read, bookings:read, bookings:write, webhooks:manage

Принцип мінімальних привілеїв

Якщо вам потрібно лише показати послуги на сайті — не давайте ключу дозвіл bookings:write. Чим менше дозволів — тим безпечніше.

---

Ліміти запитів (Rate Limiting)

Кожен API-ключ має обмеження:

Ліміт	Значення
За хвилину	60 запитів
За добу	10 000 запитів

Заголовки у відповіді

Кожна відповідь API містить заголовки з інформацією про ліміти:

Заголовок	Що означає
X-RateLimit-Limit	Ваш ліміт за хвилину
X-RateLimit-Remaining	Скільки запитів залишилось
X-RateLimit-Reset	Unix timestamp, коли лічильник скинеться

Якщо ліміт перевищено

Ви отримаєте 429 Too Many Requests:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Limit: 60 requests/minute.",
  "retryAfter": 42
}

Поле retryAfter вказує, скільки секунд потрібно зачекати перед наступним запитом.

Порада

Кешуйте відповіді на стороні клієнта. Список послуг та майстрів рідко змінюється — немає сенсу запитувати його на кожне завантаження сторінки.

---

Безпека

Зберігайте ключ на сервері

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

// ❌ НЕБЕЗПЕЧНО — ключ видно всім
fetch("https://api.zapys24.com/v1/integration/services", {
  headers: { "X-API-Key": "crm_live_secret_key_here" },
});

// ✅ ПРАВИЛЬНО — запит через ваш сервер
fetch("/api/services"); // → ваш сервер робить запит до Zapys24

CORS Origins

При створенні ключа ви можете вказати дозволені домени (allowedOrigins). Запити з інших доменів будуть відхилені.

Компрометація ключа

Якщо ви підозрюєте, що ключ став відомий стороннім:

1. Зайдіть у Налаштування → API-інтеграція
2. Натисніть «Регенерувати» (буде створено новий ключ, старий одразу перестане працювати)
3. Оновіть ключ у вашому коді

Або натисніть «Відкликати», якщо ключ більше не потрібен.

---

Статуси ключа

Статус	Іконка	Що означає
active	🟢	Ключ працює
revoked	🔴	Ключ відкликано вручну — запити відхиляються
expired	⚪	Термін дії закінчився — запити відхиляються