Syngenta Cropwise Assistant API Documentation

1. Chats

POST /api/v1/chats/new

Метод: POST

URL: /api/v1/chats/new

Описание

Создает новый чат для пользователя.

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Тело запроса: Отсутствует

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Chat created successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Новый чат",
    "created_at": "2024-10-02T12:34:56.789Z"
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными созданного чата
data.id string Уникальный идентификатор чата (UUID формат)
data.name string Название чата
data.created_at string Дата и время создания чата (ISO 8601 формат)

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/chats

Метод: GET

URL: /api/v1/chats?page={page}&limit={limit}

Описание

Возвращает список чатов пользователя с поддержкой пагинации. Чаты отсортированы по updated_at в порядке убывания (новые чаты идут первыми).

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Тело запроса: Отсутствует

Query параметры:

Параметр Тип Обязательный Описание
page integer Нет Номер страницы для пагинации (по умолчанию: 1)
limit integer Нет Количество элементов на странице (по умолчанию: 20)

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Chats fetched successfully",
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Мой первый чат",
        "mode": "cropwise_read",
        "status": "pending",
        "created_at": "2024-10-01T10:00:00.000Z",
        "updated_at": "2024-10-02T15:30:00.000Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Чат по базе знаний",
        "mode": "knowledge_base_read",
        "status": "processing",
        "created_at": "2024-09-30T08:20:00.000Z",
        "updated_at": "2024-10-02T14:15:00.000Z"
      },
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "name": "Новый чат",
        "mode": null,
        "status": "pending",
        "created_at": "2024-09-28T12:00:00.000Z",
        "updated_at": "2024-10-01T09:45:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 25,
      "has_next": true
    }
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными чатов и информацией о пагинации
data.items array Массив с данными чатов
data.items[].id string Уникальный идентификатор чата (UUID формат)
data.items[].name string Название чата
data.items[].mode string|null Режим чата: cropwise_read (чтение), cropwise_write (запись), knowledge_base_read (база знаний), или null если режим не выбран
data.items[].status string Статус чата: processing (обработка сообщения пользователя, отправка новых сообщений запрещена), pending (ожидание нового сообщения, можно отправлять сообщения)
data.items[].created_at string Дата и время создания чата (ISO 8601 формат)
data.items[].updated_at string Дата и время последнего обновления чата (ISO 8601 формат)
data.meta object Объект с метаданными пагинации
data.meta.page integer Номер текущей страницы
data.meta.limit integer Количество элементов на странице
data.meta.total integer Общее количество чатов
data.meta.has_next boolean Наличие следующей страницы

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/chats/{chat_id}

Метод: GET

URL: /api/v1/chats/{chat_id}?page={page}&limit={limit}

Описание

Возвращает информацию о конкретном чате и его историю сообщений с поддержкой пагинации. Сообщения отсортированы по created_at в порядке убывания (новые сообщения идут первыми).

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
chat_id string Да Уникальный идентификатор чата (UUID формат)

Query параметры:

Параметр Тип Обязательный Описание
page integer Нет Номер страницы для пагинации истории сообщений (по умолчанию: 1)
limit integer Нет Количество сообщений на странице (по умолчанию: 20)

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Chat fetched successfully",
  "data": {
    "chat": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Покажи мне информацию по полям",
      "mode": "cropwise_read",
      "status": "processing",
      "created_at": "2024-10-01T10:00:00.000Z",
      "updated_at": "2024-10-02T15:30:00.000Z"
    },
    "chat_action": {
      "id": "ia-123e4567-e89b-12d3-a456-426614174000",
      "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "text": "Вам также может быть интересно:",
      "options": [
        { "id": "opt-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "text": "Как ухаживать за кукурузой?" },
        { "id": "opt-2b3c4d5e-6f7a-8901-bcde-f12345678901", "text": "Что делать с обнаруженными угрозами?" }
      ]
    },
    "history": [
      {
        "id": "msg-4d5e6f7a-8b9c-0123-def0-234567890123",
        "content": "Вот отчет по полю номер 5 с актуальными данными по урожайности и состоянию культур.",
        "role": "ai",
        "mode": "cropwise_read",
        "is_final": true,
        "created_at": "2024-10-02T15:30:45.000Z",
        "attachments": [
          {
            "id": "att-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
            "message_id": "msg-4d5e6f7a-8b9c-0123-def0-234567890123",
            "name": "field_5_report.xlsx",
            "type": "document",
            "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "url": "https://s3.example.com/attachments/att-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
            "size": 245760
          }
        ],
        "feedback": {
          "id": "fb-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
          "message_id": "msg-4d5e6f7a-8b9c-0123-def0-234567890123",
          "is_helpful": true,
          "reason": null,
          "comment": null,
          "created_at": "2024-10-02T16:00:00.000Z"
        }
      },
      {
        "id": "msg-3c4d5e6f-7a8b-9012-cdef-123456789012",
        "content": "Поле номер 5",
        "role": "human",
        "mode": "cropwise_read",
        "is_final": null,
        "created_at": "2024-10-02T15:30:00.000Z",
        "attachments": [],
        "feedback": null
      },
      {
        "id": "msg-2b3c4d5e-6f7a-8901-bcde-f12345678901",
        "content": "Конечно! Уточните, пожалуйста, по каким именно полям вы хотите получить информацию? Можете указать название поля или его ID.",
        "role": "ai",
        "mode": "cropwise_read",
        "is_final": false,
        "created_at": "2024-10-01T10:05:15.000Z",
        "attachments": [],
        "feedback": null
      },
      {
        "id": "msg-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
        "content": "Покажи мне информацию по полям",
        "role": "human",
        "mode": "cropwise_read",
        "is_final": null,
        "created_at": "2024-10-01T10:05:00.000Z",
        "attachments": [],
        "feedback": null
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 16,
      "has_next": false
    }
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными чата, текущим интерактивным действием (если есть) и метаданными пагинации
data.chat object Объект с данными чата
data.chat.id string Уникальный идентификатор чата (UUID формат)
data.chat.name string Название чата
data.chat.mode string|null Режим чата: cropwise_read (чтение), cropwise_write (запись), knowledge_base_read (база знаний), или null если режим не выбран
data.chat.status string Статус чата: processing (обработка сообщения пользователя, отправка новых сообщений запрещена), pending (ожидание нового сообщения, можно отправлять сообщения)
data.chat.created_at string Дата и время создания чата (ISO 8601 формат)
data.chat.updated_at string Дата и время последнего обновления чата (ISO 8601 формат)
data.chat_action object|null Текущее интерактивное действие, доступное пользователю, или null, если действий нет
data.chat_action.id string Уникальный идентификатор интерактивного действия
data.chat_action.chat_id string Уникальный идентификатор чата, в контексте которого предложено действие
data.chat_action.text string Текстовое описание интерактивного действия
data.chat_action.options array Список доступных опций для выбора
data.chat_action.options[].id string Уникальный идентификатор опции
data.chat_action.options[].text string Текстовое описание опции
data.history array Массив с историей сообщений чата
data.history[].id string Уникальный идентификатор сообщения
data.history[].content string Содержимое сообщения
data.history[].role string Роль отправителя: human (пользователь), ai (чат-бот)
data.history[].mode string Режим чата, в котором было отправлено сообщение: cropwise_read, cropwise_write или knowledge_base_read
data.history[].is_final boolean|null Признак завершённости ответа. Для сообщений с role: "human" всегда null. Для сообщений с role: "ai": если значение true, значит бот полностью сформировал ответ, и чат можно переключать в другой режим; если false — бот ожидает дополнительную информацию от пользователя
data.history[].created_at string Дата и время создания сообщения (ISO 8601 формат)
data.history[].attachments array Массив вложенных файлов. Бот возвращает файлы во вложениях, если ответ слишком большой для текстового формата. Пустой массив [] если вложений нет
data.history[].attachments[].id string Уникальный идентификатор вложения
data.history[].attachments[].message_id string Идентификатор сообщения, к которому прикреплено вложение
data.history[].attachments[].name string Название файла с расширением
data.history[].attachments[].type string Тип файла: image (изображения), document (документы: Excel, PDF и др.), audio (голосовые сообщения)
data.history[].attachments[].mime_type string MIME-тип файла (например: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, image/png, application/pdf)
data.history[].attachments[].url string Ссылка для скачивания файла
data.history[].attachments[].size integer Размер файла в байтах
data.history[].feedback object|null Объект с фидбеком пользователя на сообщение бота, или null если фидбек не оставлен (всегда null для сообщений пользователя)
data.history[].feedback.id string Уникальный идентификатор фидбека
data.history[].feedback.message_id string Уникальный идентификатор сообщения
data.history[].feedback.is_helpful boolean Являлся ли ответ бота полезным
data.history[].feedback.reason string|null Причина низкой оценки: incorrect_data (некорректные данные), incomplete_answer (недостаточно полный ответ), misunderstood (ассистент не понял вопрос), other (другое). Указывается только при is_helpful: false
data.history[].feedback.comment string|null Опциональный комментарий пользователя с дополнительной информацией
data.history[].feedback.created_at string Дата и время создания фидбека (ISO 8601 формат)
data.meta object Объект с метаданными пагинации истории сообщений
data.meta.page integer Номер текущей страницы
data.meta.limit integer Количество сообщений на странице
data.meta.total integer Общее количество сообщений в истории чата
data.meta.has_next boolean Наличие следующей страницы

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Чат с указанным ID не найден {"success": false, "detail": "Chat not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

POST /api/v1/chats/{chat_id}/send

Метод: POST

URL: /api/v1/chats/{chat_id}/send

Описание

Отправляет сообщение пользователя в чат. Поддерживает отправку текстовых сообщений и голосовых файлов. При указании режима чата (mode) проверяется соответствие с текущим режимом чата.

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Content-Type: multipart/form-data

Path параметры:

Параметр Тип Обязательный Описание
chat_id string Да Уникальный идентификатор чата (UUID формат)

Form data параметры:

Параметр Тип Обязательный Описание
mode string Да Режим чата: cropwise_read, cropwise_write, knowledge_base_read. Если текущий режим чата null, чат переключится в указанный режим. Если текущий режим чата не null и не совпадает с указанным, вернётся ошибка 400
text string Нет Текст сообщения. Хотя бы один из параметров text или audio должен быть указан
audio file Нет Голосовой файл. Хотя бы один из параметров text или audio должен быть указан
Пример запроса (текстовое сообщение) 
POST /api/v1/chats/a1b2c3d4-e5f6-7890-abcd-ef1234567890/send
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="mode"

cropwise_read
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="text"

Покажи информацию по урожайности
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Message sent successfully",
  "data": {
    "id": "msg-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "content": "Покажи информацию по урожайности",
    "role": "human",
    "mode": "cropwise_read",
    "is_final": null,
    "created_at": "2024-10-02T16:45:30.000Z",
    "attachments": [],
    "feedback": null
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными отправленного сообщения
data.id string Уникальный идентификатор сообщения
data.content string Содержимое сообщения (текст или расшифровка аудио)
data.role string Роль отправителя (всегда human для этого эндпоинта)
data.mode string Режим чата, в котором было отправлено сообщение: cropwise_read, cropwise_write или knowledge_base_read
data.is_final boolean|null Признак завершённости ответа (всегда null для сообщений пользователя)
data.created_at string Дата и время создания сообщения (ISO 8601 формат)
data.attachments array Массив вложенных файлов (аудио, если было отправлено)
data.attachments[].id string Уникальный идентификатор вложения
data.attachments[].message_id string Идентификатор сообщения, к которому прикреплено вложение
data.attachments[].name string Название файла с расширением
data.attachments[].type string Тип файла: image (изображения), document (документы: Excel, PDF и др.), audio (голосовые сообщения)
data.attachments[].mime_type string MIME-тип файла
data.attachments[].url string Ссылка для скачивания файла
data.attachments[].size integer Размер файла в байтах
data.feedback object|null Объект с фидбеком пользователя на сообщение бота, или null если фидбек не оставлен (всегда null для сообщений пользователя)

Ошибки:

Статус Код Описание Тело ответа
Bad Request 400 Указанный режим не совпадает с текущим режимом чата {"success": false, "detail": "Chat mode mismatch", "data": null}
Bad Request 400 Не указан ни текст, ни аудио файл {"success": false, "detail": "Either text or audio must be provided", "data": null}
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Чат с указанным ID не найден {"success": false, "detail": "Chat not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/chats/{chat_id}/sse

Метод: GET

URL: /api/v1/chats/{chat_id}/sse

Описание

Устанавливает постоянное SSE (Server-Sent Events) соединение и стримит события для указанного чата в реальном времени. Эндпоинт генерирует события об изменении состояния чата, появлении новых интерактивных действий и новых сообщениях бота.

Важно: - Соединение устанавливается один раз и остаётся активным до отключения клиента; - Возвращаются только новые сообщения от бота после подключения; - Пока бот не завершил ответ, нельзя отправлять новое сообщение; - Пока бот полность не ответил на поставленный вопрос (is_final: true), режим чата переключить невозможно;

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Path параметры:

Параметр Тип Обязательный Описание
chat_id string Да Уникальный идентификатор чата (UUID формат)

Response

Формат: text/event-stream (Server-Sent Events)

События:

1. Event: chat

Сообщает об изменениях состояния чата: режим, статус, временные метки. Используется для синхронизации UI (например, блокировка ввода при processing).

Пример события 
event: chat
data: {"id": "chat-123e4567-e89b-12d3-a456-426614174000", "name": "Почва поле 5 — анализ", "mode": "cropwise_read", "status": "processing", "created_at": "2024-10-02T14:00:00.000Z", "updated_at": "2024-10-02T16:46:15.000Z"}
Пример JSON 
{
  "id": "chat-123e4567-e89b-12d3-a456-426614174000",
  "name": "Почва поле 5 — анализ",
  "mode": "cropwise_read",
  "status": "processing",
  "created_at": "2024-10-02T14:00:00.000Z",
  "updated_at": "2024-10-02T16:46:15.000Z"
}

Структура data:

Поле Тип Описание
id string Уникальный идентификатор чата (UUID формат)
name string Название чата
mode string|null Текущий режим: cropwise_read, cropwise_write, knowledge_base_read или null
status string Статус: processing (новые сообщения запрещены), pending (можно отправлять сообщения)
created_at string Дата и время создания чата (ISO 8601 формат)
updated_at string Дата и время последнего обновления чата (ISO 8601 формат)

2. Event: chat_action

Сообщает о появлении нового интерактивного действия, доступного пользователю для выбора опции.

Пример события 
event: chat_action
data: {"id": "ia-123e4567-e89b-12d3-a456-426614174000", "chat_id": "chat-123e4567-e89b-12d3-a456-426614174000", "text": "Вам также может быть интересно:", "options": [{"id": "opt-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "text": "Как ухаживать за кукурузой?"}, {"id": "opt-2b3c4d5e-6f7a-8901-bcde-f12345678901", "text": "Что делать с обнаруженными угрозами?"}]}
Пример JSON 
{
  "id": "ia-123e4567-e89b-12d3-a456-426614174000",
  "chat_id": "chat-123e4567-e89b-12d3-a456-426614174000",
  "text": "Вам также может быть интересно:",
  "options": [
    { "id": "opt-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "text": "Как ухаживать за кукурузой?" },
    { "id": "opt-2b3c4d5e-6f7a-8901-bcde-f12345678901", "text": "Что делать с обнаруженными угрозами?" }
  ]
}

Структура data:

Поле Тип Описание
id string Уникальный идентификатор интерактивного действия
chat_id string Идентификатор чата, в котором показано действие
text string Текстовое описание интерактивного действия
options array Список доступных опций для выбора
options[].id string Уникальный идентификатор опции
options[].text string Текстовое описание опции

3. Event: chat_message

Сообщает о новом сообщении бота, сгенерированном в рамках текущего чата.

Пример события 
event: chat_message
data: {"id": "msg-2b3c4d5e-6f7a-8901-bcde-f12345678901", "content": "Вот информация по полю номер 5...", "role": "ai", "mode": "cropwise_read", "is_final": true, "created_at": "2024-10-02T16:46:15.000Z", "attachments": [], "feedback": null}
Пример JSON с вложениями 
{
  "id": "msg-4d5e6f7a-8b9c-0123-def0-234567890123",
  "content": "Вот детальный отчет по полю номер 5 с актуальными данными.",
  "role": "ai",
  "mode": "cropwise_read",
  "is_final": true,
  "created_at": "2024-10-02T16:46:15.000Z",
  "attachments": [
    {
      "id": "att-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "message_id": "msg-4d5e6f7a-8b9c-0123-def0-234567890123",
      "name": "field_5_detailed_report.xlsx",
      "type": "document",
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "url": "https://s3.example.com/attachments/att-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "size": 327680
    }
  ],
  "feedback": null
}

Структура data:

Поле Тип Описание
id string Уникальный идентификатор сообщения
content string Содержимое сообщения от бота
role string Роль отправителя (всегда ai для сообщений бота)
mode string Режим чата, в котором было отправлено сообщение: cropwise_read, cropwise_write или knowledge_base_read
is_final boolean Признак завершённости ответа. true — бот завершил ответ на поставленный вопрос, и можно переключить режим чата. false — необходимо предоставить боту дополнительную информация для того, чтобы он мог ответить на поставленный вопрос, режим чата переключить нельзя
created_at string Дата и время создания сообщения (ISO 8601 формат)
attachments array Массив вложенных файлов (если есть)
attachments[].id string Уникальный идентификатор вложения
attachments[].message_id string Идентификатор сообщения, к которому прикреплено вложение
attachments[].name string Название файла с расширением
attachments[].type string Тип файла: image, document, audio
attachments[].mime_type string MIME-тип файла
attachments[].url string Ссылка для скачивания файла
attachments[].size integer Размер файла в байтах
feedback object|null Объект с фидбеком пользователя на сообщение бота, или null если фидбек не оставлен

4. Event: error

Ошибка при обработке сообщения или генерации события.

Пример события 
event: error
data: {"message": "Не удалось обработать запрос"}

Структура data:

Поле Тип Описание
message string Текст ошибки

Ошибки при подключении:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Чат с указанным ID не найден {"success": false, "detail": "Chat not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

2. Chat Actions

POST /api/v1/chat-actions

Метод: POST

URL: /api/v1/chat-actions

Описание

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

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Content-Type: application/json

Пример тела запроса 
{
  "action_id": "ia-123e4567-e89b-12d3-a456-426614174000",
  "option_id": "opt-1a2b3c4d-5e6f-7890-abcd-ef1234567890"
}

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

Параметр Тип Обязательный Описание
action_id string Да Идентификатор интерактивного действия, предложенного ботом
option_id string Да Идентификатор выбранной пользователем опции

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Action option selected successfully",
  "data": null
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data null Данные отсутствуют

Ошибки:

Статус Код Описание Тело ответа
Bad Request 400 Некорректные параметры запроса {"success": false, "detail": "Invalid parameters", "data": null}
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Интерактивное действие или опция не найдены {"success": false, "detail": "Interaction or option not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/chat-actions/{action_id}

Метод: GET

URL: /api/v1/chat-actions/{action_id}

Описание

Возвращает информацию о конкретном интерактивном действии по его идентификатору.

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
action_id string Да Уникальный идентификатор интерактивного действия

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Action fetched successfully",
  "data": {
    "id": "ia-123e4567-e89b-12d3-a456-426614174000",
    "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Вам также может быть интересно:",
    "options": [
      { "id": "opt-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "text": "Как ухаживать за кукурузой?" },
      { "id": "opt-2b3c4d5e-6f7a-8901-bcde-f12345678901", "text": "Что делать с обнаруженными угрозами?" }
    ]
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект интерактивного действия
data.id string Уникальный идентификатор интерактивного действия
data.text string Текстовое описание интерактивного действия
data.chat_id string Уникальный идентификатор чата, в контексте которого предложено действие
data.options array Список доступных опций для выбора
data.options[].id string Уникальный идентификатор опции
data.options[].text string Текстовое описание опции

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Интерактивное действие с указанным ID не найдено {"success": false, "detail": "Action not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

3. Feedbacks

POST /api/v1/feedbacks

Метод: POST

URL: /api/v1/feedbacks

Описание

Отправляет обратную связь пользователя на ответ бота. Если фидбек на данное сообщение уже был отправлен ранее, новый фидбек заменит предыдущий.

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Content-Type: application/json

Пример тела запроса 
{
  "message_id": "msg-2b3c4d5e-6f7a-8901-bcde-f12345678901",
  "is_helpful": false,
  "reason": "incomplete_answer",
  "comment": "Ответ не содержит информации о конкретных датах"
}

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

Параметр Тип Обязательный Описание
message_id string Да Уникальный идентификатор сообщения бота, на которое оставляется фидбек
is_helpful boolean Да Признак полезности ответа бота
reason string Нет Причина низкой оценки: incorrect_data (некорректные данные), incomplete_answer (недостаточно полный ответ), misunderstood (ассистент не понял вопрос), other (другое). Указывается только при is_helpful: false
comment string Нет Опциональный комментарий пользователя с дополнительной информацией

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Feedback submitted successfully",
  "data": {
    "id": "fb-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "message_id": "msg-2b3c4d5e-6f7a-8901-bcde-f12345678901",
    "is_helpful": false,
    "reason": "incomplete_answer",
    "comment": "Ответ не содержит информации о конкретных датах",
    "created_at": "2024-10-03T10:30:00.000Z"
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными фидбека
data.id string Уникальный идентификатор фидбека
data.message_id string Уникальный идентификатор сообщения, на которое оставлен фидбек
data.is_helpful boolean Являлся ли ответ бота полезным
data.reason string Причина низкой оценки: incorrect_data (некорректные данные), incomplete_answer (недостаточно полный ответ), misunderstood (ассистент не понял вопрос), other (другое). Указывается только при is_helpful: false
data.comment string Опциональный комментарий пользователя с дополнительной информацией
data.created_at string Дата и время создания фидбека (ISO 8601 формат)

Ошибки:

Статус Код Описание Тело ответа
Bad Request 400 Некорректные параметры запроса {"success": false, "detail": "Invalid request parameters", "data": null}
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Сообщение с указанным ID не найдено {"success": false, "detail": "Message not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/feedbacks/{feedback_id}

Метод: GET

URL: /api/v1/feedbacks/{feedback_id}

Описание

Возвращает информацию о конкретном фидбеке по его идентификатору.

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
feedback_id string Да Уникальный идентификатор фидбека

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Feedback fetched successfully",
  "data": {
    "id": "fb-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "message_id": "msg-2b3c4d5e-6f7a-8901-bcde-f12345678901",
    "is_helpful": false,
    "reason": "incomplete_answer",
    "comment": "Ответ не содержит информации о конкретных датах",
    "created_at": "2024-10-03T10:30:00.000Z"
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными фидбека
data.id string Уникальный идентификатор фидбека
data.message_id string Уникальный идентификатор сообщения, на которое оставлен фидбек
data.is_helpful boolean Являлся ли ответ бота полезным
data.reason string|null Причина низкой оценки: incorrect_data (некорректные данные), incomplete_answer (недостаточно полный ответ), misunderstood (ассистент не понял вопрос), other (другое). Указывается только при is_helpful: false
data.comment string|null Опциональный комментарий пользователя с дополнительной информацией
data.created_at string Дата и время создания фидбека (ISO 8601 формат)

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Фидбек с указанным ID не найден {"success": false, "detail": "Feedback not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

DELETE /api/v1/feedbacks/{feedback_id}

Метод: DELETE

URL: /api/v1/feedbacks/{feedback_id}

Описание

Удаляет фидбек пользователя по его идентификатору.

Headers

Заголовок Значение Обязательный
X-User-Credentials Base64 encoded JSON Да

Формат X-User-Credentials:

JSON объект с учетными данными пользователя, закодированный в Base64:

Пример JSON 
{
  "user_id": 12345,
  "token": "cropwise-api-token-string",
  "tenant": "example-tenant"
}
Пример заголовка 
X-User-Credentials: eyJ1c2VyX2lkIjogMTIzNDUsICJ0b2tlbiI6ICJjcm9wd2lzZS1hcGktdG9rZW4tc3RyaW5nIiwgInRlbmFudCI6ICJleGFtcGxlLXRlbmFudCJ9

Параметры учетных данных:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
token string Да Токен авторизации для доступа к Cropwise API
tenant string Да Идентификатор tenant пользователя в Cropwise

Request

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
feedback_id string Да Уникальный идентификатор фидбека

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Feedback deleted successfully",
  "data": null
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data null Данные отсутствуют

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Отсутствует заголовок X-User-Credentials {"success": false, "detail": "Unauthorized", "data": null}
Forbidden 403 Некорректные учетные данные либо доступ запрещен {"success": false, "detail": "Forbidden", "data": null}
Not Found 404 Фидбек с указанным ID не найден {"success": false, "detail": "Feedback not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

4. Users

POST /api/v1/users/attach

Метод: POST

URL: /api/v1/users/attach

Описание

Подключает пользователя к системе чат-бота и предоставляет доступ к функционалу чата. Данный эндпоинт является обязательным для использования - без успешного подключения через него пользователь не получит доступ к чату. При успешном подключении автоматически инициируется процесс синхронизации данных пользователя из Cropwise в соответствии с его tenant. Бот будет генерировать ответы на том языке, который указан в профиле пользователя в системе Cropwise.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тело запроса:

Content-Type: application/json

Пример JSON 
{
  "user_id": 12345,
  "tenant": "example-tenant",
  "token": "cropwise-api-token-string"
}

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

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя в системе Cropwise
tenant string Да Идентификатор tenant пользователя в Cropwise
token string Да Токен авторизации для доступа к Cropwise API

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "User attached successfully",
  "data": {
    "user_id": 12345,
    "username": "example_user",
    "language": "ru",
    "region": "RU"
    "company": "ООО Агрофирма",
    "tenant": "example-tenant",
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными пользователя
data.user_id integer Уникальный идентификатор пользователя
data.username string Имя пользователя
data.language string Язык пользователя
data.region string Регион пользователя
data.company string Компания пользователя
data.tenant string tenant пользователя

Ошибки:

Статус Код Описание Тело ответа
Bad Request 400 Пользователь уже подключен к системе {"success": false, "detail": "User already connected", "data": null}
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Пользователь с указанными данными не найден в Cropwise {"success": false, "detail": "Cropwise user not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/users

Метод: GET

URL: /api/v1/users?tenant={tenant}

Описание

Возвращает список подключенных пользователей в системе чат-бота. Позволяет фильтровать пользователей по tenant с помощью query параметров.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тело запроса: Отсутствует

Query параметры:

Параметр Тип Обязательный Описание
tenant string Нет Фильтрация пользователей по tenant

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "Users fetched successfully",
  "data": [
    {
      "user_id": 12345,
      "username": "example_user",
      "language": "ru",
      "region": "RU",
      "company": "ООО Агрофирма",
      "tenant": "example-tenant",
      "is_synchronized": true,
      "attached_at": "2024-10-01T08:00:00.000Z",
      "last_synced_at": "2024-10-01T08:05:30.000Z"
    },
    {
      "user_id": 67890,
      "username": "another_user",
      "language": "en",
      "region": "ES",
      "company": "Agro Company Ltd",
      "tenant": "example-tenant",
      "is_synchronized": false,
      "attached_at": "2024-09-28T14:20:00.000Z",
      "last_synced_at": null
    }
  ]
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data array Массив с данными пользователей
data[].user_id integer Уникальный идентификатор пользователя
data[].username string Имя пользователя
data[].language string Язык пользователя
data[].region string Регион пользователя
data[].company string Компания пользователя
data[].tenant string tenant пользователя
data[].is_synchronized boolean Флаг завершения синхронизации данных пользователя
data[].attached_at string Дата и время подключения пользователя к чат-боту (ISO 8601 формат)
data[].last_synced_at string|null Дата и время последней синхронизации данных пользователя (ISO 8601 формат), или null если синхронизация еще не завершена

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/users/{user_id}

Метод: GET

URL: /api/v1/users/{user_id}

Описание

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

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "User fetched successfully",
  "data": {
    "user_id": 12345,
    "username": "example_user",
    "language": "ru",
    "region": "RU",
    "company": "ООО Агрофирма",
    "tenant": "example-tenant",
    "is_synchronized": true,
    "attached_at": "2024-10-01T08:00:00.000Z",
    "last_synced_at": "2024-10-01T08:05:30.000Z"
  }
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными пользователя
data.user_id integer Уникальный идентификатор пользователя
data.username string Имя пользователя
data.language string Язык пользователя
data.region string Регион пользователя
data.company string Компания пользователя
data.tenant string tenant пользователя
data.is_synchronized boolean Флаг завершения синхронизации данных пользователя
data.attached_at string Дата и время подключения пользователя к чат-боту (ISO 8601 формат)
data.last_synced_at string|null Дата и время последней синхронизации данных пользователя (ISO 8601 формат), или null если синхронизация еще не завершена

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Пользователь с указанным ID не найден {"success": false, "detail": "User not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

DELETE /api/v1/users/{user_id}

Метод: DELETE

URL: /api/v1/users/{user_id}?delete_tenant={delete_tenant}

Описание

Удаляет пользователя из системы чат-бота. Опционально позволяет удалить все данные связанные с tenant пользователя.

По умолчанию данные tenant не удаляются. Параметр delete_tenant следует использовать только в крайних случаях. Данная функциональность доступна только в dev среде и не будет присутствовать в production.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
user_id integer Да Уникальный идентификатор пользователя

Query параметры:

Параметр Тип Обязательный Описание
delete_tenant boolean Нет Удалить все данные связанные с tenant пользователя

Response

Формат ответа: application/json

Успешный ответ:

Статус: 200 OK

Пример ответа 
{
  "success": true,
  "detail": "User deleted successfully",
  "data": null
}

Структура успешного ответа:

Поле Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data null Данные отсутствуют

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Пользователь с указанным ID не найден {"success": false, "detail": "User not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

5. Knowledge Base

POST /api/v1/knowledge-base/documents

Метод: POST

URL: /api/v1/knowledge-base/documents

Описание

Загружает новый документ в базу знаний. Поддерживаются форматы .txt (сплошной текст) и .xlsx (формат вопрос-ответ). После успешной загрузки документ получает статус is_outdated = false и становится доступен для использования ботом при ответах в режиме работы с базой знаний.

При повторной загрузке файла с теми же метаданными система создаст новый документ с уникальным document_id.

Валидация: Если указан region = all, то language должен быть только en. Документы с region = all доступны во всех регионах и на всех языках.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тип запроса: multipart/form-data

Form Data:

Параметр Тип Обязательный Описание
file file Да Файл документа в формате .txt или .xlsx. Максимальный размер: 100 МБ
language string Да Язык документа: ru, en, es, ua
region string Да Регион документа: RU, ES, UA, или all (только для language = en). Список регионов будет пополняться
tags array[string] Да Список тегов (ключевые слова на английском языке), либо [] при отсутствии тегов
description string Да Краткое описание содержания файла на языке оригинала
folder string Да Папка, куда добавляется файл (без вложенности)
Пример запроса 
POST /api/v1/knowledge-base/documents
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="FAQ_fertilizers_2024.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

(binary file data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="language"

ru
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="region"

RU
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="tags"

["fertilizers", "nutrients", "soil"]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="description"

Часто задаваемые вопросы по применению удобрений
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="folder"

agriculture
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response

Тип ответа: application/json

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

Параметр Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными загруженного документа
data.id string Уникальный идентификатор документа (UUID формат)
data.name string Название документа
data.language string Язык документа
data.region string Регион документа
data.tags array[string] Список тегов
data.description string Описание содержания документа
data.folder string Папка документа
data.created_at string Дата загрузки документа (ISO 8601 формат)
data.is_outdated boolean Флаг устаревшего документа
Пример успешного ответа 
{
  "success": true,
  "detail": "Document uploaded successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "FAQ по удобрениям 2024.xlsx",
    "language": "ru",
    "region": "RU",
    "tags": ["fertilizers", "nutrients", "soil"],
    "description": "Часто задаваемые вопросы по применению удобрений",
    "folder": "agriculture",
    "created_at": "2024-10-02T14:30:00Z",
    "is_outdated": false
  }
}

Ошибки:

Статус Код Описание Тело ответа
Bad Request 400 Некорректные параметры (например, region = all с language != en) или отсутствуют обязательные поля {"success": false, "detail": "Invalid parameters", "data": null}
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Payload Too Large 413 Размер файла превышает 100 МБ {"success": false, "detail": "File size exceeds 100 MB limit", "data": null}
Unsupported Media Type 415 Неподдерживаемый формат файла (разрешены только .txt и .xlsx) {"success": false, "detail": "Unsupported file format", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/knowledge-base/documents

Метод: GET

URL: /api/v1/knowledge-base/documents?folder={folder}&language={language}&region={region}&tags={tags}

Описание

Возвращает список документов из базы знаний с основными метаданными и возможностью фильтрации по папке, языку, региону и тегам.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тип запроса: GET

Тело запроса: Отсутствует

Query параметры:

Параметр Тип Обязательный Описание
folder string Нет Фильтр по папке
language string Нет Фильтр по языку: ru, en, es, ua
region string Нет Фильтр по региону: RU, ES, UA, all
tags string Нет Фильтр по тегам (можно указать несколько через запятую)

Response

Тип ответа: application/json

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

Параметр Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data array Массив документов базы знаний
data[].id string Уникальный идентификатор документа (UUID формат)
data[].name string Название документа
data[].language string Язык документа
data[].region string Регион документа
data[].tags array[string] Список тегов
data[].description string Описание содержания документа
data[].folder string Папка документа
data[].created_at string Дата загрузки документа (ISO 8601 формат)
data[].is_outdated boolean Флаг устаревшего документа
Пример успешного ответа 
{
  "success": true,
  "detail": "Documents fetched successfully",
  "data": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "FAQ по удобрениям 2024.xlsx",
        "language": "ru",
        "region": "RU",
        "tags": ["fertilizers", "nutrients", "soil"],
        "description": "Часто задаваемые вопросы по применению удобрений",
        "folder": "agriculture",
        "created_at": "2024-10-02T14:30:00Z",
        "is_outdated": false
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Plant Protection Guide.txt",
        "language": "en",
        "region": "all",
        "tags": ["pesticides", "diseases", "protection"],
        "description": "Comprehensive guide on plant protection methods",
        "folder": "guides",
        "created_at": "2024-09-25T09:15:00Z",
        "is_outdated": false
      }
    ]
}

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/knowledge-base/documents/{document_id}

Метод: GET

URL: /api/v1/knowledge-base/documents/{document_id}

Описание

Возвращает полные метаданные конкретного документа по его идентификатору.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тип запроса: GET

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
document_id string Да Уникальный идентификатор документа (UUID формат)

Response

Тип ответа: application/json

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

Параметр Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с данными документа
data.id string Уникальный идентификатор документа (UUID формат)
data.name string Название документа
data.language string Язык документа
data.region string Регион документа
data.tags array[string] Список тегов
data.description string Описание содержания документа
data.folder string Папка документа
data.created_at string Дата загрузки документа (ISO 8601 формат)
data.is_outdated boolean Флаг устаревшего документа
Пример успешного ответа 
{
  "success": true,
  "detail": "Document fetched successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "FAQ по удобрениям 2024.xlsx",
    "language": "ru",
    "region": "RU",
    "tags": ["fertilizers", "nutrients", "soil"],
    "description": "Часто задаваемые вопросы по применению удобрений",
    "folder": "agriculture",
    "created_at": "2024-10-02T14:30:00Z",
    "is_outdated": false
  }
}

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Документ с указанным ID не найден {"success": false, "detail": "Document not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

GET /api/v1/knowledge-base/documents/{document_id}/download

Метод: GET

URL: /api/v1/knowledge-base/documents/{document_id}/download

Описание

Скачивает файл документа из базы знаний.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тип запроса: GET

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
document_id string Да Уникальный идентификатор документа (UUID формат)

Response

Тип ответа: application/octet-stream

Успешный ответ:

Статус: 200 OK

Содержимое: Бинарные данные файла документа

Ошибки:

При возникновении ошибки возвращается JSON-ответ:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Документ с указанным ID не найден {"success": false, "detail": "Document not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

PATCH /api/v1/knowledge-base/documents/{document_id}

Метод: PATCH

URL: /api/v1/knowledge-base/documents/{document_id}?is_outdated={is_outdated}

Описание

Обновляет статус документа в базе знаний, помечая его как устаревший или актуальный.

Архивация (is_outdated = true): Документ исключается из активной базы знаний и поиска, но остаётся в системе. Архивированные документы не участвуют в выдаче ответов ботом.

Возврат из архива (is_outdated = false): Документ снова становится доступным для поиска и использования ботом при ответах.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тип запроса: PATCH

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
document_id string Да Уникальный идентификатор документа (UUID формат)

Query параметры:

Параметр Тип Обязательный Описание
is_outdated boolean Да Флаг, указывающий, является ли документ устаревшим

Response

Тип ответа: application/json

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

Параметр Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data object Объект с текущим состоянием документа
data.id string Уникальный идентификатор документа (UUID формат)
data.name string Название документа
data.language string Язык документа
data.region string Регион документа
data.tags array[string] Список тегов
data.description string Описание содержания документа
data.folder string Папка документа
data.created_at string Дата загрузки документа (ISO 8601 формат)
data.is_outdated boolean Флаг устаревшего документа
Пример успешного ответа 
{
  "success": true,
  "detail": "Document updated successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "FAQ по удобрениям 2024.xlsx",
    "language": "ru",
    "region": "RU",
    "tags": ["fertilizers", "nutrients", "soil"],
    "description": "Часто задаваемые вопросы по применению удобрений",
    "folder": "agriculture",
    "created_at": "2024-10-02T14:30:00Z",
    "is_outdated": true
  }
}

Ошибки:

Статус Код Описание Тело ответа
Bad Request 400 Некорректное значение параметра is_outdated {"success": false, "detail": "Invalid is_outdated value", "data": null}
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Документ с указанным ID не найден {"success": false, "detail": "Document not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}

DELETE /api/v1/knowledge-base/documents/{document_id}

Метод: DELETE

URL: /api/v1/knowledge-base/documents/{document_id}

Описание

Удаляет указанный документ из базы знаний.

Headers

Заголовок Значение Обязательный
Authorization Bearer <token> Да

Request

Тип запроса: DELETE

Тело запроса: Отсутствует

Path параметры:

Параметр Тип Обязательный Описание
document_id string Да Уникальный идентификатор документа (UUID формат)

Response

Тип ответа: application/json

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

Параметр Тип Описание
success boolean Статус выполнения запроса
detail string Дополнительная информация или сообщение об ошибке
data null Данные отсутствуют
Пример успешного ответа 
{
  "success": true,
  "detail": "Document deleted successfully",
  "data": null
}

Ошибки:

Статус Код Описание Тело ответа
Unauthorized 401 Токен авторизации не предоставлен {"success": false, "detail": "Token is not provided", "data": null}
Forbidden 403 Неверный токен авторизации {"success": false, "detail": "Invalid token", "data": null}
Not Found 404 Документ с указанным ID не найден {"success": false, "detail": "Document not found", "data": null}
Internal Server Error 500 Внутренняя ошибка сервера {"success": false, "detail": "Internal server error", "data": null}