Перейти к основному содержимому

Методы работы с файлами

На этой странице представлены основные методы API для работы с файлами в системе Brainysoft: загрузка, получение, редактирование, удаление, массовые операции, а также привязка файлов к различным сущностям (клиентам, контрактам, лидам, заявкам) и публичная загрузка файлов.

Методы API работы с файлами​

МетодURLОписание
POSTapi/filesЗагрузка файла
GET|HEADapi/filesСписок всех файлов
GET|HEADapi/files/{file}Получить информацию о файле по ID
PUT|PATCHapi/files/{file}Редактирование данных файла
DELETEapi/files/{file}Удалить файл
GET|HEADapi/files/{file}/linksПолучить ссылку на файл
GET|HEADapi/files/{file}/link-verified-copyПолучить проверенную ссылку на файл
POSTapi/files/batch/linksПолучение ссылок на группу файлов (по ID)
POSTapi/files/batch/selectПолучение информации по группе файлов
POSTapi/files/entities/clients/{id}Загрузить файл клиента
GET|HEADapi/files/entities/clients/{id}Получить файлы клиента
POSTapi/files/entities/contracts/{id}Загрузить файлы контракта
GET|HEADapi/files/entities/contracts/{id}Получить файлы контракта
POSTapi/files/entities/leads/{id}Загрузить файлы лида
GET|HEADapi/files/entities/leads/{id}Получить файлы лида
POSTapi/files/entities/loan-apps/{id}Загрузить файлы заявки
GET|HEADapi/files/entities/loan-apps/{id}Получить файлы заявки
GET|HEADapi/files/public-uploaderПубличная загрузка файла

Загрузка файла​

POST /api/files

Описание

Метод позволяет загрузить новый файл в систему. Файл передаётся в теле запроса в формате multipart/form-data.

Параметры запроса (query string)

ПараметрТипОписание
clientintegerИдентификатор клиента, к которому относится файл
tagsintegerИдентификатор тега, связанных с файлом

Тело запроса (form-data)

ПолеТипОписание
fileфайлЗагружаемый файл (например, .pdf, .jpg, .png, .gif)

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

POST /api/files?client=3168&tags=5

Content-Type: multipart/form-data

file: image.png

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750694475000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "id": 235                      // Уникальный идентификатор файла
    }
}

Список всех файлов​

GET /api/files

Описание

Метод возвращает список файлов с подробной информацией о каждом файле.

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

GET /api/files

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750675264000,         // Время ответа (UNIX timestamp, ms)
    "data": [
        {
            "id": 234,                 // Уникальный идентификатор файла
            "name": "images.png",      // Имя файла
            "extension": "png",        // Расширение файла
            "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/234/2e276a16b5219e4e06a5c8070d9a1a0784737062146ad1931633c17d0d7cf736fde4791182d5bd6b65e249c512a5f87e4887f3e935c40c59a7a79da42ed5c224",  // URL предпросмотра/миниатюры файла
            "userId": 1357,            // ID пользователя, загрузившего файл
            "connections": {
                "lead": null,          // ID лида
                "client": 3168,        // ID клиента
                "loanapp": null,       // ID заявки на займ
                "contract": null,      // ID контракта
                "collateral": null,    // ID залога
                "sharecontract": null, // ID договора долевого участия
                "depositcontract": null, // ID депозитного контракта
                "fundtransaction": null, // ID фондовой транзакции
                "comment": null,       // ID комментария
                "collateralline": null, // ID строки залога
                "deal": null,          // ID сделки
                "extra": []            // Дополнительные связи
            },
            "createdAt": "2025-06-23T07:36:41+0000", // Дата и время загрузки файла (ISO 8601)
            "tags": [                  // Список идентификаторов тегов
                "2"
            ],
            "size": 3789,              // Размер файла в байтах
            "sizeForHumans": "4 Kb",   // Читаемый размер файла
            "ocr": null                // Результат OCR-распознавания
        }
    ]
}

Получить информацию о файле по ID​

GET /api/files/{file}

Описание

Метод позволяет получить подробную информацию о конкретном файле по его идентификатору.

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

{file} (integer, обязательный) — уникальный идентификатор файла.

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

GET /api/files/233

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750186181000,         // Время ответа (UNIX timestamp, ms)
    "data": [
        {
            "id": 233,                 // Уникальный идентификатор файла
            "name": "images.png",      // Имя файла
            "extension": "png",        // Расширение файла
            "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...",  // URL предпросмотра/миниатюры файла
            "userId": 1357,            // ID пользователя, загрузившего файл
            "connections": {
                "lead": 7315,          // ID лида
                "client": 3166,        // ID клиента
                "loanapp": 6755,       // ID заявки на займ
                "contract": null,      // ID контракта
                "collateral": null,    // ID залога
                "sharecontract": null, // ID договора долевого участия
                "depositcontract": null, // ID депозитного контракта
                "fundtransaction": null, // ID фондовой транзакции
                "comment": null,       // ID комментария
                "collateralline": null, // ID строки залога
                "deal": null,          // ID сделки
                "extra": []            // Дополнительные связи
            },
            "createdAt": "2025-06-19T11:52:22+0000", // Дата и время загрузки файла (ISO 8601)
            "tags": ["9"],             // Список идентификаторов тегов
            "size": 3789,              // Размер файла в байтах
            "sizeForHumans": "4 Kb",   // Читаемый размер файла
            "ocr": null                // Результат OCR-распознавания
        }
    ]
}

Редактирование данных файла​

PUT/PATCH /api/files/{file}

Описание

Метод позволяет обновить информацию о файле (например, теги, имя, связи с объектами). Для редактирования файла необходимо сначала запросить его с помощью метода "Получить информацию о файле по ID", а затем отправить PATCH/PUT с нужными изменениями.

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

{file} (integer, обязательный) — уникальный идентификатор файла.

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

PUT /api/files/233
Content-Type: application/json
{
    "id": 233,                         // Уникальный идентификатор файла
    "name": "images.png",              // Имя файла
    "extension": "png",                // Расширение файла
    "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...",  // URL предпросмотра/миниатюры файла
    "userId": 1357,                    // ID пользователя, загрузившего файл
    "connections": {
        "lead": 7315,                  // ID лида
        "client": 3166,                // ID клиента
        "loanapp": 6755,               // ID заявки на займ
        "contract": null,              // ID контракта
        "collateral": null,            // ID залога
        "sharecontract": null,         // ID договора долевого участия
        "depositcontract": null,       // ID депозитного контракта
        "fundtransaction": null,       // ID фондовой транзакции
        "comment": null,               // ID комментария
        "collateralline": null,        // ID строки залога
        "deal": null,                  // ID сделки
        "extra": []                    // Дополнительные связи
    },
    "createdAt": "2025-06-19T11:52:22+0000", // Дата и время загрузки файла (ISO 8601)
    "tags": ["9", "12"],               // Список идентификаторов тегов
    "size": 3789,                      // Размер файла в байтах
    "sizeForHumans": "4 Kb",           // Читаемый размер файла
    "ocr": null                        // Результат OCR-распознавания
}

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750186181000,         // Время ответа (UNIX timestamp, ms)
    "data": [
        {
            "id": 233,                 // Уникальный идентификатор файла
            "name": "images.png",      // Имя файла
            "extension": "png",        // Расширение файла
            "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...",  // URL предпросмотра/миниатюры файла
            "userId": 1357,            // ID пользователя, загрузившего файл
            "connections": {
                "lead": 7315,          // ID лида
                "client": 3166,        // ID клиента
                "loanapp": 6755,       // ID заявки на займ
                "contract": null,      // ID контракта
                "collateral": null,    // ID залога
                "sharecontract": null, // ID договора долевого участия
                "depositcontract": null, // ID депозитного контракта
                "fundtransaction": null, // ID фондовой транзакции
                "comment": null,       // ID комментария
                "collateralline": null, // ID строки залога
                "deal": null,          // ID сделки
                "extra": []            // Дополнительные связи
            },
            "createdAt": "2025-06-19T11:52:22+0000", // Дата и время загрузки файла (ISO 8601)
            "tags": ["9", "12"],       // Список идентификаторов тегов
            "size": 3789,              // Размер файла в байтах
            "sizeForHumans": "4 Kb",   // Читаемый размер файла
            "ocr": null                // Результат OCR-распознавания
        }
    ]
}

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

PATCH /api/files/233
Content-Type: application/json
{
  "tags": ["9", "12"]  
}

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750186181000,         // Время ответа (UNIX timestamp, ms)
    "data": [
        {
            "id": 233,                 // Уникальный идентификатор файла
            "name": "images.png",      // Имя файла
            "extension": "png",        // Расширение файла
            "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...",  // URL предпросмотра/миниатюры файла
            "userId": 1357,            // ID пользователя, загрузившего файл
            "connections": {
                "lead": 7315,          // ID лида
                "client": 3166,        // ID клиента
                "loanapp": 6755,       // ID заявки на займ
                "contract": null,      // ID контракта
                "collateral": null,    // ID залога
                "sharecontract": null, // ID договора долевого участия
                "depositcontract": null, // ID депозитного контракта
                "fundtransaction": null, // ID фондовой транзакции
                "comment": null,       // ID комментария
                "collateralline": null, // ID строки залога
                "deal": null,          // ID сделки
                "extra": []            // Дополнительные связи
            },
            "createdAt": "2025-06-19T11:52:22+0000", // Дата и время загрузки файла (ISO 8601)
            "tags": ["9", "12"],       // Список идентификаторов тегов
            "size": 3789,              // Размер файла в байтах
            "sizeForHumans": "4 Kb",   // Читаемый размер файла
            "ocr": null                // Результат OCR-распознавания
        }
    ]
}

Удалить файл​

DELETE /api/files/{file}

Описание

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

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

{file} (integer, обязательный) — уникальный идентификатор файла.

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

DELETE /api/files/233

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750348133000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "status": "deleted"            // Статус удаления файла
    }
}

Получить ссылку на файл / проверенную ссылку на файл​

GET|HEAD /api/files/{file}/links

GET|HEAD /api/files/{file}/link-verified-copy

Описание

Методы позволяют получить ссылку для скачивания файла по его идентификатору.

  • /links — возвращает обычную ссылку на скачивание файла.
  • /link-verified-copy — возвращает ссылку на скачивание проверенной (верифицированной) копии файла, если такая копия доступна.

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

{file} (integer, обязательный) — уникальный идентификатор файла.

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

GET /api/files/234/links

или

GET /api/files/234/link-verified-copy

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750690491000,        // Время ответа (UNIX timestamp, ms)
    "data": {
        "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?ac-jar=..." // Ссылка для скачивания файла или проверенной копии
    }
}

Получение ссылок на группу файлов (по ID)​

POST /api/files/batch/links

Описание

Метод позволяет получить ссылки для скачивания сразу на несколько файлов по их идентификаторам. В ответе возвращается объект, где ключ — ID файла, а значение — объект с ссылкой для скачивания.

Тело запроса (application/json)

ПолеТипОписание
idsarray[int]Массив идентификаторов файлов

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

{
  "ids": [234, 236, 237] // Массив ID файлов
}

Пример успешного ответа

{
  "status": "ok",                    // Статус выполнения запроса
  "timestamp": 1751285233000,        // Время ответа (UNIX timestamp, ms)
  "data": {
    "234": {
      "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?..." // Ссылка для скачивания файла с ID 234
    },
    "236": {
      "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?..." // Ссылка для скачивания файла с ID 236
    },
    "237": {
      "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?..." // Ссылка для скачивания файла с ID 237
    }
  }
}

Получение информации по группе файлов​

POST /api/files/batch/select

Описание

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

Тело запроса (application/json)

ПолеТипОписание
idsarray[int]Массив идентификаторов файлов

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

{
  "ids": [234, 236, 237] // Массив ID файлов
}

Пример успешного ответа

{
  "status": "ok",                    // Статус выполнения запроса
  "timestamp": 1751285601000,        // Время ответа (UNIX timestamp, ms)
  "data": [
    {
      "id": 234,                     // Уникальный идентификатор файла
      "name": "images.png",          // Имя файла
      "extension": "png",            // Расширение файла
      "thumbUrl": "https://...",     // URL предпросмотра/миниатюры файла
      "userId": 1357,                // ID пользователя, загрузившего файл
      "connections": {
        "lead": null,                // ID лида
        "client": 3168,              // ID клиента
        "loanapp": null,             // ID заявки на займ
        "contract": null,            // ID контракта
        "collateral": null,          // ID залога
        "sharecontract": null,       // ID договора долевого участия
        "depositcontract": null,     // ID депозитного контракта
        "fundtransaction": null,     // ID фондовой транзакции
        "comment": null,             // ID комментария
        "collateralline": null,      // ID строки залога
        "deal": null,                // ID сделки
        "extra": []                  // Дополнительные связи
      },
      "createdAt": "2025-06-23T07:36:41+0000", // Дата и время загрузки файла (ISO 8601)
      "tags": ["2"],                // Список идентификаторов тегов
      "size": 3789,                 // Размер файла в байтах
      "sizeForHumans": "4 Kb",      // Читаемый размер файла
      "ocr": null                   // Результат OCR-распознавания
    }
    // ... другие файлы
  ]
}

Загрузить файл клиента/контракта/лида/заявки​

POST /api/files/entities/clients/{id} - Загрузить файл клиента

POST /api/files/entities/contracts/{id} - Загрузить файл контракта

POST /api/files/entities/leads/{id} - Загрузить файл лида

POST /api/files/entities/loan-apps/{id} - Загрузить файл заявки

Описание

Данные методы позволяют загрузить файл и сразу привязать его к определённой сущности: клиенту, контракту, лиду или заявке. Файл передаётся в теле запроса в формате multipart/form-data.

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

{id} (integer, обязательный) — уникальный идентификатор соответствующей сущности (клиента, контракта, лида или заявки).

Параметры запроса (query string)

ПараметрТипОписание
tagsintegerИдентификатор тега, связанных с файлом

Тело запроса (form-data)

ПолеТипОписание
fileфайлЗагружаемый файл (например, .pdf, .jpg, .png, .gif)

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

POST /api/files/entities/clients/3168?tags=8

Content-Type: multipart/form-data

file: image.png

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750696263000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "id": 237                      // Уникальный идентификатор файла
    }
}

Получить файлы клиента/контракта/лида/заявки​

GET /api/files/entities/clients/{id} - Получить файл клиента

GET /api/files/entities/contracts/{id} - Получить файл контракта

GET /api/files/entities/leads/{id} - Получить файл лида

GET /api/files/entities/loan-apps/{id} - Получить файл заявки

Описание

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

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

{id} (integer, обязательный) — уникальный идентификатор соответствующей сущности (клиента, контракта, лида или заявки).

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

GET /api/files/entities/clients/3168

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750697332000,         // Время ответа (UNIX timestamp, ms)
    "data": [
        {
            "id": 223,                 // Уникальный идентификатор файла
            "name": "default_logo.png", // Имя файла
            "extension": "png",        // Расширение файла
            "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/223/7a8a2e2296fadf0ea97c701f6edd2d5278ebf278ec2f87520e77687a89f2d59a003a94dd6f84094a682a5f2c3a44c8fd64bbb8f2b2b81098e654687f72f20e06",  // URL предпросмотра/миниатюры файла
            "userId": 1165,            // ID пользователя, загрузившего файл
            "connections": {
                "lead": null,          // ID лида
                "client": 3168,        // ID клиента
                "loanapp": null,       // ID заявки на займ
                "contract": null,      // ID контракта
                "collateral": null,    // ID залога
                "sharecontract": null, // ID договора долевого участия
                "depositcontract": null, // ID депозитного контракта
                "fundtransaction": null, // ID фондовой транзакции
                "comment": null,       // ID комментария
                "collateralline": null, // ID строки залога
                "deal": null,          // ID сделки
                "extra": []            // Дополнительные связи
            },
            "createdAt": "2025-06-16T14:40:54+0000", // Дата и время загрузки файла (ISO 8601)
            "tags": [                  // Список идентификаторов тегов
                "14"
            ],
            "size": 6005,              // Размер файла в байтах
            "sizeForHumans": "6 Kb",   // Читаемый размер файла
            "ocr": null                // Результат OCR-распознавания
        },
        {
            "id": 234,                 // Уникальный идентификатор файла
            "name": "images.png",      // Имя файла
            "extension": "png",        // Расширение файла
            "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/234/2e276a16b5219e4e06a5c8070d9a1a0784737062146ad1931633c17d0d7cf736fde4791182d5bd6b65e249c512a5f87e4887f3e935c40c59a7a79da42ed5c224",  // URL предпросмотра/миниатюры файла
            "userId": 1357,            // ID пользователя, загрузившего файл
            "connections": {
                "lead": null,          // ID лида
                "client": 3168,        // ID клиента
                "loanapp": null,       // ID заявки на займ
                "contract": null,      // ID контракта
                "collateral": null,    // ID залога
                "sharecontract": null, // ID договора долевого участия
                "depositcontract": null, // ID депозитного контракта
                "fundtransaction": null, // ID фондовой транзакции
                "comment": null,       // ID комментария
                "collateralline": null, // ID строки залога
                "deal": null,          // ID сделки
                "extra": []            // Дополнительные связи
            }
        }
    ]
}

Публичная загрузка файла​

GET|HEAD /api/files/public-uploader

Описание

Метод возвращает уникальную публичную ссылку (URL), по которой можно загрузить файл без авторизации. Эта ссылка может быть использована для предоставления возможности загрузки файлов внешним пользователям, интеграциям или сторонним сервисам.

к сведению

Данный метод используется для пользовательских загрузок не используя bsauth на стороне клиента

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

GET /api/files/public-uploader

Пример успешного ответа

{
    "status": "ok",                    // Статус выполнения запроса
    "timestamp": 1750757802000,         // Время ответа (UNIX timestamp, ms)
    "data": {
        "url": "https://fs-stage-svc-stage.brainysoft.ru/web/files/public-uploader?ac-jar=tcBASegvBz5QslUbuPx3MbxfovoWmVfYHsBMMXcO7XrUzTowK19PN1RtcyWyKcbcTkCDc6Ui18GWC1XPg8SNPv9nYSXFD0Ekp3SlNcR9ZyptHzeL975HFfTGTOEhtqOlQWIwmdullkvTOr06xJTIRNQWCjto9DS2TFe5bB46gIbGWUzeqasJz8Za6NoTHF7cmxWLUQUsujyYSnmmC6RuLQWKtI0SWucn7mignXyk3HoYqkxxdAgleNdedmzAWCXkCwZl4Fvj7jGmI4v6By4c7ZXrHib3XyFnyJXUtcBHE8ik5TnaRXVwrsdzViiYZ3VbPMd4DnQEbtdPSe4eIp6RvNZMgbjKCkyeR1qJ8ld0gQkg1oKYIXLUSfH672K8Nhb7jFEP7nqg8uCFMQRl0v0hp8o25DrAliTURhuN0ZcEydFDTpUpg6sKFqrzwTzD8qVXe24hvpdh9R3DtSjCXozmDTFIyvYo2RrXHER6pgGrsMYBmEenOWvcLJUH9279a1z6"  // Публичная ссылка для загрузки файла
    }
}

Описание полей​

ПолеТипОписание
statusstringСтатус выполнения запроса
timestampintegerВремя ответа (UNIX timestamp, ms)
dataobject/arrayОсновные данные ответа
idintegerУникальный идентификатор файла
namestringИмя файла
extensionstringРасширение файла
thumbUrlstringURL предпросмотра/миниатюры файла
userIdintegerИдентификатор пользователя
connectionsobjectСвязи с объектами системы
leadinteger|nullID лида
clientinteger|nullID клиента
loanappinteger|nullID заявки на займ
contractinteger|nullID контракта
collateralinteger|nullID залога
sharecontractinteger|nullID договора долевого участия
depositcontractinteger|nullID депозитного контракта
fundtransactioninteger|nullID фондовой транзакции
commentinteger|nullID комментария
collaterallineinteger|nullID строки залога
dealinteger|nullID сделки
extraarrayДополнительные связи
createdAtstringДата и время загрузки файла (ISO 8601)
tagsarrayСписок идентификаторов тегов
sizeintegerРазмер файла в байтах
sizeForHumansstringЧитаемый размер (например, 4 Kb)
ocrstring|nullРезультат OCR-распознавания
downloadstringСсылка для скачивания файла
urlstringПубличная ссылка для загрузки файла