Архитектура

Partner API platform: оператор как API-первый поставщик

Партнёрам нужен не custom-коннектор, а predictable API. Архитектура platform layer: developer portal, gateway, contracts, monetization, security.

Обсудить задачу

Зачем оператору отдельная partner API platform

Партнёры оператора (банки, маркетплейсы, страховые, такси, госпорталы) хотят интеграцию: проверка номера, identity bridge, location, billing-on-behalf, push notification, eSIM activation.

В большинстве операторов это решается ad-hoc: для каждого партнёра отдельный коннектор, отдельный контракт, отдельный SLA. Через 2 года — 30 интеграций, 30 разных способов всё это обслуживать.

Partner API platform консолидирует partner-facing функциональность в один платформенный слой с предсказуемым developer experience.

Структурные компоненты

API Gateway. Единая точка входа. Authentication (OAuth 2.0 client credentials), rate limiting, throttling, mTLS для критичных endpoint’ов.

Developer Portal. Публичная часть: документация, sandbox с test данными, API explorer, code samples, статус каждого API. Без портала ни один разработчик не интегрируется быстро.

API catalog. Куратируемый набор APIs по доменам (Identity, Location, Billing, Communication, Connectivity). Каждый API имеет owner, версию, SLA, deprecation policy.

Contracts and SLA. Каждый API — контракт: response time, availability, error rates. SLA differentiated по уровню партнёра (free / paid / enterprise).

Monetization layer. Биллинг за consumption: per-call, subscription, revenue-share. Без monetization API становится cost center.

Security. Beyond authentication: authorization (scopes), data masking (что видит партнёр в response), consent (на что у end-user есть согласие), audit (кто что вызвал).

Onboarding flow. Self-service регистрация партнёра, contract acceptance, API key issuance, sandbox access. Без self-service onboarding занимает недели и блокирует масштабирование.

Где обычно ломается

API строятся не как продукт, а как exposed legacy. Endpoint’ы возвращают raw данные из биллинга в формате 1996 года. Партнёры не могут consume.

Нет owner у API. При вопросе «почему этот endpoint вернул 500» никто не отвечает. SLA не reportable.

Versioning отсутствует. Изменение в API ломает всех партнёров одновременно. После этого партнёры боятся upgrade и остаются на старых версиях, которые legacy команда вынуждена поддерживать.

Sandbox = production. Партнёры тестируют на реальных клиентах. Один раз кто-то пушнул 100k тестовых SMS — оператор имеет жалобы регулятора и churn клиентов.

Monetization включена позже как afterthought. Запрос «давайте начнём брать деньги» upsets партнёров, которые год пользовались бесплатно.

Consent не проверяется на partner side. Регулятор приходит — партнёр говорит «нам оператор отдал», оператор говорит «партнёр должен был проверить». Проигрывают оба.

API design principles для оператора

REST или gRPC — выбор по контексту, но один стандарт для всех partner-facing API.

Consistent error model: коды, формат, retry semantics одинаковы во всех API.

Pagination, filtering, sorting standardised — а не каждый API изобретает заново.

Idempotency keys для всех write-operations.

Webhooks для async-уведомлений, а не polling.

Версионирование в URL (/v1/) или header — но не «в одном месте URL, в другом header».

Operating model

Owner — Head of Platform или CTO-офис. Не маркетинг, не sales — платформенная функция.

Команды:

API product management (roadmap, prioritization)
API engineering (build, run, scale)
Developer relations (документация, sample, support партнёров)
Partner success (commercial side)

Routine — quarterly review с partner advisory board: что нужно дальше, что мешает.

Как SamaraliSoft подключается

Partner API Blueprint — 8-10 недель. Inventory текущих partner integrations, дизайн target catalog, gateway/portal architecture, monetization model, governance, choice of platform (build / Apigee / Kong / managed). Pilot — 3-5 critical APIs с сэндбоксом.