# Alfa API: Получать уведомления по операциям

Сценарий из mcp-everything. Актуально на 2026-10-13.

Вебхук избавляет от опроса API по выписке или входящим платежам СБП. Сценарий заканчивается активной подпиской и доставкой событий на партнёрский `callbackUri`.

1. Реализуй на своей стороне POST {callbackUri}. Метод должен принимать массив событий и возвращать любой код `2xx` после успешной обработки.
2. Убедись, что домен второго уровня `callbackUri` совпадает с доменом второго уровня `redirect_uri` интеграции, и заранее предоставь банку сетевой доступ к адресу.
3. Создай подписку: POST /api/v1/webhooks с нужным `object`. Для выписки используй `ul_transaction_default`; для входящих платежей СБП — `jp_sbp_incoming_payments`.
4. Проверь подписку: GET /api/v2/webhooks с обязательным `object`; используй `offset` и `limit` для пагинации.
5. При получении событий устраняй дубли по `transactionId` для выписки или `nspkTransactionId` для входящего платежа СБП и всё равно отвечай `2xx` на повторное сообщение.

```bash
curl -X POST https://baas.alfabank.ru/api/v1/webhooks \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "ul_transaction_default",
    "data": {
      "accounts": [
        "40702810800000000001",
        "40702810800000000004",
        "40702810800000000007"
      ]
    },
    "callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
    "version": 1
  }'
```

## Базовые URL

- Боевой хост: `https://baas.alfabank.ru`
- Тестовый хост: `https://sandbox.alfabank.ru`
- Авторизация пользователя в боевой среде: `https://id.alfabank.ru/oidc/authorize`
- Авторизация пользователя в песочнице: `https://id-sandbox.alfabank.ru/oidc/authorize`
- Продукты и сервисы: `https://baas.alfabank.ru/api`
- Продукты и сервисы в песочнице: `https://sandbox.alfabank.ru/api`
- Alfa ID: `https://baas.alfabank.ru/oidc`
- Alfa ID в песочнице: `https://sandbox.alfabank.ru/oidc`

## Авторизация

Тип: OAuth 2.0

Alfa ID использует OAuth 2.0/OIDC. Для Authorization Code Flow нужны `client_id`, `client_secret`, `redirect_uri` и scopes подключённых продуктов; токен передаётся в заголовке `Authorization: Bearer {access_token}`. Alfa ID подходит для всех типов интеграций и продуктов.

Для части B2B- и H2H-методов доступен API Key: передавай `Authorization: ApiKey {API Key}`. Внутренний ключ предназначен для операций по своей компании, внешний — по другой компании; API Key доступен не для всех продуктов, поэтому проверяй описание конкретного метода.

## Методы сценария

### POST /api/v1/webhooks — Создание вебхука

Создаёт подписку на событие. Требует Bearer-токен и scope события.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/create-webhook/v1/create-webhook

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} |
| `Accept` | header | string | да | application/json |
| `Content-Type` | header | string | да | application/json |
| `object` | body | string | да | ul_transaction_default или jp_sbp_incoming_payments |
| `callbackUri` | body | string | да | URL партнёра для доставки вебхука |
| `version` | body | integer | нет | Для указанных объектов поддерживается 1 |
| `data` | body | object | нет | Дополнительные параметры подписки |
| `data.accounts` | body | array of string | нет | Счета для ul_transaction_default; без поля подписка создаётся на все доступные счета |

Пример ответа:

```json
{
  "id": "f9f8c674-7a2a-4297-bdb8-ddd3013de3a3",
  "object": "ul_transaction_default",
  "enabled": true,
  "callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
  "version": 1
}
```

### GET /api/v2/webhooks — Получение списка вебхуков

Возвращает подписки по типу события с пагинацией.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/get-lists-webhooks/v2/get-lists-webhooks

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} |
| `Accept` | header | string | да | application/json |
| `object` | query | string | да | ul_transaction_default или jp_sbp_incoming_payments |
| `offset` | query | integer | нет | Смещение в результатах |
| `limit` | query | integer | нет | Количество элементов |

### {callbackUri} — Партнёрский метод для получения вебхуков

Метод реализуется партнёром. При успешной обработке должен вернуть любой код `2xx`; тело входящего запроса — массив событий.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/partner-webhook/v1/partner-webhook

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `actionType` | body | string | да | Тип действия с объектом |
| `eventTime` | body | string | да | Время события |
| `object` | body | string | да | Тип объекта события |
| `data` | body | object | да | Данные события |
| `organizationId` | body | string | нет | Идентификатор организации |
| `sub` | body | string | нет | Идентификатор пользователя |

## Нюансы

- В песочнице все вызовы Alfa API должны выполняться с mTLS. Тестовый сертификат и закрытый ключ выдаются после подключения; негативные сценарии песочницы могут отличаться от промышленной среды и спецификации метода.
- Код авторизации действует две минуты и используется один раз. `access_token` действует один час; `refresh_token` — 180 дней и может быть использован не более двух раз, после обновления сохраняй новую пару токенов.
- При `Content-Type: application/x-www-form-urlencoded` в cURL специальные символы `client_secret` нужно экранировать; `redirect_uri` экранировать не нужно. При отправке через Postman в режиме `x-www-form-urlencoded` специальное экранирование не требуется.
- API Key действует один год или бессрочно, но автоматически отзывается, если после последнего запроса прошло более 30 дней.
- `statementDate` допускает даты не ранее пяти лет от первого дня текущего года. Одна страница выписки содержит не больше 1000 операций.
- `externalId` платёжного поручения назначает партнёр. Документация требует UUID; в песочнице для каждого нового теста генерируй уникальное значение.
- Платёж без `digestSignatures` сохраняется в начальном статусе и ожидает подписания в Альфа-Бизнес. Для платёжного поручения по собственному счёту можно передать одну или две подписи.
- Партнёрский обработчик вебхука рекомендуется завершать не более чем за 300 мс. Если приходит `4xx`/`5xx`, ответ не получен за пять секунд или соединение не установлено, банк повторяет доставку через 30 секунд, 5 и 30 минут, 1, 3, 6, 12, 24, 48 и 72 часа.
- Дубли вебхуков по выписке нужно определять по `transactionId`, по входящим платежам СБП — по `nspkTransactionId`; на дубликат всё равно возвращай `2xx`.
- Старые версии endpoint’ов поддерживаются от двух до шести месяцев. Переход на новую версию нужно предварительно тестировать в песочнице.
- Сохраняй заголовок ответа `x-traceid`: при обращении в поддержку банк просит передать `X-TraceId` вместе с датой, временем, URI, заголовками и телом запроса.

## Другие сценарии

- [Получить токен Alfa ID](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchit-token-alfa-id.md)
- [Получить выписку по счёту юридического лица](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchit-vypisku-po-schetu.md)
- [Создать и проконтролировать платёжное поручение](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/sozdat-i-prokontrolirovat-platezhnoe.md)

---

Если этого недостаточно — официальная документация: https://developers.alfabank.ru/products/alfa-api/documentation
Вся интеграция одним документом: https://mcp-everything.ru/integrations/alfa-bank-api.md