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

Полная документация API для интеграции с CI/CD процессами и автоматизации загрузки iOS сборок.

🚀 Быстрый старт

1. Получение API ключа

Войдите в личный кабинет и создайте API ключ в разделе "API ключи".

# Создание API ключа через API
curl -X POST https://podgruzi.ru/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Integration", "description": "For automated builds"}'

2. Тестирование API

Проверьте работу API ключа:

# Проверка подписки
curl -H "X-API-Key: YOUR_API_KEY" https://podgruzi.ru/api/v1/subscription

3. Загрузка файла

Загрузите свой первый .ipa файл:

# Загрузка файла
curl -X POST https://podgruzi.ru/api/v1/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@app.ipa" \
  -F "name=My App" \
  -F "version=1.0.0" \
  -F "build=123"

🎯 Цели использования

API "Подгрузи" подходит для множества целей в экосистеме iOS разработки. Вот основные сценарии использования:

🚀

CI/CD Автоматизация

  • Автоматическая загрузка сборок после успешной сборки
  • Интеграция с GitHub Actions, GitLab CI, Jenkins
  • Уведомления команды о готовых сборках
  • Распространение тестовых версий среди QA команды
🧪

Внутреннее тестирование

  • Beta-тестирование приложений внутри команды
  • Демонстрация функций заказчикам
  • Тестирование на реальных устройствах без App Store
  • A/B тестирование разных версий
👥

Клиентская работа

  • Демо-версии для клиентов
  • Презентации новых функций
  • Быстрое распространение обновлений
  • Клиентское тестирование перед релизом
🔧

Разработка и отладка

  • Тестирование на разных устройствах
  • Проверка совместимости с разными iOS версиями
  • Отладка проблем на реальных устройствах
  • Валидация перед отправкой в App Store

📋 Конкретные сценарии

Мобильные агентства

Клиент → Запрос демо → Автоматическая сборка → API загрузка → Ссылка клиенту → Тестирование

Корпоративные приложения

Внутренняя разработка → Автоматические сборки → Распространение среди сотрудников → Сбор обратной связи

Стартапы и инди-разработчики

Быстрое тестирование → Показ инвесторам → Получение обратной связи → Итерации

💡 Преимущества

Для разработчиков

  • Экономия времени - не нужно вручную загружать сборки
  • Автоматизация - интеграция в существующие процессы
  • Централизация - все сборки в одном месте
  • Отслеживание - статистика загрузок и использования

Для команд

  • Синхронизация - все работают с одинаковыми версиями
  • Прозрачность - видно, кто и когда скачивал
  • Контроль версий - четкое разделение по версиям
  • Безопасность - контроль доступа к сборкам

Для бизнеса

  • Ускорение процессов - быстрее от идеи до тестирования
  • Снижение ошибок - автоматизация исключает человеческий фактор
  • Масштабируемость - легко добавить новых тестировщиков
  • Аналитика - понимание использования сборок

📱 Специфика iOS разработки

AdHoc распространение

  • Без App Store - прямое распространение
  • Контроль устройств - только зарегистрированные UDID
  • Быстрое обновление - без ожидания модерации
  • Тестирование - полный доступ к функциям

Provisioning Profiles

  • Автоматическая проверка совместимости
  • Валидация сертификатов
  • Безопасность - только авторизованные устройства

🔗 Популярные интеграции

Инструменты разработки

Xcode Fastlane CocoaPods Git

CI/CD платформы

GitHub Actions GitLab CI Jenkins Bitbucket

🔐 Аутентификация

API поддерживает два типа аутентификации:

JWT Токены

Для веб-приложений и браузерных интеграций

# Получение токена
curl -X POST https://podgruzi.ru/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# Использование токена
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://podgruzi.ru/api/v1/files

API Ключи

Для CI/CD интеграций и автоматизации

# Использование API ключа
curl -H "X-API-Key: pk_live_1234567890abcdef" \
  https://podgruzi.ru/api/v1/files

🔑 Управление API ключами

POST /api/v1/api-keys

Создание нового API ключа

Запрос:

{
  "name": "CI/CD Integration",
  "description": "API key for automated builds"
}

Ответ:

{
  "success": true,
  "apiKey": {
    "id": "key_id",
    "keyId": "pk_live_1234567890abcdef",
    "fullKey": "pk_live_1234567890abcdef_secret_part",
    "name": "CI/CD Integration",
    "description": "API key for automated builds",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

GET /api/v1/api-keys

Получение списка API ключей

Ответ:

{
  "success": true,
  "apiKeys": [
    {
      "id": "key_id",
      "keyId": "pk_live_1234567890abcdef",
      "name": "CI/CD Integration",
      "description": "API key for automated builds",
      "lastUsedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "isActive": true
    }
  ]
}

DELETE /api/v1/api-keys/:keyId

Удаление API ключа

Ответ:

{
  "success": true,
  "message": "API key deleted successfully"
}

📡 API Endpoints

📁 Управление файлами

POST /api/v1/upload

Загрузка .ipa файла

Параметры:
  • file - .ipa файл (обязательно)
  • name - название приложения
  • version - версия приложения
  • build - номер сборки
  • description - описание
Пример запроса:
curl -X POST https://podgruzi.ru/api/v1/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@app.ipa" \
  -F "name=My App" \
  -F "version=1.0.0" \
  -F "build=123" \
  -F "description=Release build"
Ответ:
{
  "success": true,
  "file": {
    "id": "file_id_123",
    "name": "My App",
    "version": "1.0.0",
    "build": "123",
    "size": 52428800,
    "uploadedAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-18T10:30:00Z",
    "downloadUrl": "https://podgruzi.ru/download/file_id_123",
    "installUrl": "https://podgruzi.ru/install/file_id_123",
    "qrCode": "https://podgruzi.ru/qr/file_id_123"
  }
}

GET /api/v1/files

Получение списка файлов

Параметры запроса:
  • page - номер страницы (по умолчанию 1)
  • limit - количество файлов на странице (по умолчанию 20)
  • status - фильтр: all, active, expired
Пример:
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://podgruzi.ru/api/v1/files?page=1&limit=10&status=active"

GET /api/v1/files/:fileId

Получение информации о файле

Пример:
curl -H "X-API-Key: YOUR_API_KEY" \
  https://podgruzi.ru/api/v1/files/file_id_123

POST /api/v1/files/:fileId/extend

Продление срока жизни файла

Запрос:
{
  "days": 7
}

DELETE /api/v1/files/:fileId

Удаление файла

📊 Статистика и подписки

GET /api/v1/subscription

Информация о подписке и лимитах

GET /api/v1/stats

Статистика пользователя

💡 Примеры интеграции

GitHub Actions

name: Deploy iOS App
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build iOS App
        run: |
          xcodebuild -workspace MyApp.xcworkspace \
            -scheme MyApp \
            -configuration Release \
            -archivePath MyApp.xcarchive \
            archive
            
      - name: Upload to Подгрузи
        run: |
          curl -X POST https://podgruzi.ru/api/v1/upload \
            -H "X-API-Key: ${{ secrets.PODGRUZI_API_KEY }}" \
            -F "file=@MyApp.ipa" \
            -F "name=My App" \
            -F "version=${{ github.ref_name }}" \
            -F "build=${{ github.run_number }}"

GitLab CI

deploy_ios:
  stage: deploy
  script:
    - xcodebuild -workspace MyApp.xcworkspace -scheme MyApp archive
    - curl -X POST https://podgruzi.ru/api/v1/upload \
        -H "X-API-Key: $PODGRUZI_API_KEY" \
        -F "file=@MyApp.ipa" \
        -F "name=My App" \
        -F "version=$CI_COMMIT_TAG" \
        -F "build=$CI_PIPELINE_ID"

CLI клиент

# Загрузка файла
node cli-client.js upload app.ipa --name "My App" --version "1.0.0"

# Список файлов
node cli-client.js list --status active

# Продление файла
node cli-client.js extend file_id_123 7

# Статистика
node cli-client.js stats

❌ Коды ошибок

Код Описание Решение
400 Неверный запрос Проверьте параметры запроса
401 Не авторизован Проверьте API ключ или JWT токен
403 Доступ запрещен Проверьте подписку и лимиты
404 Ресурс не найден Проверьте ID ресурса
413 Файл слишком большой Уменьшите размер файла
429 Превышен лимит запросов Подождите или обновите подписку
500 Внутренняя ошибка сервера Обратитесь в поддержку

📊 Лимиты и ограничения

По подпискам

Подписка Загрузок/день Размер файла Срок жизни Продления
Неавторизованные 3 100MB 1 день 0
Бесплатная 5 100MB 3 дня 1
Базовая 7 200MB 14 дней 1
Расширенная 15 500MB 30 дней 3

Rate Limiting

  • Неавторизованные: 10 запросов/минуту
  • Авторизованные: 100 запросов/минуту
  • API ключи: 1000 запросов/минуту