Шаблон документации интеграции

Как использовать

Скопируйте этот файл, переименуйте и заполните секции. Удалите инструкции в блоках :::info.

---

Обзор

{Название} интеграция позволяет:

Инструкция

Опишите основные возможности интеграции. Что она делает? Зачем нужна?

Требования

Перед началом работы убедитесь, что у вас есть:

Инструкция

Укажите всё необходимое для работы интеграции: ключи, токены, аккаунты.

Настройка

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

1. Перейдите в Интеграции → Создать
2. Введите название: {Название}
3. Нажмите Создать

Шаг 2: Добавление Credentials

Ключ	Описание	Где получить
{KEY_1}
{KEY_2}

Инструкция

Перечислите все credentials с описанием и инструкцией где их получить.

Шаг 3: Добавление Secrets

Ключ	Описание	Формат
{SECRET_1}

Инструкция

Перечислите все secrets. Secrets — это конфиденциальные данные (webhook secrets, private keys).

Шаг 4: Создание Handlers

Handler	Описание	HTTP метод
{handler-name}		POST

Инструкция

Перечислите handlers (webhooks), которые создаёт интеграция.

Использование

Пример:

// Описание что делает код
{Код примера}

Инструкция

Добавьте реальные примеры использования с кодом.

Webhook URL

Handler доступен по URL:

POST {WEBHOOK_BASE_URL}/webhook/{handler-name}

Пример запроса:

curl -X POST {WEBHOOK_BASE_URL}/webhook/{handler-name} \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

API Reference

Эндпоинты

Метод	Эндпоинт	Описание
POST	/integrations/{id}/handlers/{handler}/execute	Выполнить handler

Параметры запроса

interface I{Name}Request {
	{param1}: string;
	{param2}?: number;
}

Параметры ответа

interface I{Name}Response {
	{field1}: string;
	{field2}: boolean;
}

Инструкция

Опишите API интеграции: эндпоинты, параметры запросов и ответов.

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

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

Переменная	Описание	Обязательная
{VAR_NAME}		Да/Нет

Default Args для Handlers

{
	"timeout": 5000,
	"retries": 3
}

Инструкция

Укажите доступные настройки и их значения по умолчанию.

События

Интеграция обрабатывает следующие события:

Событие	Описание	Payload
{event.name}		{ field: type }

Инструкция

Если интеграция принимает события (webhooks) — опишите их.

Troubleshooting

Симптом:

Причина:

Решение:

{Команда или действие для решения}

Инструкция

Добавьте типичные проблемы и их решения.

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

Ошибка	Причина	Решение
{error_code}

Безопасность

Важно

Инструкция

Укажите важные аспекты безопасности: хранение ключей, валидация и т.д.

Ограничения

Инструкция

Укажите известные ограничения интеграции.

Changelog

Версия	Дата	Изменения
1.0.0		Начальная версия

Инструкция

Ведите историю изменений интеграции.

Следующие шаги

• Управление интеграциями

Инструкция

Добавьте ссылки на связанную документацию.

---

Удалите перед публикацией

Удалите все блоки ::: info Инструкция перед публикацией документации.