Install-IOS Partner API

С чего начать

Для подключения достаточно основного API-ключа, адреса API и готового комплекта выше. Резервный ключ хранится отдельно и используется только если основной потребуется заменить.

Заголовки каждого запроса

Authorization: Bearer iosp_ВАШ_ОСНОВНОЙ_КЛЮЧ
Accept: application/json
Content-Type: application/json
X-Request-ID: ваш-идентификатор-запроса

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

Навигация

Как проходит одна установка

Первый тест за 15 минут

Тестовый партнёр работает в sandbox: сумма рассчитывается, но реальный долг не создаётся.

1. Скачайте комплект и укажите ключ в .env или в окружении Postman.
2. Запустите START_TEST_WINDOWS.cmd либо коллекцию Postman «01 — безопасная проверка».
3. Убедитесь, что API отвечает, каталоги получены, заявка создана, повтор не создал дубль, страница и QR открываются.
4. Для реального теста кода сначала вызовите POST /orders/{id}/code-waits, затем запросите код на iPhone и проверяйте GET /code-waits/{wait_id}.

Успешный результат: ответы 2xx, повторный заказ вернул тот же id, код не старше 60 секунд, а balance.debt_kopecks в sandbox остался равен нулю.

1. Каталоги и приложения

GET/catalogs

curl -sS "$API_BASE/catalogs" \
  -H "Authorization: Bearer $API_KEY"

{
  "ok": true,
  "data": {
    "catalogs": [
      {"id": "cat_...", "name": "maxim", "applications_count": 18}
    ]
  }
}

GET/catalogs/{catalog_id}/applications

{
  "ok": true,
  "data": {
    "catalog": {"id": "cat_...", "name": "maxim"},
    "applications": [{"id": "app_...", "name": "ВКонтакте"}]
  }
}

API намеренно не передаёт внутренние UID, IPA-адреса, версии и технические данные учёток.

2. Создание заявки

POST/orders

Автоматический выбор учёток — рекомендуемый режим

{
  "external_order_id": "SC-10482",
  "source_mode": "auto",
  "applications": [
    {"id": "app_..."},
    {"id": "app_..."}
  ]
}

Ручной выбор каталога

{
  "external_order_id": "SC-10483",
  "source_mode": "manual",
  "applications": [
    {"id": "app_...", "catalog_id": "cat_..."}
  ]
}

В одной заявке можно передать до 50 приложений. API сам объединит их в группы по Apple-учёткам.

Защита от дублей: при сетевом повторе отправляйте тот же external_order_id. Первый ответ будет HTTP 201, повторный — HTTP 200 с тем же id. Новый внешний номер при повторе создавать нельзя.

Что приходит в ответе

• id заявки и актуальный срок expires_at;
• initial_ttl_seconds — срок до первого ожидания кода, code_window_ttl_seconds — срок после него;
• группы по учёткам и приложения внутри них;
• основная и резервная короткие ссылки каждого приложения;
• fallback_url — готовая полная инструкция для клиента;
• qr_url для открытия этой страницы на другом устройстве;
• расчётная и фактически начисленная сумма в копейках.

Таймер пилота «Сервис»: новая заявка действует 24 часа. Первый успешный вызов ожидания кода сокращает срок всей заявки, клиентской страницы и всех установочных ссылок до 1 часа от этого момента. Повторные вызовы час не добавляют. Всегда сохраняйте новое order_expires_at из ответа API.

3. Реквизиты, клиентская страница и продление

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

Если не хотите собирать собственный интерфейс установки, просто откройте клиенту fallback_url. На странице уже есть QR, инструкция, логин, пароль, получение кода и обе ссылки каждого приложения.

4. Получение кода

Правильный порядок: сначала API включает ожидание, затем клиент запрашивает код на iPhone. Код, появившийся раньше ожидания, не выдаётся.

POST/orders/{id}/code-waits

Idempotency-Key: code-SC-10482-group-1

{"group_id": "grp_..."}

В ответе приходит order_expires_at. При первом успешном запуске это новый срок всей заявки; обновите таймер в своей системе и больше не используйте прежнее значение expires_at.

Сохраните полученный wait_id и проверяйте его раз в секунду:

GET/code-waits/{wait_id}

Активное ожидание работает до 5 минут. На одной учётке одновременно может ждать любое количество клиентов; один свежий код получат все ожидания, включённые до его появления. Для одной группы разрешено не более трёх успешных получений.

5. Webhook — необязательное ускорение

Polling полностью поддерживается. Webhook позволяет получать события быстрее и использовать polling только как страховку.

События: order.created, order.extended, order.expired, code.ready, billing.charged, billing.reversed, payment.recorded, order.completed.

Проверяйте подпись по точному сырому телу до JSON-разбора, отклоняйте слишком старый timestamp и отвечайте HTTP 2xx только после безопасного сохранения события. Повторы одного X-InstallIOS-Event не должны менять результат.

6. Финансы

GET/balance · GET/ledger · GET/ledger.csv

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

Денежные поля передаются целым числом в копейках: 10000 = 100 ₽.

Ошибки и безопасные повторы

Каждый ответ содержит request_id. Передавайте его владельцу при разборе ошибки, но не прикладывайте ключи, реквизиты и коды.

Чек-лист перед рабочим запуском

• Ключ находится только в серверном секрет-хранилище.
• Одинаковый external_order_id не создаёт дубль заявки.
• Клиентская страница и QR открываются на iPhone.
• Ожидание кода включается до запроса на iPhone.
• Код старше 60 секунд нигде не показывается.
• Реквизиты и коды не попадают в логи и удаляются после заявки.
• Webhook-подпись проверяется, а повтор события безопасен.
• В sandbox долг не увеличивается.
• В рабочем тесте одна заявка создаёт ровно одно начисление.