Документация API

Техническая документация для интеграции нашего сервиса конвертации в ваши приложения

Общее описание API

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

Примечание: Это базовая документация. Более подробную информацию вы можете получить ознакомившись с Swagger.

Важно:
  • Общий размер файлов в запросе на конвертацию не должен быть более 100 МБ
  • Количество файлов в запросе на конвертацию не более 10
  • CORS разрешен. Можно отправлять запроса через JS в браузере.
  • Все доступные варианты конвертации указаны ниже

Базовый URL

https://api.filebee.ru/

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

Используйте ваш API-ключ в заголовке запроса:

Authorization: Bearer YOUR_API_KEY

Endpoints

POST /convert/{source}/to/{target}

Конвертация файла или нескольких файлов

Параметры запроса:
  • source* - (path) Исходный формат (обязательный).
  • target* - (path) Целевой формат (обязательный).
  • files* - файл или несколько файлов для конвертации (обязательный).
  • webhook_url - URL на который будет отправлено оповещение (POST-запрос) о результате (успешной или неуспешной) конвертации файлов. Параметр необязательный. Содержимое webhook-запроса, который отправляет наш сервис на ваш URL, зависит от статуса задачи. Варианты содержимого запроса указаны здесь . В ответ на вебхук Ваш сервер должен ответить статусом 200. Если будет другой статус, вебхук будет отправляться еще 2 раза с таймингами 10 и 30 секунд.
  • is_async - флаг означает, что процесс конвертации асинхронный (отправляется запрос и в ответе сразу отдается ответ с двумя URL: "status_url" - ссылка для будущего скачивания файла(-ов) и "download_url" - ссылка для проверка статуса). Также можно указать webhook_url, на которы поступит такая же информация о статусе задачи конвертации.
  • delete_files - флаг для удаления документов из внутреннего хранилища сразу после отправки ответа. Однако, если запрос асинхронный (is_async = 1) или время ожидание запроса истекло (408 статус), файлы не будут удалены сразу, т.к для клиента остается возможность получить файлы позднее по URL.
  • options - JSON объект в виде строки с дополнительными параметрами конвертации, если для данного варианта конвертации они имеются. Описание доступных параметров указано ниже . Как добавлять параметры в запрос описано здесь
Пример запроса cURL:
curl --location 'https://api.filebee.ru/convert/docx/to/pdf' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'files=@"/you-path/file_1.docx"' \
--form 'files=@"/you-path/file_2.docx"'
Ответы:
200 (OK)

В случае, если конвертация прошла успешно, в ответе вернется файл со статусом 200 (OK). Тип возвращаемого файла зависит от деталей запроса:

  • Если в запросе отправлено несколько файлов - вернется ZIP-файл со всеми конвертированными файлами. Имена файлов в архиве будут такие же как у оригинальных файлов в запросе, но с актуальными расширениями.
  • Если в запросе отправлен 1 файл - вернется единственный файл, но с актуальными расширением
408 (Request Timeout)

В случае, если конвертация затянулась более чем на 1 минуту, в ответе вернется статус 408 (Request Timeout) с JSON ответом, содержащий поля: 

                            
    {
        "status": "processing",
        "task_id": "86652f34-1d8b-49c9-9b40-72826ac59fe1",
        "status_url" : "https://api.filebee.ru/convert/status/Kn3Ms/86652f34-1d8b-49c9-9b40-72826ac59fe1",
        "download_url" : "https://api.filebee.ru/files/Kn3Ms/86652f34-1d8b-49c9-9b40-72826ac59fe1"
    }
  • status - Статус задачи (pending, processing, failed, completed)
  • task_id - UUID задачи
  • status_url - URL для проверки статуса задачи (описание деталей этот эндпоинта описано ниже)
  • download_url - Предварительный URL для скачивания файла (только если задача конвертации будет выполнена успешно!)

POST /convert/base64/{source}/to/{target}

Конвертация файла или нескольких файлов (в формате Base64)

Параметры запроса:
  • source* - (path) Исходный формат (обязательный).
  • target* - (path) Целевой формат (обязательный).
  • files* - массив содержимого файла (-ов) в виде Base64-строк (обязательный).
  • webhook_url - URL на который будет отправлено оповещение (POST-запрос) о результате (успешной или неуспешной) конвертации файлов. Параметр необязательный. Содержимое webhook-запроса, который отправляет наш сервис на ваш URL, зависит от статуса задачи. Варианты содержимого запроса указаны здесь . В ответ на вебхук Ваш сервер должен ответить статусом 200. Если будет другой статус, вебхук будет отправляться еще 2 раза с таймингами 1 и 5 минут.
  • is_async - флаг означает, что процесс конвертации асинхронный (отправляется запрос и в ответе сразу отдается ответ с двумя URL: "status_url" - ссылка для будущего скачивания файла(-ов) и "download_url" - ссылка для проверка статуса). Также можно указать webhook_url, на которы поступит такая же информация о статусе задачи конвертации.
  • delete_files - флаг для удаления документов из внутреннего хранилища сразу после отправки ответа. Однако, если запрос асинхронный (is_async = 1) или время ожидание запроса истекло (408 статус), файлы не будут удалены сразу, т.к для клиента остается возможность получить файлы позднее по URL.
  • options - дополнительные параметрами конвертации, если для данного варианта конвертации они имеются. Описание доступных параметров указано ниже . Как добавлять параметры в запрос описано здесь
Пример запроса cURL:
curl --location 'http://localhost/convert/base64/docx/to/pdf' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{ "files": [ { "file_content": "base64 content file..." "filename": "example_1.docx", "options": {"dpi": "300"} }, { "file_content": "base64 content file..." "filename": "example_2.docx" } ], "is_async": false, "delete_files": false, "webhook_url": "http://my-url/webhook", "options": { "dpi": "300" } }'
Ответы:
200 (OK)

В случае, если конвертация прошла успешно, в ответе вернется JSON со статусом 200 (OK) :

                            
{
    "files": [
        {
            "file_content": "base64 content file..."
            "filename": "example_1.pdf"
        },
        {
            "file_content": "base64 content file..."
            "filename": "example_2.pdf"
        }
    ],
    "status_url": "https://api.filebee.ru/convert/status/1/9679bd44-3487-407d-8243-274021ab4090",
    "download_url": "https://api.filebee.ru/files/1/9679bd44-3487-407d-8243-274021ab4090"
}
408 (Request Timeout)

В случае, если конвертация затянулась более чем на 1 минуту, в ответе вернется статус 408 (Request Timeout) с JSON ответом, содержащий поля: 

                            
    {
        "status": "processing",
        "task_id": "86652f34-1d8b-49c9-9b40-72826ac59fe1",
        "status_url" : "https://api.filebee.ru/convert/status/Kn3Ms/86652f34-1d8b-49c9-9b40-72826ac59fe1",
        "download_url" : "https://api.filebee.ru/files/Kn3Ms/86652f34-1d8b-49c9-9b40-72826ac59fe1"
    }
  • status - Статус задачи (pending, processing, failed, completed)
  • task_id - UUID задачи
  • status_url - URL для проверки статуса задачи (описание деталей этот эндпоинта описано ниже)
  • download_url - Предварительный URL для скачивания файла (только если задача конвертации будет выполнена успешно!)

GET /convert/status/{instance}/{task_uuid}

Проверка статуса задачи конвертации

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

У данного эндпоинта нет обязательных параметров, т.к готовый URL приходит в ответе на запросы [POST] /convert/{source}/to/{target} и /convert/base64/{source}/to/{target}:

  • В случае ответа со статусом 408 (Request Timeout) данный URL будет в теле ответа в поле "status_url"
  • В случае ответа со статусом 200 (OK) в заголовке ответа (header) X-Url-Status
Пример запроса cURL:
curl --location 'https://api.filebee.ru/convert/status/11/86652f34-1d8b-49c9-9b40-72826ac59fe1' \
--header 'Authorization: Bearer YOUR_API_KEY'
Ответы:
200 (OK)

В случае если срок хранения результатов конвертации не истек (1 час) будет ответ со статусом 200 (OK) и содержимым: 

    
                            
    { 
        "task_id": "19561fd7-e055-4954-a5ee-f7247f616304",
        "status": "completed",
        "error": null,
        "files": [
            { 
                "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304/0",
                "original_name": "Example_document_1.pdf"
            },
            {
                "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304/1",
                "original_name": "Example_document_2.pdf"
            }
        ],
        "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304"
    }
  • status - Статус задачи (pending, processing, failed, completed)
  • task_id - UUID задачи.
  • error - Описание ошибки в случае если статус failed.
  • files - Массив с оригинальными именами и ссылками для скачивания отдельный файлов из задачи, если в запросе на конвертацию было несколько файлов. Если файл был один - данный массив будет отсутствовать.
  • download_url - URL для скачивания файла (ZIP - архива если файлов бло несколько в запросе) или один файл. Данное поле присутствует только когда статус status=completed.
200 (OK)

В случае если произошла какая-либо ошибка при конвертации: 

    
                            
    { 
        "task_id": "19561fd7-e055-4954-a5ee-f7247f616304",
        "status": "failed",
        "error": "Error description here........."
    }
  • status - Статус задачи (pending, processing, failed, completed)
  • task_id - UUID задачи.
  • error - Описание ошибки в случае если статус failed.

GET /subscription/stats/active

Получение информации по активной подписке и лимитах (длительность подписки = 1 месяц)

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

У данного эндпоинта нет обязательных параметров,

Пример запроса cURL:
curl --location 'https://api.filebee.ru/subscription/stats/active' \
--header 'Authorization: Bearer YOUR_API_KEY'
Ответы:
200 (OK)

В случае если есть активная подписка - вернет статус 200 (OK):

 
                            
    {
        "date_start": "2025-01-01T00:00:00Z",
        "date_end": "2029-12-31T00:00:00Z",
        "count_converted_files": 179,
        "count_files_per_month": 200
    }
  • date_start - Дата начала срока подписки
  • date_end - Дата окончания срока подписки
  • count_converted_files - Количество конвертированных файлов за данный период подписки
  • count_files_per_month - Лимит по количеству конвертаций в месяц
404 (Not Found)

В случае если подписке нет - вернет статус 404 (Not Found):

 
                            
    {
        "error": "No active subscription"
    }
  • date_start - Дата начала срока подписки
  • date_end - Дата окончания срока подписки
  • count_converted_files - Количество конвертированных файлов за данный период подписки
  • count_files_per_month - Лимит по количеству конвертаций в месяц

GET /subscription/stats

Получение информации по всем подпискам и лимитам за год (по каждому месяцу).

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

У данного эндпоинта нет обязательных параметров,

Пример запроса cURL:
curl --location 'https://api.filebee.ru/subscription/stats' \
--header 'Authorization: Bearer YOUR_API_KEY'
Ответы:
200 (OK)

В случае если у вас были подписки в течении года:

 
                            
 [
    {
        "date_start": "2025-12-01T00:00:00Z",
        "date_end": "2025-12-31T00:00:00Z",
        "count_converted_files": 14,
        "count_files_per_month": 50
    },
    {
        "date_start": "2025-11-01T00:00:00Z",
        "date_end": "2025-11-30T00:00:00Z",
        "count_converted_files": 123,
        "count_files_per_month": 50
    },
    {
        "date_start": "2025-01-12T00:00:00Z",
        "date_end": "2025-02-12T00:00:00Z",
        "count_converted_files": 1234,
        "count_files_per_month": 50
    }
]
  • date_start - Дата начала срока подписки
  • date_end - Дата окончания срока подписки
  • count_converted_files - Количество конвертированных файлов за данный период подписки
  • count_files_per_month - Лимит по количеству конвертаций в месяц
200 (OK)

В случае если подписок не было в течении года - вернет пустой ответ:

[]
  • date_start - Дата начала срока подписки
  • date_end - Дата окончания срока подписки
  • count_converted_files - Количество конвертированных файлов за данный период подписки
  • count_files_per_month - Лимит по количеству конвертаций в месяц

Коды ответа

Код Описание
200 Успешный запрос
400 Некорректные параметры запроса
401 Неверный или отсутствующий API-ключ
403 Подписка истекла или превышен лимит конвертаций файлов
408 Превышен таймаут запроса. При конвертации файла обработка может занять продолжительное время. После превышения таймаута 1 минуты обработка переходит в асинхронный режим.
413 Превышен размер запроса
422 Ошибка валидации запроса
429 Слишком много запросов
500 Внутренняя ошибка сервера
503 Сервис временно недоступен

Варианты содержимого Webhook

В случае успешной конвертации
В случае если в запросе было несколько файлов: 
                            
                               

    {
        "task_id": "19561fd7-e055-4954-a5ee-f7247f616304",
        "status": "completed",
        "status_url":"http://localhost:43096/convert/status/a76643fc-77f7-47fe-b1ba-1b746f610b84",
        "error": null,
        "files": [
            {
                "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304/0",
                "original_name": "Example_document_1.pdf"
            },
            {
                "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304/1",
                "original_name": "Example_document_2.pdf"
            }
        ],
        "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304"
    }
В случае если в запросе был один файл: 
                            

    {
        "task_id": "19561fd7-e055-4954-a5ee-f7247f616304",
        "status": "completed",
        "status_url":"http://localhost:43096/convert/status/a76643fc-77f7-47fe-b1ba-1b746f610b84",
        "error": null,
        "download_url": "https://api.filebee.ru/files/2/19561fd7-e055-4954-a5ee-f7247f616304"
    }
В случае НЕУДАЧНОЙ конвертации 
                            
    {
        "task_id": "19561fd7-e055-4954-a5ee-f7247f616304",
        "status": "failed",
        "error": "Error description here.........",
    }

Поддерживаемые варианты конвертации

Исходный формат Целевой формат
Документы (совместимы с Microsoft Word, LibreOffice, WPS office)
DOCX DOC, PDF, XPS, ODT, TXT, RTF, JPEG, PNG, TIFF, SVG, EPUB, XLSX, HTML, MD
DOC DOCX, PDF, XPS, ODT, TXT, RTF, JPEG, PNG, TIFF, SVG, EPUB, XLSX, HTML, MD
ODT DOCX, PDF, XPS, DOC, TXT, RTF, JPEG, PNG, TIFF, SVG, EPUB, XLSX, HTML, MD
RTF DOC, DOCX, PDF, XPS, ODT, TXT, JPEG, PNG, TIFF, SVG, EPUB, XLSX, HTML, MD
TXT PDF, DOCX, DOC, XPS, ODT, RTF, HTML, JPEG, PNG, TIFF, EPUB
PDF (ПДФ)
PDF DOCX, DOC, ODT, XPS, RTF, TXT, HTML, JPEG, PNG, TIFF, EPUB
Электронные таблицы (совместимы с Microsoft Excel, LibreOffice, WPS Office)
XLSX PDF, JPEG, PNG, TIFF, HTML, DOCX
XLS PDF, JPEG, PNG, TIFF, HTML, DOCX
ODS PDF, JPEG, PNG, TIFF, HTML, DOCX
Книги
EPUB DOC, DOCX, PDF, XPS, ODT, TXT, XLSX, MD
DJVU PDF
Изображения
SVG PDF
JPEG PDF
PNG PDF
TIFF PDF
Другие форматы
MD DOC, DOCX, XPS, ODT, TXT, XLSX, PDF
HTML DOC, DOCX, ODT, TXT, PDF

Дополнительные параметры конвертации

Исходный формат Целевой формат Дополнительные параметры
XLSX, XLS, ODS PNG, JPEG, JPG, PDF
  • all_columns_in_page (bool) - Все колонки на одной странице (область печати листа будет проигнорирована)
  • all_rows_in_one_page (bool) - Все строки на одной странице (область печати листа будет проигнорирована)
PDF DOCX mode (string) - Режим распознавания документы как документ с таблицами (значение mode = tables ). По-умолчанию будет использоваться режим с максимальным приближением к оригиналу
PDF XLSX mode - Режим когда все страницы PDF-документа будут добавлены на один лист (значение mode = all_on_one_page )
PDF PPTX, TIFF, JPEG, JPG, PNG, GIF dpi (integer) - разрешение (количество точек на дюйм). По-умолчанию - 192, доступно значение в диапазоне 96 - 600
HTML PDF
  • width (integer) - Установить фиксированную ширину страниц. По-умолчанию - auto, доступно значение в диапазоне 100-10000
  • height (integer) - Установить фиксированную высоту страниц. По-умолчанию - auto, доступно значение в диапазоне 100-10000
  • landscape (bool) - Установить альбомную ориентацию
  • margin_left, margin_top, margin_right, margin_bottom (integer) - Установить отступы от краев, доступно значение в диапазоне 100-10000
SVG PDF
  • width (integer) - Установить фиксированную ширину страниц. По-умолчанию - auto, доступно значение в диапазоне 100-10000
  • height (integer) - Установить фиксированную высоту страниц. По-умолчанию - auto, доступно значение в диапазоне 100-10000
  • landscape (bool) - Установить альбомную ориентацию
  • margin_left, margin_top, margin_right, margin_bottom (integer) - Установить отступы от краев, доступно значение в диапазоне 100-10000
DOCX PNG, JPEG, JPG dpi (integer) - разрешение (количество точек на дюйм). По-умолчанию - 192, доступно значение в диапазоне 96 - 600
DOCX HTML
  • export_images_as_base64 (bool) - Добавлять картинки в документ как Base64
  • inline_css (bool) - Сохранять стили в HTML файле
  • dpi (integer) - разрешение (количество точек на дюйм). По-умолчанию - 192, доступно значение в диапазоне 96 - 600

Как добавить дополнительные параметры конвертации в запрос

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

Для POST /convert/{source}/to/{target}

Пример запроса cURL:
curl --location 'https://api.filebee.ru/convert/pdf/to/png' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'files=@"/you-path/example_1.pdf"' \
--form 'files=@"/you-path/example_2.pdf"' \
--form 'options={"dpi" : 300, "files": [{"filename" : "example_1.pdf", "dpi" : "600"}]}' 
                            
    {
        "dpi": 300,   // устанавливает параметр для всех файлов
        "files": [
            "filename" : "example_1.pdf",
            "dpi" : "600"  // устанавливает параметр только для файла  example_1.pdf  
        ]
       
    }

Для POST /convert/base64/{source}/to/{target}

Пример запроса cURL:
curl --location 'http://localhost/convert/base64/docx/to/pdf' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{ "files": [ { "file_content": "base64 content file..." "filename": "example_1.pdf", "options": {"dpi": "300"} }, { "file_content": "base64 content file..." "filename": "example_2.pdf", } ], "options": { "dpi": "300" // глобальные дополнительные параметры дял всех файлов } }' 
                            
    {
        "files": [
            {
                "file_content": "base64 content file..."   
                "filename": "example_1.pdf",
                "options": {"dpi": "300"}   // устанавливает параметр только для файла  example_1.pdf
            },
            {
                "file_content": "base64 content file..."
                "filename": "example_2.pdf"
            },
            {
                "file_content": "base64 content file..."
                "filename": "example_2.docx"
            }
        ],
        "options": {
            "dpi": "300" // глобальные дополнительные параметры дял всех файлов
        }
    }