API-ключи и области доступа

REST API Ringhum позволяет вашим собственным системам работать с вашим рабочим пространством: получать списки звонков и транскриптов, создавать ассистентов, бронировать встречи, управлять контактами, совершать исходящие звонки и многое другое. Каждый запрос аутентифицируется API-ключом, принадлежащим одному рабочему пространству. В этой статье описано создание ключей и правила, общие для всех эндпоинтов. Полный справочник по эндпоинтам находится на /docs.

Кто может управлять ключами

API доступен на любом плане. При этом возможности ключа по-прежнему ограничены вашим планом: например, создание ассистента сверх лимита плана вернёт ошибку.

Создание API-ключа

1. Откройте Разработчикам в боковом меню.
2. В карточке API-ключи нажмите Создать ключ.
3. Введите Название ключа, указывающее, где используется ключ, например «Продакшн-сервер».
4. В разделе Области доступа отметьте read, write или оба варианта.
5. Нажмите Создать ключ.
6. Скопируйте ключ из зелёного блока и сохраните его в надёжном месте, например в хранилище секретов вашего сервера. Нажмите Готово.

Важно: Ключ показывается только один раз. Ringhum хранит только его отпечаток, поэтому повторно показать ключ невозможно. Если вы его потеряли, создайте новый ключ и отзовите старый.

Ключи начинаются с ck_live_. Таблица API-ключи показывает для каждого ключа название, первые символы ключа, его области доступа, время последнего использования и статус — Активен или Отозван.

Области доступа

Любой ключ может обращаться к эндпоинтам, которые только читают данные. Эндпоинты, которые что-то создают, изменяют или удаляют, требуют области доступа write. Примеры — совершение звонка, отправка сообщения, бронирование встречи или обновление ассистента. Такие эндпоинты отмечены в справочнике на /docs. Ключ без write получит на них ошибку 403.

Предоставляйте каждой системе минимально необходимый доступ. Для дашборда отчётности достаточно read.

Отзыв ключа

1. На странице Разработчикам найдите ключ в таблице API-ключи.
2. Нажмите Отозвать и подтвердите действие.

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

Отправка запросов

• Базовый URL: https://ringhum.com/api/v1
• Аутентификация: отправляйте ключ как Bearer-токен: Authorization: Bearer ck_live_…
• Формат: JSON на входе и на выходе. Отправляйте Content-Type: application/json вместе с телом запроса.
• Время указывается в формате ISO 8601 в UTC. Номера телефонов — в формате E.164, например +14155550132. Идентификаторы — целые числа.
• Обновления выполняются методом PATCH с указанием только тех полей, которые нужно изменить.
• Каждый ответ содержит заголовок X-Request-Id. Указывайте его при обращении в поддержку.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Чтобы узнать, какому рабочему пространству принадлежит ключ, вызовите GET /me.

Ответы и пагинация

Отдельный объект возвращается в виде {"data": {…}}. Списки с пагинацией возвращаются вместе с объектом meta:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Используйте page и per_page, чтобы перемещаться по результатам. per_page по умолчанию равен 25 и не может превышать 100.

Ошибки

Каждая ошибка имеет одинаковую структуру со стабильным полем type, которое можно проверять в коде:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

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

Вы можете совершать 120 запросов в минуту. Ответы содержат заголовки X-RateLimit-Limit и X-RateLimit-Remaining. При превышении лимита вы получите ошибку 429 с заголовком Retry-After, указывающим, сколько секунд нужно подождать.

Совет: Не опрашивайте API в ожидании результатов звонка. Добавьте вебхук для call.ended, и Ringhum отправит вам сводку и транскрипт, как только звонок завершится. См. Вебхуки.

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

Есть ли машиночитаемая спецификация? Да. Описание в формате OpenAPI 3.1 доступно по адресу /api/v1/openapi.json и не требует ключа. На его основе можно сгенерировать клиент.

Перестанет ли ключ работать, если человек, который его создал, уйдёт из компании? Нет. Ключи принадлежат рабочему пространству и продолжают работать, пока их не отзовут. Отзывайте ключи, которым больше не доверяете, особенно когда доступ теряет сотрудник, у которого он был.

Можно ли использовать API прямо с веб-страницы? Нет. Любой, кто откроет страницу, сможет прочитать ключ. Обращайтесь к API со своего сервера.