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

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

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

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

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

Важно:
  • Общий размер файлов в запросе на конвертацию не должен быть более 100 МБ
  • Количество файлов в запросе на конвертацию не более 15
  • 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 раза с таймингами 1 и 5 минут.
  • is_async - флаг означает, что процесс конвертации асинхронный (отправляется запрос и в ответе сразу отдается ответ с двумя URL: ссылка для будущего скачивания файла(-ов) и ссылка для проверка статуса). Также можно указать webhook_url, на которы поступит такая же информация о статусе задачи конвертации.
  • delete_files - флаг для удаления документов из внутреннего хранилища сразу после отправки ответа. Однако, если запрос асинхронный (is_async = 1) или время ожидание запроса истекло (408 статус), файлы не будут удалены сразу, т.к для клиента остается возможность получить файлы позднее по URL.
Пример запроса 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 для скачивания файла (только если задача конвертации будет выполнена успешно!)

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

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

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

У данного эндпоинта нет обязательных параметров, т.к готовый URL приходит в ответе на запрос [POST] /convert/{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 Подписка истекла или превышен лимит конвертаций файлов
413 Превышен размер запроса
422 Ошибка валидации запроса
429 Слишком много запросов
500 Внутренняя ошибка сервера

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

Пример запроса от нашего сервиса при отправке на webhook_url в случае успешной конвертации

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

                            
                               

    {
        "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"
    }
Пример запроса от нашего сервиса при отправке на webhook_url в случае НЕУДАЧНОЙ конвертации 
                            
    {
        "task_id": "19561fd7-e055-4954-a5ee-f7247f616304",
        "status": "failed",
        "error": "Error description here.........",
    }

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

Исходный формат Целевой формат
Документы
docx pdf, doc, xps, odt
doc pdf, docx, xps, odt
odt pdf, docx, doc, xps
Электронные таблицы
xlsx pdf, xls, ods
xls pdf, xlsx, ods
ods pdf, xlsx, xls
PDF
pdf docx, doc, odt, xps