Спецификация + REST API
Пример реальной спецификации (ключевые выдержки, полная версия — 34 страницы). Проект: разработка подписки «Газпром Бонус» — интеграция Системы Партнера (СП) с API программы лояльности Газпромбанка (ГПБ).
User Story
Как пользователь продуктов Экосистемы Газпром, я хочу оплачивать покупки бонусами, начисленными за оплату картой ГПБ, чтобы экономить.
Как владелец продукта групповой лояльности ГПБ, я хочу, чтобы пользователь оплачивал покупки в продуктах экосистемы бонусами, чтобы усилить его вовлечённость в продукты Банка и Экосистемы.
Контекст
В Банке реализован механизм начисления баллов по механике кэшбэка. Для доставки ценности нужен механизм использования баллов у партнёров. Участники MVP: Газпромнефть, Gorod Pay, Газпромбанк Мобайл, Шоколадница.
В данной схеме мы выступаем в роли прокси между сервисом Партнёра и Банком.
Use case
Отображение баланса баллов
Списание баллов
Проверка согласия Пользователя
Методы партнерского API
GET /v1/group-loyalty/balance
Назначение: предоставление партнёру данных по балансу баллов клиента Банка.
Заголовки:
| Параметр | Тип | Обязательность | Описание |
|---|---|---|---|
| X-Global-Transaction-Id | guid | да | Идентификатор запроса |
Query-параметры:
| Параметр | Тип | Обязательность | Описание |
|---|---|---|---|
| id | guid | да | Сквозной идентификатор операции в системе партнёра (для логов) |
| phone_number | string | да | Идентификатор клиента (номер телефона) |
Ответ:
| Параметр | Тип | Описание |
|---|---|---|
| phone_number | string | Идентификатор клиента |
| balance | int | Баланс баллов клиента |
| error_code | int | Код отказа при HTTP 200: 1 — не найден клиент, 2 — нет согласия |
Пример ответа:
{
"phone_number": "79006578435",
"balance": 100
}
POST /v1/group-loyalty/bonus/charge_off
Назначение: списание / отмена списания баллов клиента.
Body-параметры:
| Параметр | Тип | Обязательность | Описание |
|---|---|---|---|
| id | guid | да | Идентификатор транзакции (при отмене — id запроса списания) |
| phone_number | string | да | Идентификатор клиента |
| partner_id | int | да | Идентификатор партнёра в системе Банка |
| amount | int | да | Сумма баллов |
| type | int | да | 1 — списание, 2 — отмена |
Пример запроса:
{
"id": "6F9619FF-8B86-D011-B42D-00CF4FC964FF",
"phone_number": "79001234567",
"partner_id": 12,
"amount": 1000,
"type": 1
}
Ответ: error_code при HTTP 200: 1 — не найден клиент; 2 — нет согласия; 3 — недостаточный баланс или не найдена транзакция; 4 — запрос уже был выполнен успешно.
GET /v1/group-loyalty/consent
Назначение: проверка наличия согласия пользователя.
Ответ:
| Параметр | Тип | Описание |
|---|---|---|
| phone_number | string | Идентификатор клиента |
| consent | boolean | Признак наличия согласия |
| date_on / date_off | datetime | Даты предоставления / отзыва согласия (зарезервировано на будущее) |
| error_code | int | 1 — не найден клиент |
Обработка ошибок: маппинг ответов ГПБ → Шлюз СП
Ключевая логика — подмена кода ответа: 401 от GPB-API при трансляции партнёру преобразуется в 421.
| № | Причина ошибки | Ответ ГПБ | Ответ Шлюза СП |
|---|---|---|---|
| 1 | Пользователь не найден | 200 (error_code=1) | 200 (error_code=1) |
| 2 | Слишком много запросов | 429 | 429 |
| 3 | Ошибка сервера | 500 / 504 | 500 |
| 4 | Некорректный запрос | 400 | 400 |
| 5 | Ошибка авторизации | 401 | 421 |
| 6 | Сервис ГПБ недоступен | timeout error | 500 |
| 7 | Нет согласия | 200 (error_code=2) | 200 (error_code=2) |
| 8 | Недостаточно баллов / не найдена транзакция | 200 (error_code=3) | 200 (error_code=3) |
| 9 | Запрос уже был выполнен успешно | 200 (error_code=4) | 200 (error_code=4) |
Логирование, метрики, роли
- Для логов и метрик (
http_client_request_total,http_client_request_latency_bucket) заведены имена методов:partner_get_bonuses,partner_charge_off_bonuses,partner_consent. - Логирование запросов/ответов к Шлюзу СП и ГПБ; чувствительные данные не логируются в открытом виде.
- Добавлена роль тенанта
b2b-user-loyalty-system(read/write) для методов партнёрского API; фронт поддерживает отображение новой роли.
Нефункциональные требования
- Kredы хранятся в секретах, а не в переменных окружения.
- SLA 24/7: 99.9%.
- Пиковая нагрузка MVP: 996 операций в час (0.28 оп/сек).
- Гарантированное время ответа от ГПБ API: 60 сек.
- Масштабируемость: добавление партнёра с 20 млн клиентов.
- Отдельный домен и IP → отдельный балансировщик → отдельный Kubernetes.
Критерии приёмки
- Описанные методы API реализованы.
- Осуществляется подмена кода ответа (401 → 421).
- Новая роль тенанта отображается на фронте.
- Доступ партнёров работает согласно ролевой модели.
- Нефункциональные требования выполнены.