Ключі 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, що вказує кількість секунд очікування.

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

Поширені запитання

Чи є машиночитана специфікація? Так. Опис OpenAPI 3.1 знаходиться на /api/v1/openapi.json і не потребує ключа. Ви можете згенерувати клієнт на його основі.

Чи перестає ключ працювати, якщо людина, яка його створила, покидає компанію? Ні. Ключі належать робочому простору й продовжують працювати, поки їх не відкличуть. Відкликайте ключі, яким більше не довіряєте, особливо коли хтось із доступом іде.

Чи можу я використовувати API з вебсторінки? Ні. Будь-хто, хто відкриє сторінку, зможе прочитати ключ. Викликайте API з вашого сервера.