Частые вопросы

Ответы на популярные вопросы об использовании наших API-сервисов. Если вы не нашли ответ, свяжитесь с нами.

Общие вопросы

Как получить доступ к API?

Для получения доступа свяжитесь с нами через контактную форму на главной странице или напишите на email. Мы предоставим вам уникальный API-ключ и доступ к документации.

Есть ли тестовая среда (sandbox)?

Да, мы предоставляем тестовые API-ключи с префиксом vl_test_для разработки и тестирования. Тестовые ключи:

• Не создают реальных записей
• Имитируют успешные и ошибочные ответы
• Не тарифицируются
• Имеют упрощённые данные для тестирования

Какие форматы данных поддерживаются?

Все запросы и ответы используют формат JSON. Для загрузки файлов (DXF, медиа) используется multipart/form-data. Даты передаются в формате ISO 8601 (UTC).

Поддерживаются ли webhooks?

Да, для некоторых событий (создание записи, изменение статуса заказа, завершение транскрипции) можно настроить webhook-уведомления. Укажите URL вашего эндпоинта при получении API-ключа.

Есть ли официальные SDK или библиотеки?

В настоящее время мы предоставляем REST API, которое можно использовать с любым HTTP-клиентом. Официальные SDK в разработке:

• JavaScript/TypeScript SDK (планируется Q1 2025)
• Python SDK (планируется Q1 2025)

Пока используйте стандартные HTTP-клиенты: fetch, axios, requests и т.д. См. примеры кода.

Биллинг и лимиты

Какие тарифные планы доступны?

Мы предлагаем гибкие тарифные планы в зависимости от сервиса:

Календарь для психологов

• Starter: до 50 записей/мес
• Professional: до 200 записей/мес
• Enterprise: без ограничений

Лазерная резка DXF

• Pay-as-you-go: за каждый расчёт
• Business: пакет расчётов
• Индивидуальные условия

Как работает rate limiting?

Мы используем скользящее окно для ограничения запросов:

• Тестовые ключи: 60 запросов в минуту
• Production ключи: 600 запросов в минуту
• Burst лимит: до 100 запросов в секунду

При превышении лимита вы получите ответ 429 Too Many Requestsс заголовком Retry-After, указывающим время ожидания.

Что происходит при превышении квоты?

Зависит от вашего тарифного плана:

• Starter/Professional: API возвращает ошибку 403 (Forbidden)
• Enterprise: Soft limit с уведомлением, возможна автоматическая тарификация овердрафта

Мы отправляем email-уведомления при достижении 80% и 100% квоты.

Как отслеживать использование API?

В личном кабинете (в разработке) вы сможете видеть:

• Количество запросов за период
• Использованную квоту
• Распределение по эндпоинтам
• Статистику ошибок
• Стоимость использования

Аутентификация и безопасность

Как защитить API-ключ?

Следуйте этим рекомендациям:

• Храните ключ в переменных окружения (.env файл)
• Никогда не коммитьте ключи в Git
• Не встраивайте ключи в клиентский JavaScript
• Используйте серверный прокси для API-запросов
• Регулярно ротируйте ключи (раз в 3-6 месяцев)

Что делать, если ключ скомпрометирован?

Немедленно свяжитесь с нами для:

• Отзыва скомпрометированного ключа
• Генерации нового ключа
• Проверки логов на подозрительную активность

В будущем в личном кабинете будет возможность самостоятельной ротации ключей.

Поддерживается ли IP whitelisting?

Да, для Enterprise планов можно настроить список разрешённых IP-адресов. Запросы с других IP будут отклонены. Свяжитесь с нами для настройки.

Поддерживается ли OAuth 2.0?

В настоящее время мы используем API-ключи для аутентификации. OAuth 2.0 планируется добавить в 2025 году для сценариев, где требуется делегирование доступа от имени пользователей.

Типичные ошибки и решения

401

Unauthorized - API ключ недействителен

Причины:

• Ключ не передан в запросе
• Неправильный формат заголовка
• Ключ истёк или был отозван
• Опечатка в значении ключа

Решение:

• Проверьте, что заголовок x-api-key присутствует
• Убедитесь, что значение ключа корректно
• Проверьте срок действия ключа в личном кабинете

429

Too Many Requests - Превышен rate limit

Причины:

• Слишком много запросов за короткий период
• Нет механизма задержки между запросами

Решение:

// Пример retry логики с экспоненциальной задержкой
async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        
        await new Promise(resolve => 
          setTimeout(resolve, Math.max(delay, retryAfter * 1000))
        );
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

500

Internal Server Error

Причины:

• Временная проблема на сервере
• Неожиданная ошибка обработки запроса

Решение:

• Попробуйте повторить запрос через несколько секунд
• Если ошибка повторяется, свяжитесь с поддержкой
• Укажите ID запроса из заголовка X-Request-ID

409

Conflict - Слот уже занят

Причины:

• Другой пользователь успел создать запись на это время
• Race condition при одновременных запросах

Решение:

• Запросите обновлённый список свободных слотов
• Предложите пользователю выбрать другое время
• Реализуйте оптимистичную блокировку

Технические вопросы

Какие версии TLS поддерживаются?

Мы поддерживаем TLS 1.2 и TLS 1.3. Соединения через TLS 1.0 и 1.1 отклоняются из соображений безопасности.

Есть ли SLA (Service Level Agreement)?

Да, для тарифов Professional и Enterprise:

• Professional: 99.5% uptime
• Enterprise: 99.9% uptime + приоритетная поддержка

Статус сервисов можно отслеживать на странице status (в разработке).

Где хранятся данные?

Все данные хранятся в облачных дата-центрах в Европе (Германия, Нидерланды) с соблюдением GDPR. Данные резервируются ежедневно. Медиафайлы хранятся в Yandex Object Storage с шифрованием at rest.

Как связаться с поддержкой?

Доступные каналы поддержки:

• Email: api-support@vialine.ru (ответ в течение 24 часов)
• Telegram: @vialine_support (для Enterprise клиентов)
• Контактная форма на сайте