Перейти к основному содержанию

Загрузка файла (File upload)

Это руководство описывает многоэтапный процесс загрузки файлов в Postmypost API. В целом он состоит из трёх шагов:

  1. Инициализация загрузки — передача метаданных файла и получение параметров. См. API: Инициализировать загрузку файла.
  2. Загрузка файла
    • Сценарий A: прямая загрузка файла в хранилище (S3) по предподписанным параметрам.
    • Сценарий B: загрузка по ссылке (URL), когда систему просим забрать файл сама.
  3. Ожидание обработки и проверка готовности — опрос статуса до состояния готовности. См. API: Статус загрузки файла.

Предварительные условия​

  • Базовый URL API: https://api.postmypost.io/v4.1
  • Аутентификация: передавайте заголовок Authorization: Bearer <ACCESS_TOKEN> во всех запросах к API Postmypost.
  • Заранее знайте project_id (ID проекта, в который загружается файл).

Шаг 1. Инициализация загрузки​

POST /upload/init → документация метода

Выберите один из вариантов тела запроса:

  • «by file»: передайте project_id, имя файла name и размер в байтах size.
  • «by URL»: передайте project_id и url исходного файла.

Пример («by file», cURL):

curl -X POST "https://api.postmypost.io/v4.1/upload/init" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 12345,
    "name": "cat.jpg",
    "size": 259390
  }'

Успешный ответ для варианта «by file» вернёт параметры для прямой загрузки в S3:

{
  "id": 32,
  "name": "cat.jpg",
  "size": 259390,
  "action": "https://uploads.s3.amazonaws.com/",
  "fields": [
    { "key": "acl", "value": "public-read" },
    { "key": "key", "value": "1/79811084-92e0-4cf1-805c-18cc4ec20339" },
    { "key": "X-Amz-Credential", "value": "YCAJEXAMPLE/20250630/ru-central1/s3/aws4_request" },
    { "key": "X-Amz-Algorithm", "value": "AWS4-HMAC-SHA256" },
    { "key": "X-Amz-Date", "value": "20250630T064654Z" },
    { "key": "Policy", "value": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNi0zMF..." },
    { "key": "X-Amz-Signature", "value": "a9e1927a56145161345903c8c081a3194d90f641fed0bc49a651debd2e66a946" }
  ],
  "status": 5
}

Сохраните id, action и все пары fields[].key → fields[].value — они понадобятся далее.

Шаг 2. Загрузка файла: выберите сценарий​

Сценарий A — прямая загрузка в хранилище (S3)​

  1. Отправьте файл по адресу из action с параметрами из fields через multipart/form-data.

Пример (cURL):

# Подставьте значения action и fields из шага 1
curl -X POST "https://uploads.s3.amazonaws.com/" \
  -F "acl=public-read" \
  -F "key=1/79811084-92e0-4cf1-805c-18cc4ec20339" \
  -F "X-Amz-Credential=YCAJEXAMPLE/20250630/ru-central1/s3/aws4_request" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Date=20250630T064654Z" \
  -F "Policy=eyJleHBpcmF0aW9uIjoiMjAyNS0wNi0zMF..." \
  -F "X-Amz-Signature=a9e1927a56145161345903c8c081a3194d90f641fed0bc49a651debd2e66a946" \
  -F "file=@./cat.jpg"

Ожидаемый ответ от хранилища — 204/201/302. После успешной загрузки перейдите к п.2.

  1. Завершите загрузку в API: POST /upload/complete?id=<id> → документация метода
curl -X POST "https://api.postmypost.io/v4.1/upload/complete?id=32" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Пример ответа:

{ "id": 32, "status": 1 }

Сценарий B — загрузка по ссылке (URL)​

Если при инициализации (Шаг 1) вы использовали вариант «by URL», ничего вручную загружать не нужно — система скачает файл сама. Метод /upload/complete в этом сценарии не вызывается.

Для мониторинга переходите сразу к Шагу 3 и опрашивайте статус по id.

Шаг 3. Ожидание обработки и проверка готовности​

GET /upload/status?id=<id> → документация метода

curl -X GET "https://api.postmypost.io/v4.1/upload/status?id=32" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Пример ответа:

{ "id": 32, "status": 1 }

Возможные статусы:

  • 5 — ожидание загрузки
  • 4 — загрузка
  • 3 — обработка
  • 2 — ошибка
  • 1 — файл успешно загружен

Частые ошибки и советы​

  • 401/403: проверьте корректность Authorization: Bearer <ACCESS_TOKEN> и наличие прав на проект.
  • 422: проверьте тело запроса — обязательные поля:
    • для прямой загрузки: project_id, name, size
    • для загрузки по URL: project_id, url
  • На шаге S3 обязательно передавайте все поля из fields точь‑в‑точь, как они вернулись из init.
  • В multipart/form-data используйте -F "file=@/путь/к/файлу" для фактической передачи содержимого файла.
  • size указывайте в байтах.
  • Если соединение прервалось, можно повторить загрузку на шаге S3, затем снова вызвать /upload/complete (для сценария A).