Integ Docs | API

Appearance

API Guide ​

Руководство по работе с Integ API.

Обзор ​

Integ API предоставляет RESTful API для управления интеграциями, их secrets, handlers и access tokens.

Base URL ​

Local:       http://localhost:3000/api
Development: https://dev-api.yourdomain.com/api
Production:  https://api.yourdomain.com/api

Документация API ​

API документирован с использованием Scalar:

API Reference (Scalar) ​

  • Public API: http://localhost:3000/api/reference
  • Internal API (все эндпоинты): http://localhost:3000/api/reference-full
  • Docs (VitePress): https://api.integ.docs.happ.tools

Аутентификация ​

Большинство эндпоинтов требуют JWT токен в заголовке Authorization.

Формат заголовка ​

http
Authorization: Bearer <your-jwt-token>

Публичные эндпоинты ​

Не требуют токен:

  • POST /api/auth/sign-up
  • POST /api/auth/sign-in
  • GET /health

Response Format ​

Success Response ​

json
{
  "data": { ... },
  "success": true
}

Paginated Response ​

json
{
  "data": [...],
  "totalCount": 100,
  "page": {
    "number": 1,
    "size": 20
  }
}

Error Response ​

json
{
	"statusCode": 400,
	"message": "Error description",
	"error": "Bad Request"
}

HTTP Status Codes ​

CodeMeaning
200OK - Успешный запрос
201Created - Ресурс создан
400Bad Request - Невалидные данные
401Unauthorized - Требуется аутентификация
403Forbidden - Недостаточно прав
404Not Found - Ресурс не найден
500Internal Server Error - Ошибка сервера

Pagination ​

Используйте параметры take и skip для пагинации:

http
GET /api/integrations?take=20&skip=0
  • take - количество записей (по умолчанию 20)
  • skip - пропустить записей (по умолчанию 0)

Filtering ​

Фильтрация через query параметры:

http
GET /api/integrations?type=telegram&userId=123

Sorting ​

Сортировка через параметр order:

http
GET /api/integrations?order[createdAt]=DESC

Relations ​

Включение связанных данных через параметр relations:

http
GET /api/integrations?relations=user,handlers

Примеры запросов ​

cURL ​

bash
# Login
curl -X POST http://localhost:3000/api/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}'

# Get integrations
curl -X GET http://localhost:3000/api/integrations \
  -H "Authorization: Bearer <token>"

JavaScript (fetch) ​

javascript
// Login
const loginResponse = await fetch("http://localhost:3000/api/auth/sign-in", {
	method: "POST",
	headers: {
		"Content-Type": "application/json"
	},
	body: JSON.stringify({
		email: "admin@example.com",
		password: "password"
	})
});

const { accessToken } = await loginResponse.json();

// Get integrations
const integrationsResponse = await fetch("http://localhost:3000/api/integrations", {
	headers: {
		Authorization: `Bearer ${accessToken}`
	}
});

const integrations = await integrationsResponse.json();

TypeScript (axios) ​

typescript
import axios from "axios";

const api = axios.create({
	baseURL: "http://localhost:3000/api"
});

// Login
const { data } = await api.post("/auth/sign-in", {
	email: "admin@example.com",
	password: "password"
});

// Set token for future requests
api.defaults.headers.common["Authorization"] = `Bearer ${data.accessToken}`;

// Get integrations
const integrations = await api.get("/integrations");

Rate Limiting ​

В production применяются rate limits:

  • Аутентификация: 5 попыток в минуту
  • API запросы: 100 запросов в минуту

При превышении лимита возвращается 429 Too Many Requests.

CORS ​

CORS настроен для работы с фронтенд приложениями.

Development:

Access-Control-Allow-Origin: *

Production:

Access-Control-Allow-Origin: https://yourdomain.com

Разделы ​

Scalar UI ​

Для удобства рекомендуем использовать Scalar для тестирования API:

  1. Откройте http://localhost:3000/api/reference-full
  2. Авторизуйтесь (Basic Auth для доступа к внутренней документации)
  3. Тестируйте эндпоинты прямо в браузере

WebSocket (Будущее) ​

В будущих версиях планируется поддержка WebSocket для real-time уведомлений об изменениях интеграций.