📡 REST API

REST API предназначен для интеграции ваших систем с платформой Fixorix по HTTPS.

Base URL: https://api.fixorix.ru
Публичные методы: доступны только по путям вида /v1/**, /v2/** и т.д. (то есть /v*/**).
Все актуальные эндпоинты, схемы запросов/ответов и параметры перечислены в Swagger:

👉 Swagger / OpenAPI: https://api.fixorix.ru/swagger

---

🔎 Где смотреть актуальную спецификацию

Swagger — это источник истины для:

• списка эндпоинтов и версий (/v1/..., /v2/...);
• схем JSON (DTO);
• параметров (включая пагинацию/сортировку/фильтры);
• кодов ошибок и примеров.

В этой странице — обзор принципов работы (ключи, scopes, лимиты, формат ошибок) + базовые примеры.

---

🔐 API-ключи: получение и использование

API-ключи создаются и управляются в интерфейсе Fixorix (в дашборде проекта).

Как получить API-ключ

1. Откройте Dashboard → ваш Project.
2. Перейдите в раздел API.
3. Нажмите Создать ключ.
4. Заполните параметры:
   • Название — понятное имя (например, CRM integration)
   • Описание — опционально
   • Права доступа (scopes) — например, bots:read
   • Срок действия — рекомендуется указывать
5. Сохраните ключ.

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

Как использовать ключ в запросах

Передавайте секрет в заголовке:

Authorization: Bearer <YOUR_API_KEY>

Пример запроса (получить список ботов вашего проекта):

curl -X GET \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json" \
  https://api.fixorix.ru/v1/bots

Важные правила и безопасность

• Ключ привязан к одному проекту — запросы выполняются в его контексте.

• Если секрет утерян, восстановить его нельзя: создайте новый ключ, обновите интеграцию и отзовите старый.

• Храните ключ как пароль: в secret-хранилище/переменных окружения (Vault, AWS Secrets Manager, GitHub Actions Secrets и т.п.).

• Не используйте ключ в клиентских приложениях (frontend/mobile).

• Рекомендуется:

  • отдельный ключ на интеграцию и окружение (prod/stage);
  • минимально необходимые scopes;
  • регулярная ротация ключей.

---

🧭 Права доступа

Каждый API-ключ содержит список scopes — строковых прав доступа (например: tickets:read, messages:write).

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

Если нужного разрешения нет — сервер вернёт: 403 Forbidden

к сведению

Полный перечень доступных scopes и их описание можно найти на странице:
👉 Scopes — REST API

---

⏱ Rate limiting

Лимиты применяются на проект и измеряются в запросах в минуту.

• По умолчанию: 1000 запросов/мин на проект
• Фактические лимиты зависят от тарифа и могут отличаться для разных клиентов.

При превышении лимита возвращается:

• 429 Too Many Requests

Заголовки (минимальный набор):

• Retry-After: <seconds> — через сколько секунд можно повторить
• X-RateLimit-Limit: <limit> — лимит запросов/мин

---

✅ Как делать запросы

Общие заголовки

• Authorization: Bearer <YOUR_API_KEY>
• Accept: application/json
• для методов с телом запроса: Content-Type: application/json

Пример: получить ботов (GET /v1/bots)

Требуемый scope: bots:read

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json" \
  https://api.fixorix.ru/v1/bots

---

📄 Пагинация, фильтры, сортировка

Параметры зависят от конкретного эндпоинта и описаны в Swagger.

Часто используются стандартные параметры (например, page, size, sort), но точный набор и формат смотрите в спецификации конкретного метода в Swagger: https://api.fixorix.ru/swagger.

---

❗ Формат ошибок

При ошибке сервер возвращает:

• корректный HTTP статус (4xx/5xx);
• Content-Type: application/json;
• тело следующего вида:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      {
        "field": "string",
        "issue": "string"
      }
    ]
  },
  "requestId": "string"
}

Поля

• error.code — машинно-обрабатываемый код (например, AUTH_INVALID_API_KEY)
• error.message — человекочитаемое описание
• error.details — список деталей (опционально), удобно для ошибок валидации
• requestId — идентификатор запроса для поддержки/трассировки (если доступен)

Типовые коды HTTP

• 400 Bad Request — неверные параметры/тело (валидация)
• 401 Unauthorized — отсутствует/неверный/отозван/истёк API-ключ
• 403 Forbidden — недостаточно прав (scopes)
• 404 Not Found — неизвестный путь/ресурс
• 429 Too Many Requests — превышен rate limit
• 5xx — ошибка сервера (можно повторить позже)

---

🧪 Troubleshooting (частые случаи)

401 Unauthorized

• проверьте заголовок Authorization: Bearer ...
• убедитесь, что ключ активен и не истёк (в дашборде проекта)

403 Forbidden

Ключу не хватает scopes для метода (сверьтесь со Swagger и настройками ключа)

429 Too Many Requests

• используйте Retry-After и реализуйте backoff
• при регулярном упоре в лимиты — уточните тариф/лимиты