FlowCraft

Внешний вид

API эндпоинты FlowCraft ​

FlowCraft предоставляет полный набор RESTful API эндпоинтов для управления всеми аспектами платформы. API построено на FastAPI и полностью документировано с использованием OpenAPI (Swagger).

Базовая информация ​

  • Базовый URL: https://your-instance.flowcraft.io/api/v1
  • Формат данных: JSON
  • Аутентификация: JWT токены, OAuth2
  • Документация: Swagger UI доступен по адресу https://your-instance.flowcraft.io/docs

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

Все запросы к API (кроме публичных эндпоинтов) должны быть аутентифицированы. FlowCraft поддерживает следующие методы аутентификации:

JWT токены ​

Authorization: Bearer <token>

OAuth2 ​

FlowCraft поддерживает OAuth2 для интеграции с внешними системами аутентификации.

Группы эндпоинтов ​

Аутентификация и пользователи ​

POST /auth/login ​

Аутентификация пользователя и получение JWT токена.

Запрос:

json
{
  "email": "user@example.com",
  "password": "secure_password"
}

Ответ:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /auth/refresh ​

Обновление JWT токена с использованием refresh токена.

Запрос:

json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Ответ:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /auth/register ​

Регистрация нового пользователя.

Запрос:

json
{
  "email": "user@example.com",
  "password": "secure_password",
  "first_name": "John",
  "last_name": "Doe"
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2025-04-24T12:34:56.789Z",
  "is_active": true
}

GET /users/me ​

Получение информации о текущем пользователе.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2025-04-24T12:34:56.789Z",
  "is_active": true,
  "roles": ["admin", "user"]
}

GET /users ​

Получение списка пользователей (только для администраторов).

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

  • skip (int, optional): Количество пропускаемых записей (для пагинации)
  • limit (int, optional): Максимальное количество возвращаемых записей

Ответ:

json
{
  "total": 100,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "created_at": "2025-04-24T12:34:56.789Z",
      "is_active": true,
      "roles": ["admin", "user"]
    },
    // ...
  ]
}

GET /users/ ​

Получение информации о конкретном пользователе.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2025-04-24T12:34:56.789Z",
  "is_active": true,
  "roles": ["admin", "user"]
}

PUT /users/ ​

Обновление информации о пользователе.

Запрос:

json
{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com"
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.smith@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "created_at": "2025-04-24T12:34:56.789Z",
  "is_active": true,
  "roles": ["admin", "user"]
}

DELETE /users/ ​

Удаление пользователя.

Ответ:

204 No Content

Рабочие процессы ​

GET /workflows ​

Получение списка рабочих процессов.

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

  • skip (int, optional): Количество пропускаемых записей (для пагинации)
  • limit (int, optional): Максимальное количество возвращаемых записей
  • active (bool, optional): Фильтр по статусу активации
  • tag (string, optional): Фильтр по тегу

Ответ:

json
{
  "total": 50,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Email Marketing Automation",
      "description": "Automated email marketing workflow",
      "created_at": "2025-04-24T12:34:56.789Z",
      "updated_at": "2025-04-24T12:34:56.789Z",
      "is_active": true,
      "tags": ["marketing", "email"],
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    },
    // ...
  ]
}

POST /workflows ​

Создание нового рабочего процесса.

Запрос:

json
{
  "name": "Email Marketing Automation",
  "description": "Automated email marketing workflow",
  "nodes": [
    {
      "id": "node_1",
      "type": "trigger",
      "name": "Schedule Trigger",
      "parameters": {
        "schedule": "0 9 * * *"
      },
      "position": {
        "x": 100,
        "y": 200
      }
    },
    {
      "id": "node_2",
      "type": "action",
      "name": "Get Subscribers",
      "parameters": {
        "list_id": "list_123"
      },
      "position": {
        "x": 300,
        "y": 200
      }
    },
    // ...
  ],
  "connections": [
    {
      "source": "node_1",
      "target": "node_2",
      "sourceHandle": "output",
      "targetHandle": "input"
    },
    // ...
  ],
  "tags": ["marketing", "email"]
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Email Marketing Automation",
  "description": "Automated email marketing workflow",
  "created_at": "2025-04-24T12:34:56.789Z",
  "updated_at": "2025-04-24T12:34:56.789Z",
  "is_active": false,
  "tags": ["marketing", "email"],
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "nodes": [
    // ...
  ],
  "connections": [
    // ...
  ]
}

GET /workflows/ ​

Получение информации о конкретном рабочем процессе.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Email Marketing Automation",
  "description": "Automated email marketing workflow",
  "created_at": "2025-04-24T12:34:56.789Z",
  "updated_at": "2025-04-24T12:34:56.789Z",
  "is_active": true,
  "tags": ["marketing", "email"],
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "nodes": [
    // ...
  ],
  "connections": [
    // ...
  ]
}

PUT /workflows/ ​

Обновление рабочего процесса.

Запрос:

json
{
  "name": "Updated Email Marketing Automation",
  "description": "Updated automated email marketing workflow",
  "nodes": [
    // ...
  ],
  "connections": [
    // ...
  ],
  "tags": ["marketing", "email", "automation"]
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Updated Email Marketing Automation",
  "description": "Updated automated email marketing workflow",
  "created_at": "2025-04-24T12:34:56.789Z",
  "updated_at": "2025-04-24T13:45:56.789Z",
  "is_active": true,
  "tags": ["marketing", "email", "automation"],
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "nodes": [
    // ...
  ],
  "connections": [
    // ...
  ]
}

DELETE /workflows/ ​

Удаление рабочего процесса.

Ответ:

204 No Content

POST /workflows/{workflow_id}/activate ​

Активация рабочего процесса.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "is_active": true,
  "activated_at": "2025-04-24T13:45:56.789Z"
}

POST /workflows/{workflow_id}/deactivate ​

Деактивация рабочего процесса.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "is_active": false,
  "deactivated_at": "2025-04-24T13:45:56.789Z"
}

POST /workflows/{workflow_id}/export ​

Экспорт рабочего процесса.

Ответ: Файл JSON с конфигурацией рабочего процесса.

POST /workflows/import ​

Импорт рабочего процесса.

Запрос: Файл JSON с конфигурацией рабочего процесса.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "name": "Imported Workflow",
  "description": "Imported workflow description",
  "created_at": "2025-04-24T13:45:56.789Z",
  "updated_at": "2025-04-24T13:45:56.789Z",
  "is_active": false,
  "tags": ["imported"],
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

Выполнения ​

POST /workflows/{workflow_id}/execute ​

Запуск выполнения рабочего процесса.

Запрос:

json
{
  "input": {
    "key1": "value1",
    "key2": "value2"
  }
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "running",
  "started_at": "2025-04-24T13:45:56.789Z",
  "input": {
    "key1": "value1",
    "key2": "value2"
  }
}

GET /executions ​

Получение списка выполнений рабочих процессов.

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

  • skip (int, optional): Количество пропускаемых записей (для пагинации)
  • limit (int, optional): Максимальное количество возвращаемых записей
  • workflow_id (string, optional): Фильтр по ID рабочего процесса
  • status (string, optional): Фильтр по статусу выполнения

Ответ:

json
{
  "total": 100,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "workflow_id": "550e8400-e29b-41d4-a716-446655440001",
      "workflow_name": "Email Marketing Automation",
      "status": "completed",
      "started_at": "2025-04-24T13:45:56.789Z",
      "finished_at": "2025-04-24T13:46:56.789Z",
      "duration": 60.0
    },
    // ...
  ]
}

GET /executions/ ​

Получение информации о конкретном выполнении.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440001",
  "workflow_name": "Email Marketing Automation",
  "status": "completed",
  "started_at": "2025-04-24T13:45:56.789Z",
  "finished_at": "2025-04-24T13:46:56.789Z",
  "duration": 60.0,
  "input": {
    "key1": "value1",
    "key2": "value2"
  },
  "output": {
    "result": "success",
    "processed_items": 100
  },
  "node_executions": [
    {
      "node_id": "node_1",
      "node_name": "Schedule Trigger",
      "status": "completed",
      "started_at": "2025-04-24T13:45:56.789Z",
      "finished_at": "2025-04-24T13:45:57.789Z",
      "duration": 1.0,
      "input": {},
      "output": {
        "timestamp": "2025-04-24T13:45:56.789Z"
      }
    },
    // ...
  ]
}

GET /executions/{execution_id}/logs ​

Получение логов выполнения.

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

  • node_id (string, optional): Фильтр по ID узла
  • level (string, optional): Фильтр по уровню логирования

Ответ:

json
{
  "logs": [
    {
      "timestamp": "2025-04-24T13:45:56.789Z",
      "level": "info",
      "node_id": "node_1",
      "node_name": "Schedule Trigger",
      "message": "Node execution started"
    },
    {
      "timestamp": "2025-04-24T13:45:57.789Z",
      "level": "info",
      "node_id": "node_1",
      "node_name": "Schedule Trigger",
      "message": "Node execution completed"
    },
    // ...
  ]
}

POST /executions/{execution_id}/cancel ​

Отмена выполнения.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "status": "cancelled",
  "cancelled_at": "2025-04-24T13:46:00.789Z"
}

Учетные данные ​

GET /credentials ​

Получение списка учетных данных.

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

  • skip (int, optional): Количество пропускаемых записей (для пагинации)
  • limit (int, optional): Максимальное количество возвращаемых записей
  • type (string, optional): Фильтр по типу учетных данных

Ответ:

json
{
  "total": 20,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "name": "Gmail API",
      "type": "gmail_oauth2",
      "created_at": "2025-04-24T12:34:56.789Z",
      "updated_at": "2025-04-24T12:34:56.789Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    },
    // ...
  ]
}

POST /credentials ​

Создание новых учетных данных.

Запрос:

json
{
  "name": "Gmail API",
  "type": "gmail_oauth2",
  "data": {
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "refresh_token": "your_refresh_token"
  }
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "name": "Gmail API",
  "type": "gmail_oauth2",
  "created_at": "2025-04-24T13:45:56.789Z",
  "updated_at": "2025-04-24T13:45:56.789Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

GET /credentials/ ​

Получение информации о конкретных учетных данных.

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "name": "Gmail API",
  "type": "gmail_oauth2",
  "created_at": "2025-04-24T13:45:56.789Z",
  "updated_at": "2025-04-24T13:45:56.789Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "client_id": "your_client_id",
    "client_secret": "***********",
    "refresh_token": "***********"
  }
}

PUT /credentials/ ​

Обновление учетных данных.

Запрос:

json
{
  "name": "Updated Gmail API",
  "data": {
    "client_id": "new_client_id",
    "client_secret": "new_client_secret",
    "refresh_token": "new_refresh_token"
  }
}

Ответ:

json
{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "name": "Updated Gmail API",
  "type": "gmail_oauth2",
  "created_at": "2025-04-24T13:45:56.789Z",
  "updated_at": "2025-04-24T14:45:56.789Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

DELETE /credentials/ ​

Удаление учетных данных.

Ответ:

204 No Content

POST /credentials/{credential_id}/test ​

Тестирование учетных данных.

Ответ:

json
{
  "success": true,
  "message": "Connection successful"
}

Интеграции ​

GET /integrations ​

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

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

  • skip (int, optional): Количество пропускаемых записей (для пагинации)
  • limit (int, optional): Максимальное количество возвращаемых записей
  • category (string, optional): Фильтр по категории

Ответ:

json
{
  "total": 400,
  "items": [
    {
      "id": "gmail",
      "name": "Gmail",
      "description": "Send and receive emails using Gmail",
      "version": "1.0.0",
      "category": "Communication",
      "icon": "https://flowcraft.io/icons/gmail.svg",
      "credential_types": ["gmail_oauth2", "gmail_api_key"]
    },
    // ...
  ]
}

GET /integrations/ ​

Получение информации о конкретной интеграции.

Ответ:

json
{
  "id": "gmail",
  "name": "Gmail",
  "description": "Send and receive emails using Gmail",
  "version": "1.0.0",
  "category": "Communication",
  "icon": "https://flowcraft.io/icons/gmail.svg",
  "credential_types": ["gmail_oauth2", "gmail_api_key"],
  "actions": [
    {
      "id": "send_email",
      "name": "Send Email",
      "description": "Send an email using Gmail",
      "input_schema": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "format": "email",
            "description": "Recipient email address"
          },
          "subject": {
            "type": "string",
            "description": "Email subject"
          },
          "body": {
            "type": "string",
            "description": "Email body (HTML supported)"
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Attachment filename"
                },
                "content": {
                  "type": "string",
                  "format": "binary",
                  "description": "Attachment content (base64 encoded)"
                }
              }
            },
            "description": "Email attachments"
          }
        },
        "required": ["to", "subject", "body"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string",
            "description": "Unique message ID"
          },
          "thread_id": {
            "type": "string",
            "description": "Thread ID"
          }
        }
      }
    },
    // ...
  ],
  "triggers": [
    {
      "id": "new_email",
      "name": "New Email",
      "description": "Triggered when a new email is received",
      "output_schema": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "description": "Sender email address"
          },
          "to": {
            "type": "string",
            "description": "Recipient email address"
          },
          "subject": {
            "type": "string",
            "description": "Email subject"
          },
          "body": {
            "type": "string",
            "description": "Email body"
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Attachment filename"
                },
                "content": {
                  "type": "string",
                  "format": "binary",
                  "description": "Attachment content (base64 encoded)"
                }
              }
            },
            "description": "Email attachments"
          }
        }
      }
    },
    // ...
  ]
}

Система ​

GET /system/status ​

Получение статуса системы.

Ответ:

json
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 86400,
  "components": {
    "api": {
      "status": "healthy",
      "version": "1.0.0"
    },
    "execution_engine": {
      "status": "healthy",
      "version": "1.0.0",
      "active_executions": 5
    },
    "database": {
      "status": "healthy",
      "version": "PostgreSQL 14.5"
    },
    "redis": {
      "status": "healthy",
      "version": "Redis 6.2.6"
    }
  },
  "resources": {
    "cpu_usage": 25.5,
    "memory_usage": 60.2,
    "disk_usage": 45.8
  }
}

GET /system/settings ​

Получение настроек системы (только для администраторов).

Ответ:

json
{
  "execution": {
    "max_concurrent_executions": 10,
    "execution_timeout": 3600,
    "max_execution_history": 1000
  },
  "security": {
    "allow_registration": true,
    "password_policy": {
      "min_length": 8,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_numbers": true,
      "require_special_chars": true
    },
    "session_timeout": 86400
  },
  "email": {
    "smtp_server": "smtp.example.com",
    "smtp_port": 587,
    "smtp_secure": true,
    "smtp_user": "notifications@example.com",
    "from_email": "notifications@example.com",
    "from_name": "FlowCraft Notifications"
  }
}

PUT /system/settings ​

Обновление настроек системы (только для администраторов).

Запрос:

json
{
  "execution": {
    "max_concurrent_executions": 20,
    "execution_timeout": 7200
  }
}

Ответ:

json
{
  "execution": {
    "max_concurrent_executions": 20,
    "execution_timeout": 7200,
    "max_execution_history": 1000
  },
  "security": {
    "allow_registration": true,
    "password_policy": {
      "min_length": 8,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_numbers": true,
      "require_special_chars": true
    },
    "session_timeout": 86400
  },
  "email": {
    "smtp_server": "smtp.example.com",
    "smtp_port": 587,
    "smtp_secure": true,
    "smtp_user": "notifications@example.com",
    "from_email": "notifications@example.com",
    "from_name": "FlowCraft Notifications"
  }
}

GET /system/plugins ​

Получение списка установленных плагинов.

Ответ:

json
{
  "total": 10,
  "items": [
    {
      "id": "custom_crm",
      "name": "Custom CRM Integration",
      "description": "Integration with custom CRM system",
      "version": "1.0.0",
      "author": "FlowCraft Team",
      "enabled": true,
      "installed_at": "2025-04-24T12:34:56.789Z"
    },
    // ...
  ]
}

POST /system/plugins/install ​

Установка нового плагина (только для администраторов).

Запрос: Файл плагина (.zip или .tar.gz)

Ответ:

json
{
  "id": "new_plugin",
  "name": "New Plugin",
  "description": "Description of the new plugin",
  "version": "1.0.0",
  "author": "Plugin Author",
  "enabled": true,
  "installed_at": "2025-04-24T13:45:56.789Z"
}

POST /system/plugins/{plugin_id}/enable ​

Включение плагина (только для администраторов).

Ответ:

json
{
  "id": "custom_crm",
  "enabled": true,
  "enabled_at": "2025-04-24T13:45:56.789Z"
}

POST /system/plugins/{plugin_id}/disable ​

Отключение плагина (только для администраторов).

Ответ:

json
{
  "id": "custom_crm",
  "enabled": false,
  "disabled_at": "2025-04-24T13:45:56.789Z"
}

DELETE /system/plugins/ ​

Удаление плагина (только для администраторов).

Ответ:

204 No Content

Webhook API ​

FlowCraft предоставляет специальные эндпоинты для обработки входящих webhook-событий.

POST /webhook/ ​

Запуск рабочего процесса через webhook.

Запрос: Любые данные в формате JSON, которые будут переданы в рабочий процесс.

Ответ:

json
{
  "execution_id": "550e8400-e29b-41d4-a716-446655440003",
  "status": "accepted"
}

POST /webhook/{workflow_id}/ ​

Запуск конкретного триггера в рабочем процессе через webhook.

Запрос: Любые данные в формате JSON, которые будут переданы в триггер.

Ответ:

json
{
  "execution_id": "550e8400-e29b-41d4-a716-446655440003",
  "status": "accepted"
}

Коды ошибок ​

FlowCraft API использует стандартные HTTP коды состояния для индикации успеха или неудачи запроса:

  • 200 OK: Запрос выполнен успешно
  • 201 Created: Ресурс успешно создан
  • 204 No Content: Запрос выполнен успешно, но нет данных для возврата
  • 400 Bad Request: Неверный запрос (неправильный формат, отсутствуют обязательные поля и т.д.)
  • 401 Unauthorized: Требуется аутентификация
  • 403 Forbidden: Доступ запрещен
  • 404 Not Found: Ресурс не найден
  • 409 Conflict: Конфликт (например, при попытке создать ресурс с уже существующим именем)
  • 422 Unprocessable Entity: Ошибка валидации
  • 429 Too Many Requests: Превышен лимит запросов
  • 500 Internal Server Error: Внутренняя ошибка сервера

В случае ошибки API возвращает JSON-объект с информацией об ошибке:

json
{
  "error": {
    "code": "invalid_input",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Ограничения и лимиты ​

  • Максимальный размер запроса: 10 МБ
  • Максимальное количество запросов в минуту: 100 (для базового плана)
  • Максимальное количество одновременных выполнений: 10 (для базового плана)
  • Максимальное время выполнения рабочего процесса: 1 час (для базового плана)

Версионирование API ​

FlowCraft API использует семантическое версионирование. Текущая версия API: v1.

Для обеспечения обратной совместимости, все изменения в API публикуются в соответствии с следующими правилами:

  • Патч-версии (например, v1.0.1): исправления ошибок, не влияющие на совместимость
  • Минорные версии (например, v1.1.0): добавление новой функциональности с сохранением обратной совместимости
  • Мажорные версии (например, v2.0.0): изменения, нарушающие обратную совместимость

Заключение ​

FlowCraft API предоставляет полный набор инструментов для управления всеми аспектами платформы автоматизации рабочих процессов. API построено на современных принципах RESTful дизайна и полностью документировано с использованием OpenAPI (Swagger).

Выпущено под лицензией MIT.

Copyright © 2025 FlowCraft Team