Задачи

Личный ключ действует от имени сотрудника и открывает его задачи. По нему можно запустить задачу, посмотреть её статус, скачать результат, отменить и повторить. Все запросы идут на адрес портала, по которому сотрудник работает в браузере, с заголовком Authorization.

Ключ создаётся в «Настройках»: в карточке «API-ключи» нажмите «Создать ключ». Полное описание личного ключа — в разделе «Личный ключ».

Authorization: Bearer sk_forge_...

Заголовок обязателен в каждом запросе. Сессионные cookie для этих запросов не нужны.

Тип задачи и его параметры

Запускать можно только тип задачи, который сотрудник видит в каталоге. По ключу список типов и схему их параметров не получить: каталог принимает только браузерную сессию, а ключ на нём получает 401. Поэтому тип и его поля сотрудник находит в портале, а не в ответе.

Идентификатор типа — это slug, который стоит в адресе формы. Откройте каталог и нажмите «Запустить» на карточке нужного типа — в адресе браузера появится страница вида /tasks/new/sales-summary. Значение после new/ — это то, что передаётся в поле taskTypeSlug.

Параметры задачи — это поля формы этого типа. Значение поля params — JSON-объект, где ключи совпадают с идентификаторами полей формы, а значения — тем, что сотрудник ввёл бы в форму. Какие поля есть у типа и какие значения допустимы в выпадающем списке, видно на самой форме. Точные ключи полей видно в поле userParams уже запущенной задачи — в ответе одной задачи.

Типичный сценарий

1. Найдите тип задачи в каталоге и возьмите его slug из адреса формы.
2. Запустите задачу запросом POST /api/tasks, передав taskTypeSlug, params и файлы.
3. В ответе получите id задачи и статус pending.
4. Опрашивайте GET /api/tasks/:id, пока статус не станет done, partial или failed.
5. Когда задача готова, получите список файлов и скачайте результат.
6. Если задача упала, повторите её или возобновите с места остановки.

Дальше — справочник по каждому запросу.

Создание задачи

Запускает задачу выбранного типа от имени владельца ключа.

Запрос

POST /api/tasks

Тело — форма multipart/form-data. Поле params передаётся строкой с JSON-объектом.

Пример

curl -X POST "https://portal.example.com/api/tasks" \
  -H "Authorization: Bearer sk_forge_..." \
  -F "taskTypeSlug=sales-summary" \
  -F 'params={"period":"2026-08","region":"Центральный"}' \
  -F "visibility=private" \
  -F "files=@отчёт-2026-08.xlsx"

Ответ

Код 201. Ответ — строка задачи; ниже — поля, которые нужны дальше.

{
  "data": {
    "id": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "taskTypeId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "userId": "1e2d3c4b-5a6f-4e7d-8c9b-0a1b2c3d4e5f",
    "status": "pending",
    "title": null,
    "visibility": "private",
    "userParams": { "period": "2026-08", "region": "Центральный" },
    "currentStep": 0,
    "totalSteps": 3,
    "retryOf": null,
    "durationMs": null,
    "error": null,
    "createdAt": "2026-09-28T09:15:00.000Z",
    "startedAt": null,
    "finishedAt": null,
    "scheduledFor": null,
    "kind": "execute"
  }
}

В ответе есть и другие поля; в таблице — те, что нужны для работы.

Ошибки

• 400. Нет taskTypeSlug или params, в params некорректный JSON, значение поля не совпадает со схемой типа, слишком много файлов, недопустимый тип или размер файла. Причина — в error.message; при нарушении схемы типа error.details добавляет поле и правило.
• 404. Тип задачи не найден, это черновик или он отключён.
• 403. Тип системный, доступен только в чате или имеет ограниченный доступ; либо сначала нужно оценить предыдущий результат этого типа.
• 429. Запуск этого типа слишком частый или превышен лимит задач в час; сообщение показывает, сколько ждать.
• 401. Ключ не передан, недействителен или истёк.

Список задач

Возвращает постраничный список задач с фильтрами по статусу, типу, дате и тексту.

Запрос

GET /api/tasks

Значения scope: my — ваши задачи, shared — публичные завершённые задачи любого автора, shared-with-me — задачи, которыми с вами поделились.

Пример

curl "https://portal.example.com/api/tasks?status=done&pageSize=20" \
  -H "Authorization: Bearer sk_forge_..."

Ответ

{
  "data": [
    {
      "id": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "taskTypeId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "userId": "1e2d3c4b-5a6f-4e7d-8c9b-0a1b2c3d4e5f",
      "title": "Сводка по продажам за август",
      "status": "done",
      "visibility": "private",
      "currentStep": 3,
      "totalSteps": 3,
      "durationMs": 184000,
      "createdAt": "2026-09-28T09:15:00.000Z",
      "startedAt": "2026-09-28T09:15:04.000Z",
      "finishedAt": "2026-09-28T09:18:04.000Z",
      "scheduledFor": null,
      "taskType": {
        "name": "Сводка по продажам",
        "slug": "sales-summary",
        "icon": "chart",
        "version": 4,
        "updatedAt": "2026-08-01T10:00:00.000Z"
      }
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 12, "totalPages": 1 }
}

В ответе есть и другие поля; в таблице — те, что нужны для работы.

Ошибки

• 400. Некорректный параметр запроса: неизвестный status, pageSize больше 100, page меньше 1.
• 401. Ключ не передан, недействителен или истёк.

Одна задача и её статус

Возвращает карточку задачи: статус, прогресс по шагам, файлы и параметры. Это основной запрос для опроса: повторяйте его, пока статус не станет завершённым.

Запрос

GET /api/tasks/<id задачи>

Пример

curl "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c" \
  -H "Authorization: Bearer sk_forge_..."

Ответ

{
  "data": {
    "id": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "taskTypeId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "userId": "1e2d3c4b-5a6f-4e7d-8c9b-0a1b2c3d4e5f",
    "status": "done",
    "title": "Сводка по продажам за август",
    "visibility": "private",
    "userParams": { "period": "2026-08", "region": "Центральный" },
    "currentStep": 3,
    "totalSteps": 3,
    "error": null,
    "durationMs": 184000,
    "createdAt": "2026-09-28T09:15:00.000Z",
    "startedAt": "2026-09-28T09:15:04.000Z",
    "finishedAt": "2026-09-28T09:18:04.000Z",
    "canEdit": true,
    "files": [
      {
        "id": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
        "direction": "output",
        "filename": "сводка-2026-08.xlsx",
        "fileSize": 48213,
        "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "isFinalResult": true,
        "createdAt": "2026-09-28T09:18:00.000Z"
      }
    ],
    "references": [],
    "sources": []
  }
}

В ответе есть и другие поля; в таблице — те, что нужны для работы.

Ошибки

• 400. id в адресе не в формате UUID.
• 404. Задача не найдена.
• 403. Нет доступа к задаче.
• 401. Ключ не передан, недействителен или истёк.

Статусы

Поле status принимает семь значений. На экране те же состояния подписаны по-русски и разобраны в справочнике статусов.

Задача с отложенным запуском тоже имеет статус pending, но у неё заполнено поле scheduledFor; на экране она подписана «Запланировано на …». Завершённые для скачивания результата статусы — done и partial.

Файлы задачи

Возвращает список файлов задачи: входные и результаты. Идентификатор файла из этого списка нужен для скачивания одного файла.

Запрос

GET /api/tasks/<id задачи>/files

Пример

curl "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c/files" \
  -H "Authorization: Bearer sk_forge_..."

Ответ

{
  "data": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "taskId": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "direction": "input",
      "filename": "отчёт-2026-08.xlsx",
      "fileSize": 102400,
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "isFinalResult": false,
      "createdAt": "2026-09-28T09:15:00.000Z",
      "modifiedAt": "2026-09-28T09:15:00.000Z"
    },
    {
      "id": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "taskId": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "direction": "output",
      "filename": "сводка-2026-08.xlsx",
      "fileSize": 48213,
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "isFinalResult": true,
      "createdAt": "2026-09-28T09:18:00.000Z",
      "modifiedAt": "2026-09-28T09:18:00.000Z"
    }
  ]
}

Если у задачи есть файлы-результаты, в списке показываются входные файлы и результаты; промежуточные файлы между шагами не показываются.

Ошибки

• 400. id в адресе не в формате UUID.
• 404. Задача не найдена.
• 403. Нет доступа к задаче.
• 401. Ключ не передан, недействителен или истёк.

Скачать один файл

Возвращает содержимое одного файла задачи. Ответ — сами байты файла, не JSON.

Запрос

GET /api/tasks/<id задачи>/files/<id файла>/download

Пример

curl "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c/files/7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d/download" \
  -H "Authorization: Bearer sk_forge_..." \
  -o сводка-2026-08.xlsx

Ответ

Код 200, тело — файл. Заголовки:

Ошибки

• 400. id или fileId в адресе не в формате UUID.
• 404. Задача или файл не найдены.
• 403. Нет доступа к задаче или файлу.
• 401. Ключ не передан, недействителен или истёк.

Скачать всё (ZIP)

Возвращает архив со всеми результатами задачи. Ответ — ZIP-файл, не JSON.

Запрос

GET /api/tasks/<id задачи>/download

Пример

curl "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c/download" \
  -H "Authorization: Bearer sk_forge_..." \
  -o task-3f2a1b4c.zip

Ответ

Код 200, тело — ZIP-архив. Заголовки:

Ошибки

• 400. id в адресе не в формате UUID.
• 404. Задача не найдена или у неё ещё нет файлов-результатов.
• 403. Нет доступа к задаче.
• 401. Ключ не передан, недействителен или истёк.

Отменить задачу

Останавливает задачу, которая ещё не закончилась. Задача в очереди становится cancelled сразу, задача в обработке — cancel_requested и останавливается сама.

Запрос

POST /api/tasks/<id задачи>/cancel

Пример

curl -X POST "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c/cancel" \
  -H "Authorization: Bearer sk_forge_..."

Ответ

{
  "data": {
    "id": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "status": "cancel_requested"
  }
}

Повторный запрос к задаче в статусе cancel_requested возвращает тот же статус без ошибки.

Ошибки

• 400. id в адресе не в формате UUID.
• 404. Задача не найдена.
• 403. Нет доступа к задаче.
• 409. Задача не может быть отменена: отменяются только задачи pending и processing.
• 401. Ключ не передан, недействителен или истёк.

Повторить задачу

Создаёт новую задачу с теми же файлами и параметрами. Доступно для завершённых задач — done, partial, failed, cancelled.

Запрос

POST /api/tasks/<id задачи>/retry

Пример

curl -X POST "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c/retry" \
  -H "Authorization: Bearer sk_forge_..."

Ответ

Код 201.

{
  "data": {
    "id": "4a3b2c1d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "retryOf": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "status": "pending"
  }
}

Если повтор уже запущен и ещё не закончен, повторный запрос возвращает его без создания новой задачи.

Ошибки

• 400. id в адресе не в формате UUID.
• 404. Задача не найдена или её тип больше недоступен.
• 403. Нет доступа к задаче.
• 409. Задача не может быть повторена: повтор доступен только для завершённых задач.
• 401. Ключ не передан, недействителен или истёк.

Возобновить задачу

Возвращает упавшую задачу в очередь с того шага, на котором она остановилась. Доступно только для задач failed, которые уже начали обработку.

Запрос

POST /api/tasks/<id задачи>/resume

Пример

curl -X POST "https://portal.example.com/api/tasks/3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c/resume" \
  -H "Authorization: Bearer sk_forge_..."

Ответ

{
  "data": {
    "id": "3f2a1b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "status": "pending",
    "currentStep": 2,
    "totalSteps": 3
  }
}

Если задача упала, не начав ни одного шага, возобновить её нельзя — используйте повтор.

Ошибки

• 400. id в адресе не в формате UUID или задача не начала обработку.
• 404. Задача не найдена.
• 403. Нет доступа к задаче.
• 409. Задача не может быть возобновлена: только failed, либо статус изменился.
• 401. Ключ не передан, недействителен или истёк.