# Как это работает

Источник: https://dev.smartpdf.ru/docs/how-it-works

## Жизненный цикл операции

1. **Загрузка.** `POST /v1/upload` сохраняет файл и возвращает `file_id`. Он действует час, и в течение часа его можно использовать в нескольких операциях.
2. **Запуск.** `POST /v1/pdf/<операция>` проверяет параметры и баланс, списывает оплату и ставит операцию в очередь. Ответ — `202` и `task_id`. Если денег не хватает — `402`, ничего не списано.
3. **Обработка.** Статус меняется `pending` → `processing` → `done` или `failed`. Если обработка не удалась, оплата возвращается на баланс.
4. **Результат.** `GET /v1/tasks/{task_id}/download` выдаёт ссылку на скачивание; ссылка действует час.

## Статусы задачи

| status | Что значит |
|---|---|
| `pending` | Операция в очереди. |
| `processing` | Обрабатывается. У PDF в Word — прогресс по страницам в `progress` и `stage`. |
| `done` | Готово — можно скачивать. |
| `failed` | Не удалось. В `error` — причина, понятная человеку (например, неверный пароль или повреждённый PDF); оплата вернулась на баланс. |

## Очередь

Операции аккаунтов на тарифе Бизнес обрабатываются первыми, остальные — по порядку.

## Хранение файлов

- **Загруженные файлы** и их `file_id` — час, затем удаляются.
- **Результаты** — по тарифу аккаунта: бесплатный — час, и ссылку на скачивание можно получить один раз; Про — 7 дней; Бизнес — 30 дней.
- **Ссылка на скачивание** действует час; на Про и Бизнесе новую можно запросить, пока результат хранится.
- Серверы и резервные копии — в Москве.

## Имена результатов

Результат называется `<исходное имя>_smartpdf.<расширение>`: `document.pdf` → `document_smartpdf.pdf`. Объединение возвращает `merged_smartpdf.pdf`, сборка из изображений — `images_smartpdf.pdf`. PDF в JPG и разделение возвращают ZIP-архив. Имя приходит в поле `filename` и в заголовке `Content-Disposition`.

## Водяной знак

У результатов через API и MCP водяного знака нет — на любом тарифе.