Ласкаво просимо до REST API HelpCrunch 👋

REST API дозволяє вам отримувати доступ та керувати вашими даними у HelpCrunch. Методи запитів використовуються згідно з протоколом HTTP:

• GET використовується для читання одного або декількох сутностей;
• POST використовується для створення або оновлення сутностей;
• PUT використовується для оновлення сутностей;
• DELETE використовується для видалення сутностей;
• Формат JSON використовується для запитів, відповідей та повідомлень про помилки;
• Відповіді містять стандартні HTTP-коди.

Якщо ви бажаєте отримувати в реальному часі інформацію щодо оновлень ваших чатів або контактів, ознайомтеся з нашою документацією щодо Вебхуків.

Перш ніж ви почнете використовувати API, ознайомтесь з наступними п'ятьма пунктами👇.

1️⃣ Точка доступу API

REST API HelpCrunch - це лише HTTPS-API, яке працює за адресою:

https://api.helpcrunch.com/v1

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

Вам слід аутентифікувати всі ваші HTTP-запити до API HelpCrunch за допомогою вашого API-ключа.

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

Будь ласка, не використовуйте Старий ключ API, оскільки він сумісний лише зі старим REST API, підтримка якого скоро буде припинена.

Для аутентифікації ваших HTTP-запитів слід додати Authorization header до ваших запитів та вказати там ваш ключ API.

Authorization: Bearer <your_api_key_goes_here>

Вам не потрібно виконувати жодних додаткових маніпуляцій з вашим API ключем. Він постійний і не має терміну дії.

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

3️⃣ Обмеження за частотою запитів

Для захисту HelpCrunch від різкого збільшення API трафіку, що може негативно вплинути на працездатність нашої бази даних, ми використовуємо обмеження за частотою запитів. Коли ви перевищите обмеження, ви будете отримувати HTTP-помилку 429 Too Many Requests у відповідь на ваші запити.

За замовчуванням ліміт кількості запитів складає 120 на хвилину.

4️⃣ Помилки

Для вашої зручності, ми додали розділ 🛑 Відповіді з помилками до кожної статті, що описує конкретний метод API з точними кодами відповіді та прикладами.

Залежно від конкретного методу, ви можете отримати один із наступних кодів стану помилки та відповідей:

400 Bad Request

Запит не може бути розпізнаний сервером HelpCrunch через некоректний синтаксис або недійсне значення атрибуту. НЕ ПОВТОРЮЙТЕ такі запити без змін.

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "customer",
      "message": "This value should be of type numeric."
    },
    {
      "code": "filter[0].field",
      "message": "This value should not be blank."
    }
  ]
}

401 Unauthorized

Ця помилка означає, що щось не вірно з вашим API ключем або він взагалі не доданий до заголовків запиту. Переконайтеся, що ви передаєте його так, як описано у розділі про аутентифікацію вище.

{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  ]
}

404 Not Found

Ми не змогли знайти жодного відповідного результату за вашим запитом.

{
  "errors": [
    {
      "code": "not_found",
      "message": "Chat not found"
    }
  ]
}

429 Too Many Requests

Ви досягли обмеження 120-ти викликів API на хвилину.

{
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests"
    }
  ]
}

5️⃣ Групи точок API

Ось список усіх доступних груп точок API, які ви можете використовувати для доступу до вашої інформації у HelpCrunch та її управління.