Программный интерфейс как продукт

Версия: 1.0 Дата: 26.04.2026 Статус: Готов к обсуждению

Назначение документа

Документ определяет программный интерфейс платформы как продукт (application programming interface as a product, API-as-a-Product) — то есть платный, версионируемый, поддерживаемый, доказуемо стабильный коммерческий продукт со своим жизненным циклом, отдельным от внутренней реализации платформы.

Документ читается после трёх корневых:

• Архитектурный якорь и бизнес-модель — главное направление монетизации (маркетплейс программных интерфейсов для бизнес-клиентов, B2B API marketplace).
• Платформа как продукт — семь продуктовых атрибутов платформы.
• Поверхности взаимодействия — место партнёрской поверхности (Partner API Surface) в архитектуре.

В этих документах зафиксировано что платформа продаёт партнёрам и где проходит граница партнёрской поверхности. Документ api-as-product.md описывает как партнёрский программный интерфейс становится коммерческим продуктом — от первой регистрации разработчика до зрелого корпоративного клиента, через жизненный цикл версий и обязательства стабильности.

Программный интерфейс как продукт — главный коммерческий хребет архитектурного якоря. Без зрелого продуктового слоя над программным интерфейсом маркетплейс программных интерфейсов остаётся обещанием. С зрелым продуктовым слоем — становится сетевым эффектом.

Главное решение

Программный интерфейс платформы Vitiana — отдельный коммерческий продукт со своим жизненным циклом, не приложение к внутренней архитектуре.

Это означает:

• У программного интерфейса есть версии с явной политикой устаревания (deprecation policy) и сроками поддержки.
• У программного интерфейса есть тарифные уровни с измеряемыми ограничениями (квоты, мощность, доступные возможности).
• У программного интерфейса есть среда тестирования (sandbox) с реалистичными тестовыми данными, отдельная от боевой среды (production).
• У программного интерфейса есть поток сертификации партнёров перед боевым подключением.
• У программного интерфейса есть обязательства стабильности контракта — ломающие изменения недопустимы внутри одной версии.
• У программного интерфейса есть публичный статус (status page), партнёрская консоль (partner console), документация, пакеты средств разработки (software development kits, SDK), журнал изменений (changelog).
• У программного интерфейса есть жизненный цикл партнёра — от первого визита разработчика до корпоративного контракта.

Правило 00000 (платформа главенствует над поставщиками) применяется здесь напрямую: продуктовая модель программного интерфейса задаётся платформой, а не подгоняется под привычки конкретного партнёра. Партнёр, согласный на тарифную дисциплину и стабильный контракт, получает доступ; партнёр, требующий захватной интеграции, не получает.

Жизненный цикл партнёра

Этап 1. Открытие (discovery)

Потенциальный партнёр находит платформу через:

• Публичную страницу разработчиков (developer portal) на основном сайте платформы.
• Публикации в индустриальных изданиях, на отраслевых конференциях.
• Сайт vitrip.store как демонстрацию возможностей платформы — партнёр видит «вот что построено на этом программном интерфейсе».
• Прямые продажи (sales outreach) для крупных корпоративных клиентов.

Главный материал на этом этапе — публичная документация программного интерфейса в открытом доступе (без требования регистрации) с примерами запросов и ответов. Это обязательное условие для маркетплейса программных интерфейсов: партнёр должен иметь возможность оценить продукт до регистрации.

Этап 2. Регистрация и среда тестирования

Партнёр регистрируется через самообслуживание (self-service signup) на портале разработчиков:

• Базовые контактные данные.
• Каноничный идентификатор тенанта генерируется автоматически.
• Создаётся ключ доступа в среду тестирования (sandbox API key) с ограниченными квотами.
• Партнёр сразу попадает в тарифный уровень Free (бесплатный) с доступом только к среде тестирования.

Этап не требует ручной модерации платформой. Регистрация и среда тестирования — самообслуживание.

Этап 3. Интеграция в среде тестирования

Партнёр разрабатывает интеграцию против среды тестирования:

• Среда тестирования имеет реалистичные тестовые данные (sandbox seed data) — гостиницы, регионы, цены, доступность. Не пустые заглушки.
• Среда тестирования поддерживает полный жизненный цикл: поиск, коммерческая фиксация (quote), бронирование, отмена, частичный возврат, изменение, обработка возвратного платежа (chargeback simulation).
• Среда тестирования эмулирует различные сценарии ошибок — отказ поставщика, истечение коммерческой фиксации, провал платежа, недоступность регионов.
• Партнёр имеет доступ к консоли (partner console) с историей запросов, журналами ошибок, метриками вызовов.

Этап 4. Сертификация (certification)

Перед переходом в боевой режим (production) партнёр проходит поток сертификации (certification flow):

• Автоматическая часть — программная проверка базовых сценариев интеграции (тест-кит, certification test kit) в среде тестирования. Платформа проверяет: партнёр умеет делать поиск, фиксировать предложение, создавать бронирование, обрабатывать webhooks, обрабатывать ошибки.
• Ручная часть — для тарифов выше Free платформа проводит финальную ручную проверку (compliance review): проверка данных тенанта (Know Your Customer, KYC), проверка соответствия использования условиям соглашения, проверка корректности обработки персональных данных конечных клиентов партнёра.
• Подписание соглашения — соглашение об использовании программного интерфейса (API license agreement), соглашение об обработке персональных данных (Data Processing Agreement, DPA), коммерческие условия выбранного тарифа.

Сертификация — обязательный этап для перехода в боевой режим. Без неё ключ доступа остаётся в среде тестирования.

Этап 5. Боевой запуск (production launch)

После успешной сертификации:

• Создаётся ключ доступа в боевой режим (production API key).
• Применяются ограничения выбранного тарифа (квоты, мощность, доступные возможности).
• Партнёр получает доступ к боевой консоли с реальными метриками.
• Активируется выставление счетов (billing) по выбранному тарифу.

Этап 6. Эксплуатация и рост

Партнёр работает в боевом режиме:

• При приближении к лимиту тарифа платформа проактивно уведомляет партнёра о необходимости повышения тарифа.
• Платформа предоставляет аналитический продукт (partner-facing analytics) — данные о фактической нагрузке партнёра, эффективности конверсии, сравнение с другими партнёрами того же тарифа.
• Партнёр может самостоятельно повысить или понизить тариф через консоль без переговоров (для тарифов до профессионального).
• При достижении объёмов корпоративного уровня платформа предлагает индивидуальные коммерческие условия.

Этап 7. Эволюция версии программного интерфейса

При выпуске новой версии программного интерфейса:

• Партнёр получает уведомление о новой версии и сроках устаревания текущей.
• Партнёр имеет минимум 12 месяцев на переход (для основных версий) — гарантия совместимости текущей версии в течение этого срока.
• Платформа предоставляет инструменты миграции — справочник изменений (migration guide), различия (diff) спецификаций, симулятор обратной совместимости (compatibility shim) для постепенного перехода.

Тарифные уровни программного интерфейса

Концептуальная структура — в Архитектурный якорь и бизнес-модель и Платформа как продукт. Здесь — операционная сторона каждого уровня.

Бесплатный уровень (Free)

Назначение: разработка интеграции, оценка платформы, обучение разработчиков.

Ограничения:

• Только среда тестирования (sandbox), без боевого доступа.
• Ограниченное число поисковых вызовов (например, 10 000 в месяц) для интеграционного тестирования.
• Без возможности боевого бронирования (только тестовые в среде тестирования).
• Без расширенной аналитики, без приоритетной поддержки.
• Без обязательств соглашения об уровне обслуживания (SLA).

Без регистрации в течение 12 месяцев — учётная запись помечается как неактивная.

Стартовый уровень (Starter)

Назначение: малый бизнес, начинающие интеграции, локальные агентства.

Ограничения:

• Боевой доступ с минимальными квотами (например, 100 000 поисковых вызовов в месяц, до 1000 бронирований в месяц).
• Базовая партнёрская поверхность (Partner API Surface) — поиск, коммерческая фиксация, бронирование, отмена.
• Ограниченное покрытие поставщиками (только основные поставщики первой волны).
• Без программного интерфейса конструктора туров (Tour Builder API).
• Без расширенной аналитики.
• Стандартное соглашение об уровне обслуживания (95% доступности) без компенсаций.

Цена: фиксированная подписка плюс плата за фактическое потребление сверх минимальной квоты.

Профессиональный уровень (Professional)

Назначение: средние интеграторы, большие агентства, реселлеры.

Включает:

• Расширенные боевые квоты (без жёсткого верхнего предела, плата по динамическим тарифам за фактическое потребление).
• Полное покрытие поставщиками.
• Доступ к программному интерфейсу конструктора туров (Tour Builder API).
• Партнёрский продукт аналитики (partner-facing analytics) — фактические метрики потребления, эффективность конверсии, рекомендации по оптимизации.
• Управление подписками на уведомления по обратным вызовам (webhook subscriptions).
• Стандартное соглашение об уровне обслуживания (99% доступности) с компенсациями (credits) при нарушении.
• Стандартная техническая поддержка (рабочие часы, гарантированное время первого ответа).

Корпоративный уровень (Enterprise)

Назначение: крупные корпоративные клиенты, метапоиски с высоким объёмом, корпоративные системы туризма.

Включает:

• Гарантированная мощность (capacity envelope) — выделенные ресурсы инфраструктуры.
• Возможность выделенной инфраструктуры (dedicated infrastructure, фаза 4 — см. Эластичное масштабирование и упаковка по фазам).
• Полный набор возможностей платформы.
• Премиум-соглашение об уровне обслуживания (99.9% доступности) с расширенными компенсациями.
• Выделенный инженер по успеху клиентов (dedicated success engineer).
• Поддержка пользовательской интеграции (custom integration support).
• Индивидуальные коммерческие условия — разделение выручки (revenue-share), гибридная тарификация, договорные сроки эволюции версий.
• Опциональная поверхность взаимодействия с собственным брендом (white-label) — поддержка решения партнёра под его собственным брендом.

Класс партнёра поверх тарифа

Помимо тарифного уровня платформа выделяет классы партнёра (partner class), описанные в Каталог внешних async-проекций:

• Доверенный партнёр (trusted partner) — корпоративные интеграции, проверенные KYC, длительные отношения. Расширенный доступ к событиям и проекциям.
• Стандартный партнёр (standard partner) — типовой бизнес-партнёр, прошедший сертификацию.
• Песочница (sandbox-only) — партнёр в среде тестирования, без боевого доступа.

Класс партнёра определяет видимость событий и проекций в каждой поверхности.

Среда тестирования и боевая среда

Принципы разделения

Среда тестирования (sandbox) — полностью изолированная среда платформы:

• Отдельная база данных, отдельные сервисы.
• Реалистичные тестовые данные (sandbox seed data) — фиктивные гостиницы, регионы, цены, доступность, имитирующие реальный продакшн.
• Платежи симулируются через провайдер платёжных услуг в режиме среды тестирования (см. Платёжный домен).
• Бронирования у поставщиков не отправляются — поставщик заменяется заглушкой (stub) с настраиваемым поведением.
• События публикуются как обычно — партнёр получает уведомления по обратным вызовам в среду тестирования.
• Квоты в среде тестирования жёсткие — нельзя нагружать среду тестирования боевым трафиком.

Боевая среда (production) — реальная платформа с реальными поставщиками, реальными платежами, реальными бронированиями.

Доступ к среде тестирования и боевой среде

• Среда тестирования — самообслуживание, без сертификации.
• Боевая среда — после сертификации, с подписанным соглашением.

Запрещено смешивать ключи: ключ среды тестирования не работает в боевой среде, и наоборот.

Сценарии в среде тестирования

Среда тестирования поддерживает управляемые сценарии:

• Партнёр может явно запросить сценарий ошибки (например, через специальные значения в запросе) — провал платежа, отказ поставщика, истечение коммерческой фиксации.
• Партнёр может сбросить состояние своих тестовых бронирований без последствий.
• Партнёр может перематывать время для тестирования сценариев истечения, отмены за N дней, и т.д.

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

Версионирование и обязательства стабильности

Семантика версий

Программный интерфейс использует семантическое версионирование (semantic versioning) на уровне основной версии:

• Основная версия (major version) — v1, v2, v3. Может содержать ломающие изменения.
• Корректирующие изменения внутри основной версии — добавление полей, добавление возможностей, документация. Не ломают существующих интеграций.

Партнёр всегда указывает основную версию в каждом запросе (через путь /api/v1/... или заголовок).

Обязательства стабильности внутри основной версии

Внутри одной основной версии платформа гарантирует:

• Существующие поля не удаляются.
• Существующие поля не меняют тип.
• Существующие коды ошибок не меняют значение.
• Существующие пути не удаляются.
• Существующие требования аутентификации не ужесточаются.
• Существующие квоты не ужесточаются (могут только смягчаться).
• Существующие события не меняют структуру (могут добавляться новые, существующие — стабильны).

Что разрешено внутри одной основной версии:

• Добавление новых полей в ответы (партнёр должен игнорировать неизвестные поля — это закреплено в правилах партнёра).
• Добавление новых необязательных полей в запросы.
• Добавление новых путей.
• Добавление новых событий.
• Добавление новых кодов ошибок (партнёр должен иметь стратегию обработки неизвестных кодов).

Политика устаревания (deprecation policy)

При выпуске новой основной версии:

• Минимум 12 месяцев гарантированной поддержки текущей основной версии параллельно с новой.
• Минимум 6 месяцев уведомления партнёрам о выходе новой версии перед её выпуском.
• Минимум 6 месяцев после окончания гарантированной поддержки версии — режим «только аварийные исправления безопасности» (security-only mode).
• Корпоративные партнёры имеют индивидуальные сроки перехода, согласованные в контракте, обычно с увеличенным горизонтом до 24 месяцев.

Что не относится к версии

Некоторые изменения не требуют новой основной версии:

• Добавление новых поверхностей (например, выпуск нового программного интерфейса для аналитики не означает новую версию основного программного интерфейса).
• Добавление новых тарифов и квот.
• Добавление новых поставщиков (увеличение покрытия — это не изменение контракта).
• Изменение внутренних деталей реализации (если контракт не меняется).

Запрещённые изменения

• Удаление поля с того же дня (no-deprecation removal) — всегда требует объявления устаревания и перехода в новую версию.
• Изменение семантики поля без переименования (тихое breaking change).
• Изменение кодов состояний HTTP без объявления.
• Сужение принимаемых значений в запросе.

Обещание стабильности контракта

Контрактное тестирование (contract testing)

Каждый релиз платформы прогоняется через контрактные тесты (contract tests, паттерн Pact) против всех опубликованных версий программного интерфейса:

• Хранится зафиксированная спецификация каждой основной версии.
• При релизе платформа автоматически тестирует, что текущий код полностью соответствует опубликованным спецификациям всех поддерживаемых версий.
• Любое нарушение контракта блокирует релиз.

Подробности — в Релизы и совместимость.

Спецификации программного интерфейса

Платформа публикует формальные спецификации:

• Синхронный программный интерфейс — OpenAPI 3.x спецификация для REST endpoints (см. Скелеты OpenAPI и семейства ресурсов).
• Асинхронный программный интерфейс — AsyncAPI 2.x спецификация для каналов событий и уведомлений по обратным вызовам (см. Скелеты AsyncAPI и event envelopes).
• Машиночитаемые ограничения — лимиты, квоты, форматы как часть спецификации.

Спецификации публикуются в портале разработчиков и доступны для автоматической генерации клиентского кода.

Опыт разработчика (developer experience, DX)

Минимальный набор с фазы 2

В Платформа как продукт уже зафиксировано:

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

Расширенный набор с фазы 3

• Пакеты средств разработки (Software Development Kits, SDK) для основных языков — TypeScript/JavaScript, Python, PHP, Go, Java, .NET. Генерируются из спецификаций программного интерфейса. Поддерживаются сообществом и платформой.
• Примеры кода для типовых сценариев — поиск, бронирование, обработка возврата, обработка уведомлений по обратным вызовам.
• Тест-кит для сертификации — комплект автоматических тестов, которые партнёр запускает локально для проверки готовности к боевому режиму.
• Виртуальный помощник для разработчиков на основе ML — отвечает на вопросы по спецификациям, помогает построить запрос, объясняет ошибки.

Принцип «SDK как тонкая обёртка»

Раздел добавлен после внешнего архитектурного ревью 30.04.2026, в котором отмечен риск: «партнёры на чистом API будут гражданами второго сорта по сравнению с теми, кто использует SDK».

Этот риск не актуален для каноничной модели Vitiana. Принцип фиксируется явно, чтобы культура разработки SDK не разъехалась с принципом по мере роста.

Каноничный принцип

SDK — это тонкая обёртка над публичным программным интерфейсом, не самостоятельный слой бизнес-логики. SDK предоставляет:

• типизированные модели для входных и выходных данных (генерируются из спецификаций программного интерфейса);
• повторные попытки при сетевых сбоях (для идемпотентных операций);
• ключи идемпотентности для не-идемпотентных операций;
• обработку ошибок через типизированные исключения (вместо ручного парсинга error.code);
• удобства языка: контекстные менеджеры, async/await, итераторы для пагинации, типизированные перечисления (enum);
• журналирование запросов для отладки;
• подключаемые middleware для трассировки и метрик.

SDK не предоставляет:

• никаких бизнес-правил, которых нет в API;
• никакой дополнительной валидации входных данных сверх того что валидирует API;
• никаких скрытых трансформаций результатов API;
• никаких специальных привилегий при работе с API (тот же scope, та же квота, та же ставка тарифа).

Почему это критично

Тезис. Если в SDK появляется бизнес-правило, которого нет в API, это создаёт раздвоение surface: партнёры на чистом API получают худший продукт, чем партнёры на SDK. Это:

• ломает обещание «один контракт через все каналы» (см. главное решение этого документа);
• наказывает партнёров, у которых другой стек (например, язык, для которого нет нашего SDK);
• скрывает поведение системы за оболочкой, делая отладку через сетевой уровень невозможной;
• создаёт долговое обязательство поддерживать поведение SDK даже когда оно расходится с API.

Каноничный паттерн (Stripe, Twilio, Algolia): SDK — генерируется или частично генерируется из спецификаций, бизнес-логики не несёт, версии SDK строго следуют версиям API.

Каноничные правила разработки SDK

1. Каждый метод SDK имеет точное соответствие одному запросу к API. Если в SDK появилась функция, которая делает несколько API-вызовов и склеивает результаты, — это признак gap'а в API: нужно добавить соответствующий API-метод, а в SDK он будет тонкой обёрткой. Композитные методы в SDK запрещены.
2. Валидация входных данных в SDK — только schema-validation (типы полей, обязательные поля, регулярные выражения формата). Бизнес-правила («deadline должен быть позже текущей даты», «price должен быть положительным», «booking возможен только для подтверждённого quote») валидируются API.
3. Обработка ответов в SDK — только парсинг envelope ({ok, data, error, meta} → типизированная модель или typed exception). Никаких преобразований данных, фильтрации, агрегации.
4. Любая фича SDK документируется как API-фича первичной, а потом упоминается её SDK-проявление. Не наоборот.
5. Тесты SDK сравниваются с тестами API: если поведение SDK расходится с поведением API — это баг SDK, фиксится в SDK, не в API.

Как партнёр на raw API получает тот же опыт

Партнёр, разрабатывающий собственного клиента под наш API напрямую, должен иметь возможность получить функционально эквивалентный опыт. Это достигается через:

• Полнота публичной спецификации. OpenAPI / AsyncAPI спецификации содержат всё что использует наш SDK — никаких «приватных эндпоинтов» или «недокументированных полей».
• Equal authentication and rate limiting. Партнёр на raw API имеет тот же набор скоупов, тех же ключей идемпотентности, тех же rate limits — никакого «SDK trusted bonus».
• Reference implementation в open source. Наши SDK для базовых языков (TypeScript, Python) публикуются с открытым кодом — партнёр может посмотреть как реализована любая convenience-фича и воспроизвести её сам. Если SDK закрыт — это автоматически создаёт асимметрию.
• Documentation parity. Документация API содержит все примеры в двух формах: «сниппет на curl/HTTP» и «сниппет через SDK». Это явно показывает что SDK — не заменяет API, а его удобный фасад.

Что считается нарушением принципа

Если в коде SDK обнаружено любое из следующих — это bug-priority issue, требующий исправления:

• захардкоженные политики ретраев, отличные от рекомендаций API;
• кеш на стороне SDK ответов, к которым API не предполагает кеширование;
• автоматическая логика fallback между эндпоинтами без явного намерения партнёра;
• скрытое преобразование валют, дат, локалей внутри SDK;
• агрегация нескольких API-вызовов в один SDK-метод;
• скрытая дополнительная аутентификация / магия с ключами;
• любая бизнес-логика связанная с конкретными tenant-ами или surface-ами.

При обнаружении такой логики — пишется issue, приоритет fix'а — high, с rollout не позже следующей минорной версии SDK.

Обоснование (тезисы)

Тезис 1. SDK — это удобство, не суверенный канал.

Альтернативы: (а) SDK как полноценный слой логики (model FastSpring, некоторые legacy travel-провайдеры); (б) SDK как тонкая обёртка (model Stripe, Twilio).

Trade-off: вариант (а) даёт SDK-партнёрам преимущество, но создаёт раздвоение surface и долговую яму поддержки; вариант (б) — каноничный для верхнеуровневых платформ.

Тезис 2. Композитные методы — это gap в API, не feature SDK.

Альтернативы: (а) добавлять composite-методы в SDK когда несколько API-вызовов используются вместе; (б) добавлять composite-методы в API.

Trade-off: вариант (а) скрывает паттерн использования от платформы (мы не видим что партнёры делают эти 3 вызова всегда вместе и не можем оптимизировать); вариант (б) делает паттерн first-class в API, что улучшает product roadmap.

Тезис 3. Equal experience для raw API ≠ равный продукт без удобств.

Альтернативы: (а) raw API партнёры получают меньше функционала (например, нет доступа к новым эндпоинтам); (б) equal functional access, но без удобств типизации.

Trade-off: вариант (а) нарушает принцип «один контракт через все каналы»; вариант (б) каноничный — все партнёры имеют доступ к одинаковым функциям, удобство SDK — только в DX, не в capabilities.

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

Документация программного интерфейса — отдельный продукт, не «приложение к коду». Свойства:

• Версионирована вместе со спецификациями.
• Содержит описание каждого поля, не только структуру.
• Содержит сценарии использования (use cases), не только справочник методов.
• Содержит ограничения и тарифные следствия каждого вызова.
• Поддерживает поиск с учётом контекста (где упоминается это поле, какие связанные методы).
• Содержит журнал изменений (changelog) с группировкой по версиям и датам.

Партнёрская консоль (partner console)

Веб-интерфейс для разработчика и для бизнес-владельца партнёрской интеграции.

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

• Управление ключами доступа (создание, отзыв, ротация).
• Журнал запросов с детализацией (какой запрос, в какое время, какой ответ, сколько времени занял).
• Метрики потребления в реальном времени (графики, агрегации).
• Тестовые сценарии в среде тестирования.
• Подписки на уведомления по обратным вызовам и журнал доставок.
• Документация и журнал изменений.

Раздел бизнес-владельца

• Текущий тариф и фактическое потребление.
• Прогноз счёта на текущий период.
• История счетов и платежей.
• Самостоятельное повышение или понижение тарифа.
• Соглашения и юридические документы.
• Контактная поддержка.

Управление обратными вызовами и событиями

Подписки на события

Партнёр подписывается на события через консоль или программный интерфейс:

• Выбор каналов событий, на которые подписан (например, booking.confirmed, payment.captured).
• Конфигурация целевого URL для уведомлений по обратным вызовам.
• Конфигурация секрета для проверки подписи.
• Политика повторных попыток (retry policy).

Гарантии доставки

Платформа гарантирует доставку хотя бы один раз (at-least-once) — партнёр обязан обрабатывать события идемпотентно. Подробности — в Событийная шина и асинхронная дисциплина.

Подпись и проверка

Каждое уведомление по обратному вызову содержит подпись (signature) с использованием секрета партнёра. Партнёр обязан проверять подпись перед обработкой.

Учёт потребления и квоты

Каждый вызов программного интерфейса учитывается по метрикам, описанным в Учёт потребления и квоты:

• Поисковые вызовы (search calls).
• Сложность поиска (search complexity).
• Создание коммерческих фиксаций.
• Подтверждение бронирований.
• Доставки уведомлений по обратным вызовам.
• Использование хранилища.
• Операции взаиморасчёта и клиринга.
• Вызовы машинного обучения.

При приближении к лимиту тарифа партнёр получает предупреждения через консоль и через канал событий учёта потребления. При превышении — применяется политика, описанная в Архитектурный якорь и бизнес-модель (тариф превышения, повышение тарифа, ожидание).

Ограничение скорости (rate limiting)

Платформа применяет многоуровневое ограничение скорости для защиты от деградации:

• Глобальный лимит на всю партнёрскую поверхность для предотвращения каскадных сбоев.
• Тарифный лимит на тенанта в соответствии с выбранным тарифом.
• Защита от всплесков (burst protection) — короткие пики разрешены, длительные пики ограничиваются.
• Адаптивное ограничение (adaptive rate limiting) — при деградации поставщиков или внутренних систем платформа может временно снизить лимиты для всех или для определённых классов запросов.

При срабатывании ограничения партнёр получает код HTTP 429 Too Many Requests с заголовком Retry-After.

Аутентификация и авторизация

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

Партнёрская поверхность использует программные ключи доступа (API keys) с возможностью повышения до подписанных запросов с короткоживущими токенами:

• Базовый уровень — ключ доступа в заголовке Authorization: Bearer <key>. Подходит для большинства партнёров.
• Усиленный уровень — взаимная аутентификация (mutual TLS, mTLS) и подписанные запросы с короткоживущими токенами. Для корпоративных тенантов и для финансово-критических операций.

Области (scopes)

Каждый ключ доступа имеет набор областей (scopes) — какие группы программного интерфейса разрешены:

• search:read — поиск.
• quote:write — создание коммерческих фиксаций.
• booking:write — создание бронирований.
• webhook:manage — управление подписками на уведомления.
• analytics:read — чтение аналитики.
• И так далее.

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

Ротация ключей

• Каждый ключ имеет срок действия (expiration), по умолчанию 365 дней.
• Партнёр может ротировать ключ через консоль (создать новый, переключиться, отозвать старый).
• Платформа отправляет предупреждение за 30 дней до истечения ключа.

Запрещённые паттерны

• ❌ Передача ключа в URL (только в заголовках или в теле запроса).
• ❌ Логирование ключей в журналы платформы.
• ❌ Отправка ключа в публичных каналах поддержки.

Соглашение об уровне обслуживания (Service Level Agreement, SLA)

Метрики уровня обслуживания

Платформа публикует следующие метрики:

• Доступность (availability) — процент времени, в течение которого партнёрская поверхность доступна.
• Задержка отклика (response latency) на 95-м и 99-м процентилях для основных вызовов.
• Свежесть данных (data freshness) — задержка между событием в системе платформы и его отражением в ответах программного интерфейса.
• Доставка уведомлений по обратным вызовам — процент успешно доставленных уведомлений в первые попытки.

Уровни обещания по тарифу

Тариф	Доступность	Задержка p95	Компенсация при нарушении
Free	Best-effort	Best-effort	Без компенсации
Starter	95%	<500мс	Без компенсации, право досрочного расторжения подписки при многократных нарушениях
Professional	99%	<300мс	Компенсации (credits) на следующий период по фиксированной шкале
Enterprise	99.9%	<200мс	Расширенные компенсации, индивидуальные обязательства по контракту

Публичный статус (status page)

Платформа поддерживает публичную страницу статуса (status page) с реальным состоянием:

• Доступность партнёрской поверхности.
• Текущие инциденты и плановое обслуживание.
• Историческая статистика.
• Подписка на уведомления о состоянии.

Подробности — в Наблюдаемость и реагирование на инциденты.

Поддержка партнёров

Уровни поддержки по тарифу

Тариф	Каналы	Время первого ответа	Доступность поддержки
Free	Сообщество, форум	Не гарантировано	Без обещания
Starter	Электронная почта	48 часов	Рабочие часы (8×5)
Professional	Электронная почта, чат	8 часов для критических вопросов	Рабочие часы (8×5) с доступностью 24/7 для критических
Enterprise	Выделенный менеджер, прямая линия	1 час для критических	24/7

Каноничные категории обращений

• Инциденты — нарушение обещания соглашения об уровне обслуживания, ошибка платформы.
• Запросы на помощь — вопросы по спецификации, по интеграции.
• Запросы на возможности (feature requests) — пожелания партнёра.
• Биллинг — вопросы по счёту, тарифам, оплате.

Безопасность партнёрской поверхности

Каноничные меры

• Все запросы — только через TLS 1.3 (стандарт безопасности транспортного уровня).
• Защита от подделки запроса через подпись (HMAC) для критических операций.
• Защита от воспроизведения (replay protection) через временные метки и nonce.
• Защита от перебора через ограничение скорости и обнаружение аномалий.
• Журнал всех чувствительных операций (audit log) с возможностью партнёру скачать журнал своих операций.
• Изоляция тенантов — каждый партнёр видит только свои данные. Подробности — в Тенантная идентичность и изоляция.

Раскрытие уязвимостей

Платформа поддерживает программу раскрытия уязвимостей (responsible disclosure):

• Публичный канал для сообщений об уязвимостях.
• Гарантия отсутствия преследования при добросовестном раскрытии.
• Срок реакции — не более 72 часов на первичный ответ.

Фазы развёртывания продуктового слоя

Фаза Bootstrap (0–6 месяцев)

• Прототип партнёрской поверхности с одной группой методов (поиск).
• Среда тестирования с одним поставщиком (Stuba) и реалистичными тестовыми данными.
• Базовая документация в портале разработчиков.
• Самообслуживание регистрации и среды тестирования.

Фаза 2 — Production launch (6–12 месяцев)

• Полная партнёрская поверхность (поиск, коммерческая фиксация, бронирование, отмена).
• Поток сертификации (автоматический + ручной).
• Тарифы Free, Starter, Professional с боевым доступом.
• Партнёрская консоль (раздел разработчика и раздел бизнес-владельца).
• Управление подписками на уведомления по обратным вызовам.
• Базовое соглашение об уровне обслуживания.
• Публичная страница статуса.

Фаза 3 — Профессиональная зрелость (12–24 месяца)

• Корпоративный тариф (Enterprise) с гарантированной мощностью.
• Пакеты средств разработки (SDK) для основных языков, генерируемые из спецификаций.
• Расширенный аналитический продукт для партнёров.
• Контрактное тестирование на каждом релизе.
• Программа раскрытия уязвимостей (bug bounty).
• Многоязычная документация.

Фаза 4 — Многорегиональная зрелость (24+ месяцев)

• Многорегиональное развёртывание партнёрской поверхности с маршрутизацией по близости.
• Выделенная инфраструктура для корпоративных партнёров.
• Поддержка решений под партнёрским брендом (white-label) с UI-компонентами.
• Виртуальный помощник для разработчиков на ML.

Архитектурные решения с тезисным обоснованием

Решение 1. Программный интерфейс — отдельный коммерческий продукт

Цель: обеспечить долгосрочную стабильность интеграций партнёров и предсказуемую коммерциализацию.

Тезисы поддержки:

1. Маркетплейс программных интерфейсов — главный архитектурный якорь. Без зрелого продуктового слоя над программным интерфейсом маркетплейс не реализуется.
2. Партнёрские интеграции — это месяцы разработки и долгосрочные обязательства. Партнёр не подключится без гарантий стабильности контракта на 12+ месяцев.
3. Современные лучшие практики платформ верхнего уровня (Stripe, Twilio, Algolia, Cloudflare) — все строят программный интерфейс как отдельный продукт. Это база, не выбор.

Альтернатива: программный интерфейс как «выходное окно» внутренней реализации. Отклонено: это превращает партнёров в заложников внутренних изменений платформы. Каждое внутреннее изменение становится партнёрской проблемой.

Принимаемые компромиссы:

• Сложность поддержки нескольких версий одновременно — выше. Это часть продукта, а не накладные расходы.
• Дисциплина версионирования и обратной совместимости — обязательная. Это закрепляется в Релизы и совместимость.

Решение 2. Самообслуживание регистрации и среды тестирования

Цель: убрать барьер входа для партнёров и обеспечить масштабирование маркетплейса.

Тезисы:

1. Маркетплейс программных интерфейсов работает только при сетевом эффекте — чем больше партнёров, тем привлекательнее платформа. Сетевой эффект невозможен при ручной модерации каждой регистрации.
2. Среда тестирования не несёт операционного риска (платежи симулируются, поставщики заменены заглушками) — нет повода требовать модерации до интеграции.
3. Stripe, Twilio, Algolia — все позволяют самообслуживание для среды тестирования. Это база.

Принимаемые компромиссы:

• Возможны злоупотребления среды тестирования (создание множества тестовых учётных записей). Решается ограничениями скорости и автоматическим обнаружением аномалий, а не ручной модерацией.

Решение 3. Минимум 12 месяцев гарантированной поддержки версии

Цель: дать партнёру предсказуемый горизонт для планирования.

Тезисы:

1. Корпоративные интеграции имеют годовые циклы планирования — короткий горизонт несовместим с корпоративными клиентами.
2. 12 месяцев — индустриальный стандарт (Stripe, AWS, Twilio). Меньше — уход в сторону менее зрелых платформ.
3. Корпоративные партнёры часто требуют 24+ месяцев — это решается индивидуальными контрактами.

Решение 4. Среда тестирования с реалистичными данными, не пустыми заглушками

Цель: ускорить путь интеграции партнёра от регистрации до боевого запуска.

Тезисы:

1. Партнёр, разрабатывающий против пустых заглушек, не обнаруживает 80% проблем интеграции — они проявляются только в боевом режиме. Это разрушает доверие.
2. Реалистичные данные позволяют партнёру тестировать бизнес-логику, не только техническую интеграцию.
3. Stripe, Twilio имеют богатые песочницы — это часть конкурентного преимущества.

Принимаемые компромиссы:

• Сборка и поддержка реалистичных тестовых данных — отдельная инженерная задача. Это часть продукта.

Решение 5. Сертификация перед боевым запуском

Цель: защита платформы и поставщиков от некачественных интеграций.

Тезисы:

1. Некачественная интеграция в боевом режиме создаёт операционные расходы для платформы (оперативные обращения, неудачные бронирования, возвратные платежи).
2. Поставщики оценивают платформу по качеству передаваемого партнёрского трафика. Плохой трафик — потеря отношений с поставщиком.
3. Автоматическая сертификация даёт основной фильтр без ручной нагрузки на платформу.

Открытые развилки

Развилка 1. Конкретная схема цен для каждого тарифа

Тарифы зафиксированы концептуально. Точные цены, фиксированные подписки, тарифы за единицу превышения, скидки за объём — открытая развилка.

Эскалируется: при создании Экономическая модель (новый документ, фаза 4).

Развилка 2. Поддержка не-REST форматов программного интерфейса (GraphQL, gRPC)

Партнёрская поверхность фазы 1–3 — REST + Webhooks. GraphQL для гибких запросов и gRPC для высокопроизводительных интеграций — открытая развилка фазы 4.

Эскалируется: при появлении партнёрских запросов на эти форматы.

Развилка 3. Программа партнёрских комиссий (referral program)

Возможна программа, в которой партнёры получают комиссию за привлечение новых партнёров на платформу. Это потенциальный сетевой эффект, но добавляет операционные расходы (отслеживание реферралов, выплаты).

Эскалируется: при достижении бизнес-триггера объёма партнёров.

Развилка 4. Маркетплейс расширений (extensions marketplace)

В фазе 4 возможна модель, в которой третьи стороны публикуют расширения программного интерфейса (например, специализированные ML-модели ранжирования, специфичные форматы данных) на платформе с разделением выручки.

Эскалируется: при достижении зрелости основного маркетплейса.

Развилка 5. Точные коды ошибок и каноничный словарь

Коды ошибок зафиксированы концептуально. Полный каноничный словарь с маппингом на коды HTTP — открытая развилка.

Эскалируется: при детальной проработке спецификации API Contracts v2.

Связанная документация

Корневые архитектурные документы

• Архитектурный якорь и бизнес-модель — главное направление монетизации, тарифы.
• Платформа как продукт — семь продуктовых атрибутов, опыт разработчика.
• Поверхности взаимодействия — Partner API Surface как поверхность 3.
• Каноничная доменная ось — каноничные сущности, на которых строится контракт программного интерфейса.
• Операционная ось — наблюдаемость, инциденты, страница статуса.

Связанные доменные документы

• API Contracts — surface contracts, состояния бронирования, минимальный каркас спецификаций.
• Учёт потребления и квоты — метрики тарификации.
• Коммерческая модель — канальные коммерческие правила.
• Платёжный домен — платежи за платформенные услуги, выставление счетов корпоративным клиентам.
• Партнёрские взаиморасчёты — расчётные периоды, обязательства партнёра.
• Тенантная настройка — настройка тенанта при сертификации.
• Тенантная идентичность и изоляция — изоляция партнёрских данных, области.
• Соответствие требованиям регуляторов — соглашение об обработке персональных данных, KYC.
• Событийная шина и асинхронная дисциплина — каналы событий для уведомлений по обратным вызовам.
• Первоначальная таксономия событий — какие события доступны партнёру.

Документы развития и контрактов

• Скелеты OpenAPI и семейства ресурсов — формальная спецификация синхронного программного интерфейса.
• Скелеты AsyncAPI и event envelopes — формальная спецификация асинхронного.
• Каталог внешних async-проекций — классы партнёров и видимость событий.
• Реестр ломающих изменений и совместимость — политика эволюции асинхронных контрактов.
• Проверочный список совместимости consumer'а — что партнёр обязан соблюдать.
• Проверочный список готовности producer'а — что платформа обязана проверить перед выпуском изменения.
• Реестр повторов, очередей мёртвых писем и replay — как доставляются уведомления партнёру.

Операционная сторона

• Релизы и совместимость — контрактное тестирование на каждом релизе.
• Наблюдаемость и реагирование на инциденты — публичная страница статуса.
• Дорожная карта инфраструктурного масштабирования — фазы развёртывания.

Архитектурные правила

• Закон 00000 — платформа главенствует над поставщиками — платформа задаёт продуктовую дисциплину.
• Современные лучшие практики верхнеуровневых платформ — Stripe, Twilio, Algolia, Cloudflare как ориентиры продукта.
• Развитие без деградации — без захватных интеграций, без устаревших версий навсегда.
• Эластичное масштабирование и упаковка по фазам — фазы развёртывания продуктового слоя.
• Тезисное обоснование архитектурных решений — формат принятия решений.