Integ Docs

Замените {Название интеграции} на реальное название (например: "Telegram", "Slack", "WhatsApp")

Краткое описание интеграции в 1-2 предложения. Что это за сервис и для чего используется интеграция.

Быстрый старт

typescript

// Минимальный пример для начала работы
import { IntegClient } from "@integ/core";

const client = new IntegClient({
	accessToken: "your-access-token"
});

// Пример вызова основного метода
const result = await client.integrationName.send({
	to: "recipient",
	message: "Hello!"
});

Обзор

Возможности

Возможность 1 - краткое описание
Возможность 2 - краткое описание
Возможность 3 - краткое описание

Архитектура

mermaid

graph LR
    App[Ваше приложение] --> IntegAPI[Integ API]
    IntegAPI --> Gateway[Gateway API]
    Gateway --> Service[Внешний сервис]

Требования

Предварительные условия

[ ] Аккаунт в сервисе
[ ] API ключ / Bot Token (получить здесь: [ссылка])
[ ] Настроенный Integ API

Необходимые секреты

Секрет	Описание	Где получить
`api_key`	API ключ для авторизации	[ссылка]
`bot_token`	Токен бота (если есть)	[ссылка]
`webhook_url`	URL для вебхуков (optional)	Настроить

Установка

1. Создание интеграции

bash

curl -X POST http://localhost:3000/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "integration-name"}'

2. Добавление секретов

bash

# API Key
curl -X POST http://localhost:3000/api/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "integration-name",
    "key": "api_key",
    "value": "your-api-key"
  }'

# Bot Token (если нужен)
curl -X POST http://localhost:3000/api/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "integration-name",
    "key": "bot_token",
    "value": "your-bot-token"
  }'

3. Создание handlers

bash

curl -X POST http://localhost:3000/api/handlers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "your-integration-id",
    "name": "send-message",
    "defaultArgs": {
      "timeout": 5000,
      "retries": 3
    }
  }'

4. Проверка установки

bash

# Получить информацию об интеграции
curl http://localhost:3000/api/integrations/your-integration-id \
  -H "Authorization: Bearer $TOKEN"

Конфигурация

Переменные окружения

Переменная	Описание	По умолчанию
`INTEGRATION_NAME_TIMEOUT`	Таймаут запросов (ms)	`5000`
`INTEGRATION_NAME_RETRIES`	Количество повторов	`3`

Handler параметры

typescript

interface HandlerDefaultArgs {
	timeout?: number; // Таймаут в миллисекундах
	retries?: number; // Количество повторных попыток
	// Добавьте специфичные для интеграции параметры
}

API Reference

Методы

`sendMessage`

Отправка сообщения.

Параметры:

Параметр	Тип	Обязательный	Описание
`to`	string	Да	Получатель
`text`	string	Да	Текст сообщения
`options`	object	Нет	Дополнительные опции

Пример:

typescript

const result = await client.integrationName.sendMessage({
	to: "user-id",
	text: "Hello, World!",
	options: {
		parse_mode: "HTML"
	}
});

Ответ:

json

{
	"success": true,
	"messageId": "msg-123",
	"timestamp": "2024-01-01T00:00:00.000Z"
}

`getStatus`

Получение статуса сообщения.

Параметры:

Параметр	Тип	Обязательный	Описание
`messageId`	string	Да	ID сообщения

Пример:

typescript

const status = await client.integrationName.getStatus({
	messageId: "msg-123"
});

Вебхуки (если поддерживаются)

Настройка вебхука

bash

curl -X POST http://localhost:3000/api/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "integration-name",
    "url": "https://your-domain.com/webhook",
    "events": ["message.received", "message.delivered"]
  }'

Формат входящих событий

json

{
	"event": "message.received",
	"timestamp": "2024-01-01T00:00:00.000Z",
	"data": {
		"messageId": "msg-456",
		"from": "user-id",
		"text": "Hello!"
	}
}

Примеры использования

Отправка простого сообщения

typescript

import axios from "axios";

const api = axios.create({
	baseURL: "http://localhost:3000/api",
	headers: {
		Authorization: `Bearer ${process.env.TOKEN}`
	}
});

async function sendMessage(to: string, text: string) {
	const { data } = await api.post("/handlers/handler-id/invoke", {
		args: { to, text }
	});

	return data;
}

// Использование
await sendMessage("user-123", "Hello from Integ!");

Обработка входящих сообщений

typescript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
	const { event, data } = req.body;

	switch (event) {
		case "message.received":
			console.log(`Received message from ${data.from}: ${data.text}`);
			// Обработка входящего сообщения
			break;

		case "message.delivered":
			console.log(`Message ${data.messageId} delivered`);
			break;
	}

	res.status(200).send("OK");
});

app.listen(3001);

Полный пример интеграции

typescript

import axios from "axios";

const TOKEN = process.env.INTEG_TOKEN;
const INTEGRATION_NAME = "integration-name";

const api = axios.create({
	baseURL: "http://localhost:3000/api",
	headers: { Authorization: `Bearer ${TOKEN}` }
});

async function setupIntegration() {
	// 1. Создать интеграцию
	const { data: integration } = await api.post("/integrations", {
		name: INTEGRATION_NAME
	});
	console.log("Integration created:", integration.id);

	// 2. Добавить секреты
	await api.post("/secrets", {
		integration: INTEGRATION_NAME,
		key: "api_key",
		value: process.env.SERVICE_API_KEY
	});
	console.log("Secrets configured");

	// 3. Создать handler
	const { data: handler } = await api.post("/handlers", {
		integrationId: integration.id,
		name: "send-message",
		defaultArgs: { retries: 3, timeout: 5000 }
	});
	console.log("Handler created:", handler.id);

	// 4. Использовать handler
	const { data: result } = await api.post(`/handlers/${handler.id}/invoke`, {
		args: {
			to: "recipient-id",
			text: "Test message"
		}
	});
	console.log("Message sent:", result);

	return { integration, handler };
}

setupIntegration().catch(console.error);

Troubleshooting

Частые ошибки

401 Unauthorized

Причина: Неверный или истёкший токен.

Решение:

bash

# Проверить токен
curl http://localhost:3000/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

# Получить новый токен
curl -X POST http://localhost:3000/api/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

400 Invalid API Key

Причина: Секрет api_key не настроен или неверный.

Решение:

bash

# Проверить секреты
curl http://localhost:3000/api/secrets?integration=integration-name \
  -H "Authorization: Bearer $TOKEN"

# Обновить секрет
curl -X PATCH http://localhost:3000/api/secrets/secret-id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "correct-api-key"}'

504 Gateway Timeout

Причина: Внешний сервис не отвечает.

Решение:

Проверить статус внешнего сервиса
Увеличить таймаут в defaultArgs
Проверить сетевое подключение

Логирование

bash

# Просмотр логов Integ API
docker logs integ-api --tail 100 -f

# Фильтрация по интеграции
docker logs integ-api 2>&1 | grep "integration-name"

Ограничения

Максимальный размер сообщения: X KB
Rate limit: Y запросов в минуту
Поддерживаемые типы файлов: список

Связанные документы

Secrets API - Управление секретами
Handlers API - Работа с handlers
Access Tokens - M2M аутентификация
Официальная документация сервиса

​

Быстрый старт ​

Обзор ​

Возможности ​

Архитектура ​

Требования ​

Предварительные условия ​

Необходимые секреты ​

Установка ​

1. Создание интеграции ​

2. Добавление секретов ​

3. Создание handlers ​

4. Проверка установки ​

Конфигурация ​

Переменные окружения ​

Handler параметры ​

API Reference ​

Методы ​

sendMessage ​

getStatus ​

Вебхуки (если поддерживаются) ​

Настройка вебхука ​

Формат входящих событий ​

Примеры использования ​

Отправка простого сообщения ​

Обработка входящих сообщений ​

Полный пример интеграции ​

Troubleshooting ​

Частые ошибки ​

401 Unauthorized ​

400 Invalid API Key ​

504 Gateway Timeout ​

Логирование ​

Ограничения ​

Связанные документы ​

Быстрый старт

Обзор

Возможности

Архитектура

Требования

Предварительные условия

Необходимые секреты

Установка

1. Создание интеграции

2. Добавление секретов

3. Создание handlers

4. Проверка установки

Конфигурация

Переменные окружения

Handler параметры

API Reference

Методы

`sendMessage`

`getStatus`

Вебхуки (если поддерживаются)

Настройка вебхука

Формат входящих событий

Примеры использования

Отправка простого сообщения

Обработка входящих сообщений

Полный пример интеграции

Troubleshooting

Частые ошибки

401 Unauthorized

400 Invalid API Key

504 Gateway Timeout

Логирование

Ограничения

Связанные документы