Быстрый старт · File API

Первый файл через File API за несколько шагов.

Создайте приложение, выпустите серверный ключ, проверьте подключение и загрузите файл. Дальше тот же File ID используется для чтения, замены содержимого, истории версий и выдачи.

Перед началом

Секретный ключ — только для серверной части.

Скопируйте секретный ключ из Workspace и храните его только в серверном окружении. Не помещайте его в JavaScript-код сайта, localStorage, пакет настольного или мобильного приложения или публичный репозиторий. Для прямой загрузки из браузера используйте отдельное короткоживущее разрешение.

1. Создайте Приложение

Откройте Workspace → Приложения. Укажите название — для первого файла стандартных разрешений достаточно. Рабочую или тестовую среду можно выбрать позднее. Среда находится внутри приложения и имеет собственные ключи доступа.

Открыть Workspace

2. Создайте секретный ключ

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

PULSE_MEDIA_URL=https://media.pulsehq.ru
PULSE_MEDIA_TOKEN=<секретный ключ из Workspace>

3. Проверьте подключение

curl --fail-with-body \
  "$PULSE_MEDIA_URL/v1/media/connection" \
  -H "Authorization: Bearer $PULSE_MEDIA_TOKEN"

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

4. Загрузите первый файл

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

CREATE="$(curl --fail-with-body -sS \
  -X POST "$PULSE_MEDIA_URL/v1/media/files" \
  -H "Authorization: Bearer $PULSE_MEDIA_TOKEN" \
  -F "file=@photo.jpg")"
echo "$CREATE" | jq .
FILE_ID="$(printf '%s' "$CREATE" | jq -er '.file_id')"

В ответ придут file_id — постоянный идентификатор файла — и delivery_url — адрес для получения содержимого. Адрес закрытого файла временный: когда он истечёт, запросите новый по file_id.

Дополнительно: привязка к вашей системе и безопасные повторы

Для рабочих сценариев задавайте Idempotency-Key: при повторе той же операции с тем же ключом Pulse Media не создаст второй файл. Без этого заголовка каждый новый запрос считается отдельной загрузкой — даже если повтор был после сетевого сбоя. Пара заголовков владельца и тип ресурса нужны, только если хотите связать файл с заказом, пользователем или другой сущностью вашей системы.

curl --fail-with-body \
  -X POST "$PULSE_MEDIA_URL/v1/media/files" \
  -H "Authorization: Bearer $PULSE_MEDIA_TOKEN" \
  -H "Idempotency-Key: order-123-attachment-1" \
  -H "X-PMC-Owner-Type: order" \
  -H "X-PMC-Owner-ID: 123" \
  -F "resource_type=attachment" \
  -F "file=@document.pdf"

Если указываете владельца, нужны оба заголовка; незаполненная половина не принимается. Загрузка из браузера по короткому разрешению остаётся отдельным защищённым сценарием.

5. Получите тот же файл по File ID

Используем FILE_ID с предыдущего шага. Для автоматического извлечения ID в примере нужен jq.

curl --fail-with-body \
  "$PULSE_MEDIA_URL/v1/media/files/$FILE_ID" \
  -H "Authorization: Bearer $PULSE_MEDIA_TOKEN"

Для закрытого файла чтение возвращает свежую временную подписанную ссылку. Не храните временный подписанный URL как основной идентификатор файла.

6. Заменяйте содержимое, не меняя File ID

Замена создаёт следующую неизменяемую версию и атомарно делает её текущей. Предыдущая успешная версия остаётся в истории.

curl --fail-with-body \
  -X POST "$PULSE_MEDIA_URL/v1/media/files/$FILE_ID/replace" \
  -H "Authorization: Bearer $PULSE_MEDIA_TOKEN" \
  -H "Idempotency-Key: release-desktop-client-v2" \
  -F "file=@package-v2.bin"

7. Для браузера используйте короткоживущее разрешение

Сервер выдаёт ограниченное pulse_ug разрешение через POST /v1/media/upload-grants. Браузер получает токен разрешения, точный URL загрузки и созданный сервером ключ идемпотентности, после чего отправляет файл напрямую в Pulse Media.

ПРЯМАЯ ЗАГРУЗКАсекрет остаётся на сервере

браузер → ваш сервер → получить разрешение
браузер ← pulse_ug + upload_url
браузер → Pulse Media
браузер ← file_id + ссылка

8. Подключите вебхук для событий о файлах

Доступные события: file.created, file.processed, file.failed, file.deleted. Подписка относится к конкретным приложению и среде. Подпись проверяется по исходному телу запроса.

9. SDK — короткий путь к тому же API

SDK для Node.js и PHP работают с тем же API. В Центре интеграции Workspace можно скачать набор SDK, совпадающий с установленной версией Pulse Media. Обычный cURL остаётся основным примером.

Перейти в Центр интеграции Платформа для разработчиков Безопасность