Hasan/alfa-bank-sdk
1
0
Fork 0
forked from apoloz/alfa-bank-sdk
Code Pull Requests Activity
Files
main
alfa-bank-sdk/docs/xml/alfa_payin_docs.xml
Anatoliy Poloz 6a9243d969 update docs
2026-06-08 11:43:18 +03:00

12150 lines
751 KiB
XML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<?xml version="1.0" encoding="UTF-8"?>
<payin_and_kyc>
<Alfa_ID>
<alfa_id_login_button_md>
<![CDATA[
# Кнопка входа по Alfa ID
**Теги:** `B2B` `B2C` `H2H`
Для того чтобы Ваши пользователи могли аутентифицироваться через Alfa ID, вы можете добавить кнопку **«Войти по Alfa ID»**, реализовав её в соответствии с требованиями, указанными на официальной странице руководства:
🔗 [https://alfabank.ru/sme/guide-alfaid](https://alfabank.ru/sme/guide-alfaid)
### Исходные файлы
Вы можете импортировать макет кнопки для использования в своем дизайне из следующего файла:
📥 [Скачать button.fig](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/button/files/button.fig)
---
## Общая информация об Alfa ID
_(Данные из справочного раздела системы)_
**Alfa ID** — единая учётная запись пользователя ЮЛ (юридического лица) / ФЛ (физического лица), которая помогает пользователям входить на ваш сайт или в приложение, а также в продукты и сервисы Альфа-Банка.
### Преимущества для пользователей
- Простая и быстрая аутентификация на сайтах и в приложениях;
- Единый и безопасный аккаунт;
- Упрощение процесса покупки или подачи заявки;
- Безопасность персональных данных;
- Не нужно запоминать множество паролей.
### Преимущества для партнёров
- Простая и быстрая аутентификация, выше конверсия на вход;
- Быстрое получение актуальных данных пользователя от Банка;
- Автозаполнение форм и заявок;
- Проверка реальности пользователя;
- Индустриальные стандарты защиты данных и персональной информации;
- Отсутствие необходимости хранить персональные данные на своей стороне.
### Рекомендуемые браузеры
- **Яндекс Браузер:** версии 21 и выше;
- **Safari:** версии 16 и выше;
- **Google Chrome:** версии 117 и выше.
---
**Навигация:**
← [Аутентификация](/products/alfa-api/documentation/articles/alfa-id/articles/authentication/authentication) | [Как использовать ACF](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) →
]]>
</alfa_id_login_button_md>
<authentication_md>
<![CDATA[
# Аутентификация
**Теги:** `B2B` `B2C` `H2H`
При входе через Alfa ID для вашего пользователя доступны следующие способы аутентификации:
- логин и пароль;
- QR-код;
- электронная подпись;
- биометрия.
---
### Логин и пароль
Аутентификация по логину и паролю — пользователь вводит свой логин и пароль. После успешной аутентификации пользователь получает доступ к защищённым ресурсам.
**Процесс аутентификации:**
1. Введите свои учётные данные на странице входа.
2. Введите код из СМС.
---
### QR-код
Аутентификация по QR-коду — это технология, которая позволяет пользователям быстро и безопасно подтверждать свою личность путём сканирования QR-кода.
**Процесс аутентификации:**
1. Отсканируйте QR-код камерой мобильного устройства.
2. Подтвердите вход через приложение Альфа-Бизнес Мобайл (АБМ).
3. Введите код из СМС.
> **Примечание**
> Наличие приложения Альфа-Бизнес Мобайл (АБМ) является условием входа по QR-коду.
---
### Электронная подпись
Аутентификация с помощью электронной подписи (ЭП) — это технология, основанная на применении средств криптографической защиты информации, для использования которой необходимо наличие токена (USB-носитель) с сертификатом и специализированного программного обеспечения на компьютере.
Для аутентификации используются следующие виды ЭП:
- квалифицированная электронная подпись (КЭП);
- сертификат Альфа-Банка (неквалифицированная электронная подпись, НЭП).
#### Квалифицированная электронная подпись (КЭП)
**Процесс аутентификации:**
1. Вставить токен с сертификатом КЭП в компьютер.
2. Нажать на кнопку «Войти по токену».
3. Нажать на кнопку «С сертификатом КЭП».
4. Выбрать необходимый сертификат из списка.
5. Ввести пароль (при его наличии) от сертификата.
6. Ввести пароль от учётной записи Банка.
#### Сертификат Альфа-Банка (НЭП)
**Процесс аутентификации:**
1. Вставить токен с сертификатом Альфа-Банка (НЭП) в компьютер.
2. Нажать на кнопку «Войти по токену».
3. Нажать на кнопку «С сертификатом Альфа-Банка».
4. Выбрать необходимый сертификат из списка.
5. Ввести пароль от токена.
6. Ввести пароль от учётной записи Банка.
---
### Биометрия
Аутентификация с помощью биометрических данных является одним из наиболее надёжных методов защиты информации. Она позволяет идентифицировать пользователя на основе его уникальных физических характеристик (отпечаток пальца, лицо).
**Процесс аутентификации:**
1. Выберите «Быстрый вход».
2. Приложите палец или отсканируйте лицо.
> **Примечание**
>
> 1. Данный способ аутентификации работает на устройствах, поддерживающих работу с биометрическими данными.
> 2. Для того чтобы использовать данный способ аутентификации, необходимо предварительно пройти регистрацию биометрических данных при входе через логин и пароль.
---
### Навигация
- [← Что такое Alfa ID](/products/alfa-api/documentation/articles/alfa-id/articles/intro/intro)
- [Кнопка входа по Alfa ID →](/products/alfa-api/documentation/articles/alfa-id/articles/button/button)
]]>
</authentication_md>
<Authorization_Code_Flow>
<access_token_refresh_POST_md>
<![CDATA[
# Обновление токена доступа
**Тип интеграции:** B2B, B2C
## Эндпоинты
| Окружение | Метод и URL |
| :------------ | :-------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/oidc/token` |
| **Пром** | `POST https://baas.alfabank.ru/oidc/token` |
---
## Описание
> **Внимание**
> Токен обновления действует 180 дней и не может быть использован более 2 раз.
> **Внимание**
> Токен обновления может быть отозван в случае, если:
>
> - пользователь сменил пароль;
> - пользователь превысил допустимое количество попыток ввода пароля;
> - аккаунт пользователя был заблокирован.
В результате запроса, помимо нового токена доступа, вы также получите новый токен обновления, а старый `refresh_token` станет недействительным.
При использовании `curl` запроса с заголовком `"Content-Type": "application/x-www-form-urlencoded"` необходимо экранировать специальные символы параметра `client_secret`. В то время как `redirect_uri` экранировать не нужно.
Если запрос отправляется через Postman с заголовком `"Content-Type": "application/x-www-form-urlencoded"` и `body` в формате `x-www-form-urlencoded` — нет необходимости экранировать специальные символы.
Подробную информацию по экранированию можно посмотреть [здесь](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--------------- | :----- | :------------- | :---------------------------------- |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | required | `application/x-www-form-urlencoded` |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| **grant_type** | string | required | Тип гранта. Возможные значения: `refresh_token` |
| **refresh_token** | string | required | Токен обновления. Обновить `access_token` через `refresh_token` можно только 2 раза. В дальнейшем необходимо использовать новый `refresh_token` |
| **client_id** | string | required | Идентификатор партнёрского сервиса |
| **client_secret** | string | required | Секретный ключ партнёрского сервиса |
---
## Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=13b8230b-b6bf-4bb9-b977-3bc0a988a5fd' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**HEADERS**
- **Content-Type**: `application/json`
- **Cache-Control**: `no-store`
- **Pragma**: `no-cache`
**BODY**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **access_token** | string | required | Токен доступа |
| **refresh_token** | string | required | Токен обновления |
| **token_type** | string | required | Тип токена (например, `Bearer`) |
| **expires_in** | integer | optional | Срок жизни токена в секундах |
**Пример JSON-ответа:**
```json
{
"access_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
"refresh_token": "2cc8d34c-130a-4674-91fa-f9835fff6e88",
"token_type": "Bearer",
"expires_in": 3600
}
```
---
### Ошибка (400 Bad Request)
**BODY**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки. Возможные значения: `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | optional | Описание ошибки |
---
## Навигация
- [← Получение профиля представителя пользователя](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-profile-info/v1/get-profile-info)
- [Как использовать ACF для H2H →](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro)
]]>
</access_token_refresh_POST_md>
<how_to_use_ACF_md>
<![CDATA[
# Как использовать ACF
**Теги:** `B2B` `B2C`
Вы можете использовать **Authorization Code Flow** в своих приложениях для получения доступа к защищённым ресурсам Alfa API. Доступ осуществляется с помощью `access_token`, который Вы получаете после аутентификации пользователя и подписания им согласия на передачу данных.
Также с помощью полученного `access_token` Вы сможете:
1. **Реализовать процесс бесшовной аутентификации** между партнёром и Банком.
2. **Получить доступ к операциям или документам других организаций** (при наличии от них согласия) для предоставления услуг B2B / B2C SaaS. Подходит для облачных бухгалтерий, маркетплейсов, CRM и других.
`access_token`, полученный по **Authorization Code Flow**, даёт возможность переходить между банковскими приложениями и приложениями партнёра без дополнительной аутентификации.
В рамках **Authorization Code Flow** доступны все сервисы, реализованные в Alfa API.
---
### Шаги авторизации
1. **Получение кода авторизации**
2. **Получение токена доступа**
3. **Получение информации о профиле представителя ЮЛ/ФЛ**
4. **Проверка подписи**
5. **Перенаправление авторизованного пользователя на ваш ресурс**
---
### Согласия пользователей
- **Срок жизни согласия:** 365 дней.
- **Продление:** После истечения срока необходимо заново пройти авторизацию. Для этого в параметре запроса на получение кода авторизации нужно передать параметр `prompt = consent`.
- **Проверка статуса:** Узнать дату окончания действия согласия можно с помощью метода [Данные по согласиям пользователей](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/client-consents/v1/client-consents).
---
### Дополнительно
При необходимости вы можете:
- [Обновить токен](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/token-update/v1/token-update)
- [Отозвать токен](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/revoke-token/v1/revoke-token)
---
**Навигация:**
← [Кнопка входа по Alfa ID](/products/alfa-api/documentation/articles/alfa-id/articles/button/button) | [Получение кода авторизации](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-auth-code/v1/get-auth-code) →
---
_Примечание: В данном документе используются относительные ссылки. Для перехода по ним используйте базовый адрес портала (developers.alfabank.ru)._
]]>
</how_to_use_ACF_md>
<obtaining_an_access_token_POST_md>
<![CDATA[
# Получение токена доступа
**Тип интеграции:** B2B, B2C
**Метод:** `POST`
## Эндпоинты
| Среда | URL |
| :------------ | :--------------------------------------- |
| **Песочница** | `https://sandbox.alfabank.ru/oidc/token` |
| **Пром** | `https://baas.alfabank.ru/oidc/token` |
---
## Описание
В результате выполнения запроса будет получено три токена: `access_token`, `refresh_token`, `id_token`.
> **Внимание**
>
> - Токен доступа действует **1 час**.
> - Токен доступа может быть отозван в случае, если:
> - пользователь сменил пароль;
> - пользователь превысил допустимое количество попыток ввода пароля;
> - аккаунт пользователя был заблокирован;
> - срок жизни согласия пользователя истёк.
### Особенности передачи параметров
- При использовании `curl` с заголовком `"Content-Type": "application/x-www-form-urlencoded"` необходимо **экранировать** специальные символы параметра `client_secret`. Параметр `redirect_uri` экранировать не нужно.
- Если запрос отправляется через **Postman** (body в формате `x-www-form-urlencoded`) — экранировать специальные символы не требуется.
Подробную информацию по экранированию можно посмотреть [здесь](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--------------- | :----- | :---- | :---------------------------------- |
| **Accept** | string | Да | `application/json` |
| **Content-Type** | string | Да | `application/x-www-form-urlencoded` |
### BODY (x-www-form-urlencoded)
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :----- | :---- | :--------------------------------------------------- |
| **grant_type** | string | Да | Тип гранта. Возможные значения: `authorization_code` |
| **code** | string | Да | Код авторизации |
| **client_id** | string | Да | Идентификатор партнёрского сервиса |
| **client_secret** | string | Да | Секретный ключ партнёрского сервиса |
| **redirect_uri** | string | Да | URI перенаправления |
| **code_verifier** | string | Нет | Код верификатор |
---
## Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=8962c304-89b1-11ec-a8a3-0242ac120002' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!' \
--data-urlencode 'redirect_uri=https://wwww.partner.ru/code' \
--data-urlencode 'code_verifier=string'
```
---
## Параметры ответа
### Ответ 200 (OK)
**HEADERS**
- `Content-Type`: `application/json`
- `Cache-Control`: `no-store`
- `Pragma`: `no-cache`
**BODY**
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **access_token** | string | Да | Токен доступа |
| **refresh_token** | string | Да | Токен обновления |
| **token_type** | string | Да | Тип токена (обычно `Bearer`) |
| **expires_in** | integer | Нет | Срок жизни токена в секундах |
| **id_token** | string | Да | Идентификационный токен |
**Пример JSON-ответа:**
```json
{
"access_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
"refresh_token": "13b8230b-b6bf-4bb9-b977-3bc0a988a5fd",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ..."
}
```
---
### Ответ 400 (Bad Request)
| Атрибут | Тип | Обяз. | Описание |
| :-------------------- | :----- | :---- | :--------------------------------------- |
| **error** | string | Да | Код ошибки (например, `invalid_request`) |
| **error_description** | string | Нет | Описание ошибки |
---
## Таблица возможных значений параметра error
| Значение | Описание |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `invalid_request` | Отсутствует обязательный параметр, неподдерживаемое значение, повторение параметра или неправильный формат запроса. |
| `invalid_client` | Ошибка аутентификации клиента (неизвестный клиент или неподдерживаемый метод). |
| `invalid_grant` | Недействительный код авторизации, токен обновления или несоответствие URI перенаправления. |
| `unsupported_grant_type` | Тип `grant_type` не поддерживается сервером. |
| `internal_error` | Произошла непредвиденная ошибка. |
---
## Описание клэймов (claims)
### access_token
| Значение | Описание |
| :----------------- | :----------------------------------------------------- |
| **iss** | URL-адрес Alfa ID (https://id.alfabank.ru/oidc) |
| **sub** | Уникальный идентификатор Alfa ID пользователя |
| **aud** | Идентификатор сервиса-партнёра (аудитория токена) |
| **exp** | Время окончания срока действия токена (Unix timestamp) |
| **iat** | Время выпуска токена (Unix timestamp) |
| **scope_claims** | Массив клэймов области применения |
| **scope_services** | Массив операций области применения |
### id_token
| Значение | Описание | Scope |
| :------------ | :--------------------------------------- | :----- |
| **iss** | URL-адрес Alfa ID | openid |
| **sub** | Уникальный идентификатор пользователя | openid |
| **aud** | Идентификатор сервиса-партнёра | openid |
| **exp** | Время окончания срока действия | openid |
| **iat** | Время выпуска | openid |
| **auth_time** | Время аутентификации пользователя | openid |
| **nonce** | Строка для защиты от повторных атак | openid |
| **acr** | Способ аутентификации пользователя | openid |
| **azp** | Сторона, которой выдан токен (client_id) | openid |
]]>
</obtaining_an_access_token_POST_md>
<obtaining_an_authorization_code_GET_md>
<![CDATA[
Вот преобразованный в Markdown контент вашего HTML-файла. Я сохранил структуру шагов, таблицы параметров, примеры кода и ссылки на изображения.
---
# Получение кода авторизации
**Теги:** `B2B` `B2C`
Процесс получения кода авторизации в сценарии **Authorization Code Flow** состоит из нескольких шагов.
---
### Краткий обзор шагов
1. Отобразите пользователю кнопку "Войти по Alfa ID".
2. Сформируйте ссылку для авторизации.
3. Переадресуйте пользователя для прохождения аутентификации.
4. Получите код авторизации в ответе от Alfa ID.
5. Alfa ID возвращает пользователя на Ваш ресурс по указанному `redirect_uri`.
---
### Шаг 1. Кнопка «Войти по Alfa ID»
Пользователь переходит по встроенной кнопке на Вашем ресурсе.
![windowAlfaId](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf/articles/get-auth-code/v1/files/picture3.png)
---
### Шаг 2. Формирование ссылки
#### Эндпоинты
* **Песочница:**
`GET https://id-sandbox.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`
* **Пром:**
`GET https://id.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`
> **Важно:** При формировании ссылки указывайте весь доступный `scope` через знак пробела или `%20`. Параметр `prompt=consent` используйте только если нужно, чтобы пользователь повторно подписал согласие.
#### Параметры запроса (QUERY)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| `response_type` | string | Да | Тип ответа. Возможные значения: `code` |
| `client_id` | string | Да | Идентификатор партнёрского сервиса (выдается банком) |
| `redirect_uri` | string | Да | URI для перенаправления пользователя после успешной авторизации |
| `scope` | string | Да | Область применения (информирует, какие данные будут использованы) |
| `state` | string | Да | Параметр для защиты от CSRF. UUID, 36 символов. |
| `nonce` | string | Нет | Строка для связи сессии с ID-токеном и защиты от повторных атак |
| `code_challenge` | string | Нет | Код вызова |
| `code_challenge_method` | string | Нет | Метод преобразования: `plain` или `S256` |
| `prompt` | string | Нет | Параметр повторной аутентификации: `none`, `login`, `consent` |
| `max_age` | string | Нет | Максимальный период аутентификации |
#### Пример запроса
```bash
curl -X GET https://id.alfabank.ru/oidc/authorize?response_type=code&client_id=0cee0683-85ae-49f2-a63d-29f97aad1911&redirect_uri=https%3A%2F%2Fwwww.partner.ru%2Fcode&scope=openid&state=abcdef
```
---
### Шаг 3. Аутентификация пользователя
1. Пользователь проходит процедуру аутентификации.
![loginPassword](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf/articles/get-auth-code/v1/files/picture4.png)
2. Пользователь выбирает организацию (для ЮЛ; для ФЛ шаг пропускается).
![organisationUL](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf/articles/get-auth-code/v1/files/picture6.png)
3. Пользователь подписывает форму согласия.
![signForm](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf/articles/get-auth-code/v1/files/signForm.png)
---
### Шаг 4. Получение кода авторизации
Код авторизации получен, если пришел ответ **302 Found**.
> **Внимание:** Код авторизации действует **2 минуты** и может быть использован только **1 раз**.
#### Пример успешного ответа
```bash
https://wwww.partner.ru/code?code=8962c304-89b1-11ec-a8a3-0242ac120002&state=abcdef
-H 'Location: https://wwww.partner.ru/code?code=8962c304-89b1-11ec-a8a3-0242ac120002&state=abcdef'
-H 'Set-Cookie: ALFASESSIONID=f9e9532f-7b06-4023-83a2-f6cc77a7bfe4'
```
#### Параметры ответа (302 Found)
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| `Location` | string | Содержит URI перенаправления вида: `redirect_uri?code={code}&state={state}` |
| `Set-Cookie` | string | Содержит идентификатор сессии |
---
### Ошибки
В случае неуспешного выполнения запроса в заголовке `Location` передаётся строка вида: `redirect_uri_error_page?error={error}`.
#### Таблица возможных значений параметра error
| Значение | Описание |
| :--- | :--- |
| `unsupported_response_type` | Сервер не поддерживает получение кода этим методом |
| `login_required` | Необходима аутентификация (возникает при `prompt=none`) |
| `invalid_scope` | Недопустимая или неизвестная область применения |
| `invalid_request` | Отсутствует обязательный параметр или неверный формат запроса |
| `consent_required` | Необходимо согласие пользователя (возникает при `prompt=none`) |
| `access_denied` | Владелец ресурса или сервер отклонил запрос |
| `invalid_operation_response` | Используйте только данные из спецификации ACF |
| `login_expired` | Пользователь не прошел аутентификацию за 15 минут или сделал logout |
---
**Далее:** [Получение токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-access-token/v1/get-access-token)
]]>
</obtaining_an_authorization_code_GET_md>
<obtaining_a_user_representative_profile_md>
<![CDATA[
# Получение профиля представителя пользователя `B2B` `B2C`
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :---------------------------------------------- |
| **Песочница** | `GET https://sandbox.alfabank.ru/oidc/userinfo` |
| **Пром** | `GET https://baas.alfabank.ru/oidc/userinfo` |
---
## Описание
Для идентификации пользователя выполняется запрос на получение информации о профиле представителя ЮЛ/ФЛ.
- **Входящие параметры:** `access_token`.
- **Исходящие параметры:** данные пользователя, на передачу которых от пользователя есть разрешение.
> Для каждого Партнёра API перечень допустимых клэймов настраивается индивидуально.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :-------------------- |
| **Authorization** | string | required | Bearer {access_token} |
| **Accept** | string | required | application/jwt |
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/userinfo' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/jwt'
```
---
## Параметры ответа
### 200 OK
**Headers:**
- `Content-Type: application/jwt` (optional)
**Пример ответа (JWT):**
```text
eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJjdXMiOiJVQUFBQUEiLCJzdWIiOiIzMjI4ZTY4ZS1jYzM0LTRiODItYjQzZC00OTExMmI1ZDlkM2UiLCJiaXJ0aGRhdGUiOiIyMDAwLTAyLTIwIiwicm9sZSI6IkFDQ09VTlRBTlQsIE1BTkFHRVIiLCJnZW5kZXIiOiJNQUxFIiwiaWRlbnRpdHlfZG9jdW1lbnRfbmFtZSI6ItCf0LDRgdC_0L7RgNGCINCz0YDQsNC20LTQsNC90LjQvdCwINCg0KQiLCJpZGVudGl0eV9kb2N1bWVudF9udW1iZXIiOjIyMjIyMiwiaXNzIjoiaHR0cHM6XC9cL2JhYXMuYWxmYWJhbmsucnUiLCJpbm4iOjc0MTUxMTExMjIyMiwiZWlvIjp0cnVlLCJnaXZlbl9uYW1lIjoi0KLQtdGB0YIiLCJtaWRkbGVfbmFtZSI6ItCi0LXRgdGC0L7QstC40YciLCJhY3VzIjoiWEFBQUFBIiwiaWRlbnRpdHlfZG9jdW1lbnRfc2VyaWVzIjoxMTExLCJhdWQiOiIwY2VlMDY4My04NWFlLTQ5ZjItYTYzZC0yOWY5N2FhZDE5MTEiLCJhY2xjIjoiWEFBQUExIiwidXBkYXRlZF9hdCI6IjIwMjItMDEtMjAiLCJuYW1lIjoi0KLQtdGB0YLQvtCyINCi0LXRgdGCINCi0LXRgdGC0L7QstC40YciLCJwaG9uZV9udW1iZXIiOjc5MTkxMTEyMjMzLCJjbGMiOiJVQUFBQTEiLCJmYW1pbHlfbmFtZSI6ItCi0LXRgdGC0L7QsiIsImVtYWlsIjoiZW1haWxAZW1haWwucnUifQ.WVr5xkQSEGqpPXN3aIo0zHZLDL0vvtxEEQ83BrgJo7l0BjjALeGDRYENF2bL8j3n1pXRnduiBQcYNV6teBhESI8V_8kd7Kh7LTePkJWadPSvD__KskC69b4XZ-zN-IQ73NmAcBDStnnhSXGKL6xhdRy-TGiAoKPsRWiDVntsDlpCQNHAt3tJk8q_SQS4S1k6qju9eJ2GFkgmd6z8rR2vaBykaOF0K61ltksw6YgXhuek3OlYkqIAivyKYl59uio8zMpJk-YrPlmawwmvWPF0vKhaLj8Mvn4mVMsVSfuVVKP2ksHG0MAlWpO3Sh9GoKO4d6TQplJ4vgIIeNx-44npqw
```
### 400 Bad Request
**Body:**
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :------------------------------------------------------------------------------------- |
| **error** | string | required | Код ошибки. Принимает значения: `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | optional | Описание ошибки |
---
## Описание клэймов UserInfo
| Name | Description | Scope |
| :-------------- | :-------------------------------------------------------------------- | :------------------ |
| **iss** | URL-адрес Alfa ID по протоколу https (https://id.alfabank.ru/oidc) | openid |
| **sub** | Уникальный идентификатор Alfa ID пользователя (до 255 символов ASCII) | openid |
| **aud** | Идентификатор сервиса-партнёра (аудитория токена) | openid |
| **name** | Полное имя конечного пользователя в отображаемой форме | profile, name |
| **given_name** | Имя конечного пользователя | profile, givenname |
| **family_name** | Фамилия конечного пользователя | profile, familyname |
| **middle_name** | Отчество конечного пользователя | profile, middlename |
| **email** | Предпочтительный адрес электронной почты | email |
| **gender** | Пол конечного пользователя | profile, gender |
| **birthdate** | День рождения в формате `YYYY-MM-DD` | profile, birthdate |
]]>
</obtaining_a_user_representative_profile_md>
</Authorization_Code_Flow>
<Authorization_Code_Flow_for_H2H_Integrations>
<geting_access_token_POST_md>
<![CDATA[
# Получение токена доступа `H2H` `POST`
### Эндпоинты
| Окружение | Метод и URL |
| :------------ | :-------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/oidc/token` |
| **Пром** | `POST https://baas.alfabank.ru/oidc/token` |
---
### Описание
В результате запроса будет получено три токена: `access_token`, `refresh_token`, `id_token`.
> **Внимание**
> Токен доступа действует **1 час**.
> **Внимание**
> Токен доступа может быть отозван в случае, если:
>
> - пользователь сменил пароль;
> - пользователь превысил допустимое количество попыток ввода пароля;
> - аккаунт пользователя был заблокирован.
При использовании `curl` запроса с заголовком `"Content-Type": "application/x-www-form-urlencoded"` необходимо экранировать специальные символы параметра `client_secret`. В то время как `redirect_uri` экранировать не нужно.
Если запрос отправляется через Postman с заголовком `"Content-Type": "application/x-www-form-urlencoded"` и `body` в формате `x-www-form-urlencoded` — нет необходимости экранировать специальные символы.
Подробную информацию по экранированию можно посмотреть [здесь](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening).
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--------------- | :----- | :------------- | :---------------------------------- |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | required | `application/x-www-form-urlencoded` |
#### BODY
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :--------------------------------------------------- |
| **grant_type** | string | required | Тип гранта. Возможные значения: `authorization_code` |
| **code** | string | required | Код авторизации |
| **client_id** | string | required | Идентификатор партнёрского сервиса |
| **client_secret** | string | required | Секретный ключ партнёрского сервиса |
| **redirect_uri** | string | required | URI перенаправления |
| **code_verifier** | string | optional | Код верификатор |
---
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=8962c304-89b1-11ec-a8a3-0242ac120002' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!' \
--data-urlencode 'redirect_uri=https://wwww.partner.ru/code' \
--data-urlencode 'code_verifier=string'
```
---
### Параметры ответа
#### Пример ответа 200 (OK)
```json
{
"access_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
"refresh_token": "13b8230b-b6bf-4bb9-b977-3bc0a988a5fd",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ..."
}
```
#### Описание полей BODY (200 OK)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :------ | :------------- | :--------------------------- |
| **access_token** | string | required | Токен доступа |
| **refresh_token** | string | required | Токен обновления |
| **token_type** | string | required | Тип токена |
| **expires_in** | integer | optional | Срок жизни токена в секундах |
| **id_token** | string | required | Идентификационный токен |
---
### Ошибки (400 Bad Request)
| Значение | Описание |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **invalid_request** | Отсутствует обязательный параметр, неподдерживаемое значение параметра (кроме grant_type), повторение параметра, несколько учётных данных или неправильный формат запроса |
| **invalid_client** | Ошибка аутентификации клиента (неизвестный клиент, отключенная аутентификация клиента или неподдерживаемый метод аутентификации) |
| **invalid_grant** | Недействительное разрешение авторизации (недействительный код авторизации, токен обновления или несоответствие URI перенаправления) |
| **unsupported_grant_type** | Тип разрешения на авторизацию (grant_type) не поддерживается сервером авторизации |
| **internal_error** | Произошла непредвиденная ошибка |
---
### Описание клэймов access_token
| Значение | Описание |
| :----------------- | :-------------------------------------------------------------------- |
| **iss** | URL-адрес Alfa ID по протоколу https (https://id.alfabank.ru/oidc) |
| **sub** | Уникальный идентификатор Alfa ID пользователя (до 255 символов ASCII) |
| **aud** | Идентификатор сервиса-партнёра (аудитория токена) |
| **exp** | Время окончания срока действия токена (Unix timestamp UTC) |
| **iat** | Время выпуска токена (Unix timestamp UTC) |
| **scope_claims** | Массив клэймов области применения |
| **scope_services** | Массив операций области применения |
---
### Описание клэймов ID_TOKEN
| Значение | Описание | Scope |
| :------------ | :--------------------------------------------------- | :----- |
| **iss** | URL-адрес Alfa ID | openid |
| **sub** | Уникальный идентификатор пользователя | openid |
| **aud** | Идентификатор сервиса-партнёра | openid |
| **exp** | Время окончания срока действия | openid |
| **iat** | Время выпуска | openid |
| **auth_time** | Время аутентификации пользователя | openid |
| **nonce** | Значение для связи сессии и защиты от повторных атак | openid |
| **acr** | Способ аутентификации пользователя | openid |
| **azp** | Сторона, которой выдан токен (client_id) | openid |
---
**Навигация:**
- [← Получение кода авторизации](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/get-auth-code/v1/get-auth-code)
- [Обновление токена доступа →](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/token-update/v1/token-update)
]]>
</geting_access_token_POST_md>
<How_to_use_ACF_for_H2H_md>
<![CDATA[
# Как использовать ACF для H2H
**Тег:** `H2H`
Вы можете использовать **Authorization Code Flow для H2H-интеграций** как канал взаимодействия ваших автоматизированных систем с Банком по операциям Вашей организации.
С помощью `access_token`, полученного по **Authorization Code Flow для H2H-интеграций**, Вы сможете встроить банковские продукты в ERP-систему организации для выполнения запросов и операций только по своей организации.
### Шаги авторизации
1. **Формирование ссылки и редирект сотрудника**
2. **Получение кода авторизации**
3. **Получение токена доступа**
### Дополнительно
При необходимости вы можете [обновить](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/token-update/v1/token-update) токен или [отозвать](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/revoke-token/v1/revoke-token) его.
---
#### Навигация по разделу:
- ← [Обновление токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/token-update/v1/token-update)
- → [Получение кода авторизации](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/get-auth-code/v1/get-auth-code)
---
### Структура меню (Alfa ID):
- [Что такое Alfa ID](/products/alfa-api/documentation/articles/alfa-id/articles/intro/intro)
- [Аутентификация](/products/alfa-api/documentation/articles/alfa-id/articles/authentication/authentication)
- [Кнопка входа по Alfa ID](/products/alfa-api/documentation/articles/alfa-id/articles/button/button)
- [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/acf)
- **Authorization Code Flow для H2H-интеграций**
- [Как использовать ACF для H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) (Текущая страница)
- [Получение кода авторизации](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/get-auth-code/v1/get-auth-code)
- [Получение токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/get-access-token/v1/get-access-token) `POST`
- [Обновление токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/token-update/v1/token-update) `POST`
- [Authorization Code Flow для холдингов](/products/alfa-api/documentation/articles/alfa-id/articles/acf-holding/acf-holding)
- [Client Credentials Flow](/products/alfa-api/documentation/articles/alfa-id/articles/ccf/ccf)
- [Расширение сценариев](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/expansion)
- [Экранирование](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening)
]]>
</How_to_use_ACF_for_H2H_md>
<obtaining_an_authorization_code_md>
<![CDATA[
# Получение кода авторизации
**Тип интеграции:** `H2H`
### Шаг 1. Формирование ссылки
Для получения кода авторизации необходимо сформировать GET-запрос.
#### Эндпоинты:
- **Песочница:**
`GET https://id-sandbox.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`
- **Пром:**
`GET https://id.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`
#### Параметры:
- `{client_id}` — идентификатор приложения Партнёра API, полученный после регистрации приложения на стороне Банка.
- `{redirect_uri}` — URI-адрес перенаправления для получения кода авторизации (можно использовать [http://localhost](http://localhost)).
- `{scope}` — области применения токена доступа, указывают, какие права должен содержать токен доступа (можно указать несколько через пробел), должны быть озвучены при регистрации приложения на стороне Банка. Например, для получения выписки необходимо указать `openid transactions`.
- `{state}` — любое строковое значение для защиты от CSRF, например `string12345`.
**Пример итоговой ссылки:**
[https://id.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri=http://localhost&scope=openid transactions&state=string12345](https://id.alfabank.ru/oidc/authorize?response_type=code&client_id=%7Bclient_id%7D&redirect_uri=http://localhost&scope=openid%20transactions&state=string12345)
> **Внимание**
> Не забывайте заменить `{client_id}` на реальное значение, полученное после регистрации приложения на стороне Банка.
---
### Шаг 2. Аутентификация
1. В окне браузера отобразится страница аутентификации Alfa ID для ввода логина/пароля пользователя:
![authAlfaID](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-h2h/articles/get-auth-code/v1/files/picture8.png)
2. После ввода логина/пароля пользователя отобразится страница второго фактора аутентификации для ввода otp-кода (sms, push):
![otpCode](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-h2h/articles/get-auth-code/v1/files/picture9.png)
3. Необходимо ввести полученный на телефон otp-код (sms, push), и в адресной строке браузера отобразится код авторизации (`code`):
![authorizationCode](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-h2h/articles/get-auth-code/v1/files/picture11.jpg)
---
### Шаг 3. Получение кода авторизации
Полученное в браузере **значение кода авторизации** (параметр `code` в URL) необходимо скопировать и **обменять на [токен доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/get-access-token/v1/get-access-token)**.
> **Внимание**
> Код авторизации по умолчанию действует **2 минуты** и может быть использован только **1 раз**.
---
**Навигация:**
- [← Как использовать ACF для H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro)
- [Получение токена доступа →](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/get-access-token/v1/get-access-token)
]]>
</obtaining_an_authorization_code_md>
<refreshing_access_token_POST_md>
<![CDATA[
# Обновление токена доступа
**Тип интеграции:** H2H (Host-to-Host)
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :-------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/oidc/token` |
| **Пром** | `POST https://baas.alfabank.ru/oidc/token` |
## Описание
В результате запроса, помимо нового токена доступа, вы также получите новый токен обновления, а старый `refresh_token` станет недействительным.
> [!IMPORTANT]
> **Внимание**
>
> - Токен обновления действует **180 дней** и не может быть использован более **2 раз**.
> - Токен обновления может быть отозван, если:
> - пользователь сменил пароль;
> - пользователь превысил допустимое количество попыток ввода пароля;
> - аккаунт пользователя был заблокирован.
### Особенности кодирования
- При использовании `curl` с заголовком `"Content-Type": "application/x-www-form-urlencoded"` необходимо экранировать специальные символы параметра `client_secret`. Параметр `redirect_uri` экранировать не нужно.
- Если запрос отправляется через **Postman** с телом в формате `x-www-form-urlencoded` — экранировать символы вручную не требуется.
- Подробную информацию по экранированию можно посмотреть [здесь](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--------------- | :----- | :------------- | :---------------------------------- |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | required | `application/x-www-form-urlencoded` |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :-------------------------------------------------------------------------------------------------------------------- |
| **grant_type** | string | required | Тип гранта. Возможные значения: `refresh_token` |
| **refresh_token** | string | required | Токен обновления. Обновить `access_token` можно только 2 раза. В дальнейшем нужно использовать новый `refresh_token`. |
| **client_id** | string | required | Идентификатор партнёрского сервиса. |
| **client_secret** | string | required | Секретный ключ партнёрского сервиса. |
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=13b8230b-b6bf-4bb9-b977-3bc0a988a5fd' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**BODY**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **access_token** | string | required | Новый токен доступа. |
| **refresh_token** | string | required | Новый токен обновления. |
| **token_type** | string | required | Тип токена (обычно `Bearer`). |
| **expires_in** | integer | optional | Срок жизни токена в секундах. |
**Пример ответа:**
```json
{
"access_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
"refresh_token": "2cc8d34c-130a-4674-91fa-f9835fff6e88",
"token_type": "Bearer",
"expires_in": 3600
}
```
### Ошибка (400 Bad Request)
**BODY**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки. Например: `invalid_request` (неверные входные параметры). |
| **error_description** | string | optional | Текстовое описание ошибки. |
---
## Дополнительная информация
### Таблица возможных значений параметра error
| Значение | Описание |
| :----------------------- | :---------------------------------------------------------------------------------------------------------- |
| `invalid_request` | Отсутствует обязательный параметр, неподдерживаемое значение, повторение параметра или неправильный формат. |
| `invalid_client` | Ошибка аутентификации клиента (неизвестный ID или неверный secret). |
| `invalid_grant` | Недействительный токен обновления или несоответствие URI. |
| `unsupported_grant_type` | Тип `grant_type` не поддерживается сервером. |
| `internal_error` | Внутренняя ошибка сервера. |
### Описание клэймов access_token
| Значение | Описание |
| :----------------- | :----------------------------------------------- |
| **iss** | URL-адрес Alfa ID (https://id.alfabank.ru/oidc). |
| **sub** | Уникальный идентификатор пользователя. |
| **aud** | Идентификатор сервиса-партнёра (аудитория). |
| **exp** | Время окончания срока действия (Unix timestamp). |
| **iat** | Время выпуска токена. |
| **scope_claims** | Массив клэймов области применения. |
| **scope_services** | Массив операций области применения. |
]]>
</refreshing_access_token_POST_md>
</Authorization_Code_Flow_for_H2H_Integrations>
<Authorization_Code_Flow_for_Holding_Companies>
<access_token_refresh_md>
<![CDATA[
# Обновление токена доступа
**Типы интеграции:** `B2B`, `H2H`
## Эндпоинты
| Окружение | Метод | URL |
| :------------ | :----- | :--------------------------------------- |
| **Песочница** | `POST` | `https://sandbox.alfabank.ru/oidc/token` |
| **Пром** | `POST` | `https://baas.alfabank.ru/oidc/token` |
---
## Описание
В результате запроса, помимо нового токена доступа, вы также получите новый токен обновления, а старый `refresh_token` станет недействительным.
> **Внимание**
>
> - Токен обновления действует **180 дней** и не может быть использован **более 2 раз**.
> - При использовании `curl` запроса с заголовком `"Content-Type": "application/x-www-form-urlencoded"` необходимо экранировать специальные символы параметра `client_secret`. При этом `redirect_uri` экранировать не нужно.
> - Если запрос отправляется через **Postman** с телом в формате `x-www-form-urlencoded` — экранировать символы не нужно.
> - Подробную информацию по экранированию можно посмотреть [здесь](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening).
### Токен обновления может быть отозван, если:
- пользователь сменил пароль;
- пользователь превысил допустимое количество попыток ввода пароля;
- аккаунт пользователя был заблокирован.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--------------- | :----- | :---- | :---------------------------------- |
| **Accept** | string | Да | `application/json` |
| **Content-Type** | string | Да | `application/x-www-form-urlencoded` |
### BODY (x-www-form-urlencoded)
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :----- | :---- | :-------------------------------------------------- |
| **grant_type** | string | Да | Тип гранта. Значение: `refresh_token` |
| **refresh_token** | string | Да | Токен обновления. Можно использовать только 2 раза. |
| **client_id** | string | Да | Идентификатор партнёрского сервиса |
| **client_secret** | string | Да | Секретный ключ партнёрского сервиса |
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=13b8230b-b6bf-4bb9-b977-3bc0a988a5fd' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Описание |
| :---------------- | :------ | :----------------------------------- |
| **access_token** | string | Новый токен доступа |
| **refresh_token** | string | Новый токен обновления |
| **token_type** | string | Тип токена (обычно `Bearer`) |
| **expires_in** | integer | Срок жизни токена доступа в секундах |
**Пример ответа 200:**
```json
{
"access_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0...",
"refresh_token": "2cc8d34c-130a-4674-91fa-f9835fff6e88",
"token_type": "Bearer",
"expires_in": 3600
}
```
### Ошибка (400 Bad Request)
| Атрибут | Тип | Описание |
| :-------------------- | :----- | :--------------------------------------- |
| **error** | string | Код ошибки (например, `invalid_request`) |
| **error_description** | string | Описание ошибки |
---
## Справочные таблицы
### Возможные значения параметра error
| Значение | Описание |
| :----------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `invalid_request` | Отсутствует обязательный параметр, неподдерживаемое значение, повторение параметра или неверный формат запроса. |
| `invalid_client` | Ошибка аутентификации клиента (неизвестный клиент или неверный `client_secret`). |
| `invalid_grant` | Недействительный `refresh_token`. |
| `unsupported_grant_type` | Тип `grant_type` не поддерживается сервером. |
| `internal_error` | Произошла непредвиденная ошибка на стороне сервера. |
### Описание клэймов access_token
| Клэйм | Описание |
| :----------------- | :----------------------------------------------------- |
| **iss** | URL-адрес Alfa ID (https://id.alfabank.ru/oidc) |
| **sub** | Уникальный идентификатор Alfa ID пользователя |
| **aud** | Идентификатор сервиса-партнёра (аудитория токена) |
| **exp** | Время окончания срока действия токена (Unix Timestamp) |
| **iat** | Время выпуска токена (Unix Timestamp) |
| **scope_claims** | Массив клэймов области применения |
| **scope_services** | Массив операций области применения |
---
**Полезные ссылки:**
- [Новости в Telegram](https://t.me/AlfaAPI)
- [Общая спецификация Alfa API](/products/alfa-api/documentation/articles/specification/specification)
- [Инструкция по подключению](/products/alfa-api/documentation/articles/connection/connection)
]]>
</access_token_refresh_md>
<getting_authorization_token_md>
<![CDATA[
# Получение кода авторизации
**Теги:** `B2B` `H2H`
Процесс получения кода авторизации состоит из трех основных этапов:
1. Сформируйте ссылку.
2. Переадресация дочерней компании для прохождения аутентификации.
3. Получение кода авторизации.
---
## Шаг 1. Формирование ссылки
### Эндпоинты
- **Песочница:**
`GET https://id-sandbox.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`
- **Пром:**
`GET https://id.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`
### Описание
Ссылка должна содержать обязательные параметры, указанные ниже в таблице. Также опционально могут быть использованы необязательные параметры.
При формировании ссылки указывайте весь доступный `scope` через знак пробела или (`%20`). Дополнительный параметр `prompt=consent` использовать только в том случае, если необходимо, чтобы дочерняя компания подписала/переподписала новое согласие.
Сформированную ссылку необходимо передать своим дочерним компаниям.
### Параметры запроса (QUERY)
| Атрибут | Тип | Обязательность | Описание |
| :------------------------ | :----- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **response_type** | string | required | Тип ответа. Возможные значения: `code` |
| **client_id** | string | required | Идентификатор партнёрского сервиса (банк выдает партнёру API) |
| **redirect_uri** | string | required | URI перенаправления, необходимый для переадресации пользователя после успешной авторизации. На этот URI будет отправлен код авторизации. |
| **scope** | string | required | Область применения (партнёр API информирует, какой scope будет использован) |
| **state** | string | required | Параметр для предотвращения межсайтовой подделки запросов. Значение генерирует партнёр (UUID, 36 символов). |
| **nonce** | string | optional | Строковое значение для связи сессии клиента с ID-токеном и защиты от повторных атак. |
| **code_challenge** | string | optional | Код вызова. |
| **code_challenge_method** | string | optional | Метод преобразования кода верификатора. Значения: `plain`, `S256`. |
| **prompt** | string | optional | Параметр повторной аутентификации/согласия. Значения: `none`, `login`, `consent`. |
| **max_age** | string | optional | Максимальный период аутентификации. |
### Пример ссылки
```bash
https://id.alfabank.ru/oidc/authorize?response_type=code&client_id=0cee0683-85ae-49f2-a63d-29f97aad1911&redirect_uri=https%3A%2F%2Fwwww.partner.ru%2Fcode&scope=openid&state=abcdef
```
---
## Шаг 2. Аутентификация дочерней компании
1. При переходе по ссылке дочерняя компания проходит процедуру аутентификации.
![loginPassword](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-holding/articles/get-auth-code/v1/files/picture4.png)
2. Выбирает необходимую организацию (при работе с несколькими юридическими лицами).
![organisationUL](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-holding/articles/get-auth-code/v1/files/picture6.png)
3. Далее проходит процедуру авторизации, **подписывая форму согласия**.
![signForm](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-holding/articles/get-auth-code/v1/files/signForm.png)
4. После прохождения авторизации в адресной строке браузера отобразится код авторизации (`code`). Дочерней компании необходимо скопировать этот код и передать головной компании.
![authorizationCode](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-holding/articles/get-auth-code/v1/files/picture11.jpg)
---
## Шаг 3. Получение кода авторизации
Полученное от дочерней компании **значение кода авторизации** (code) необходимо скопировать и **обменять на [токен доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf-holding/articles/get-access-token/v1/get-access-token)**.
> **Внимание**
> Код авторизации по умолчанию действует **2 минуты** и может быть использован только **1 раз**.
---
**Далее:** [Получение токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf-holding/articles/get-access-token/v1/get-access-token)
**Назад:** [Как использовать ACF для холдингов](/products/alfa-api/documentation/articles/alfa-id/articles/acf-holding/articles/intro/intro)
]]>
</getting_authorization_token_md>
<how_to_use_acf_for_holdings_md>
<![CDATA[
Вот преобразованный в Markdown контент страницы. Я очистил его от лишнего программного кода и навигационных элементов портала, оставив только суть документации, ссылки и структуру.
---
# Как использовать ACF для холдингов
**Теги:** `B2B` `H2H`
Холдинги представляют собой интеграцию, которая включает в себя использования двух сценариев: партнёрские сервисы и прямая интеграция.
С помощью одного `client_id` вы сможете выполнять запросы и операции по своей организации. Для этого необходимо получить `access_token` для прямой интеграции по [Authorization Code Flow для H2H-интеграций](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/acf-h2h).
С помощью второго `client_id` вы сможете выполнять операции по своим дочерним компаниям.
### Видео-инструкция
[Скачать или посмотреть видео](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/acf-holding/articles/intro/files/acf-holding.mp4)
### Шаги авторизации
1. **Формирование ссылки**
2. **Получение кода авторизации**
3. **Получение токена доступа**
### Согласия пользователей
Срок жизни согласия пользователя – **365 дней**, после его истечения необходимо заново пройти авторизацию. Для этого в ссылке на получение кода авторизации необходимо передать параметр `prompt = consent`.
Узнать дату окончания действия согласия можно с помощью метода [Данные по согласиям пользователей](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/client-consents/v1/client-consents).
### Дополнительно
При необходимости вы можете [обновить](/products/alfa-api/documentation/articles/alfa-id/articles/acf-holding/articles/token-update/v1/token-update) токен или [отозвать](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/revoke-token/v1/revoke-token) его.
---
**Навигация:**
← [Обновление токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/token-update/v1/token-update) | [Получение кода авторизации](/products/alfa-api/documentation/articles/alfa-id/articles/acf-holding/articles/get-auth-code/v1/get-auth-code) →
]]>
</how_to_use_acf_for_holdings_md>
<obtaining_an_access_token_md>
<![CDATA[
# Получение токена доступа
### Эндпоинты
| Окружение | Метод | URL |
| :------------ | :----- | :--------------------------------------- |
| **Песочница** | `POST` | `https://sandbox.alfabank.ru/oidc/token` |
| **Пром** | `POST` | `https://baas.alfabank.ru/oidc/token` |
---
### Описание
В результате запроса будет получено три токена: `access_token`, `refresh_token`, `id_token`.
> **⚠️ Внимание**
>
> - Токен доступа действует **1 час**.
> - Токен доступа может быть отозван, если:
> - пользователь сменил пароль;
> - пользователь превысил допустимое количество попыток ввода пароля;
> - аккаунт пользователя был заблокирован;
> - срок жизни согласия пользователя истёк.
#### Особенности кодирования:
- При использовании `curl` с заголовком `"Content-Type": "application/x-www-form-urlencoded"` необходимо **экранировать** специальные символы параметра `client_secret`. Параметр `redirect_uri` экранировать не нужно.
- Если запрос отправляется через **Postman** (формат `x-www-form-urlencoded`) — экранировать символы вручную не требуется.
- Подробную информацию по экранированию можно посмотреть [здесь](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening).
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--------------- | :----- | :------------- | :---------------------------------- |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | required | `application/x-www-form-urlencoded` |
#### BODY
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :--------------------------------------------------- |
| **grant_type** | string | required | Тип гранта. Возможные значения: `authorization_code` |
| **code** | string | required | Код авторизации |
| **client_id** | string | required | Идентификатор партнёрского сервиса |
| **client_secret** | string | required | Секретный ключ партнёрского сервиса |
| **redirect_uri** | string | required | URI перенаправления |
| **code_verifier** | string | optional | Код верификатор |
---
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=8962c304-89b1-11ec-a8a3-0242ac120002' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!' \
--data-urlencode 'redirect_uri=https://wwww.partner.ru/code' \
--data-urlencode 'code_verifier=string'
```
---
### Параметры ответа
#### Пример ответа 200 (OK)
```json
{
"access_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
"refresh_token": "13b8230b-b6bf-4bb9-b977-3bc0a988a5fd",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ..."
}
```
#### Описание полей ответа (BODY)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :------ | :------------- | :--------------------------- |
| **access_token** | string | required | Токен доступа |
| **refresh_token** | string | required | Токен обновления |
| **token_type** | string | required | Тип токена (Bearer) |
| **expires_in** | integer | optional | Срок жизни токена в секундах |
| **id_token** | string | required | Идентификационный токен |
---
### Таблица возможных значений параметра error (400 Bad Request)
| Значение | Описание |
| :----------------------- | :---------------------------------------------------------------------------------------------------------- |
| `invalid_request` | Отсутствует обязательный параметр, неподдерживаемое значение, повторение параметра или неправильный формат. |
| `invalid_client` | Ошибка аутентификации клиента (неизвестный клиент или неверный метод). |
| `invalid_grant` | Недействительный код авторизации, токен обновления или несоответствие URI. |
| `unsupported_grant_type` | Тип `grant_type` не поддерживается сервером. |
| `internal_error` | Произошла непредвиденная ошибка. |
---
### Описание клэймов access_token
| Значение | Описание |
| :----------------- | :------------------------------------------------ |
| **iss** | URL-адрес Alfa ID (https://id.alfabank.ru/oidc) |
| **sub** | Уникальный идентификатор пользователя Alfa ID |
| **aud** | Идентификатор сервиса-партнёра (аудитория токена) |
| **exp** | Время окончания срока действия (Unix timestamp) |
| **iat** | Время выпуска токена |
| **scope_claims** | Массив клэймов области применения |
| **scope_services** | Массив операций области применения |
---
### Описание клэймов ID_TOKEN
| Значение | Описание | Scope |
| :------------ | :-------------------------------------------------- | :----- |
| **iss** | URL-адрес Alfa ID | openid |
| **sub** | Уникальный идентификатор пользователя | openid |
| **aud** | Идентификатор сервиса-партнёра | openid |
| **exp** | Время окончания срока действия | openid |
| **iat** | Время выпуска JWT | openid |
| **auth_time** | Время аутентификации пользователя | openid |
| **nonce** | Значение для связи сессии (если передавалось ранее) | openid |
| **acr** | Способ аутентификации пользователя | openid |
| **azp** | Сторона, которой выдан токен (client_id) | openid |
---
_Документация Alfa API_
]]>
</obtaining_an_access_token_md>
</Authorization_Code_Flow_for_Holding_Companies>
<client_credentials_flow>
<how_to_use_ccf_md>
<![CDATA[
# Как использовать CCF (Client Credentials Flow)
**Теги:** `B2B` `B2C` `H2H`
Вы можете использовать **Client Credentials Flow** в своих приложениях для получения доступа к определённому числу сервисов Alfa API. Доступ осуществляется с помощью `access_token`, который Вы получаете без участия пользователя.
### Доступные методы
Методы, доступные с помощью `access_token`, полученного по Client Credentials Flow:
- [Платежи через СБП](/products/alfa-api/documentation/articles/sbp/articles/sbp-b2c/articles/intro/intro)
- [Кредиты](/products/alfa-api/documentation/articles/scoring/scoring)
- [Оплата покупок через СБП](/products/alfa-api/documentation/articles/sbp/articles/sbp-c2b/articles/intro/intro)
- [Операции СБП для юрлиц](/products/alfa-api/documentation/articles/sbp/articles/sbp-b2b/articles/intro/intro)
- [Дебетовая анкета](/products/alfa-api/documentation/articles/debit-cards/articles/intro/intro)
- [Цифровые финансовые активы (ЦФА)](/products/alfa-api/documentation/articles/dfa/dfa)
> **Важно:** Client Credentials Flow не позволяет использовать методы, которые содержат персональные данные пользователя или банковскую тайну. В соответствии с регуляторными требованиями, Банк обязан проверить полномочия представителя на получение такой информации.
---
## Шаги авторизации
1. **Получение токена доступа** (см. детали ниже).
### Дополнительно
При необходимости вы можете [отозвать токен](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/revoke-token/v1/revoke-token).
---
## Техническая спецификация API
### Получение токена доступа
**Endpoint:** `POST https://baas.alfabank.ru/oidc/token`
#### Заголовки (Headers)
| Название | Обязательно | Значение |
| :------------- | :---------- | :---------------------------------- |
| `Content-Type` | Да | `application/x-www-form-urlencoded` |
| `Accept` | Да | `application/json` |
#### Параметры тела запроса (Request Body)
| Параметр | Тип | Описание |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------- |
| `grant_type` | string | Тип гранта. Для CCF обычно используется `client_credentials` (в данном примере указан `authorization_code`) |
| `client_id` | uuid | Идентификатор партнёрского сервиса |
| `client_secret` | string | Секретный ключ партнёрского сервиса |
| `code` | uuid | Код авторизации |
| `redirect_uri` | string | URI перенаправления |
---
## Примеры кода
### cURL
```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=8962c304-89b1-11ec-a8a3-0242ac120002' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!' \
--data-urlencode 'redirect_uri=https://wwww.partner.ru/code'
```
### Python
```python
import requests
url = "https://baas.alfabank.ru/oidc/token"
payload = 'grant_type=authorization_code&code=8962c304-89b1-11ec-a8a3-0242ac120002&client_id=0cee0683-85ae-49f2-a63d-29f97aad1911&client_secret=Qwerty1234567890Qwerty1234567890!&redirect_uri=https%3A%2F%2Fwwww.partner.ru%2Fcode'
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
---
## Возможные ошибки (параметр `error`)
| Значение | Описание |
| :----------------------- | :------------------------------------------------------------------ |
| `invalid_request` | Отсутствует обязательный параметр или неверный формат запроса. |
| `invalid_client` | Ошибка аутентификации клиента (неизвестный ID или неверный secret). |
| `invalid_grant` | Недействительный код авторизации или несоответствие redirect_uri. |
| `unsupported_grant_type` | Тип grant_type не поддерживается сервером. |
| `internal_error` | Внутренняя ошибка сервера. |
---
## Структура ответа (Success 200 OK)
При успешном запросе возвращается JSON со следующими полями:
- `access_token`: Токен доступа (JWT). Действует 1 час.
- `refresh_token`: Токен для обновления access_token.
- `id_token`: Идентификационный токен.
- `expires_in`: Срок жизни токена в секундах (3600).
- `token_type`: Тип токена (Bearer).
---
_Документация Alfa API. [Портал разработчика](https://developers.alfabank.ru)_
]]>
</how_to_use_ccf_md>
<obteining_access_token_POST_md>
<![CDATA[
]]>
</obteining_access_token_POST_md>
</client_credentials_flow>
<expansion>
<client_consents_GET_md>
<![CDATA[
# Данные по согласиям пользователей
**Теги:** `B2B` `B2C` `H2H`
## Эндпоинты
### Песочница
`GET https://sandbox.alfabank.ru/oidc/client-consents`
### Пром
`GET https://baas.alfabank.ru/oidc/client-consents`
---
## Описание
Данный метод можно включать в `scope` с типом гранта [Client Credentials Flow](/products/alfa-api/documentation/articles/alfa-id/articles/ccf/articles/intro/intro) или с типом гранта [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/acf).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :-------------------- |
| **Authorization** | string | required | Bearer {access_token} |
| **Accept** | string | required | application/json |
### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :--------------------- | :------ | :------------- | :------------------------------------------------------------------------------------ |
| **clientId** | string | optional | Идентификатор партнёрского сервиса |
| **sub** | string | optional | Идентификатор субъекта (пользователя) |
| **organizationIdHash** | string | optional | Хэш идентификатора ЮЛ (организации) |
| **isActive** | boolean | optional | Признак активного согласия |
| **limit** | integer | optional | Количество объектов на одной странице. Значение по умолчанию: 1000 |
| **offset** | integer | optional | Количество объектов в списке, которые необходимо пропустить. Значение по умолчанию: 0 |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/oidc/client-consents?clientId={clientId}&sub={sub}&organizationIdHash={organizationIdHash}&isActive={isActive}&limit={limit}&offset={offset}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 OK
**HEADERS**
- **Content-Type**: `application/json` (optional)
**BODY**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **pagination** | object | Данные пагинации |
| ∟ **limit** | number | Количество записей на одной странице |
| ∟ **offset** | number | Количество записей в списке, которые были пропущены |
| ∟ **totalCount** | number | Общее количество записей |
| **items** | array of objects | Массив объектов результата |
| ∟ **createDateTime** | string | Дата и время создания (required) |
| ∟ **sub** | string | Идентификатор субъекта (пользователя) (required) |
| ∟ **organizationIdHash** | string | Хэш идентификатора ЮЛ (организации) (optional) |
| ∟ **clientId** | string | Идентификатор партнёрского сервиса (required) |
| ∟ **isActive** | boolean | Признак активного согласия (required) |
| ∟ **expireDate** | string | Дата окончания действия (required) |
#### Пример ответа 200
```json
{
"pagination": {
"limit": 1,
"offset": 0,
"totalCount": 1000
},
"items": [
{
"createDateTime": "2022-10-10T12:15:10",
"sub": "3228e68e-cc34-4b82-b43d-49112b5d9d3e",
"organizationIdHash": "665f4c5837ea35d1b081f4feb05de61522b6854c2268583f3f5865a0981f9268",
"clientId": "0cee0683-85ae-49f2-a63d-29f97aad1911",
"isActive": true,
"expireDate": "2023-04-10"
}
]
}
```
---
### Ошибки
| Код | Описание | Возможные значения `error` |
| :------ | :-------------------- | :------------------------------------------------------------ |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
---
## Навигация
- ← [Отзыв токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/revoke-token/v1/revoke-token)
- → [Экранирование](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening)
---
_Документация Alfa API. [Официальный портал](https://developers.alfabank.ru/)_
]]>
</client_consents_GET_md>
<revoke_token_POST_md>
<![CDATA[
# Отзыв токена доступа
**Теги:** `B2B` `B2C` `H2H`
## Эндпоинты
| Окружение | Метод и URL |
| :------------ | :--------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/oidc/revoke` |
| **Пром** | `POST https://baas.alfabank.ru/oidc/revoke` |
## Описание
Данный метод используется для отзыва `access_token` и `refresh_token`.
В случае отзыва `refresh_token`, `access_token` будет также отозван.
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--------------- | :----- | :------------- | :---------------------------------- |
| **Content-Type** | string | required | `application/x-www-form-urlencoded` |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :------------------ | :----- | :------------- | :----------------------------------------------------------------------------------------------------------------------- |
| **client_id** | string | required | Идентификатор партнёрского сервиса |
| **client_secret** | string | required | Секретный ключ партнёрского сервиса |
| **token** | string | required | Отзываемый токен |
| **token_type_hint** | string | optional | Тип отзываемого токена. Возможные значения:<br>• `access_token` — токен доступа;<br>• `refresh_token` — токен обновления |
---
## Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/oidc/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=0cee0683-85ae-49f2-a63d-29f97aad1911' \
--data-urlencode 'client_secret=Qwerty1234567890Qwerty1234567890!' \
--data-urlencode 'token=string' \
--data-urlencode 'token_type_hint=refresh_token'
```
---
## Параметры ответа
### 200 OK
Нет тела ответа.
### 400 Bad Request
**Headers:**
- `Content-Type: application/json` (optional)
**Body:**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки. Возможные значения:<br>• `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | optional | Описание ошибки |
---
## Навигация
- [← Проверка подписи](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/signature-checking/signature-checking)
- [Данные по согласиям пользователей →](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/client-consents/v1/client-consents)
---
_Документация Alfa ID / Расширение сценариев_
]]>
</revoke_token_POST_md>
<signature_checking_md>
<![CDATA[
# Проверка подписи
Проверить подпись можно для трех сущностей:
- `id_token`;
- `access_token`;
- `userinfo`.
Партнёр API получает ответ в формате сформированного токена **JWS**, который состоит из:
- **Заголовка (Header)**, содержащего алгоритм подписи, идентификатор ключа и тип токена;
- **JSON-объекта (Payload)**, в котором перечислены клэймы полезной нагрузки;
- **Электронной подписи (Signature)**, содержащей подпись данных секретным ключом, парным открытому ключу, выпущенному для Alfa ID.
### Декодирование компактной сериализации JWS
JWS формируется из трех составляющих и представляет структуру вида:
`Base64URL(Header).Base64URL(Payload).Base64URL(Signature)`
---
#### Пример access_token
**Закодированный токен:**
`eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIzMjI4ZTY4ZS1jYzM0LTRiODItYjQzZC00OTExMmI1ZDlkM2UiLCJhdWQiOiIwY2VlMDY4My04NWFlLTQ5ZjItYTYzZC0yOWY5N2FhZDE5MTEiLCJpc3MiOiJodHRwczpcL1wvaWQuYWxmYWJhbmsucnUiLCJleHAiOjE2MzE2NjY2NjMsInNjb3BlX3NlcnZpY2VzIjpbInBheW1lbnQiLCJzdGF0ZW1lbnQiXSwiaWF0IjoxNjMxNjYzMDYzLCJzY29wZV9jbGFpbXMiOlsibmFtZSIsImdpdmVuX25hbWUiLCJmYW1pbHlfbmFtZSIsIm1pZGRsZV9uYW1lIiwiZW1haWwiLCJwaG9uZV9udW1iZXIiXX0.WVr5xkQSEGqpPXN3aIo0zHZLDL0vvtxEEQ83BrgJo7l0BjjALeGDRYENF2bL8j3n1pXRnduiBQcYNV6teBhESI8V_8kd7Kh7LTePkJWadPSvD__KskC69b4XZ-zN-IQ73NmAcBDStnnhSXGKL6xhdRy-TGiAoKPsRWiDVntsDlpCQNHAt3tJk8q_SQS4S1k6qju9eJ2GFkgmd6z8rR2vaBykaOF0K61ltksw6YgXhuek3OlYkqIAivyKYl59uio8zMpJk-YrPlmawwmvWPF0vKhaLj8Mvn4mVMsVSfuVVKP2ksHG0MAlWpO3Sh9GoKO4d6TQplJ4vgIIeNx-44npqw`
**Раскодированные данные:**
**Header**
```json
{
"kid": "alfa-test-jwt",
"typ": "JWT",
"alg": "RS256"
}
```
**Payload**
```json
{
"sub": "3228e68e-cc34-4b82-b43d-49112b5d9d3e",
"aud": "0cee0683-85ae-49f2-a63d-29f97aad1911",
"iss": "https://id.alfabank.ru",
"exp": 1631666663,
"scope_services": ["payment", "statement"],
"iat": 1631663063,
"scope_claims": [
"name",
"given_name",
"family_name",
"middle_name",
"email",
"phone_number"
]
}
```
**Signature**
```javascript
RSASHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
your - 256 - bit - secret,
); // secret base64 encoded
```
---
#### Пример JWS идентификационного токена id_token
Каждая часть, разделённая точкой, должна декодироваться отдельно с использованием алгоритма Base64URL Encoding.
**Закодированный токен:**
`eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ .eyJzdWIiOiIzMjI4ZTY4ZS1jYzM0LTRiODItYjQzZC00OTExMmI1ZDlkM2UiLCJhdWQiOiIwY2VlMDY4My04NWFlLTQ5ZjItYTYzZC0yOWY5N2FhZDE5MTEiLCJhY3IiOiJMb0EzIiwiYXpwIjoiMGNlZTA2ODMtODVhZS00OWYyLWE2M2QtMjlmOTdhYWQxOTExIiwiYXV0aF90aW1lIjoxNjMxNjYzMDUzLCJpc3MiOiJodHRwczpcL1wvaWQuYWxmYWJhbmsucnUiLCJleHAiOjE2MzE2NjY2NjMsImlhdCI6MTYzMTY2MzA2Mywibm9uY2UiOiJuLTBTNl9XekEyTWoifQ .xBE6LEUxOKleHCZVQacldJfKr5KtyyvJKCCmInqapmRJ_aRF-cEoVfpJd_kxlNmJYT7AcjMMppovNkmhB49VL5DK8FhF0fvRgLskKR9Eohy4eiC8ued03Z1LyLz1H7EcKSkusaCIajzIvxxZfVtSHI4jmgLg6ItXPdZgIDUWINgESkl6I7IP5CbfONHweNnbkWEOEzxDgGGnxxtPxrWVoPVP-ijUeUSH_iESHfrhY_ePRMYi2If62IsKX_0GT5BHRYOhXVDZ9fyn5fRCvg8_QoCykDVIOZMtWQ3w4TadqS0dfMlsLBxkVbVftzH2fWRLTCX3SJ5AXiytHkpow8V45w`
**Раскодированные данные:**
**Header**
```json
{
"kid": "alfa-test-jwt",
"typ": "JWT",
"alg": "RS256"
}
```
**Payload**
```json
{
"sub": "3228e68e-cc34-4b82-b43d-49112b5d9d3e",
"aud": "0cee0683-85ae-49f2-a63d-29f97aad1911",
"acr": "LoA3",
"azp": "0cee0683-85ae-49f2-a63d-29f97aad1911",
"auth_time": 1631663053,
"iss": "https://id.alfabank.ru",
"exp": 1631666663,
"iat": 1631663063,
"nonce": "n-0S6_WzA2Mj"
}
```
---
#### Пример userinfo
**Закодированный токен:**
`eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJjdXMiOiJVQUFBQUEiLCJzdWIiOiIzMjI4ZTY4ZS1jYzM0LTRiODItYjQzZC00OTExMmI1ZDlkM2UiLCJiaXJ0aGRhdGUiOiIyMDAwLTAyLTIwIiwicm9sZSI6IkFDQ09VTlRBTlQsIE1BTkFHRVIiLCJnZW5kZXIiOiJNQUxFIiwiaWRlbnRpdHlfZG9jdW1lbnRfbmFtZSI6ItCf0LDRgdC_0L7RgNGCINCz0YDQsNC20LTQsNC90LjQvdCwINCg0KQiLCJpZGVudGl0eV9kb2N1bWVudF9udW1iZXIiOjIyMjIyMiwiaXNzIjoiaHR0cHM6XC9cL2JhYXMuYWxmYWJhbmsucnUiLCJpbm4iOjc0MTUxMTExMjIyMiwiZWlvIjp0cnVlLCJnaXZlbl9uYW1lIjoi0KLQtdGB0YIiLCJtaWRkbGVfbmFtZSI6ItCi0LXRgdGC0L7QstC40YciLCJhY3VzIjoiWEFBQUFBIiwiaWRlbnRpdHlfZG9jdW1lbnRfc2VyaWVzIjoxMTExLCJhdWQiOiIwY2VlMDY4My04NWFlLTQ5ZjItYTYzZC0yOWY5N2FhZDE5MTEiLCJhY2xjIjoiWEFBQUExIiwidXBkYXRlZF9hdCI6IjIwMjItMDEtMjAiLCJuYW1lIjoi0KLQtdGB0YLQvtCyINCi0LXRgdGCINCi0LXRgdGC0L7QstC40YciLCJwaG9uZV9udW1iZXIiOjc5MTkxMTEyMjMzLCJjbGMiOiJVQUFBQTEiLCJmYW1pbHlfbmFtZSI6ItCi0LXRgdGC0L7QsiIsImVtYWlsIjoiZW1haWxAZW1haWwucnUifQ.WVr5xkQSEGqpPXN3aIo0zHZLDL0vvtxEEQ83BrgJo7l0BjjALeGDRYENF2bL8j3n1pXRnduiBQcYNV6teBhESI8V_8kd7Kh7LTePkJWadPSvD__KskC69b4XZ-zN-IQ73NmAcBDStnnhSXGKL6xhdRy-TGiAoKPsRWiDVntsDlpCQNHAt3tJk8q_SQS4S1k6qju9eJ2GFkgmd6z8rR2vaBykaOF0K61ltksw6YgXhuek3OlYkqIAivyKYl59uio8zMpJk-YrPlmawwmvWPF0vKhaLj8Mvn4mVMsVSfuVVKP2ksHG0MAlWpO3Sh9GoKO4d6TQplJ4vgIIeNx-44npqw`
**Payload (раскодированный)**
```json
{
"cus": "UAAAAA",
"sub": "3228e68e-cc34-4b82-b43d-49112b5d9d3e",
"birthdate": "2000-02-20",
"role": "ACCOUNTANT, MANAGER",
"gender": "MALE",
"identity_document_name": "Паспорт гражданина РФ",
"identity_document_number": 222222,
"iss": "https://baas.alfabank.ru",
"inn": 741511112222,
"eio": true,
"given_name": "Тест",
"middle_name": "Тестович",
"acus": "XAAAAA",
"identity_document_series": 1111,
"aud": "0cee0683-85ae-49f2-a63d-29f97aad1911",
"aclc": "XAAAA1",
"updated_at": "2022-01-20",
"name": "Тестов Тест Тестович",
"phone_number": 79191112233,
"clc": "UAAAA1",
"family_name": "Тестов",
"email": "email@email.ru"
}
```
---
### Алгоритм проверки подписи
1. Вычислите хэш-функцию **SHA256** от данных `Base64URL(Header).Base64URL(Payload)`.
2. Дешифруйте данные `Base64URL(Signature)`, используя алгоритм **RS256** и открытый ключ с идентификатором, переданным в Заголовке (Header) в клэйме `kid` (в приведенном выше примере это `alfa-test-jwt`).
3. Сравните вычисленный хэш из 1 шага и дешифрованные данные из 2 шага. Если значения равны, значит, подпись верна.
**Сертификат для проверки электронной подписи:** [certificate-prod](/assets/developers-portal.docs.alfa-api/articles/alfa-id/articles/expansion/articles/signature-checking/files/cert.cer)
---
_Навигация:_
[← Получение токена доступа](/products/alfa-api/documentation/articles/alfa-id/articles/ccf/articles/get-access-token/v1/get-access-token) | [Отзыв токена доступа →](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/revoke-token/v1/revoke-token)
]]>
</signature_checking_md>
</expansion>
<screening_eg_character_shielding_md>
<![CDATA[
Вот преобразованный контент страницы в формат Markdown. Я сохранил структуру, иерархию заголовков, примеры кода и таблицу кодировки.
---
# Экранирование
**Теги:** `B2B` `B2C` `H2H`
**Путь:** [Главная](https://developers.alfabank.ru/) / Alfa ID / Экранирование
---
**Экранирование специальных символов** — это процесс преобразования специальных символов (например, кавычек, пробелов, знаков препинания) в их соответствующие эквиваленты для передачи данных через различные протоколы и форматы.
Процентное кодирование или кодирование URI-адресов представляет собой метод кодирования произвольных данных с использованием ограниченных символов US-ASCII, разрешённых в URI.
Синтаксис URI содержит зарезервированные символы (двух типов) и незарезервированные символы.
### Зарезервированные символы
* **gen-delims**: `":"`, `"/"`, `"?"`, `"# "`, `"["`, `"]"`, `"@"` — символы, разделяющие URI на крупные компоненты.
* **sub-delims**: `"!"`, `"$ "`, `"&"`, `"' "`, `"("`, `")"`, `"* "`, `"+"`, `","`, `";"`, `"="` — символы, разделяющие крупный компонент на более мелкие составляющие.
### Незарезервированные символы
В общем случае незарезервированные символы — это `ALPHA`, `DIGIT`, `"-"`, `"."`, `"_"`, `"~"`, где `ALPHA` — это буквы, а `DIGIT` — десятичные цифры.
Если символ из набора зарезервированных символов используется в другом контексте, то он должен быть закодирован в процентах. Процентное кодирование зарезервированного символа представляет собой замену/преобразование символа в соответствующее ему значение.
Например, зарезервированный символ `"/"` может быть заменен следующими символами: `%2F`.
---
### Примеры запросов
#### Пример запроса без экранирования
```bash
https://id.alfabank.ru/oidc/authorize?response_type=code&client_id=0cee0683-85ae-49f2-a63d-29f97aad1911&redirect_uri=https://wwww.partner.ru/code&scope=openid&state=abcdef
```
#### Пример запроса с экранированием
```bash
https://id.alfabank.ru/oidc/authorize?response_type=code&client_id=0cee0683-85ae-49f2-a63d-29f97aad1911&redirect_uri=https%3A%2F%2Fwwww.partner.ru%2Fcode&scope=openid&state=abcdef
```
---
### Таблица кодирования символов
| Символ | ANSI (Percent-encoding) |
| :--- | :--- |
| `~` | `%7E` |
| `` ` `` | `%60` |
| `'` | `%27` |
| `"` | `%22` |
| `@` | `%40` |
| `?` | `%3F` |
| `!` | `%21` |
| `#` | `%23` |
| `№` | `%B9` |
| `$` | `%24` |
---
### Навигация
* ← [Данные по согласиям пользователей](/products/alfa-api/documentation/articles/alfa-id/articles/expansion/articles/client-consents/v1/client-consents)
* [API Key](/products/alfa-api/documentation/articles/api-key/api-key) →
---
*Документация Alfa API*
]]>
</screening_eg_character_shielding_md>
<what_is_alfa_id_md>
<![CDATA[
# Что такое Alfa ID
**Alfa ID** — единая учётная запись пользователя ЮЛ (юридического лица) / ФЛ (физического лица), которая помогает пользователям входить на ваш сайт или в приложение, а также в продукты и сервисы Альфа-Банка.
### Преимущества для пользователей
- Простая и быстрая аутентификация на сайтах и в приложениях;
- Единый и безопасный аккаунт;
- Упрощение процесса покупки или подачи заявки;
- Безопасность персональных данных;
- Не нужно запоминать множество паролей.
### Преимущества для партнёров
- Простая и быстрая аутентификация, выше конверсия на вход;
- Быстрое получение актуальных данных пользователя от Банка;
- Автозаполнение форм и заявок;
- Проверка реальности пользователя;
- Индустриальные стандарты защиты данных и персональной информации;
- Отсутствие необходимости хранить персональные данные на своей стороне.
### Рекомендуемые браузеры для работы с Alfa ID
- **Яндекс Браузер** версии 21 и выше;
- **Safari** версии 16 и выше;
- **Google Chrome** версии 117 и выше.
---
## Инструкция: Настройка прав доступа
По умолчанию доступ к Порталу разработчика имеет только руководитель вашей организации. Для предоставления доступа другим пользователям (например, разработчикам), необходимо создать соответствующую роль в «Альфа-Бизнес».
> **Внимание для ИП:**
> Права разработчика можно назначить от имени самого ИП (роль «Руководитель») или от имени любого другого сотрудника с ролью «Руководитель» (потребуется подтверждение от владельца ИП).
### Шаг 1. Перейдите в раздел «Пользователи и роли»
На главном экране Альфа-Бизнес перейдите в настройки компании.
![image](files/1.png)
![image](files/2.png)
В разделе **Моя компания** выберите карточку **Пользователи и роли**.
![image](files/3.png)
### Шаг 2. Создайте новую роль
Нажмите **Создать роль**.
![image](files/4.png)
Укажите название роли (например, «Разработчик API»).
![image](files/5.png)
Далее настройте права. Рекомендуется создавать роль на основании прав руководителя, сбросив лишнее:
1. Нажмите **Снять все**, чтобы сбросить права руководителя.
![image](files/6.png)
2. В разделе **Обслуживание бизнеса** выберите **Alfa API**, указав необходимые права.
![image](files/7.png)
3. Нажмите **Создать роль** для сохранения.
### Шаг 3. Назначьте роль разработчику
В разделе **Пользователи** нажмите на три точки справа от нужного сотрудника и выберите **Сменить роль**.
![image](files/9.png)
Выберите созданную роль и нажмите **Сменить**.
![image](files/11.png)
Подтвердите смену роли кодом из СМС.
![image](files/12.png)
После успешной смены в записи пользователя отобразится статус **Подключён**. Теперь пользователь может работать с Порталом разработчика.
![image](files/13.png)
---
## Требования к полномочиям для авторизации
Для корректной работы H2H-интеграций ключ доступа (`access_token` / `API Key`) должен получать пользователь, обладающий правами на конкретные сервисы:
- **При использовании ACF H2H:** Авторизацию в Alfa ID должен проходить пользователь, у которого в Альфа-Бизнес настроены полномочия на использование выбранных `scopes`.
- **При использовании API Key:** Выпускать ключ должен пользователь, имеющий права на те продукты, которые выбраны при выпуске ключа.
**Пример:** Если у разработчика есть права на редактирование интеграций, но нет прав на «Просмотр выписки», то выпущенный им API Key для сервиса `transactions` работать не будет.
]]>
</what_is_alfa_id_md>
</Alfa_ID>
<API_Key>
<api_key_md>
<![CDATA[
Вот преобразованный контент страницы в формате Markdown. Я сохранил структуру, важные пометки (бета-тест, H2H) и все функциональные ссылки.
---
# API Key
**β-ТЕСТ** **H2H**
**API Key** — ключ доступа для упрощённой авторизации запросов по H2H-интеграциям, который не требует аутентификации пользователей. Он выпускается один раз через интерфейс Портала разработчика и действует бессрочно, но будет автоматически отозван, если с момента последнего запроса прошло более 30 дней.
### Сервисы, доступные с использованием `API Key` в H2H-интеграциях:
* [Выписки по счетам юрлиц](/products/alfa-api/documentation/articles/transactions/transactions) (для методов, где `scope=transactions`)
* [Профиль организации](/products/alfa-api/documentation/articles/customer-info/customer-info)
* [Электронная подпись](/products/alfa-api/documentation/articles/signature/signature)
Для настройки авторизации по `API Key` необходимо выпустить его на Портале разработчика и добавить его в свои рабочие инструменты. Как это сделать, описано [в статье Управление API Key](/products/alfa-api/documentation/articles/selfservice/articles/api-key/api-key).
### Управление ключами доступа
Управлять ключами доступа можно также на Портале разработчика. Вы можете:
* **Перевыпустить ключ** в случае потери данных, компрометации ключа или необходимости замены данных для него.
* **Отозвать ключ**, если больше не хотите использовать упрощённый способ авторизации.
[**Как управлять API Key**](/products/alfa-api/documentation/articles/selfservice/articles/api-key/api-key)
---
## Навигация по разделу
* ← [Экранирование](/products/alfa-api/documentation/articles/alfa-id/articles/screening/screening)
* → [Начало работы в песочнице](/products/alfa-api/documentation/articles/sandbox/articles/intro/intro)
---
### Общая информация (Alfa API)
1. [Общая информация](/products/alfa-api/documentation/articles/specification/specification)
2. [Подключение к Alfa API](/products/alfa-api/documentation/articles/connection/connection)
3. [Портал разработчика](/products/alfa-api/documentation/articles/selfservice/selfservice)
4. [Alfa ID](/products/alfa-api/documentation/articles/alfa-id/alfa-id)
5. **API Key** (Текущая страница)
6. [Песочница](/products/alfa-api/documentation/articles/sandbox/sandbox)
7. [Java SDK](/products/alfa-api/documentation/articles/sdk/sdk)
8. [Обмен файлами](/products/alfa-api/documentation/articles/secure-file-transfer/secure-file-transfer)
9. [Транспортная подпись и шифрование](/products/alfa-api/documentation/articles/signature-encryption/signature-encryption)
10. [Вебхуки](/products/alfa-api/documentation/articles/webhooks/webhooks)
### Продукты и сервисы
* [Выписки по счетам юрлиц](/products/alfa-api/documentation/articles/transactions/transactions)
* [Информация по счетам физлиц](/products/alfa-api/documentation/articles/accounts/accounts)
* [Эскроу-счета 214-ФЗ](/products/alfa-api/documentation/articles/escrow/escrow)
* [Профиль организации](/products/alfa-api/documentation/articles/customer-info/customer-info)
* [Платёжные поручения](/products/alfa-api/documentation/articles/payments/payments)
* [Самозанятые](/products/alfa-api/documentation/articles/selfemployed/selfemployed)
* [Система быстрых платежей (СБП)](/products/alfa-api/documentation/articles/sbp/sbp)
* [Кредиты](/products/alfa-api/documentation/articles/scoring/scoring)
* [Электронная подпись](/products/alfa-api/documentation/articles/signature/signature)
* [Карты](/products/alfa-api/documentation/articles/cards/cards)
* [Зарплатный проект](/products/alfa-api/documentation/articles/salary/salary)
* [Alfa Pay Business](/products/alfa-api/documentation/articles/invoices/invoices)
* [Факторинг](/products/alfa-api/documentation/articles/factoring/factoring)
* [Номинальные счета](/products/alfa-api/documentation/articles/nominal-accounts/nominal-accounts)
]]>
</api_key_md>
</API_Key>
<Java_SDK>
</Java_SDK>
<Вебхуки>
<create_webhook_md>
<![CDATA[
# Создание вебхука
**Типы интеграции:** `B2B` `B2C` `H2H`
**Метод:** `POST`
Сервис информирования при наступлении в системе события, на которое подписан Партнёр API.
## Эндпоинты
| Окружение | URL |
| :------------ | :------------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/v1/webhooks` |
| **Пром** | `POST https://baas.alfabank.ru/api/v1/webhooks` |
---
## Scope
`scope` события, на которое подписываетесь, с допустимыми значениями можно посмотреть [здесь](/products/alfa-api/documentation/articles/webhooks/webhooks).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :------- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | `string` | **required** | Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` | **required** | `application/json` |
| **Content-Type** | `string` | **required** | `application/json` |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :---------------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **object** | `string` | **required** | Объект/сущность, на который партнёр API хочет подписаться. Возможные значения:<br>• `ul_transaction_default` — получение выписки;<br>• `jp_sbp_incoming_payments` — получение входящих платежей. |
| **data** | `object` | optional | Дополнительные данные по вебхукам. Список полей зависит от события. Для `jp_sbp_incoming_payments` не заполняется. |
| **data.accounts** | `array of string` | optional | Список счетов. Заполняется при `object: ul_transaction_default`. Если не переданы, вебхук создается на все доступные счета. |
| **callbackUri** | `string` | **required** | URL партнёра. Должен соответствовать хосту `redirect_uri` из настроек Alfa ID (проверка по домену второго уровня). |
| **version** | `integer` | optional | Версия формата данных. Для текущих объектов возможное значение — `1`. |
---
## Пример запроса
```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
}'
```
---
## Параметры ответа
### Успешный ответ (201 Created)
| Атрибут | Тип | Описание |
| :-------------- | :-------- | :------------------------------------------------------------------------ |
| **id** | `uuid` | Идентификатор записи вебхука. |
| **object** | `string` | Сущность подписки (`ul_transaction_default`, `jp_sbp_incoming_payments`). |
| **enabled** | `boolean` | Статус вебхука (`true` — включён, `false` — выключен). |
| **data** | `object` | Дополнительные данные (например, список `accounts`). |
| **callbackUri** | `string` | URL партнёра, на который будет отправлен вебхук. |
| **version** | `integer` | Версия формата данных. |
**Пример JSON ответа:**
```json
{
"id": "f9f8c674-7a2a-4297-bdb8-ddd3013de3a3",
"object": "ul_transaction_default",
"enabled": true,
"data": {
"accounts": [
"40702810800000000001",
"40702810800000000004",
"40702810800000000007"
]
},
"callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
"version": 1
}
```
---
## Ошибки
| Код | Описание (error) | Описание ошибки (error_description) |
| :------ | :------------------------ | :-------------------------------------------------------------- |
| **400** | `invalid_request` | Неверные входные параметры запроса. |
| **401** | `invalid_token` | Токен просрочен, отозван или имеет неправильный формат. |
| **403** | `insufficient_scope` | Нет прав на использование сервиса (настройки scope). |
| **403** | `insufficient_privileges` | Нет доступа к `callbackUri` или вебхуки выключены для партнёра. |
| **404** | `unknown_route` | Эндпоинт не найден или неактивен. |
| **429** | — | Too Many Requests (превышение лимита запросов). |
| **500** | `internal_error` | Внутренняя ошибка сервиса. |
| **503** | — | Service Unavailable (сервис временно недоступен). |
> **Примечание:** Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных выше.
---
**Навигация:**
← [Как подключить](/products/alfa-api/documentation/articles/webhooks/articles/intro/intro) | [Редактирование вебхука](/products/alfa-api/documentation/articles/webhooks/articles/edit-webhook/v1/edit-webhook) →
]]>
</create_webhook_md>
<delete_webhook_md>
<![CDATA[
Ниже представлен сконвертированный из HTML текст документации в формате Markdown. Все ссылки сохранены, структура таблиц и примеров кода приведена к удобному для чтения виду.
---
# Удаление вебхука
**Теги:** `B2B` `B2C` `H2H`
## Эндпоинты
| Среда | Метод и URL |
| :--- | :--- |
| **Песочница** | `DELETE https://sandbox.alfabank.ru/api/v1/webhooks/{id}` |
| **Пром** | `DELETE https://baas.alfabank.ru/api/v1/webhooks/{id}` |
### Scope
`scope` события, на которое подписываетесь, с допустимыми значениями можно посмотреть [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/webhooks).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | **required** | Bearer {access_token}, полученный по [Authorization Code Flow](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | **required** | `application/json` |
| **Content-Type** | string | optional | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **id** | uuid | **required** | Идентификатор вебхука |
### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **object** | string | **required** | Объект/сущность, на который партнёр API хочет подписаться. Возможные значения:<br>• `ul_transaction_default` — получение выписки;<br>• `jp_sbp_incoming_payments` — получение входящих платежей. |
---
## Пример запроса
```bash
curl -X DELETE https://baas.alfabank.ru/api/v1/webhooks/f9f8c674-7a2a-4297-bdb8-ddd3013de3a3?object=ul_transaction_default \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
```
---
## Параметры ответа
### 200 — OK
Нет тела ответа.
### 400 — Bad Request
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки: `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | optional | Описание ошибки |
### 401 — Unauthorized
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки: `invalid_token` — предоставленный токен просрочен, отозван или недействителен |
| **error_description** | string | optional | Описание ошибки |
### 403 — Forbidden
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки:<br>• `insufficient_scope` — нет прав (настройки scope);<br>• `insufficient_privileges` — вебхуки выключены для клиента или сервиса |
| **error_description** | string | optional | Описание ошибки |
### 404 — Not Found
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки: `unknown_route` — эндпоинт не найден или неактивен |
| **error_description** | string | optional | Описание ошибки |
### 429 — Too Many Requests
Нет тела ответа.
### 500 — Internal Server Error
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки: `internal_error` — внутренняя ошибка сервиса |
| **error_description** | string | optional | Описание ошибки |
### 503 — Service Unavailable
Нет тела ответа.
> **Примечание:** Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в данной документации.
---
**Навигация:**
[← Редактирование вебхука](https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/edit-webhook/v2/edit-webhook) | [Получение вебхука →](https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/get-webhook/v1/get-webhook)
]]>
</delete_webhook_md>
<edit_webhook_md>
<![CDATA[
Ниже представлено содержимое документа, преобразованное в структурированный Markdown.
---
# Редактирование вебхука
**Теги:** `B2B` `B2C` `H2H`
**Версия:** Последняя версия v2
## Эндпоинты
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `PUT https://sandbox.alfabank.ru/api/v2/webhooks/{id}` |
| **Пром** | `PUT https://baas.alfabank.ru/api/v2/webhooks/{id}` |
### Scope
`scope` события, на которое подписываетесь, с допустимыми значениями можно посмотреть [здесь](/products/alfa-api/documentation/articles/webhooks/webhooks).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | `string` | **required** | Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` | **required** | `application/json` |
| **Content-Type** | `string` | **required** | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **id** | `uuid` | **required** | Идентификатор вебхука |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **object** | `string` | **required** | Объект/сущность для подписки: <br>• `ul_transaction_default` — получение выписки;<br>• `jp_sbp_incoming_payments` — получение входящих платежей |
| **enabled** | `boolean` | optional | Статус: `true` (включён), `false` (выключен) |
| **organizationIdHash** | `string` | optional | Хэш идентификатора организации |
| **data** | `object` | optional | Дополнительные данные. Для `jp_sbp_incoming_payments` не заполняется. |
| **data.accounts** | `array of string`| optional | Список счетов. При `object: ul_transaction_default` — **обязательно** (передавать все счета). Пустой массив = вебхук на все счета. |
| **callbackUri** | `string` | optional | URL партнёра. Можно менять только `path`, менять `host` нельзя. |
| **version** | `integer` | optional | Версия формата данных. Допустимое значение — `1`. |
---
## Пример запроса
```bash
curl -X PUT https://baas.alfabank.ru/api/v2/webhooks/f9f8c674-7a2a-4297-bdb8-ddd3013de3a3 \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Request-ID: {uuid}' \
-d '{
"object": "ul_transaction_default",
"enabled": true,
"data": {
"accounts": [
"40802810401300015422",
"40802810401300015422"
]
},
"callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
"version": 1
}'
```
---
## Параметры ответа
### Пример ответа 200 (ОК)
```json
{
"id": "f9f8c674-7a2a-4297-bdb8-ddd3013de3a3",
"object": "ul_transaction_default",
"enabled": true,
"organizationIdHash": "ff22df927f36344155f7075fae297541fcfca87e3dabef5aa9c951a21c4f072c",
"data": {
"accounts": [
"40702810800000000001",
"40702810800000000004",
"40702810800000000007"
]
},
"callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
"version": 1,
"statusDescriptions": [
{
"cause": "Revocation of agreement",
"description": "The webhook is disabled due to the agreement being revoked in Alfa ID"
},
{
"cause": "Disabled by administrator",
"description": "Webhook disabled by administrator"
}
]
}
```
### Описание полей ответа (200 OK)
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **id** | `uuid` | Идентификатор записи |
| **object** | `string` | Сущность подписки (`ul_transaction_default` или `jp_sbp_incoming_payments`) |
| **enabled** | `boolean` | Статус активации |
| **data.accounts** | `array` | Список счетов (для выписок) |
| **callbackUri** | `string` | URL получения уведомлений |
| **statusDescriptions** | `array` | Причины выключения вебхука (если есть) |
---
## Коды ошибок
| Код | Описание | Возможные значения `error` |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав доступа; `insufficient_privileges` — нет доступа к callbackUri |
| **404** | Not Found | `unknown_route` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
> **Рекомендация:** Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации.
---
[← Назад к списку: Редактирование вебхука v1](/products/alfa-api/documentation/articles/webhooks/articles/edit-webhook/v1/edit-webhook) | [Вперёд: Удаление вебхука →](/products/alfa-api/documentation/articles/webhooks/articles/delete-webhook/v1/delete-webhook)
]]>
</edit_webhook_md>
<get_webhook_md>
<![CDATA[
# Получение вебхука
**Типы интеграции:** `B2B`, `B2C`, `H2H`
**Версия API:** `v2` (Последняя)
Метод позволяет получить информацию о конкретном вебхуке по его идентификатору.
---
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :----------------------------------------------------- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/v2/webhooks/{id}` |
| **Пром** | `GET https://baas.alfabank.ru/api/v2/webhooks/{id}` |
### Scope
`scope` события, на которое подписываетесь, с допустимыми значениями можно посмотреть [здесь](/products/alfa-api/documentation/articles/webhooks/webhooks).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :----- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | `Bearer {access_token}`, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | optional | `application/json` |
### PATH (Параметры пути)
| Атрибут | Тип | Обяз. | Описание |
| :------ | :--- | :------- | :-------------------- |
| **id** | uuid | required | Идентификатор вебхука |
### QUERY (Параметры строки запроса)
| Атрибут | Тип | Обяз. | Описание |
| :--------- | :----- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **object** | string | required | Объект/сущность, на который партнер хочет подписаться:<br>• `ul_transaction_default` — получение выписки;<br>• `jp_sbp_incoming_payments` — получение входящих платежей. |
---
## Пример запроса
```bash
curl -X GET https://baas.alfabank.ru/api/v2/webhooks/f9f8c674-7a2a-4297-bdb8-ddd3013de3a3?object=ul_transaction_default \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Описание |
| :--------------------- | :------------ | :------------------------------------------------------------------------ |
| **id** | uuid | Идентификатор записи |
| **object** | string | Объект подписки (`ul_transaction_default` или `jp_sbp_incoming_payments`) |
| **enabled** | boolean | Статус вебхука: `true` — включен, `false` — выключен |
| **organizationIdHash** | string | Хэш идентификатора организации |
| **data** | object | Дополнительные данные. Список полей зависит от события. |
| └ **accounts** | array[string] | Список счетов (для `ul_transaction_default`) |
| **callbackUri** | string | URL партнёра, на который отправляется вебхук |
| **version** | integer | Версия формата данных. Для текущих объектов значение — `1`. |
| **statusDescriptions** | array[object] | Описание статуса выключения вебхука |
| └ **cause** | string | Причина выключения |
| └ **description** | string | Описание причины |
#### Пример ответа 200:
```json
{
"id": "f9f8c674-7a2a-4297-bdb8-ddd3013de3a3",
"object": "ul_transaction_default",
"enabled": true,
"organizationIdHash": "ff22df927f36344155f7075fae297541fcfca87e3dabef5aa9c951a21c4f072c",
"data": {
"accounts": [
"40702810800000000001",
"40702810800000000004",
"40702810800000000007"
]
},
"callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
"version": 1,
"statusDescriptions": [
{
"cause": "Revocation of agreement",
"description": "The webhook is disabled due to the agreement being revoked in Alfa ID"
},
{
"cause": "Disabled by administrator",
"description": "Webhook disabled administrator"
}
]
}
```
---
## Коды ошибок
| Код | Описание | Ошибка (`error`) |
| :------ | :------------------ | :--------------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса (scope) |
| **404** | Not Found | `unknown_route` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
> **Рекомендация:** Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации.
---
_Документация Alfa API_
]]>
</get_webhook_md>
<get_webhooks_list_md>
<![CDATA[
# Получение списка вебхуков
`B2B` `B2C` `H2H`
Метод позволяет получить список всех настроенных вебхуков для конкретного объекта подписки.
### Эндпоинты
| Окружение | Метод | URL |
| :------------ | :---- | :-------------------------------------------- |
| **Песочница** | `GET` | `https://sandbox.alfabank.ru/api/v2/webhooks` |
| **Пром** | `GET` | `https://baas.alfabank.ru/api/v2/webhooks` |
### Scope
`scope` события, на которое подписываетесь, с допустимыми значениями можно посмотреть [здесь](/products/alfa-api/documentation/articles/webhooks/webhooks).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :----- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | optional | `application/json` |
### QUERY
| Атрибут | Тип | Обяз. | Описание |
| :--------- | :------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **object** | string | required | Объект/сущность, на который партнёр API хочет подписаться. Возможные значения:<br>• `ul_transaction_default` — получение выписки;<br>• `jp_sbp_incoming_payments` — получение входящих платежей. |
| **offset** | integer | optional | Смещение в результатах поиска. |
| **limit** | integer | optional | Количество элементов на странице. |
### Пример запроса
```bash
curl -X GET https://baas.alfabank.ru/api/v2/webhooks?offset=20&limit=10&object=ul_transaction_default \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
#### Тело ответа (JSON)
| Атрибут | Тип | Описание |
| :----------------------- | :------ | :---------------------------------------------------------------------------------------------------------- |
| **pagination** | object | Данные пагинации |
| ∟ **limit** | number | Количество объектов на одной странице |
| ∟ **offset** | number | Количество объектов в списке, которые необходимо пропустить |
| ∟ **totalCount** | number | Общее количество записей |
| **items** | array | Массив объектов результата |
| ∟ **id** | uuid | Идентификатор записи |
| ∟ **object** | string | Объект/сущность подписки (`ul_transaction_default`, `jp_sbp_incoming_payments`) |
| ∟ **enabled** | boolean | Статус вебхука: `true` — включён, `false` — выключен |
| ∟ **organizationIdHash** | string | Хэш идентификатора организации |
| ∟ **data** | object | Дополнительные данные. Поле **accounts** (array of string) заполняется при `object: ul_transaction_default` |
| ∟ **callbackUri** | string | URL партнёра, на который отправляется вебхук |
| ∟ **version** | integer | Версия формата данных (возможные значения — `1`) |
| ∟ **statusDescriptions** | array | Описание причин выключения вебхука |
| ∟∟ **cause** | string | Причина выключения |
| ∟∟ **description** | string | Описание причины |
#### Пример ответа 200
```json
{
"pagination": {
"offset": 45,
"limit": 10,
"totalCount": 100
},
"items": [
{
"id": "f9f8c674-7a2a-4297-bdb8-ddd3013de3a3",
"object": "ul_transaction_default",
"enabled": true,
"organizationIdHash": "ff22df927f36344155f7075fae297541fcfca87e3dabef5aa9c951a21c4f072c",
"data": {
"accounts": [
"40702810800000000001",
"40702810800000000004",
"40702810800000000007"
]
},
"callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
"version": 1,
"statusDescriptions": [
{
"cause": "Revocation of agreement",
"description": "The webhook is disabled due to the agreement being revoked in Alfa ID"
},
{
"cause": "Disabled by administrator",
"description": "Webhook disabled administrator"
}
]
}
]
}
```
---
## Ошибки
| Код | Описание | Возможные `error` |
| :------ | :------------------ | :--------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав (scope) |
| **404** | Not Found | `unknown_route` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа (превышен лимит запросов) |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа (сервис временно недоступен) |
> Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации.
---
**Навигация:**
← [Получение вебхука](/products/alfa-api/documentation/articles/webhooks/articles/get-webhook/v2/get-webhook) | [Партнёрский метод для получения вебхуков](/products/alfa-api/documentation/articles/webhooks/articles/partner-webhook/v1/partner-webhook) →
]]>
</get_webhooks_list_md>
<partner_webhook_md>
<![CDATA[
# Партнёрский метод для получения вебхуков
На стороне партнёра должен быть реализован метод **POST** с URL, на который будет отправляться вебхук. Важно, чтобы второй уровень домена совпадал со вторым уровнем домена, который указывали в качестве `redirect_uri` при интеграции с Alfa ID. Подробнее [в инструкции по подключению вебхуков](/products/alfa-api/documentation/articles/webhooks/webhooks).
### **Авторизация**
Реализованный метод может быть как открытым, так и закрыт авторизацией. В случае, если метод закрыт авторизацией, необходимо отправить письмо на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru) с данными, как авторизоваться в методе. Для авторизации запросов может использоваться:
- **Client Credentials Flow** ([RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749))
- **Basic Authentication** ([RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617))
### **Время ответа**
Метод партнёра должен возвращать ответ не более чем за **300 миллисекунд**. Это оптимальная скорость ответа для обеспечения стабильной работы интеграции и оперативной обработки событий.
### **Retry-запросы**
Если метод партнёра отвечает с ошибкой, превышает сконфигурированное время ожидания или Банку не удаётся отправить запрос, то банк отправляет retry-запросы на доставку вебхука.
**Интервалы повторной отправки:** 30 секунд, 5 минут, 30 минут, 1 час, 3 часа, 6 часов, 12 часов, 24 часа, 48 часов, 72 часа.
**Возможные причины отправки retry-запроса:**
- был получен ответ с одним из следующих статусов: 401, 408, 409, 429, 500, 502, 503, 504, 507, 508, 509;
- ответ на запрос не был получен в пределах сконфигурированного времени ожидания (5 секунд);
- не удалось установить TCP-соединение;
- хост недоступен или не отвечает.
> **Важно:** Для предотвращения отправки Банком лишних retry-запросов необходимо возвращать коды, отличные от 2xx, только при возникновении технических сбоев на стороне партнёра.
### **Выписки**
В сервисе ["Выписки по счетам юрлиц"](/products/alfa-api/documentation/articles/transactions/transactions) в методах есть уникальный идентификатор транзакции (`transactionId`). Важно, чтобы партнёр на своей стороне игнорировал задублированные сообщения по этому идентификатору, возвращая код успешной обработки (2xx).
### **Входящие платежи по СБП для юрлиц**
В методе ["Получение входящих платежей"](/products/alfa-api/documentation/articles/sbp/articles/sbp-b2b/articles/incoming-payments/v1/incoming-payments) есть уникальный идентификатор операции НСПК (`nspkTransactionId`). Важно игнорировать задублированные сообщения по этому идентификатору, возвращая код успешной обработки (2xx).
---
## Параметры запроса (BODY)
| Атрибут | Тип | Обязательность | Описание |
| :----------------- | :----- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **actionType** | string | required | Действие над объектом. Возможные значения: `create` (создание), `update` (обновление), `delete` (удаление). |
| **eventTime** | string | required | Время, когда произошло событие. |
| **object** | string | required | Объект/сущность подписки: `ul_transaction_default` (выписка), `jp_sbp_incoming_payments` (входящие платежи СБП). |
| **data** | object | required | Данные по вебхукам. Поля зависят от объекта (см. методы [«Получение выписки»](/products/alfa-api/documentation/articles/transactions/articles/statement/v1/statement) или [«Получение входящих платежей»](/products/alfa-api/documentation/articles/sbp/articles/sbp-b2b/articles/incoming-payments/v1/incoming-payments)). |
| **organizationId** | string | optional | Идентификатор организации. |
| **sub** | string | optional | Идентификатор субъекта. |
---
## Пример запроса
```bash
curl -X POST https://webhook.partner.ru/api/v1/webhook-events \
-H "Content-Type: application/json" \
-d '[
{
"actionType": "create",
"eventTime": "2022-01-12T00:00:00",
"object": "ul_transaction_default",
"organizationId": "vvvvvv",
"sub": "f7490296-1ae1-11ec-9621-0242ac130002",
"data": {
"amount": {
"amount": 1.00,
"currencyName": "RUR"
},
"amountRub": {
"amount": 1.00,
"currencyName": "RUR"
},
"correspondingAccount": "30101810200000000593",
"direction": "CREDIT",
"documentDate": "2022-01-12",
"filial": "АО \"АЛЬФА-БАНК\" г Москва",
"number": "178",
"operationCode": "01",
"operationDate": "2022-01-12T00:00:00",
"paymentPurpose": "Перевод собственных средств. НДС не облагается.",
"priority": "5",
"revaln": null,
"uuid": "9084d309-b30b-5083-9a54-d4522472e11a",
"transactionId": "1220112MOCO#DS4001415",
"rurTransfer": {
"cartInfo": {
"documentCode": null,
"documentContent": null,
"documentDate": null,
"documentNumber": null,
"paymentNumber": null,
"restAmount": null
},
"deliveryKind": "электронно",
"departmentalInfo": {
"uip": "1",
"drawerStatus101": "01",
"kbk": "18210102010011000110",
"oktmo": "12301000",
"reasonCode106": "ТП",
"taxPeriod107": "ГД.01.2022",
"docNumber108": "123",
"docDate109": "12.01.2022",
"paymentKind110": "1"
},
"payeeAccount": "40702810301300000763",
"payeeBankBic": "044525593",
"payeeBankCorrAccount": "30101810200000000593",
"payeeBankName": "АО \"АЛЬФА-БАНК\" г Москва",
"payeeInn": "0140237176",
"payeeKpp": "770801001",
"payeeName": "Полное наименование Орг № 11329",
"payerAccount": "40702810701300000761",
"payerBankBic": "044525593",
"payerBankCorrAccount": "30101810200000000593",
"payerBankName": "АО \"АЛЬФА-БАНК\" г Москва",
"payerInn": "0140237176",
"payerKpp": "770801001",
"payerName": "Полное наименование Орг № 11329",
"payingCondition": null,
"purposeCode": "2",
"receiptDate": "2022-01-12",
"valueDate": "2022-01-12"
}
}
}
]'
```
---
## Параметры ответа
В случае успешной обработки ответа на стороне клиента необходимо вернуть любой код успешной обработки (**2xx**).
]]>
</partner_webhook_md>
<webhooks_intro_md>
<![CDATA[
# Как подключить вебхуки
**Теги:** `B2B` `B2C` `H2H`
Вебхук — это механизм информирования при наступлении в системе события, на которое подписан партнёр API.
Вебхуки повышают эффективность рабочих процессов. Для получения новой информации достаточно будет создать вебхук, и Банк сам будет отправлять информацию по изменениям состояния системы.
Используется токен доступа, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/acf) для партнёрских сервисов или по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/acf-h2h) для прямой интеграции.
---
### Инструкция по подключению
1. **Отправить письмо** на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru) с указанием `callbackUri` и события, на которое хотите подписаться.
2. **Реализовать метод:** Партнёру API на своей стороне необходимо реализовать открытый [Партнёрский метод для получения вебхуков](/products/alfa-api/documentation/articles/webhooks/articles/partner-webhook/v1/partner-webhook).
3. **Подписаться на событие** с помощью метода [«Создание вебхука»](/products/alfa-api/documentation/articles/webhooks/articles/create-webhook/v1/create-webhook).
4. **Управлять вебхуками**, используя следующие методы:
- [Редактирование вебхука](/products/alfa-api/documentation/articles/webhooks/articles/edit-webhook/v2/edit-webhook)
- [Удаление вебхука](/products/alfa-api/documentation/articles/webhooks/articles/delete-webhook/v1/delete-webhook)
- [Получение вебхука](/products/alfa-api/documentation/articles/webhooks/articles/get-webhook/v2/get-webhook)
- [Получение списка вебхуков](/products/alfa-api/documentation/articles/webhooks/articles/get-lists-webhooks/v2/get-lists-webhooks)
Инструкция по тестированию вебхуков представлена [здесь](/products/alfa-api/documentation/articles/sandbox/articles/check-webhook/articles/intro/intro).
---
### Требования к полю callbackUri
В поле `callbackUri` необходимо указывать хост, который указывали в качестве `redirect_uri` при интеграции с Alfa ID. Проверка будет проводиться только на соответствие домена второго уровня.
Это позволяет расширить возможные варианты для `callbackUri`. Например, если в качестве `redirect_uri` был указан [https://partner.ru](https://partner.ru), то можно создать следующие `callbackUri`:
- [https://partner.ru](https://partner.ru)
- [https://webhook.alfa.partner.ru](https://webhook.alfa.partner.ru)
- [https://webhook.partner.ru](https://webhook.partner.ru)
- [https://webhook.partner.partner.partner.ru](https://webhook.partner.partner.partner.ru)
> **Важно**
> Для создания вебхука с другим хостом необходимо удалить уже существующий вебхук.
---
### Допустимые значения scope
| Событие | scope |
| :-------------------------------- | :------------- |
| Операции по счетам | `transactions` |
| Входящие платежи по СБП для юрлиц | `b2b-sbp` |
---
**Дополнительные материалы:**
- **Предыдущая тема:** [Шифрование TXT ГОСТ-сертификатом](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/text-gost/text-gost)
- **Следующая тема:** [Создание вебхука](/products/alfa-api/documentation/articles/webhooks/articles/create-webhook/v1/create-webhook)
- **Видео-инструкция:** [Смотреть MP4](/assets/developers-portal.docs.alfa-api/articles/webhooks/articles/intro/files/webhooks.mp4)
]]>
</webhooks_intro_md>
</Вебхуки>
<Обмен_файлами>
<download_md>
<![CDATA[
# Скачивание файла
**Метки:** `B2B` `B2C` `H2H`
## Этапы процесса
1. **Получите ссылку для скачивания файла.** Подробнее в пункте «Получение ссылки».
2. **Выполните запрос на скачивание файла.** Подробнее в пункте «Запрос на скачивание».
3. **Скачивание файла.**
---
## Получение ссылки
Первым шагом необходимо получить ссылку на скачивание файла в рамках Вашего взаимодействия. Ниже приведен пример получаемой Вами ссылки для скачивания файла с описанием параметров.
### Атрибуты тела ответа (BODY)
| Атрибут | Тип | Обязательность | Описание |
| :------------------------------------ | :-------------- | :------------- | :------------------------------------------- |
| **downloadFileLinks** | array of object | optional | Ссылка для скачивания файла из Банка |
| └─ **url** | string | optional | Ссылка для скачивания файла |
| └─ **method** | string | optional | Метод, используемый для скачивания файла |
| └─ **detachedSignatureLink** | object | optional | Открепленная ЭЦП содержимого файла |
| &nbsp;&nbsp;&nbsp;&nbsp;└─ **url** | string | optional | Ссылка для скачивания файла открепленной ЭЦП |
| &nbsp;&nbsp;&nbsp;&nbsp;└─ **method** | string | optional | Метод для скачивания открепленной ЭЦП |
### Пример ссылок на скачивание
```json
{
"downloadFileLinks": [
{
"url": "https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ab?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=e78c051fcff1017a68795620c20e50db33126ab8374c2ee9644ef4743b3625c6",
"method": "GET",
"detachedSignatureLink": {
"url": "https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ab.sign?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=36ef1ccf28bdf6e54710fc3c1dd235c8f383275c2bbb0c9db365da272d3c24a8",
"method": "GET"
}
},
{
"url": "https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ac?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=e78c051fcff1017a68795620c20e50db33126ab8374c2ee9644ef4743b3625c6",
"method": "GET",
"detachedSignatureLink": {
"url": "https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ac.sign?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=36ef1ccf28bdf6e54710fc3c1dd235c8f383275c2bbb0c9db365da272d3c24a8",
"method": "GET"
}
}
]
}
```
---
## Запрос на скачивание
Для скачивания файла по полученной ссылке необходимо выполнить `http` запрос методом, указанным в параметре `method`, и полученной в параметре `url` ссылкой `https://baas.alfabank.ru/filebox/{bucketName}/{objectKey}` с параметрами запроса.
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :----------------- | :----- | :------------- | :------------------------- |
| **Accept** | string | required | `*/*` |
| **Content-Length** | string | required | 1024 |
| **Content-Type** | string | optional | `application/octet-stream` |
#### PATH
| Атрибут | Тип | Обязательность | Описание |
| :------------- | :----- | :------------- | :-------------------------------- |
| **bucketName** | string | required | Имя bucket'а для сохранения файла |
| **objectKey** | string | required | Имя файла |
#### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :------------------- | :------ | :------------- | :------------------------------------------------------- |
| **X-Amz-Date** | string | required | Дата и время генерации ссылки |
| **X-Amz-Expires** | integer | required | TTL ссылки (в секундах) относительно времени её создания |
| **X-Amz-Credential** | string | required | Данные об учётной записи s3 и подписи запроса |
| **X-Amz-Algorithm** | string | required | Алгоритм подписи запроса |
| **X-Amz-Signature** | string | required | Подпись запроса |
| **Content-Length** | integer | required | Размер содержимого файла |
### Пример запроса
```bash
curl -X GET https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ab?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=e78c051fcff1017a68795620c20e50db33126ab8374c2ee9644ef4743b3625c6 \
-H 'Accept: */*' \
-H 'Content-Length: 1024' \
-H 'Content-Type: application/octet-stream'
```
---
## Параметры ответа
| Код | Описание | Тело ответа |
| :---------------------------- | :------------------------ | :---------------------------------------------------------------------------------------------- |
| **200 OK** | Успешное скачивание | Нет тела ответа |
| **400 Bad Request** | Ошибка в запросе | `{"error": "Код ошибки"}` |
| **403 Forbidden** | Доступ запрещен | `{"error": "Время жизни ссылки истекло / Используется некорректный метод или ссылка изменена"}` |
| **404 Not Found** | Файл не найден | `{"error": "Код ошибки"}` |
| **500 Internal Server Error** | Внутренняя ошибка сервера | `{"error": "Код ошибки"}` |
---
### См. также:
- [Требования и ограничения](/products/alfa-api/documentation/articles/secure-file-transfer/articles/intro/intro)
- [Загрузка файла](/products/alfa-api/documentation/articles/secure-file-transfer/articles/upload/v1/upload)
- [Официальный портал разработчиков Alfa-Bank](https://developers.alfabank.ru/)
]]>
</download_md>
<requirements_and_restrictions_md>
<![CDATA[
# Требования и ограничения
**Область применения:** `B2B`, `B2C`, `H2H`
**Раздел:** Обмен файлами
Механизм для загрузки и скачивания файлов. В рамках продуктового метода API, который предполагает загрузку или скачивание файлов, Вы получите атрибут `downloadFileLinks`, который используется для скачивания файла, или атрибут `uploadFileLinks`, который используется для загрузки файла.
### Ограничения
1. По одной ссылке можно загрузить только один файл.
2. Для загрузки нескольких файлов необходимо поместить их в архив формата `.zip` (без пароля), либо загружать файлы отдельными загрузками (каждая в рамках своей задачи, переиспользовать ссылку нельзя).
### Форматы и размеры файлов
1. Для файлов, чей `MIME-тип = text/plain`, максимальный размер одного файла — **250 Мбайт**.
2. Для файлов, чей `MIME-тип ≠ text/plain`, максимальный размер одного файла — **60 Мбайт**.
### Время жизни ссылки
Ссылка содержит в себе параметр с датой и временем генерации ссылки `X-Amz-Date`.
- **Формат параметра:** `YYYYMMDDTHHMISSZ`.
- **Длительность:** Время жизни ссылки указывается в секундах параметром `X-Amz-Expires`.
Отсчёт времени жизни идет от времени генерации ссылки.
---
## Навигация
- [← SDK для подписи](/products/alfa-api/documentation/articles/sdk/articles/signature/v1/signature)
- [Скачивание файла →](/products/alfa-api/documentation/articles/secure-file-transfer/articles/download/v1/download)
---
### Структура раздела «Обмен файлами»
- **Требования и ограничения** (текущая страница)
- [Скачивание файла](/products/alfa-api/documentation/articles/secure-file-transfer/articles/download/v1/download)
- [Загрузка файла](/products/alfa-api/documentation/articles/secure-file-transfer/articles/upload/v1/upload)
---
_Документация Alfa-Bank (Alfa API)_
]]>
</requirements_and_restrictions_md>
<upload_md>
<![CDATA[
# Загрузка файла
**Теги:** `B2B` `B2C` `H2H`
Процесс загрузки файла состоит из трех основных этапов:
1. **Получите ссылку для загрузки файла** (Подробнее в пункте «Получение ссылки»)
2. **Выполните запрос на загрузку файла** (Подробнее в пункте «Запрос на загрузку»)
3. **Загрузка файла**
---
## Получение ссылки
Первым шагом необходимо получить ссылку на загрузку файла в рамках Вашего взаимодействия. Ниже приведен пример получаемой Вами ссылки для загрузки файла с описанием параметров.
### Атрибуты ответа (BODY)
| Атрибут | Тип | Обязательность | Описание |
| :------------------ | :---------------- | :------------- | :------------------------------------- |
| **uploadFileLinks** | `array of object` | optional | Ссылка для загрузки файла в Банк |
| ↳ **url** | `string` | optional | Ссылка для загрузки файла |
| ↳ **method** | `string` | optional | Метод, используемый для загрузки файла |
### Пример ссылок на загрузку
```json
{
"uploadFileLinks": [
{
"url": "https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ab?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=36ef1ccf28bdf6e54710fc3c1dd235c8f383275c2bbb0c9db365da272d3c24a8",
"method": "PUT"
},
{
"url": "https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90ab-cdef-1234-1234567890ac?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230608T152952Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fdev%2Fs3%2Faws4_request&X-Amz-Signature=36ef1ccf28bdf6e54710fc3c1dd235c8f383275c2bbb0c9db365da272d3c24a8",
"method": "PUT"
}
]
}
```
---
## Запрос на загрузку
Для загрузки файла по полученной ссылке необходимо выполнить `http` запрос методом, указанным в параметре `method`, и полученной в параметре `url` ссылкой:
`https://baas.alfabank.ru/filebox/{bucketName}/{objectKey}` с параметрами запроса.
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :----------------- | :------- | :------------- | :------------------------- |
| **Accept** | `string` | **required** | `*/*` |
| **Content-Length** | `string` | **required** | Например: `1024` |
| **Content-Type** | `string` | optional | `application/octet-stream` |
#### PATH
| Атрибут | Тип | Обязательность | Описание |
| :------------- | :------- | :------------- | :-------------------------------- |
| **bucketName** | `string` | **required** | Имя bucket'а для сохранения файла |
| **objectKey** | `string` | **required** | Имя файла |
#### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :------------------- | :-------- | :------------- | :------------------------------------------------------- |
| **X-Amz-Date** | `string` | **required** | Дата и время генерации ссылки |
| **X-Amz-Expires** | `integer` | **required** | TTL ссылки (в секундах) относительно времени её создания |
| **X-Amz-Credential** | `string` | **required** | Данные об учётной записи s3 и подписи запроса |
| **X-Amz-Algorithm** | `string` | **required** | Алгоритм подписи запроса |
| **X-Amz-Signature** | `string` | **required** | Подпись запроса |
| **Content-Length** | `integer` | **required** | Размер содержимого файла |
### Пример запроса
```bash
curl -X PUT https://baas.alfabank.ru/filebox/secure-file-transfer.incoming-files.to-processing/12345678-90AB-CDEF-1234-1234567890AB?X-Amz-Date=20230608T152952Z&X-Amz-Expires=3600&X-Amz-Credential=secure-file-transfer%2F20230608%2Fbaas%2Fs3%2Faws4_request&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=36ef1ccf28bdf6e54710fc3c1dd235c8f383275c2bbb0c9db365da272d3c24a8 \
-H 'Accept: */*' \
-H 'Content-Length: 1024' \
-H 'Content-Type: application/octet-stream' \
--data-binary 'Выписка по счету.pdf'
```
---
## Параметры ответа
### 200 OK
_Нет тела ответа_
### 400 Bad Request
| Атрибут | Тип | Обязательность | Описание |
| :-------- | :------- | :------------- | :--------- |
| **error** | `string` | **required** | Код ошибки |
### 403 Forbidden
| Атрибут | Тип | Обязательность | Описание |
| :-------- | :------- | :------------- | :------------------------------------------------------------------------------------------- |
| **error** | `string` | **required** | Код ошибки. Время жизни ссылки истекло / Используется некорректный метод или ссылка изменена |
### 404 Not Found
| Атрибут | Тип | Обязательность | Описание |
| :-------- | :------- | :------------- | :--------- |
| **error** | `string` | **required** | Код ошибки |
### 500 Internal Server Error
| Атрибут | Тип | Обязательность | Описание |
| :-------- | :------- | :------------- | :--------- |
| **error** | `string` | **required** | Код ошибки |
---
**Навигация:**
- [← Скачивание файла](/products/alfa-api/documentation/articles/secure-file-transfer/articles/download/v1/download)
- [Для чего это нужно →](/products/alfa-api/documentation/articles/signature-encryption/articles/intro/intro)
]]>
</upload_md>
</Обмен_файлами>
<Общая_информация>
<authorization_md>
<![CDATA[
# Авторизация
Теги: `B2B` `B2C` `H2H`
---
Получить доступ к продуктам и сервисам Alfa API можно двумя способами: с помощью Alfa ID или API Key.
Выбор способа авторизации зависит от типа интеграции, используемых вами продуктов и сервисов, требований безопасности и настроек вашей интеграции.
## Alfa ID
`B2B` `B2C` `H2H`
Этот способ подходит для любого типа интеграций и позволяет работать со всеми продуктами и сервисами Alfa API. Контроль безопасности обеспечивается за счёт использования токенов с коротким сроком действия и проведения аутентификации пользователей.
Подойдёт вам в следующих случаях:
•вы хотите выполнять операции по другим организациям (партнёрская интеграция);•вы хотите выполнять операции по своей организации (H2H-интеграция) и вам необходимо, чтобы ваши сотрудники проходили аутентификацию для получения доступа к продуктам и сервисам Alfa API.
## API Key
`H2H`
Это упрощённый способ авторизации запросов без аутентификации сотрудников вашей организации, который не требует регулярного обновления ключа доступа. Подходит для выполнения операций по своей организации. Контроль безопасности обеспечивается за счёт того, что запросы принимаются только с ваших доверенных серверов.
Доступные с помощью этого способа авторизации продукты и сервисы можно посмотреть [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/selfservice/articles/api-key/api-key).
Использование упрощённого способа авторизации будет оптимальным вариантом, если у вас H2H-интеграция, использующая продукты и сервисы, доступные с помощью `API Key` , и вам не требуется аутентификация сотрудников для доступа к продуктам и сервисам Alfa API.
Подробнее о способах авторизации можно прочитать в статьях ниже.
[Alfa ID](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/intro/intro)[API Key](https://developers.alfabank.ru/products/alfa-api/documentation/articles/api-key/api-key)
]]>
</authorization_md>
<channel_protection_md>
<![CDATA[
# Защита канала
Теги: `B2B` `B2C` `H2H`
---
## Введение
Защита данных с применением криптографических преобразований - одно из решений проблем информационной безопасности. Механизмы шифрования и дешифрования канала обеспечивает надёжность передачи информации. Защитить канал можно, используя асимметричные алгоритмы шифрования данных (RSA-сертификат) и транспортную подпись.
## Шифрование канала
Шифрование канала происходит исходя из выбора метода шифрования. Это может быть:
•шифрование с применением сертификата RSA (как применить RSA-сертификат смотрите в разделе [Требования к сертификату](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/tls/tls));•шифрование с применением сертификатов ГОСТ (раздел в подготовке).Выбор того или иного метода шифрования канала определяется критичностью данных:
•если персональные данные не передаются, то TLS RSA будет самым простым, дешёвым и гибким инструментом интеграции;•если персональные данные передаются, то обязательно использование сертификата ГОСТ. Партнёр API может выбирать, что использовать - TLS ГОСТ или вариант с ФПСУ ГОСТ.
]]>
</channel_protection_md>
<check_list_md>
<![CDATA[
## Чек-лист готовности к тестовой интеграции
1. **Заключите соглашение и договор**
Заключите соглашение о конфиденциальности и неразглашении информации, договор на информационно-технологическое взаимодействие с банком и подпишите приложения к нему. Подробнее в шаге 1 [инструкции по подключению](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/instruction/instruction).
2. **Получите тестовые client_id и scope**
Подробнее в шаге 2 [инструкции по подготовке к работе с песочницей](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/instruction/instruction).
3. **Установите тестовый TLS-сертификат, сертификаты Минцифры и проверьте доступ до Swagger UI**
Подробнее в шагах 3-5 [инструкции по подготовке к работе с песочницей](https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/sandbox).
4. **Получите тестовый client_secret**
Подробнее [на странице Client secret](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret).
5. **Реализуйте и протестируйте интеграцию Alfa ID и Alfa API в песочнице**
## Чек-лист готовности к промышленной интеграции
1. **Выполните все пункты из подраздела «Проверьте готовность к тестовой интеграции»**
2. **Создайте интеграцию в проме на Портале разработчика**
Подробнее [на странице Создание интеграции в проме](https://developers.alfabank.ru/products/alfa-api/documentation/articles/selfservice/articles/prod/prod)
3. **Выпустите TLS-сертификат**
Подробнее [на странице TLS-сертификат](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/tls/tls)
4. **Получите client_secret**
Подробнее [на странице Client secret](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret)
5. **Начните использовать Alfa ID и Alfa API**
]]>
</check_list_md>
<introduction_md>
<![CDATA[
`B2B` `B2C` `H2H`
# Введение
Добро пожаловать в документацию для разработчиков!
Мы рады приветствовать вас на нашем портале, где вы найдёте исчерпывающую информацию об Alfa API и все необходимые инструменты для успешного и безопасного использования наших услуг.
Перед началом работы рекомендуем внимательно ознакомиться с нашей документацией, которая содержит всю необходимую информацию для успешной интеграции.
[Подключение к Alfa API](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/connection)
[Песочница](https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/sandbox)
## Преимущества
Alfa API предоставляет ряд преимуществ для наших клиентов и партнёров, включая:
- быстрый и безопасный доступ к нашим банковским услугам;
- простоту интеграции с вашими приложениями и сервисами;
- возможность управления счетами, переводами и другими банковскими операциями;
- доступ к актуальным данным о состоянии счетов и истории операций.
## Типы интеграций
`B2B` `B2C`
**Партнёрские сервисы** — при данном типе интеграции предоставляется возможность выполнять операции по другим организациям (при наличии от них согласия) для предоставления им услуг. В рамках этой интеграции можно выполнять операции по юридическим лицам (другие компании), взаимодействие бизнеса с бизнесом. А также можно выполнять операции, где конечным потребителем услуг является физическое лицо.
`H2H`
**H2H-интеграции (Host-to-Host)** — при данном типе интеграции предоставляется возможность встроить банковские продукты в ERP-систему для выполнения операций по своей организации.
**Холдинги** — при данном типе интеграции предоставляется возможность для головной организации выполнять казначейские функции по своим дочерним компаниям.
Поможем выбрать интеграцию за 15 секунд — **[Пройдите опрос]**
При создании Alfa API и Alfa ID использовались спецификации: [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749); [OIDC 1.0](https://openid.net/specs/openid-connect-core-1_0.html); [формат JSON](https://www.json.org/json-en.html); RESTful архитектура и синхронный обмен данными.
Обновления по релизам публикуются в [Телеграм-канал](https://t.me/AlfaAPI)
]]>
</introduction_md>
<pagination_md>
<![CDATA[
[](https://developers.alfabank.ru/) / Общая информация / Пагинация
`B2B` `B2C` `H2H`
# Пагинация
---
Пагинация - разделение ответа на несколько страниц. Механизм пагинации может быть использован в REST-запросах GET.
## Параметры запроса
**Пример запроса**
```bash
1curl -X GET '{host}/claims?limit=5&offset=5'
-H 'Content-Type: application/json'
```
### QUERY
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **limit** | `NUMBER` _(optional)_ | Количество объектов на одной странице. Значение по умолчанию: 1000. Максимальное значение: 1000 |
| **offset** | `NUMBER` _(optional)_ | Количество объектов в списке, которые необходимо пропустить. Значение по умолчанию: 0 |
Количество объектов на одной странице. Значение по умолчанию: 1000. Максимальное значение: 1000
Количество объектов в списке, которые необходимо пропустить. Значение по умолчанию: 0
## Параметры ответа
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **limit** | `NUMBER` _(optional)_ | Количество объектов на одной странице |
| **offset** | `NUMBER` _(optional)_ | Количество объектов в списке, которые необходимо пропустить |
| **totalCount** | `NUMBER` _(optional)_ | Общее количество записей |
#### Ответ: 200 OK
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **limit** | `NUMBER` _(optional)_ | Количество объектов на одной странице |
| **offset** | `NUMBER` _(optional)_ | Количество объектов в списке, которые необходимо пропустить |
| **totalCount** | `NUMBER` _(optional)_ | Общее количество записей |
Количество объектов на одной странице
Количество объектов в списке, которые необходимо пропустить
Общее количество записей
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | `STRING` **(required)** | Код ошибки. Принимает возможные значения: invalid_request - неверные входные параметры запроса |
| **error_description** | `STRING` _(optional)_ | Описание ошибки |
#### Ответ: 400 Bad Request
```json
invalid_request
```
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | `STRING` **(required)** | Код ошибки. Принимает возможные значения: invalid_request - неверные входные параметры запроса |
| **error_description** | `STRING` _(optional)_ | Описание ошибки |
Код ошибки. Принимает возможные значения: invalid_request - неверные входные параметры запроса
Описание ошибки
## Алгоритм работы пагинации
Пример 1: Если клиент запрашивает limit = 100, offset = 0, то клиенту вернётся с 1-ой по 100-ую запись.
Пример 2: Если клиент запрашивает limit = 100, offset = 1000, то клиенту вернётся с 1001-ой по 1100-ую запись.
Сортировка в пагинации происходит следующим образом: вверху списка возвращаются новые записи, внизу - старые записи.
---
[Версионирование](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/version/version) | [Термины и определения](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/terms/terms)
]]>
</pagination_md>
<scopes_md>
<![CDATA[
* / Общая информация / Scopes (области применения)*
`B2B` `B2C` `H2H`
# Scopes (области применения)
| SCOPE | DESCRIPTION | RESOURSES |
| --- | --- | --- |
| transactions | Выписки по счетам юрлиц | `GET /jp/v1/statement/transactions`<br>`GET /jp/v2/accounts/{accountNumber}/transactions/1C`<br>`GET /jp/v1/accounts/{accountNumber}/transactions/MT940`<br>`GET /jp/v1/correspondent-accounts/{accountNumber}/transactions`<br>`GET /jp/v1/statement/summary`<br>`POST /jp/v1/accounts/{accountNumber}/transactions/files/requests`<br>`GET /jp/v1/accounts/transactions/files/requests/{requestId}` |
| escrow | Эскроу-счета 214-ФЗ. Резервирование | `GET /build-projects`<br>`POST /escrow-orders`<br>`GET /jp/v1/escrow-orders/{referenceID}`<br>`GET /jp/v1/escrow-orders`<br>`PATCH /escrow-orders/{referenceID}/execute`<br>`DELETE /escrow-orders/{referenceID}`<br>`POST /jp/v1/escrow-orders/{referenceID}/cancel`<br>`POST /jp/v1/escrow-orders-full` |
| escrow-reports | Эскроу-счета 214-ФЗ. Формирование отчётов | `GET /jp/v1/escrow-reports/developers/build-projects`<br>`POST /jp/v1/escrow-reports` |
| customer | Профиль организации | `GET /jp/v2/customer-info` |
| payment | Платёжные поручения | `POST /jp/v2/payments`<br>`GET /jp/v2/payments/{externalId}/state`<br>`GET /jp/v1/payments/{externalId}`<br>`GET /jp/v1/payments/{externalId}/print-form`<br>`GET /jp/v1/payments/{externalId}/print-form/download`<br>`PATCH /jp/v2/payments/{externalId}/state` |
| as-operation-with-selfemployed | Добавление самозанятых, получение справочных данных | `POST /semp/v1/agreement-pages`<br>`POST /semp/v1/selfemployed/registries/add-selfemployed`<br>`GET /semp/v1/selfemployed/registries/add-selfemployed/{requestId}`<br>`GET /semp/v1/dictionary/activities`<br>`GET /semp/v1/dictionary/regions`<br>`GET /semp/v1/selfemployed/lists`<br>`GET /semp/v1/selfemployed/{vatin}`<br>`PUT /semp/v1/selfemployed/{vatin}` |
| as-selfemployed-fts-status | Статус самозанятого | `POST /semp/v1/selfemployed/taxpayer-statuses`<br>`GET /semp/v1/selfemployed/taxpayer-statuses/{requestId}` |
| as-accrual-and-debt | Налоговые начисления, задолженности и пени самозанятого | `POST /semp/v1/selfemployed/accruals-and-debts`<br>`GET /semp/v1/selfemployed/accruals-and-debts/{requestId}`<br>`POST /semp/v1/selfemployed/payment-documents`<br>`GET /semp/v1/selfemployed/payment-documents/{requestId}`<br>`POST /semp/v1/selfemployed/income-for-period`<br>`GET /semp/v1/selfemployed/income-for-period/{requestId}`<br>`POST /semp/v1/selfemployed/income`<br>`GET /semp/v1/selfemployed/income/{requestId}`<br>`POST /semp/v1/selfemployed/taxpayer-account-info`<br>`GET /semp/v1/selfemployed/taxpayer-account-info/{requestId}` |
| as-receipt-and-payout | Проведение выплат и формирование чеков, список банков-участников СБП | `POST /semp/v1/payouts/registries/receipts-and-payouts`<br>`GET /semp/v1/payouts/registries/{requestId}`<br>`GET /semp/v1/payouts`<br>`GET /semp/v1/dictionary/sbp-banks`<br>`GET /semp/v1/payouts/lists`<br>`GET /semp/v1/payouts/selfemployed/{vatin}`<br>`POST /semp/v1/payouts/registries/cancel-receipts`<br>`POST /semp/v1/payouts/registries/accept/{requestId}` |
| as-receipt | Декларация доходов, аннулирование чеков | `POST /semp/v1/payouts/registries/receipts`<br>`POST /semp/v1/payouts/registries/cancel-receipts`<br>`GET /semp/v1/payouts/registries/cancel-receipts/{requestId}`<br>`GET /semp/v1/payouts/registries/{requestId}`<br>`GET /semp/v1/payouts`<br>`GET /semp/v1/payouts/lists`<br>`GET /semp/v1/payouts/selfemployed/{vatin}`<br>`POST /semp/v1/payouts/registries/accept/{requestId}` |
| as-payout-with-check-status | Проведение выплат самозанятым, список банков-участников СБП | `POST /semp/v1/payouts/registries/with-selfemployed-check-status`<br>`GET /semp/v1/payouts/registries/{requestId}`<br>`GET /semp/v1/payouts`<br>`GET /semp/v1/dictionary/sbp-banks`<br>`GET /semp/v1/payouts/lists`<br>`GET /semp/v1/payouts/selfemployed/{vatin}`<br>`POST /semp/v1/payouts/registries/accept/{requestId}` |
| as-payout | Осуществление выплат самозанятым | `POST /semp/v1/payouts/registries/payouts`<br>`GET /semp/v1/payouts/registries/{requestId}`<br>`GET /semp/v1/payouts`<br>`GET /semp/v1/dictionary/sbp-banks`<br>`GET /semp/v1/payouts/lists`<br>`GET /semp/v1/payouts/selfemployed/{vatin}`<br>`POST /semp/v1/payouts/registries/accept/{requestId}` |
| sbp_terminals_reg | Приём оплаты через СБП | `GET /jp/v1/legal`<br>`GET /jp/v1/merchants/{merchantId}`<br>`POST /jp/v1/terminals` |
| loan-applications | Кредиты | `POST /smart-loans/jp/v1/loan-applications`<br>`POST /loan-applications`<br>`GET /smart-loans/jp/v1/loan-applications/{dealId}/status` |
| signature | Электронная подпись | `GET /jp/v3/signature/dn`<br>`GET /jp/v3/signature/dn/file`<br>`POST /jp/v3/signature/rsa-certificates/requests/issue`<br>`POST /jp/v3/signature/requests/{id}/operations`<br>`PUT /jp/v3/signature/requests/operations/{id}`<br>`GET /jp/v3/signature/requests/{id}`<br>`GET /jp/v3/signature/rsa-certificates/{id}`<br>`POST /jp/v3/signature/rsa-certificates/{id}/requests/activation`<br>`PUT /jp/v3/signature/sign-settings`<br>`POST /jp/v3/signature/rsa-certificates/{Id}/requests/switch`<br>`POST /jp/v3/signature/rsa-certificates/{Id}/requests/reissue`<br>`POST /jp/v3/signature/rsa-certificates/{Id}/requests/revocation`<br>`POST /jp/v3/signature/qes/requests`<br>`POST /jp/v3/signature/qes/requests/{Id}`<br>`PATCH /jp/v3/signature/qes/requests/{Id}`<br>`POST /jp/v3/signature/powers-of-attorney/requests`<br>`GET /jp/v3/signature/powers-of-attorney/requests/{id}/status`<br>`GET /jp/v3/signature/powers-of-attorney/requests/{id}` |
| accounts | Счета | `GET /pp/v1/accounts`<br>`GET /pp/v1/accounts/{accountNumber}`<br>`GET /pp/v1/accounts/{accountNumber}/requisites`<br>`GET /jp/open-banking/v1.3/accounts`<br>`GET /jp/open-banking/v1.3/accounts/{accountId}/statements`<br>`POST /jp/open-banking/v1.3/statements`<br>`GET /jp/open-banking/v1.3/statements/{statementId}` |
| cards | Карты | `GET /pp/v1/cards`<br>`GET /pp/v1/cards/{cardId}/tariffs`<br>`GET /pp/v1/cards/{cardId}/subscriptions` |
| card-sec-actions | Тарифы и операции по карте | `GET /pp/v1/cards/{cardId}/actions`<br>`POST /pp/v1/cards/{cardId}/actions`<br>`PUT /pp/v1/cards/{cardId}/actions` |
| operations-history | Истории операций | `GET /pp/v1/operations`<br>`GET /pp/v1/operations/{id}` |
| reports-downloading | Получение документов | `GET /pp/v1/reports`<br>`GET /pp/v1/reports/{reportId}/body` |
| debit-statements | Выписки по счёту | `POST /pp/v1/reports/type/account`<br>`POST /pp/v1/reports/type/account/balance/eng`<br>`POST /pp/v1/reports/type/account/balance/rus` |
| credit-statements | Справки по кредитам | `POST /pp/v1/reports/type/credit/closed`<br>`POST /pp/v1/reports/type/credit/info`<br>`POST /pp/v1/reports/type/credit/statement` |
| deposit-statements | Справка по депозиту | `POST /pp/v1/reports/type/deposit` |
| limits-control | Лимиты по операциям | `GET /pp/v1/limits/general`<br>`GET /pp/v1/cards/{cardId}/user-limits`<br>`POST /pp/v1/cards/{cardId}/user-limits`<br>`DELETE /pp/v1/cards/{cardId}/user-limits/{limitId}` |
| loyalty | Программа лояльности | `POST /pp/v1/bonus-accounts-transactions`<br>`GET /pp/v1/bonus-accounts`<br>`GET /pp/v1/bonus-accounts/{accountNumber}` |
| b2c_sbp_payments | Платежи через СБП | `POST /b2cpay/jp/v1/payments`<br>`GET /b2cpay/jp/v1/payments`<br>`GET /b2cpay/jp/v1/payments/packages/{packageId}`<br>`POST /b2cpay/jp/v1/clients/checks`<br>`GET /b2cpay/jp/v1/clients/checks/{checkId}`<br>`GET /b2cpay/jp/v1/clients/info`<br>`GET /b2cpay/jp/v1/banks`<br>`GET /b2cpay/jp/v1/payments/download/{transactionId}` |
| credit | Кредитные предложения | `GET /pp/v1/credit-offers` |
| c2b-sbp | Оплата покупок через СБП | `POST /sbp/jp/v1/qrcs`<br>`POST /sbp/jp/v1/subscriptions`<br>`GET /sbp/jp/v1/qrc-status`<br>`POST /sbp/jp/v1/petitions`<br>`POST /sbp/jp/v1/terminals/{termNo}/cash-qrcs`<br>`POST /sbp/jp/v1/terminals/{termNo}/cash-qrcs/{qrcId}/activation`<br>`DELETE /sbp/jp/v1/terminals/{termNo}/cash-qrcs/{qrcId}/activation`<br>`POST /sbp/jp/v1/refund`<br>`GET /sbp/jp/v1/refund/status` |
| b2b-sbp | Операции СБП для юрлиц | `POST /sbp/jp/v1/payment-urls/one-time-use`<br>`POST /sbp/jp/v1/payment-urls/reusable`<br>`GET /sbp/jp/v1/payment-urls`<br>`GET /sbp/jp/v1/payment-urls/{qrcId}/data`<br>`GET /sbp/jp/v1/incoming-payments`<br>`POST /sbp/jp/v1/outgoing-payments/one-pay`<br>`GET /sbp/jp/v1/outgoing-payments`<br>`GET /sbp/jp/v1/outgoing-payments/{outgoingPaymentId}/status`<br>`POST /sbp/jp/v1/payment-urls/batch`<br>`GET /sbp/jp/v1/payment-urls/batch/{batchId}`<br>`PATCH /sbp/jp/v1/payment-urls` |
| digital-tariff | Дебетовая анкета | `POST /pp/v1/debit-cards/forms`<br>`POST /pp/v1/debit-cards/forms/{formId}/verification-sms`<br>`POST /pp/v1/debit-cards/forms/{formId}/resending-sms`<br>`POST /pp/v1/debit-cards/forms/{formId}/verification-passport` |
| plastic-delivery | Доставка дебетовой карты | `POST /pp/v1/debit-cards/forms/{formId}/verification-sms`<br>`POST /pp/v1/debit-cards/forms/{formId}/resending-sms`<br>`GET /pp/v1/debit-cards/forms/{formId}/draft`<br>`GET /pp/v1/debit-cards/forms/{formId}/delivery-type`<br>`GET /pp/v1/debit-cards/forms/{formId}/time-slots`<br>`POST /pp/v1/debit-cards/forms/{formId}/time-slots`<br>`POST /pp/v1/debit-cards/forms/{formId}/confirmation` |
| dfa | Цифровые финансовые активы (ЦФА) | `GET /dfa/gd/v1/dfa-profile/initial-placement-list` |
| salary-project | Зарплатный проект | `POST /jp/v1/salary-project/accounts/applications`<br>`GET /jp/v1/salary-project/accounts/applications/{applicationId}`<br>`POST /jp/v1/salary-project/payroll/applications`<br>`GET /jp/v1/salary-project/payroll/applications/{applicationId}` |
| loyalty-program | Получение бонусных номеров | `GET /pp/v1/bonus-numbers` |
| payment-registries | Реестры рублёвых платежей | `POST /jp/v2/payments/registries`<br>`GET /jp/v2/payments/registries/{registryId}` |
| invoices | Выставление счёта клиенту | `POST /jp/v1/payments/from-invoice`<br>`POST /jp/v2/payments/from-invoice-budget` |
| factoring | Факторинг | `GET /aff/jp/v1/creditors/compliance`<br>`POST /aff/jp/v1/payments`<br>`POST /aff/jp/v1/registers`<br>`POST /aff/jp/v1/registers/sign`<br>`GET /aff/jp/v1/payments/{paymentId}`<br>`GET /aff/jp/v1/registers/{registerId}`<br>`GET /aff/jp/v1/registers/{registerId}/documents` |
| beneficiaries | Информация о номинальных счетах и их контрагенты | `GET /na/jp/v1/nominal-accounts`<br>`GET /na/jp/v1/beneficiaries/requests/{requestId}/status`<br>`POST /na/jp/v1/beneficiaries`<br>`GET /na/jp/v1/beneficiaries`<br>`GET /na/jp/v1/beneficiaries/{beneficiaryId}`<br>`PUT /na/jp/v1/beneficiaries/{beneficiaryId}`<br>`POST /na/jp/v1/beneficiaries/{beneficiaryId}/scoring`<br>`POST /na/jp/v1/beneficiaries/{beneficiaryId}/requisites`<br>`GET /na/jp/v1/beneficiaries/{beneficiaryId}/requisites`<br>`PATCH /na/jp/v1/beneficiaries/{beneficiaryId}/requisites/{requisiteId}`<br>`GET /na/jp/v1/beneficiaries/{beneficiaryId}/balance`<br>`GET /na/jp/v1/beneficiaries/{beneficiaryId}/transactions`<br>`POST /na/jp/v1/universal-recipients`<br>`GET /na/jp/v1/universal-recipients`<br>`GET/na/jp/v1/universal-recipients/{universalRecipientId}`<br>`POST /na/jp/v1/universal-recipients/{universalRecipientId}/requisites`<br>`GET /na/jp/v1/universal-recipients/{universalRecipientId}/requisites`<br>`PATCH /na/jp/v1/universal-recipients/{universalRecipientId}/requisites/{requisiteId}` |
| deals | Безопасные сделки | `POST /na/jp/v1/deals`<br>`GET /na/jp/v1/deals`<br>`GET /na/jp/v1/deals/{dealId}`<br>`PATCH /na/jp/v1/deals/{dealId}/is-valid`<br>`GET /na/jp/v1/deals/{dealId}/payoffs`<br>`PATCH /na/jp/v1/deals/action`<br>`POST /na/jp/v1/deals/steps`<br>`GET /na/jp/v1/deals/{dealId}/requests/{requestId}/status`<br>`GET /na/jp/v1/deals/{dealId}/steps`<br>`GET /na/jp/v1/deals/{dealId}/steps/{stepId}`<br>`PATCH /na/jp/v1/deals/steps/contractors`<br>`GET /na/jp/v1/deals/{dealId}/steps/{stepId}/contractors` |
| beneficiary-payments | Идентификация пополнений номинального счёта и выплаты с него | `GET /na/jp/v1/unidentified-transactions`<br>`POST /na/jp/v1/unidentified-transactions/{id}/identify`<br>`GET /na/jp/v1/unidentified-transactions/{id}/identify/{identifyId}`<br>`POST /na/jp/v1/unidentified-transactions/{id}/refunds`<br>`GET /na/jp/v1/unidentified-transactions/{id}/refunds/{refundId}`<br>`POST /na/jp/v1/payoffs`<br>`GET /na/jp/v1/payoffs/{payoffId}/status`<br>`PATCH /na/jp/v1/payoffs/{payoffId}/accept`<br>`GET /na/jp/v1/payoffs/{payoffId}`<br>`POST /na/jp/v1/tax-refund`<br>`GET /na/jp/v1/tax-refund/{taxRefundId}/status`<br>`PATCH /na/jp/v1/tax-refund/{taxRefundId}/accept` |
]]>
</scopes_md>
<terms_and_definitions_md>
<![CDATA[
[](https://developers.alfabank.ru/) / Общая информация / Термины и определения
`B2B` `B2C` `H2H`
# Термины и определения
---
**Аутентификация** – процедура проверки данных пользователя, обратившегося для доступа к информационному ресурсу Партнёра API.
**Банк** – Акционерное общество «Альфа-банк».
**Грант** – вид сценария интеграции, такие как Authorization Code Flow или Client Credentials Flow.
Партнёр API – клиент Банка, использующий канал Alfa API для проведения интеграции своей системы и системы/сервисов Банка. Для Партнёра API необходимо заключить Договор на информационно-технологическое взаимодействие в целях использования канала Alfa API.
**Сервис** – набор методов API, доступ к которым от имени пользователя Вы можете получить.
**Alfa API** – это канал предоставления банковских продуктов и услуг, а также инструмент их безопасной интеграции в бизнес-процессы Партнёров API.
**Alfa ID** – единая учётная запись пользователя ЮЛ (юридического лица) / ФЛ (физического лица), используемая для регистрации и входа пользователей в продукты и сервисы Банка и Партнёров API.
**Access token** – токен доступа, который формируется на основе согласия пользователя на взаимодействие от его имени Партнёра с Банком.
**Claims** – набор данных пользователя, доступ к которым Вы можете получить.
**Client ID** – уникальный идентификатор Партнёра API, который Вы получаете при регистрации.
**Client secret** – секретный ключ партнёрского сервиса.
**Redirect URI** – URL, на который сервер авторизации будет отправлять пользователя после успешной авторизации приложения и которому будет предоставляться код авторизации. Необходим при использовании типа гранта Authorization Code Flow.
**Refresh token** - токен, который даёт возможность получить новый токен доступа взамен истекшего.
**Scopes** – это общий набор операций и/или клэймов.
---
[Пагинация](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/pagination/pagination) | [Что это и для чего нужно](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/certificate/articles/intro/intro)
]]>
</terms_and_definitions_md>
<vensioning_md>
<![CDATA[
# Версионирование
Теги: `B2B` `B2C` `H2H`
---
Версии методов/эндпоинтов обозначаются как `v1` , `v2` , `v3` и так далее. Это позволяет явно указать, какую версию API использует клиент.
## Мажорные изменения
Мажорные изменения подразумевают выпуск новой версии API. Они включают изменения, которые приводят к обратной несовместимости.
Примеры мажорных изменений:
•добавление обязательных параметров в запрос;•удаление обязательных параметров из запроса или ответа;•трансформация необязательных параметров в обязательные;•изменение типа параметра в запросе или ответе.
## Минорные изменения
Минорные изменения не требуют выпуска новой версии API. Они не нарушают обратную совместимость.
Примеры минорных изменений:
•добавление новой функциональности без нарушения обратной совместимости;•исправление ошибок;•улучшение производительности;•дополнительные необязательные параметры в запросе или ответе.
## Поддержание старой версии
Срок поддержки работы старой версии составляет от двух до шести месяцев. После этого срока Банк оставляет за собой право прекратить поддержку старой версии. При этом будет добавлено уведомление о прекращении поддержки старой версии эндпоинта.
## Тестирование в песочнице
Переход на новую версию обязательно должен включать тестирование в песочнице (тестовой среде).
]]>
</vensioning_md>
<Сертификаты_Минцифры>
<for_android_md>
<![CDATA[
*Общая информация / Сертификаты для Android*
B2BB2CH2H# Сертификаты для Android
Инструкция по установке сертификатов на телефон или планшет с системой Android. Для корректной работы нужно два сертификата - корневой и выпускающий.
## Установка корневого сертификата
1. **Скачайте корневой сертификат**
1.Скачайте корневой сертификат [Russian Trusted Root CA](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/russian_trusted_root_ca.cer).2.Перейдите в «Настройки».3.В поиске введите «Сертификат».4.Выберите «Сертификат CA».5.Если появится окно «Укажите название сертификата», введите «Russian Trusted Root CA».6.Выберите «VPN и приложения» и нажмите «ОК».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android1.png)
2. **Установите сертификат**
Если откроется предупреждение, нажмите «Всё равно установить» или «Установить в любом случае».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android2.png)
3. **Введите пароль**
1.Введите код-пароль от устройства.2.Нажмите «Подтвердить».3.В загрузках выберите «Russian Trusted Root CA.cer».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android3.png)
4. **Сертификат установлен**
После установки в нижней части экрана появится уведомление «Сертификат ЦС установлен».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android4.png)
## Установка выпускающего сертификата
1. **Скачайте выпускающий сертификат**
1.Скачайте выпускающий сертификат [Russian Trusted Sub CA](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/russian_trusted_sub_ca.cer).2.Перейдите в «Настройки».3.В поиске введите «Сертификат».4.Выберите «Сертификат CA».5.В предупреждении нажмите «Всё равно установить» или «Установить в любом случае».6.Если появится окно «Укажите название сертификата», введите «Russian Trusted Sub CA».7.Выберите «VPN и приложения» и нажмите «ОК».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android1.png)
2. **Установите сертификат**
Если откроется предупреждение, нажмите «Всё равно установить» или «Установить в любом случае».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android3.png)
3. **Введите пароль**
1.Введите код-пароль от устройства.2.Нажмите «Подтвердить».3.В загрузках выберите «Russian Trusted Sub CA.cer».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android4.png)
4. **Сертификат установлен**
После установки в нижней части экрана появится уведомление «Сертификат ЦС установлен».
## Проверка установки сертификатов
Проверьте, что сертификаты успешно установлены:
1. **Перейдите в «Настройки»**
2. **В поиске введите «Надёжные сертификаты» или «Надёжные учётные данные»**
3. **Перейдите во вкладку «Пользователь»**
При успешной установке сертификатов в списке должно отобразиться два установленных сертификата Минцифры: «Russian Trusted Root CA» и «Russian Trusted Sub CA».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/android/files/android5.png)
Очистите кэш вашего браузераОчистите кэш браузера на устройстве, с которого осуществляется доступ. Это необходимо для корректной работы с ресурсами, защищёнными сертификатами безопасности Минцифры.
[Что это и для чего нужно](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/certificate/articles/intro/intro)[Сертификаты для iOS](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/certificate/articles/ios/ios)
]]>
</for_android_md>
<for_linux_md>
<![CDATA[
*Общая информация / Сертификаты для Linux*
B2BB2CH2H# Сертификаты для Linux
Инструкция по установке сертификатов для владельцев ноутбуков и компьютеров с операционной системой Linux. Для корректной работы нужно два сертификата - корневой и выпускающий.
Процедура установки сертификатов зависит от используемого браузера.
## Red Hat Enterprise Linux
1. **Скачайте сертификаты**
Скачайте [корневой сертификат](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/russian_trusted_root_ca_pem.crt) и [выпускающий сертификат](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/russian_trusted_sub_ca_pem.crt). Загрузите сертификаты в папку «Downloads».
2. **Установите сертификаты Удостоверяющего Центра Минцифры**
1. Нажмите на «Activities» -> «Terminal», чтобы открыть терминал.
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/linux1.png)
2. Убедитесь, что файлы сертификатов «russian_trusted_root_ca_pem.crt» и «russian_trusted_sub_ca_pem.crt» находятся в директории «Downloads». Для проверки перейдите в неё с помощью `cd` и вызовите команду `ls` для отображения списка файлов.
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/linux2.png)
3. Скопируйте корневой сертификат в каталог `/usr/share/pki/ca-trust-source/anchors/` . Выполните команду `sudo cp russian_trusted_root_ca_pem.crt /usr/share/pki/ca-trust-source/anchors` .
4. Введите пароль суперпользователя.
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/linux3.png)
5. Cкопируйте в этот же каталог выпускающий сертификат. Выполните команду `sudo cp russian_trusted_sub_ca_pem.crt /usr/share/pki/ca-trust-source/anchors` .
6. Обновите общесистемное хранилище сертификатов командой `sudo update-ca-trust` .
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/linux4.png)
7. Проверьте хранилище доверенных сертификатов. Воспользуйтесь командой `trust list` . В конце списка должны появиться сертификаты «Russian Trusted Root CA» и «Russian Trusted Sub CA».
Очистите кэш вашего браузераОчистите кэш браузера на устройстве, с которого осуществляется доступ. Это необходимо для корректной работы с ресурсами, защищёнными сертификатами безопасности Минцифры.
## Mozilla Firefox
1. **Скачайте сертификаты**
Скачайте [«корневой сертификат»](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/russian_trusted_root_ca_pem.crt) и [«выпускающий сертификат»](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/russian_trusted_sub_ca_pem.crt). Загрузите сертификаты в папку «Downloads».
2. **Установите сертификаты Удостоверяющего Центра Минцифры**
1. Откройте браузер Firefox → перейдите в «Настройки» → в поиске введите «Сертификат» → выберите «Просмотр сертификатов…».
2. В открывшемся окне «Управление сертификатами» нажмите на «Импортировать…».
3. Перейдите в папку со скачанными сертификатами. Дважды кликните по сертификату «russian_trusted_root_ca_pem.crt» → установите флажок «Доверять при идентификации веб-сайтов» → нажмите «ОК».
4. В открывшемся окне «Управление сертификатами» нажмите «Импортировать».
5. Вернитесь в папку со скачанными сертификатами. Дважды кликните по сертификату «russian_trusted_sub_ca_pem.crt» → установите флажок «Доверять при идентификации веб-сайтов» → нажмите «ОК».
6. Проверьте список сертификатов. Найдите в нём «The Ministry of Digital Development and Communications». Внутри должны находиться сертификаты «Russian Trusted Root CA» и «Russian Trusted Sub CA».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/linux5.png)
Очистите кэш вашего браузераОчистите кэш браузера на устройстве, с которого осуществляется доступ. Это необходимо для корректной работы с ресурсами, защищёнными сертификатами безопасности Минцифры.
## Chromium
1. **Скачайте сертификаты**
Скачайте [](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/russian_trusted_root_ca_pem.crt) и [](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/russian_trusted_sub_ca_pem.crt). Загрузите сертификаты в папку «Downloads».
2. **Установите сертификаты Удостоверяющего Центра Минцифры**
1. Откройте браузер Chromium → перейдите в «Настройки» → в строке поиска введите «Сертификат» → нажмите на «Безопасность» в разделе «Конфиденциальность и безопасность» → выберите «Настроить сертификаты».
2. Перейдите во вкладку «Центры сертификации» → выберите «Импорт».
3. Перейдите в папку со скачанными сертификатами. Дважды кликните по сертификату «russian_trusted_root_ca_pem.crt» → установите флажок «Доверять этому сертификату при идентификации сайтов» → нажмите «ОК».
4. Во вкладке «Центры сертификации» снова выберите кнопку «Импорт» → дважды кликните по сертификату «russian_trusted_sub_ca_pem.crt» → установите флажок «Доверять этому сертификату при идентификации сайтов» → нажмите «ОК».
5. Проверьте список сертификатов. Найдите «org-The Ministry of Digital Development and Communications» и раскройте список. Внутри должны находиться сертификаты «Russian Trusted Root CA» и «Russian Trusted Sub CA».
![image](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/specification/articles/certificate/articles/linux/files/linux6.png)
Очистите кэш вашего браузераОчистите кэш браузера на устройстве, с которого осуществляется доступ. Это необходимо для корректной работы с ресурсами, защищёнными сертификатами безопасности Минцифры.
[Сертификаты для MacOS](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/certificate/articles/macos/macos)[Как подключить](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/instruction/instruction)
]]>
</for_linux_md>
<what_it_is_and_what_it_is_for_md>
<![CDATA[
[](https://developers.alfabank.ru/) / Общая информация / ... / Что это и для чего нужно
`B2B` `B2C` `H2H`
# Что это и для чего нужно
---
Установка сертификата Министерства цифрового развития, связи и массовых коммуникаций Российской Федерации (Минцифры) необходима для подтверждения личности и безопасности пользователя при работе с определёнными типами данных и сервисов.
Этот сертификат используется для шифрования данных, аутентификации пользователя и защиты от мошенничества и кибератак.
Кроме того, он может потребоваться для доступа к некоторым государственным услугам и сервисам, связанным с электронной подписью и документооборотом.
Для получения защищённого доступа ко всем сайтам и онлайн-сервисам используйте браузеры с поддержкой российских сертификатов: Яндекс Браузер или Атом.
Альтернативный способ - установка корневого сертификата. Если Вы привыкли работать в других браузерах или возникли проблемы с работой сторонних программ, Вы можете установить корневой сертификат в операционную систему.
Ответы на часто задаваемые вопросы можно посмотреть здесь.
---
[Термины и определения](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/terms/terms) | [Сертификаты для Android](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/certificate/articles/android/android)
]]>
</what_it_is_and_what_it_is_for_md>
</Сертификаты_Минцифры>
</Общая_информация>
<Песочница>
<check_webhook>
<checking_the_webhook_eg_transactions_md>
<![CDATA[
# Проверка работы вебхука
**Теги:** `B2B` `B2C` `H2H`
### Эндпоинт для Песочницы
`POST https://sandbox.alfabank.ru/api/v1/webhooks-events`
### Scope
`transactions` `b2b-sbp`
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
| **Content-Type** | string | required | application/json |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :--------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **object** | string | required | Объект/сущность, на который партнёр API хочет подписаться. Возможные значения:<br>• `ul_transaction_default` — получение выписки;<br>• `jp_sbp_incoming_payments` — получение входящих платежей |
### Пример запроса
```bash
curl -X POST https://sandbox.alfabank.ru/api/v1/webhooks-events \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"object": "ul_transaction_default"
}'
```
---
## Параметры ответа
### 201 Created
Нет тела ответа.
### 400 Bad Request
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :--------------------------------------------------------------------------- |
| **error** | string | required | Код ошибки. Значение: `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | optional | Описание ошибки |
### 401 Unauthorized
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **error** | string | required | Код ошибки. Значение: `invalid_token` — предоставленный токен просрочен, отозван, имеет неправильный формат или недействителен |
| **error_description** | string | optional | Описание ошибки |
### 403 Forbidden
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :----------------------------------------------------------------------------------------------------------- |
| **error** | string | required | Код ошибки. Значение: `insufficient_scope` — у пользователя нет прав на использование запрашиваемого сервиса |
| **error_description** | string | optional | Описание ошибки |
### 404 Not Found
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :----------------------------------------------------------------------- |
| **error** | string | required | Код ошибки. Значение: `unknown_route` — эндпоинт не найден или неактивен |
| **error_description** | string | optional | Описание ошибки |
### 429 Too Many Requests
Нет тела ответа.
### 500 Internal Server Error
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :----------------------------------------------------------------- |
| **error** | string | required | Код ошибки. Значение: `internal_error` — внутренняя ошибка сервиса |
| **error_description** | string | optional | Описание ошибки |
### 503 Service Unavailable
Нет тела ответа.
> **Примечание:** Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации.
---
## Навигация
- ← [Инструкция по тестированию](/products/alfa-api/documentation/articles/sandbox/articles/check-webhook/articles/intro/intro)
- [Тестирование электронной подписи](/products/alfa-api/documentation/articles/sandbox/articles/check-signature/check-signature) →
]]>
</checking_the_webhook_eg_transactions_md>
<check_webhook_intro_md>
<![CDATA[
# Инструкция по тестированию
**Теги:** `B2B` `B2C` `H2H`
1. Отправьте письмо на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru) с указанием, что хотите подключить вебхуки.
2. На своей стороне реализуйте открытый [Партнёрский метод для получения вебхуков](/products/alfa-api/documentation/articles/webhooks/articles/partner-webhook/v1/partner-webhook).
3. Создайте вебхук в песочнице с помощью метода [«Создание вебхука»](/products/alfa-api/documentation/articles/webhooks/articles/create-webhook/v1/create-webhook).
4. Вызовите метод [«Проверка работы вебхука»](/products/alfa-api/documentation/articles/sandbox/articles/check-webhook/articles/transactions/v1/transactions).
- В результате успешного запроса для `object = ul_transaction_default` создаются тестовые транзакции для следующих счетов:
- `40702810102300000001`
- `40702810402300000002`
- `40702810002300000003`
- `40702978902300000004`
- В результате успешного запроса для `object = jp_sbp_incoming_payments` будет создан тестовый платёж для счёта:
- `40702810100010000000`
5. После создания транзакций на ваш метод будет отправлен вебхук. Примеры форматов представлены ниже.
### Пример формата вебхука для выписки
```json
[
{
"actionType": "update",
"eventTime": "2022-01-12T00:00:00",
"object": "ul_transaction_default",
"organizationId": "vvvvvv",
"data": {
"amount": {
"amount": 1.0,
"currencyName": "RUR"
},
"amountRub": {
"amount": 1.0,
"currencyName": "RUR"
},
"correspondingAccount": "30101810200000000593",
"direction": "CREDIT",
"documentDate": "2022-01-12",
"filial": "АО \"АЛЬФА-БАНК\" г Москва",
"number": "178",
"operationCode": "01",
"operationDate": "2022-01-12T00:00:00",
"paymentPurpose": "Перевод собственных средств. НДС не облагается.",
"priority": "5",
"revaln": null,
"uuid": "9084d309-b30b-5083-9a54-d4522472e11a",
"transactionId": "1220112MOCO#DS4001415",
"rurTransfer": {
"cartInfo": {
"documentCode": null,
"documentContent": null,
"documentDate": null,
"documentNumber": null,
"paymentNumber": null,
"restAmount": null
},
"deliveryKind": "электронно",
"departmentalInfo": {
"uip": "1",
"drawerStatus101": "01",
"kbk": "18210102010011000110",
"oktmo": "12301000",
"reasonCode106": "ТП",
"taxPeriod107": "ГД.01.2022",
"docNumber108": "123",
"docDate109": "12.01.2022",
"paymentKind110": "1"
},
"payeeAccount": "40702810301300000763",
"payeeBankBic": "044525593",
"payeeBankCorrAccount": "30101810200000000593",
"payeeBankName": "АО \"АЛЬФА-БАНК\" г Москва",
"payeeInn": "0140237176",
"payeeKpp": "770801001",
"payeeName": "Полное наименование Орг № 11329",
"payerAccount": "40702810701300000761",
"payerBankBic": "044525593",
"payerBankCorrAccount": "30101810200000000593",
"payerBankName": "АО \"АЛЬФА-БАНК\" г Москва",
"payerInn": "0140237176",
"payerKpp": "770801001",
"payerName": "Полное наименование Орг № 11329",
"payingCondition": null,
"purposeCode": "2",
"receiptDate": "2022-01-12",
"valueDate": "2022-01-12"
}
}
}
]
```
### Пример формата вебхука для входящих платежей
```json
[
{
"actionType": "update",
"eventTime": "2022-01-12T00:00:00",
"object": "jp_sbp_incoming_payments",
"organizationId": "vvvvvv",
"data": {
"qrcId": "AD1000038AQ1FG409KGACUQU5QRSH3FM",
"nspkTransactionId": "B467FC50C59A469A9898AB7B05EE3F07",
"amount": 1000000,
"taxAmount": 200000,
"paymentPurpose": "Оплата по договору №123456789 от 01.09.2001",
"payeeAccount": "40702810100010000000",
"payerAccount": null,
"currency": "RUR",
"timestamp": "2024-11-26T09:09:32Z",
"payerInfo": {
"name": "ИП Викулин",
"inn": "911006876365",
"bik": "044525593",
"accountType": "BBAN",
"bankName": "АО \"АЛЬФА-БАНК\"",
"bankCorrAccount": "30101810200000000593"
},
"recipientInfo": {
"name": "OOO Ромашка",
"inn": "8110068763612",
"bik": "044625503",
"accountType": null,
"bankName": "БАНК",
"bankCorrAccount": "30101810200000000522"
}
}
}
]
```
---
**Навигация:**
- ← [Начало работы в песочнице](/products/alfa-api/documentation/articles/sandbox/articles/intro/intro)
- [Проверка работы вебхука](/products/alfa-api/documentation/articles/sandbox/articles/check-webhook/articles/transactions/v1/transactions) →
]]>
</check_webhook_intro_md>
</check_webhook>
<managing_certificates_md>
<![CDATA[
# Управление сертификатами для подписи и шифрования
**Теги:** `B2B` `B2C` `H2H`
### RSA
Для тестирования подписи и шифрования сообщений с помощью RSA-сертификата Вам будет необходимо выпустить сертификат в УЦ Альфа-Банка с помощью сервиса [«Электронная подпись»](/products/alfa-api/documentation/articles/signature/signature).
Первым шагом инструкции на выпуск RSA-сертификата выполняется запрос на сертификат. Для получения тестового сертификата на втором пункте с созданием закрытого ключа необходимо воспользоваться тестовым закрытым ключом [key-encrypted.zip](/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/managing-certificates/files/sandbox_alfa_test_jwt_2026.zip) (пароль для архива уточняйте у персонального менеджера).
Для проверки подписи необходимо использовать тестовый [сертификат](/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/managing-certificates/files/sandbox_alfa_test_jwt_2026.cer) ключа проверки подписи.
### ГОСТ
Для тестирования подписи и шифрования сообщений с помощью ГОСТ-сертификата Вам будет необходимо выпустить сертификат в любом специализированном [государственном УЦ](https://digital.gov.ru/ru/activity/govservices/certification_authority/?utm_referrer=https%3a%2f%2fwww.google.com%2f). Далее сертификат необходимо загрузить в Банк с помощью метода [«Добавление сертификата»](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/post-certificates/post-certificates), указав при этом в поле `type` тип этого сертификата.
Для тестирования методов необходимо использовать URL [https://sandbox.alfabank.ru/api](https://sandbox.alfabank.ru/api).
Для проверки подписи необходимо использовать тестовый сертификат ключа проверки подписи. Для получения сертификата напишите на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
---
#### Навигация
- ← [Тестирование электронной подписи](/products/alfa-api/documentation/articles/sandbox/articles/check-signature/check-signature)
- [Формат исходного сообщения JSON](/products/alfa-api/documentation/articles/sandbox/articles/signature/articles/jws/v1/jws) →
]]>
</managing_certificates_md>
<payments_md>
<![CDATA[
# Тестирование платёжных поручений
**Теги:** `B2B` `H2H`
Для тестирования метода [«Создание рублёвого платёжного поручения»](/products/alfa-api/documentation/articles/payments/articles/create/v2/create) в песочнице необходимо сгенерировать уникальный идентификатор для передачи в параметре `externalId`.
При создании рублёвого платёжного поручения **с подписью** в параметре `certificateUuid` необходимо передать серийный номер RSA-сертификата:
`61000366d11e143acbc03a56d70001000366d1`
### Значения БИК банка для тестирования
Эти значения передаются в полях `payerBankBic` и `payeeBankBic`:
- `040173745`
- `044525593`
---
### Пример тестового запроса
```bash
curl --location --request POST 'https://sandbox.alfabank.ru/api/jp/v2/payments' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"amount": 1.00,
"date": "2022-10-11",
"deliveryKind": "электронно",
"departmentalInfo": {
"uip": "0",
"drawerStatus101": "01",
"kbk": "18210102010011000110",
"oktmo": "45902000",
"reasonCode106": "ТП",
"taxPeriod107": "МС.02.2022",
"docNumber108": "000000000000001",
"docDate109": "2022-05-25"
},
"digestSignatures": [
{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "61000366d11e143acbc03a56d70001000366d1"
}
],
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"number": "1047",
"operationCode": "01",
"payeeAccount": "40702810564564564531",
"payeeBankBic": "040173745",
"payeeBankCorrAccount": "30101810800000000745",
"payeeInn": "7723870785",
"payeeKpp": "553453453",
"payeeName": "Общество с ограниченной ответственностью \"Центр \"ИННОВАЦИЯ\"",
"payerAccount": "40702810102300000001",
"payerBankBic": "044525593",
"payerBankCorrAccount": "30101810200000000593",
"payerInn": "0453438040",
"payerKpp": "046773311",
"payerName": "Общество с ограниченной ответственностью \"Клиент\"",
"priority": "5",
"purpose": "Оплата заказа №1. НДС не облагается",
"urgencyCode": "NORMAL",
"vat": {
"rate": "0",
"type": "NO_VAT"
}
}'
```
---
### Навигация
- ← [Формат исходного сообщения TXT](/products/alfa-api/documentation/articles/sandbox/articles/signature/articles/text/v1/text)
- [Для чего нужен SDK](/products/alfa-api/documentation/articles/sdk/articles/intro/intro) →
---
_Примечание: Данный документ предназначен для работы в среде **Песочница**._
]]>
</payments_md>
<sandbox_intro_md>
<![CDATA[
# Начало работы в песочнице
**Теги:** `B2B` `B2C` `H2H`
**Песочница API** — это среда, которую партнёры API могут использовать для имитации промышленной среды и получения смоделированных ответов по всем API.
Песочница позволяет пройти аутентификацию в Alfa ID и вызвать методы Alfa API в тестовом режиме, не воздействуя на реальные данные.
> **Внимание**
> Обработка негативных сценариев (например, ошибки валидации или доступа) **в песочнице** может отличаться от обработки в промышленной среде и спецификации тестируемого метода.
---
## Подготовка к работе в песочнице
Для начала работы в песочнице пройдите следующие шаги:
1. **Заключите договор о техническо-информационном взаимодействии**
Подробнее [на странице Подписание договора](/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding).
2. **Получите тестовый `client_id` и `scope`**
Получите `client_id` и доступные `scope` [на Портале разработчика](/products/alfa-api/documentation/articles/selfservice/articles/test/test). Также эти данные можно найти в письме, отправленном банком вам на почту после подписания договора.
3. **Установите тестовый TLS-сертификат**
Для получения доступа к тестовой среде необходимо установить тестовый TLS-сертификат – [test_cert.zip](/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/intro/files/test_cert.zip) – пароль для архива уточняйте у персонального менеджера.
**Архив состоит из файлов:**
- `sandbox_cert_2026.cer` – сертификат для клиента (открытый ключ);
- `sandbox_key_2026.key` – закрытый ключ;
- `apica_2022_chain.cer` – цепочка сертификатов УЦ (содержит в себе `root_apica_2022.cer` и `sub_root_apica_2022.cer`);
- `root_apica_2022.cer` – корневой сертификат УЦ;
- `sub_root_apica_2022.cer` – промежуточный сертификат УЦ;
- `baas_swagger_2026.p12` – контейнер p12, содержащий вышеперечисленные файлы.
Для доступа к Swagger UI можно использовать следующие комбинации (в зависимости от выбора Вашего ПО для работы с API):
- открытый ключ + закрытый ключ + цепочка сертификатов УЦ;
- открытый ключ + закрытый ключ + корневой сертификат УЦ + промежуточный сертификат УЦ;
- контейнер p12 (`baas_swagger_2026.p12`) – самый простой способ.
**Важно!** Корневой сертификат УЦ необходимо добавить в доверенные сертификаты на своей стороне.
Для вызова методов можно использовать стандартные программные средства для работы с API: Postman, SoapUI, JMeter, curl или использовать самописные программные средства или встроенные возможности ERP-системы.
4. **Установите сертификаты Минцифры**
Для корректной работы песочницы необходимо установить [сертификаты Минцифры](/products/alfa-api/documentation/articles/specification/articles/certificate/articles/intro/intro).
5. **Проверьте тестовый Swagger UI**
Тестовый Swagger UI находится по адресу [https://sandbox.alfabank.ru/swagger-ui/](https://sandbox.alfabank.ru/swagger-ui/)
6. **Получите тестовый `client_secret`**
Подробнее [на странице Client secret](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret).
---
## Особенности вызовов
После выполнения указанных шагов вы можете приступать к тестированию запросов в песочнице.
При использовании песочницы все вызовы API должны осуществляться с установкой mTLS-соединения. В зависимости от требований используемого вами клиента при отправке запросов вам может понадобиться сертификат и закрытый ключ. Рекомендуем ознакомиться с документацией используемого клиента.
### Пример запроса (cURL)
```bash
curl -X GET https://sandbox.alfabank.ru/api/v1/endpoint \
-v --cert test_certificate.cer \
--key test_key.key \
--header 'accept: application/json' \
--header 'content-type: application/json'
```
---
## Как сообщить об ошибке
Отправьте письмо на [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru), указав следующие данные:
1. `client_id`.
2. Дата и время запроса с указанием часового пояса.
3. Метод и URI запроса.
4. Заголовки и тело запроса.
5. Полученная ошибка и заголовки ответа, включая `X-TraceId`.
6. IP-адрес, с которого был отправлен запрос.
---
## Адреса для тестирования
- **Получение кода авторизации:** [https://id-sandbox.alfabank.ru/oidc/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}](https://id-sandbox.alfabank.ru/oidc/authorize?response_type=code&client_id=%7Bclient_id%7D&redirect_uri=%7Bredirect_uri%7D&scope=%7Bscope%7D&state=%7Bstate%7D)
- **Другие запросы в Alfa ID:** [https://sandbox.alfabank.ru/oidc](https://sandbox.alfabank.ru/oidc)
- **Запросы в Alfa API:** [https://sandbox.alfabank.ru/api](https://sandbox.alfabank.ru/api)
---
## Счета для тестирования
**Номера счетов:**
- `40702810102300000001`
- `40702810402300000002`
- `40702810002300000003`
- `40702810002300000004`
**Номер корреспондентского счёта:**
- `30102810102300000593`
---
## Рекомендации по тестированию Alfa ID ЮЛ (Юридические лица)
Для прохождения процедуры аутентификации используйте тестовые данные:
- **Login:** `SomeDifficultLogin`
- **Password:** `1qaz!QAZ`
- **One-Time Password (OTP):** `000000`
Для подписания формы согласия используйте:
- **One-Time Password:** `111111`
Подробнее [в разделе Alfa ID](/products/alfa-api/documentation/articles/alfa-id/alfa-id).
---
## Рекомендации по тестированию Alfa ID ФЛ (Физические лица)
Для прохождения процедуры аутентификации используйте тестовые данные:
- **Номер телефона:** `71111111111`
- **Login:** `SomeDifficultLogin`
- **Password:** `000000`
- **One-Time Password (OTP):** `000000`
Для подписания формы согласия используйте:
- **One-Time Password:** `000000`
Подробнее [в разделе Alfa ID](/products/alfa-api/documentation/articles/alfa-id/alfa-id).
---
[← API Key](/products/alfa-api/documentation/articles/api-key/api-key) | [Инструкция по тестированию вебхуков →](/products/alfa-api/documentation/articles/sandbox/articles/check-webhook/articles/intro/intro)
]]>
</sandbox_intro_md>
<signature_checking_md>
<![CDATA[
# Тестирование электронной подписи
**Теги:** `B2B` `H2H`
Во втором шаге инструкции на [выпуск RSA-сертификата](/products/alfa-api/documentation/articles/signature/articles/intro/intro) выполняется запрос на сертификат. Для тестирования в песочнице необходимо использовать приложенный ниже `pkcs10Content` при вызове метода ["Заявка на выпуск RSA-сертификата"](/products/alfa-api/documentation/articles/signature/articles/issue-rsa/v1/issue-rsa).
### Содержимое pkcs10Content (Certificate Request)
```text
-----BEGIN CERTIFICATE REQUEST-----
MIIC/DCCAeQCAQAwgacxJTAjBgkqhkiG9w0BCQEWFlVzZXI1MDRAcG9jaHRvY2hr
YS5jb20xOzA5BgNVBAMMMtCa0YPQtNGA0Y/QstGG0LXQsiDQldGA0LzQvtC70LDQ
nuSDQmNCz0L7RgNC10LLQuNGHMQswCQYDVQQGEwJSVTEbMBkGA1UEBAwS0JrRg9C0
0YDRj9Cy0YbQtdCyMRcwFQYDVQQqDA7QldGA0LzQvtC70LDQuTCCASIwDQYJKoZI
hvcNAQEBBQADggEPADCCAQoCggEBANGTN2bX/kaOHuuEfMiOKg1f8y3SY1AseVjQ
ceoHKdaSeLoUIscPgEsuDsbtF6ezsZqV7bwyRYuJK+kMprczDWKiQNxmZPOafiKG
5MKOcxysgX9LV+R8JhVoycfQqmSqfImQBcPZ6s9bqq6J8cs04FCzy+nhPYoFUs2l
X+ZrFfLF135fO4LlRxfj4dfIbHZ4NVogiezIteBE3SPTtEeXiYj2c7SyB0Z17gbQ
dTmtWIolrb5GTZ6SyjjcMZY3U2ZR+4eyn2l1MFt5F/K9Ke47zu4DYTF7zkitST11
nr5gR64zjVZRtmrVqMU9iB7NmQ8/gS8YEsC3PTSECvqioSDHwNcCAwEAAaAPMA0G
CSqGSIb3DQEJDjEAMA0GCSqGSIb3DQEBCwUAA4IBAQBazGrfYMfeUdJ7ofbQ5lom
EsHO/cA312QUpyzFEsHbjYhy9OZTjiVXLfVExf8QrcRchi4/6IECp01S2Ed+nfMm
E/MtD3rtE2oBtH6FjA9APtZb9NZuiSYCzl7nL3rd0ui+F32Dy/JNkudktn64jsMH
YVt5u8Ik0dtxl0axa3E5RUkpJTTl7iIOWD+P8UkOOpa9EMPA2hrtrZvPr8xr60IS
d2t4vKFcHIdgdI2Qe5ATvaYfbccLGjxdWm05lXVuxRjpEOXjuhc5mRkEj06bPavD
9k7h/Tsz4Jb9gNKDZ3TEzfynQkDFFse8in6IDDkwPO21J6onTMd7KOP1gqMSYjrh
-----END CERTIFICATE REQUEST-----
```
### Данные для подтверждения
Для шага с подписанием заявки с помощью кода из СМС использовать:
**One-Time Password: 11111111**
---
#### Навигация
- ← [Проверка работы вебхука](/products/alfa-api/documentation/articles/sandbox/articles/check-webhook/articles/transactions/v1/transactions)
- [Управление сертификатами для подписи и шифрования](/products/alfa-api/documentation/articles/sandbox/articles/managing-certificates/managing-certificates) →
]]>
</signature_checking_md>
<signature_encryption_tests>
<jws_POST_md>
<![CDATA[
# Формат исходного сообщения JSON
**Метод:** `POST`
**Эндпоинт (Песочница):** `https://sandbox.alfabank.ru/api/signature-encryption-tests/json`
---
### Описание
С помощью данного метода можно протестировать подпись и шифрование сообщения в формате JSON с использованием ГОСТ- или RSA-сертификата.
- Процесс формирования и подписания сообщения с использованием RSA-сертификата описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/json-rsa/json-rsa).
- Процесс формирования и шифрования сообщения RSA описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/json-rsa/json-rsa).
- Подписание запроса и дешифрование ответа происходит с использованием закрытого ключа сертификата. Для тестирования необходимо использовать тестовый [закрытый ключ](/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/signature/articles/jws/v1/files/sandbox_alfa_test_jwt_2026.zip) (пароль уточняйте у персонального менеджера).
- Процесс формирования и подписания сообщения с использованием ГОСТ-сертификата описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/json-gost/json-gost).
- Процесс формирования и шифрования сообщения ГОСТ описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/json-gost/json-gost).
> **Внимание**
> Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :----------------------------- | :----- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authorization** | string | required | Bearer {access_token} |
| **Accept** | string | required | application/jose |
| **Content-Type** | string | required | application/jose |
| **X-Request-ChannelSecurity** | string | optional | Тип защиты канала для запроса. Значения: `NO` (без защиты), `SIGNATURE` (проверка подписи), `ENCRYPTION` (дешифрование и проверка подписи). |
| **X-Response-ChannelSecurity** | string | optional | Тип защиты канала для ответа. Значения: `NO` (без защиты), `SIGNATURE` (подписание ответа), `ENCRYPTION` (подписание и шифрование ответа). |
#### BODY
| Атрибут | Тип | Обязательность | Описание |
| :------ | :----- | :------------- | :-------------------------------- |
| (root) | string | required | Тело подписи в виде base64-строки |
---
### Пример запроса
```bash
curl -X POST https://sandbox.alfabank.ru/api/signature-encryption-tests/json \
-H 'Authorization: Bearer {access-token}' \
-H 'Accept: application/jose' \
-H 'Content-Type: application/jose' \
-H 'X-Request-ChannelSecurity: SIGNATURE' \
-H 'X-Response-ChannelSecurity: SIGNATURE' \
-d 'eyJraWQiOiI2MTAwMDM4YWFhYTAxZTRkN2YzOTM5OGQ4NDAwMDEwMDAzOGFhYSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJjb3VudCI6MTAwLCJzb21lRmllbGQiOiJzb21lVmFsdWUiLCJpZCI6IjNiNzk1YTBlLTFjOTctNDIxMi05YTI4LWYyODJkODAxNWI1YSIsImNyZWF0aW9uRGF0ZSI6IjIwMjItMDUtMThUMTA6Mjc6MDkuNzEyWiIsInN0YXR1cyI6ImFjdGl2ZSJ9.WYQKfllUHfs7IN0DdujjKlqpnThfJZgY_A6CZN-ghFohTYbDiRAJBAk4IxIkRfj2Hxcz4rR5DEKX8remdXEOHGrBpNf4okOob0bfIutNRhaeaZAIMFKjungALPRBmMhAiU0t5-Vp3ImUwhidSnSSP08gCHrTD1by5zYrzzYBB6tyikf8lNwYJQKRxscZcXqwOU9gAWBuV4rteClIbDCeTwkx5ci6WKWAq8bv7RDuwU_1KPjh6upJmwJ1g1epmvPdaFOQq5uf9NhAxomeeptmJoBOm3c8ZSYASYMno8KNWxr94B2xAhD7NCakfFCiQZjSH9b6MjM2aJEBhDyKYo2IGw'
```
---
### Параметры ответа
#### 201 Created
| Атрибут | Тип | Обязательность | Описание |
| :------ | :----- | :------------- | :---------- |
| (root) | string | optional | Тело ответа |
#### 400 Bad Request
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :----------------------------------------------------------------- |
| **error** | string | required | Код ошибки: `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | optional | Описание ошибки |
#### 401 Unauthorized
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :------------------------------------------------------------------------ |
| **error** | string | required | Код ошибки: `invalid_token` — токен просрочен, отозван или недействителен |
| **error_description** | string | optional | Описание ошибки |
#### 404 Not Found
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :---------------------------------------------------------------- |
| **error** | string | required | Код ошибки: `unknown_endpoint` — эндпоинт не найден или неактивен |
| **error_description** | string | optional | Описание ошибки |
#### 500 Internal Server Error
| Атрибут | Тип | Обязательность | Описание |
| :-------------------- | :----- | :------------- | :------------------------------------------------------- |
| **error** | string | required | Код ошибки: `internal_error` — внутренняя ошибка сервиса |
| **error_description** | string | optional | Описание ошибки |
---
_Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации._
---
**Навигация:**
- [← Управление сертификатами для подписи и шифрования](/products/alfa-api/documentation/articles/sandbox/articles/managing-certificates/managing-certificates)
- [Формат исходного сообщения XML →](/products/alfa-api/documentation/articles/sandbox/articles/signature/articles/xmldsig/v1/xmldsig)
]]>
</jws_POST_md>
<text_POST_md>
<![CDATA[
Вот преобразованный в Markdown формат документации для метода тестирования подписи и шифрования TXT-сообщений.
---
# Формат исходного сообщения TXT
Метод позволяет протестировать подпись и шифрование сообщения в формате TXT с использованием ГОСТ- или RSA-сертификата.
### Эндпоинт (Песочница)
`POST https://sandbox.alfabank.ru/api/signature-encryption-tests/text`
---
### Описание процесса
* **RSA-сертификат:** Процесс формирования и подписания описан [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/text-rsa/text-rsa), а шифрования — [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/text-rsa/text-rsa).
* **ГОСТ-сертификат:** Процесс формирования и подписания описан [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/text-gost/text-gost), а шифрования — [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/text-gost/text-gost).
* **Тестирование:** Подписание запроса и дешифрование ответа происходит с использованием закрытого ключа. Для тестов используйте [закрытый ключ](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/signature/articles/text/v1/files/sandbox_alfa_test_jwt_2026.zip) (пароль уточняйте у персонального менеджера).
> **⚠️ Внимание**
> Способ защиты данных определяется настройками интеграции. Для уточнения настроек или их изменения напишите на [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru), указав способ защиты (подпись или подпись с шифрованием) и алгоритм (RSA или ГОСТ).
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token} |
| **Accept** | string | required | text/plain |
| **Content-Type** | string | required | text/plain |
| **X-Request-ChannelSecurity** | string | optional | Тип защиты запроса. Значения: `NO` (без защиты), `SIGNATURE` (подпись), `ENCRYPTION` (дешифрование и подпись). |
| **X-Response-ChannelSecurity** | string | optional | Тип защиты ответа. Значения: `NO` (без защиты), `SIGNATURE` (подпись), `ENCRYPTION` (подпись и шифрование). |
#### BODY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| — | string | required | Тело подписи в виде base64-строки |
#### Пример запроса
```bash
curl -X POST https://sandbox.alfabank.ru/api/signature-encryption-tests/text \
-H 'Authorization: Bearer {access-token}' \
-H 'Accept: text/plain' \
-H 'Content-Type: text/plain' \
-H 'X-Request-ChannelSecurity: SIGNATURE' \
-H 'X-Response-ChannelSecurity: SIGNATURE' \
-d 'eyJraWQiOiI2MTAwMDM4YWFhYTAxZTRkN2YzOTM5OGQ4NDAwMDEwMDAzOGFhYSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJjb3VudCI6MTAwLCJzb21lRmllbGQiOiJzb21lVmFsdWUiLCJpZCI6IjNiNzk1YTBlLTFjOTctNDIxMi05YTI4LWYyODJkODAxNWI1YSIsImNyZWF0aW9uRGF0ZSI6IjIwMjItMDUtMThUMTA6Mjc6MDkuNzEyWiIsInN0YXR1cyI6ImFjdGl2ZSJ9.WYQKfllUHfs7IN0DdujjKlqpnThfJZgY_A6CZN-ghFohTYbDiRAJBAk4IxIkRfj2Hxcz4rR5DEKX8remdXEOHGrBpNf4okOob0bfIutNRhaeaZAIMFKjungALPRBmMhAiU0t5-Vp3ImUwhidSnSSP08gCHrTD1by5zYrzzYBB6tyikf8lNwYJQKRxscZcXqwOU9gAWBuV4rteClIbDCeTwkx5ci6WKWAq8bv7RDuwU_1KPjh6upJmwJ1g1epmvPdaFOQq5uf9NhAxomeeptmJoBOm3c8ZSYASYMno8KNWxr94B2xAhD7NCakfFCiQZjSH9b6MjM2aJEBhDyKYo2IGw'
```
---
### Параметры ответа
#### 201 Created
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **responseTextFiled** | string | optional | Тело ответа |
**Пример ответа:**
```text
responseTextFiled:responseTextValue
```
#### Ошибки (400, 401, 404, 500)
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | required | Код ошибки (например, `invalid_request`, `invalid_token`, `unknown_endpoint`, `internal_error`) |
| **error_description** | string | optional | Детальное описание ошибки |
---
*Примечание: Значения параметров ошибок могут изменяться. Рекомендуется предусмотреть стандартную обработку ошибок.*
]]>
</text_POST_md>
<xmldsig_POST_md>
<![CDATA[
# Формат исходного сообщения XML
**Теги:** `B2B` `B2C` `H2H`
### Эндпоинт для тестирования (Песочница)
`POST https://sandbox.alfabank.ru/api/signature-encryption-tests/xml`
---
### Описание
С помощью данного метода можно протестировать подпись и шифрование сообщения в формате XML с использованием RSA-сертификата.
Процесс формирования и подписания сообщения с использованием RSA-сертификата описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/xml-rsa/xml-rsa), а процесс формирования и шифрования сообщения описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/xml-rsa/xml-rsa). Подписание запроса и дешифрование ответа происходит с использованием закрытого ключа сертификата. Для тестирования необходимо использовать тестовый [закрытый ключ](/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/signature/articles/xmldsig/v1/files/sandbox_alfa_test_jwt_2026.zip) (пароль уточняйте у персонального менеджера).
Процесс формирования и подписания сообщения с использованием ГОСТ-сертификата описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/xml-gost/xml-gost), а процесс формирования и шифрования сообщения описан [здесь](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/xml-gost/xml-gost).
> **Внимание**
> Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :----------------------------- | :----- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authorization** | string | required | Bearer {access_token} |
| **Accept** | string | required | application/xml |
| **Content-Type** | string | required | application/xml |
| **X-Request-ChannelSecurity** | string | optional | Тип защиты канала для запроса. Значения: `NO` — без защиты; `SIGNATURE` — проверка подписи; `ENCRYPTION` — дешифрование и проверка подписи. |
| **X-Response-ChannelSecurity** | string | optional | Тип защиты канала для ответа. Значения: `NO` — без защиты; `SIGNATURE` — подписание ответа; `ENCRYPTION` — подписание и шифрование. |
#### BODY
| Атрибут | Тип | Обязательность | Описание |
| :------------- | :----- | :------------- | :-------------------------------- |
| (тело запроса) | string | required | Тело подписи в виде base64-строки |
#### Пример запроса
```bash
curl -X POST https://sandbox.alfabank.ru/api/signature-encryption-tests/xml \
-H 'Authorization: Bearer {access-token}' \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-H 'X-Request-ChannelSecurity: SIGNATURE' \
-H 'X-Response-ChannelSecurity: SIGNATURE' \
-d 'eyJraWQiOiI2MTAwMDM4YWFhYTAxZTRkN2YzOTM5OGQ4NDAwMDEwMDAzOGFhYSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJjb3VudCI6MTAwLCJzb21lRmllbGQiOiJzb21lVmFsdWUiLCJpZCI6IjNiNzk1YTBlLTFjOTctNDIxMi05YTI4LWYyODJkODAxNWI1YSIsImNyZWF0aW9uRGF0ZSI6IjIwMjItMDUtMThUMTA6Mjc6MDkuNzEyWiIsInN0YXR1cyI6ImFjdGl2ZSJ9.WYQKfllUHfs7IN0DdujjKlqpnThfJZgY_A6CZN-ghFohTYbDiRAJBAk4IxIkRfj2Hxcz4rR5DEKX8remdXEOHGrBpNf4okOob0bfIutNRhaeaZAIMFKjungALPRBmMhAiU0t5-Vp3ImUwhidSnSSP08gCHrTD1by5zYrzzYBB6tyikf8lNwYJQKRxscZcXqwOU9gAWBuV4rteClIbDCeTwkx5ci6WKWAq8bv7RDuwU_1KPjh6upJmwJ1g1epmvPdaFOQq5uf9NhAxomeeptmJoBOm3c8ZSYASYMno8KNWxr94B2xAhD7NCakfFCiQZjSH9b6MjM2aJEBhDyKYo2IGw'
```
---
### Параметры ответа
#### Успешный ответ (201 Created)
| Атрибут | Тип | Описание |
| :---------------------------- | :----- | :---------------------------------------------------------------- |
| **ds:Signature** | string | Корневой элемент XML Signature |
| **ds:SignedInfo** | string | Содержит информацию об алгоритме канонизации, подписи и дайджесте |
| **ds:CanonicalizationMethod** | string | Алгоритм канонизации (атрибут `Algorithm`) |
| **ds:SignatureMethod** | string | Алгоритм подписи (атрибут `Algorithm`) |
| **ds:DigestMethod** | string | Алгоритм дайджеста (атрибут `Algorithm`) |
| **ds:SignatureValue** | string | Значение тела подписи в кодировке base64 |
| **ds:KeyInfo** | string | Информация о ключах и сертификатах для проверки подписи |
| **ds:X509Data** | string | Информация о сертификатах |
| **ds:X509Certificate** | string | Сертификат, которым подписано тело, в base64 |
#### Пример ответа 201
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<XmlElementName2>XmlElementValue2</XmlElementName2>
<ds:Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="sigID1">
<ds:SignatureValue>H6jGW+bKLwvQ9xxbhZ6jNYRHtupT4aJ4jjlLh4W8svK0w5G7ZXf4OxqRR0t2l6aYOpNBdN2Q0+2T
1LXyadtnz7XJ7QYXNXrnWNcq7mOxM5Lj5bBQa2JPZSiMkp1lsnAV/LFDAJ+Uhruj3mFQxjiFpJLR
W/vRJzmRv925xXWopb94PFvP9mjtAwPXtBGEL5rqJICabzVo8+1BfPwFF5+8sqYzT74mmJIQmeFm
FiYVMNive5lRxlt7nXEgS4iENF1dXq5+prCPloms8hIX6I4HQo3Jn+G37Os57nv8g61gk4jnu2OK
bOsZasIzXSLVG2GrCbDQ+HFjWs3Fgg4JOkULfw==
</ds:SignatureValue>
<ds:SignedInfo>
<ds:Reference URI="">
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha384">
</ds:DigestMethod>
<ds:DigestValue>xgVcc1UZhuWRp4/8K0OAVLuQUhySUtJg7mYo78Od+WWidnIZr2XZUvPqwxOpFwRY</ds:DigestValue>
<ds:Transforms>
<ds:Transform/>
<ds:Transform/>
</ds:Transforms>
</ds:Reference>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256">
</ds:SignatureMethod>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
</ds:CanonicalizationMethod>
</ds:SignedInfo>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>MIIGATCCBLWgAwIBAgITYQADiqqgHk1/OTmNhAABAAOKqjBBBgkqhkiG9w0BAQowNKAPMA0GCWCG... (урезано для краткости)</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
<XmlElementName1>XmlElementValue1</XmlElementName1>
</Response>
```
---
### Ошибки
| Код | Описание | Возможные значения `Error` |
| :------ | :-------------------- | :------------------------------------------------------------ |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
#### Пример ошибки 400
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ErrorResponse>
<Error>invalid_request</Error>
<ErrorDescription>Authorization header is not present in request headers</ErrorDescription>
</ErrorResponse>
```
---
_Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации._
]]>
</xmldsig_POST_md>
</signature_encryption_tests>
</Песочница>
<Подключение_к_Alfa_API>
<client_id_md>
<![CDATA[
# Client ID
**B2B** **B2C** **H2H**
Тестовый `client_id` и доступный для использования `scope` будут отправлены на почту, указанную [при подписании договора](/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding), сразу после его подписания. Также тестовые учётные данные будут доступны [на Портале разработчика](/products/alfa-api/documentation/articles/selfservice/articles/intro/intro).
Для получения промышленного `client_id` необходимо [создать интеграцию в проме](/products/alfa-api/documentation/articles/selfservice/articles/prod/prod) на Портале разработчика. `client_id` будет указан в карточке интеграции.
У вас может быть несколько `client_id` в случаях, если:
- вы интегрируете Alfa API / Alfa ID в свой сервис, используя разные точки входа для пользователей-физических лиц и пользователей-юридических лиц;
- вы планируете предоставлять разные сервисы своим пользователям;
- вам требуется получение данных по своей организации, а также использование партнёрского сервиса (если есть прямая интеграция банка и ERP-системы пользователя и есть отдельная интеграция продукта пользователя с Alfa API / Alfa ID).
Для получения нескольких `client_id` вам необходимо запросить у сотрудников Банка отдельный `client_id` для каждой интеграции, а также учитывать наличие нескольких `client_id` при реализации интеграции.
---
### Навигация
[← Отзыв договора](/products/alfa-api/documentation/articles/connection/articles/revoke/revoke) | [TLS-сертификат →](/products/alfa-api/documentation/articles/connection/articles/tls/tls)
---
### Содержание раздела «Подключение к Alfa API»
- [Как подключить](/products/alfa-api/documentation/articles/connection/articles/instruction/instruction)
- [Подписание договора](/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding)
- [Отзыв договора](/products/alfa-api/documentation/articles/connection/articles/revoke/revoke)
- **Client ID** (текущая страница)
- [TLS-сертификат](/products/alfa-api/documentation/articles/connection/articles/tls/tls)
- [Client secret (POST)](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret)
]]>
</client_id_md>
<client_secret_md>
<![CDATA[
# Client secret
**Типы интеграции:** `B2B` | `B2C` | `H2H`
**Метод:** `POST`
> [!IMPORTANT]
> **Внимание**
> Получить и заменить `client_secret` можно двумя способами:
>
> 1. С помощью кнопки в карточке интеграции на **Портале разработчика**.
> 2. С помощью описанного ниже API-метода.
---
## Эндпоинты
| Среда | URL |
| :------------ | :----------------------------------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/oidc/clients/{clientId}/client-secret` |
| **Пром** | `POST https://baas.alfabank.ru/oidc/clients/{clientId}/client-secret` |
---
## Описание
`client_secret` представляет собой уникальную строку символов, которая генерируется один раз и не меняется в процессе работы. Достаточно получить его **один раз** и **не менять** в дальнейшем.
При необходимости вы можете использовать этот метод для замены `client_secret` или в случае его компрометации для получения нового.
Если оперативная замена `client_secret` невозможна, необходимо уведомить Банк о факте компрометации по адресу: [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--------- | :----- | :------------- | :----------------------------- |
| **Accept** | string | required | Должен быть `application/json` |
### PATH (Путь)
| Атрибут | Тип | Обязательность | Описание |
| :----------- | :----- | :------------- | :--------------------------------- |
| **clientId** | string | optional | Идентификатор партнёрского сервиса |
### Пример запроса (cURL)
```bash
curl --location --globoff --request POST 'https://baas.alfabank.ru/oidc/clients/{clientId}/client-secret' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Описание |
| :--------------- | :----- | :---------------------------------------- |
| **clientId** | string | Идентификатор партнёрского сервиса |
| **clientSecret** | string | Новый секретный ключ партнёрского сервиса |
**Пример ответа:**
```json
{
"clientId": "0cee0683-85ae-49f2-a63d-29f97aad1911",
"clientSecret": "Qwerty1234567890Qwerty1234567890!"
}
```
---
## Коды ошибок
| Код | Описание | Возможные значения `error` |
| :------ | :------------- | :---------------------------------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверный формат запроса или отсутствуют обязательные параметры. |
| **401** | Unauthorized | `invalid_token` — ошибка авторизации. |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен. |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса. |
---
_Документация Alfa API_
]]>
</client_secret_md>
<contract_signing_md>
<![CDATA[
Вот очищенная и структурированная версия документа в формате Markdown.
---
# Подписание договора
**Теги:** `B2B` `B2C` `H2H`
Для подписания договора на информационно–технологическое взаимодействие посредством Alfa API необходимо выполнить следующие шаги:
### 1. Зайдите в Альфа-Бизнес
Зайдите в Альфа-Бизнес любым удобным для вас способом.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/1.png)
Далее на странице второго фактора аутентификации введите полученный на телефон otp-ĸод (sms, push).
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/2.png)
Вы зашли в Альфа-Бизнес.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/3.png)
---
### 2. Перейдите во «Все сервисы и продукты»
Перейдите на страницу **Все сервисы и продукты** и выберите **Alfa API** в разделе **Обслуживание бизнеса**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/4.png)
При отсутствии на странице пункта «Alfa API» отправьте письмо на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
---
### 3. Подключите Alfa API
На открывшемся лендинге нажмите на кнопку **Подключить Alfa API**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/5.png)
Выберите необходимую организацию (при наличии нескольких организаций).
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/6.png)
---
### 4. Подпишите договор
Внимательно ознакомьтесь с текстом договора. При необходимости введите e-mail для технических и для иных запросов. Нажмите на кнопку **Подписать**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/7.png)
Далее на странице введите полученный на телефон otp-ĸод (sms, push).
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/8.png)
Или подпишите договор при помощи усиленной квалифицированной электронной подписи (**УКЭП**). *Обратите внимание, что данный функционал доступен не всем пользователям.*
Вы успешно подключили Alfa API.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/9.png)
---
### 5. Просмотрите подписанный договор
Для просмотра договора необходимо нажать в верхнем правом углу на наименование компании. В появившейся боковой панели выберите **Настройки**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/10.png)
Далее необходимо выбрать карточку **Управление согласиями**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/11.png)
В разделе **Alfa API** будет отображаться подписанный вами договор. Для просмотра нажмите **Прочитать согласие**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/12.png)
В открывшемся окне вы сможете прочитать договор и скачать его в формате **PDF**.
![image](/assets/developers-portal.docs.alfa-api/articles/connection/articles/onboarding/files/13.png)
---
### 6. Приступайте к тестированию Alfa API
После успешного подписания договора вы можете:
* Получить тестовые учётные данные [на Портале разработчика](/products/alfa-api/documentation/articles/sandbox/sandbox).
* Приступить к тестированию Alfa API [в Песочнице](/products/alfa-api/documentation/articles/sandbox/sandbox).
Для работы с Порталом вашему разработчику предварительно необходимо получить права на управление настройками Alfa API. Как их назначить, описано [на странице Права доступа](/products/alfa-api/documentation/articles/selfservice/articles/access-rights/access-rights).
---
**Навигация:**
← [Как подключить](/products/alfa-api/documentation/articles/connection/articles/instruction/instruction) | [Отзыв договора](/products/alfa-api/documentation/articles/connection/articles/revoke/revoke) →
]]>
</contract_signing_md>
<contract_termination_md>
<![CDATA[
# Отзыв договора
**Теги:** `B2B` `B2C` `H2H`
Для отзыва договора на информационно–технологическое взаимодействие посредством Alfa API необходимо выполнить следующие шаги:
### 1. Зайдите в Альфа-Бизнес
Зайдите в [Альфа-Бизнес](https://link.alfabank.ru) любым удобным для вас способом.
![Скриншот входа](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/1.png)
Далее на странице второго фактора аутентификации введите полученный на телефон otp-ĸод (sms, push).
![Скриншот ввода кода](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/2.png)
Вы зашли в Альфа-Бизнес.
![Скриншот личного кабинета](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/3.png)
### 2. Перейдите в «Управление согласиями»
Нажмите в верхнем правом углу на наименование компании. В появившейся боковой панели выберите **Настройки**.
![Скриншот настроек](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/4.png)
Выберите карточку **Управление согласиями**.
![Скриншот управления согласиями](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/5.png)
### 3. Отзовите договор
В разделе **Alfa API** будет отображаться подписанный вами договор на информационно–технологическое взаимодействие посредством Alfa API. Для отзыва договора необходимо нажать на кнопку **Отозвать**.
![Скриншот раздела Alfa API](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/6.png)
Подтвердите своё намерение, нажав на кнопку **Да, расторгнуть**.
![Скриншот подтверждения](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/7.png)
### 4. Подпишите уведомление
Внимательно ознакомьтесь с текстом уведомления. Нажмите на кнопку **Подписать уведомление**.
![Скриншот уведомления](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/8.png)
Далее на странице введите полученный на телефон otp-ĸод (sms, push).
![Скриншот подтверждения кодом](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/9.png)
Договор отозван.
![Скриншот результата](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/10.png)
### 5. Просмотрите отозванный договор
Для просмотра отозванного договора необходимо выбрать вкладку **Отозванные согласия**.
![Скриншот архива согласий](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/connection/articles/revoke/files/11.png)
---
**Навигация:**
- ← [Подписание договора](/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding)
- → [Client ID](/products/alfa-api/documentation/articles/connection/articles/clientid/clientid)
]]>
</contract_termination_md>
<how_to_connect_md>
<![CDATA[
*Подключение к Alfa API / Как подключить*
`POST` `B2B` `B2C` `H2H`
# Как подключить
> ### Внимание
> Если вы ещё не являетесь клиентом Альфа-Банка, то для подключения к Alfa API вам необходимо открыть [счёт](https://alfabank.ru/sme/quick/docstariffs/), оформить [расчётно-кассовое обслуживание](https://alfabank.ru/sme/) и подключить [Альфа-Бизнес](https://alfabank.ru/corporate/rko/internet-bank/#form).
1. **Подпишите договор**
[Подпишите договор](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding).
Комиссия за подключение и использование не взимается. Вопросы по заключению договора можно направлять на почту [alfa_api@alfabank.ru](https://developers.alfabank.rumailto:alfa_api@alfabank.ru).
2. **Проверьте тестовую интеграцию**
Получите тестовые учётные данные и настройте тестовую интеграцию [на Портале разработчика](https://developers.alfabank.ru/products/alfa-api/documentation/articles/selfservice/articles/test/test), реализуйте и протестируйте аутентификацию в Alfa ID и вызов методов Alfa API [в песочнице](https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/sandbox).
3. **Подготовьтесь к промышленной интеграции**
Создайте интеграцию в проме, выпустите TLS-сертификат и `client_secret` . Подробнее [в инструкции](https://developers.alfabank.ru/products/alfa-api/documentation/articles/selfservice/articles/prod/prod).
4. **Используйте Alfa API**
Если вы ещё не являетесь клиентом Альфа-Банка, то для подключения к Alfa API вам необходимо открыть [счёт](https://alfabank.ru/sme/quick/docstariffs/), оформить [расчётно-кассовое обслуживание](https://alfabank.ru/sme/) и подключить [Альфа-Бизнес](https://alfabank.ru/corporate/rko/internet-bank/#form).
---
[← Сертификаты для Linux](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/certificate/articles/linux/linux) [← Подписание договора](https://developers.alfabank.ru/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding)
]]>
</how_to_connect_md>
<tls_cert_md>
<![CDATA[
# TLS-сертификат
`B2B` `B2C` `H2H`
Взаимодействие между вами и Банком реализовано с использованием двухстороннего TLS-соединения (поддерживаемая версия TLS 1.2), для которого необходимо выпустить сертификат.
---
## Инструкция по выпуску сертификата
Для выпуска сертификата необходимо сгенерировать закрытый ключ и запрос на сертификат в OpenSSL, получить выпущенный сертификат и установить в своей системе:
### 1. Используйте готовый файл конфигурации
Воспользуйтесь заранее подготовленным конфигурационным файлом: [openssl_INNLE.cnf](/assets/developers-portal.docs.alfa-api/articles/connection/articles/tls/files/openssl_INNLE.cnf).
> **Внимание**
> Данный файл уже содержит все необходимые атрибуты и не требует внесения изменений. Все остальные параметры будут введены вручную через терминал в процессе генерации закрытого ключа и запроса на сертификат.
> **Важно**
> Если возникает ошибка `object identifier routines:OBJ_create:oid exists`, необходимо закомментировать строку с объявлением этого OID в начале файла: `INNLE=1.2.643.100.4`.
### 2. Сгенерируйте закрытый ключ
1. Откройте терминал и перейдите в папку с файлом. Если это «Загрузки»:
`cd ~/Downloads`
2. Убедитесь, что файл на месте командой `ls`.
3. Сгенерируйте закрытый ключ:
`openssl genrsa -des3 -out Company.key 2048`
4. Задайте пароль для ключа (**PEM pass phrase**) и запомните его.
5. В папке появится файл `Company.key`.
> **Рекомендация для Mac OS**
> Введите дважды пароль от вашего Mac OS, когда терминал запросит подтверждение действий.
### 3. Сгенерируйте запрос на сертификат (CSR)
1. Введите команду:
`openssl req -utf8 -config openssl_INNLE.cnf -key Company.key -new -sha256 -out Company.csr`
2. Атрибут `CLIENT_ID`, а также поля `An optional company name` и `A challenge password` являются опциональными (можно оставить пустыми).
3. Введите данные организации (название, ФИО, ИНН), когда терминал их запросит.
> **Рекомендации для заполнения полей**
> Поля `OrganizationName` и `CommonName` можно заполнять транслитом или кириллицей (UTF-8).
> **ИНН:** строго 10 цифр для ЮЛ и 12 цифр для ИП (без пробелов).
> Поля `CountryName` и `INNLE` формируют имя профиля в LDAP и должны быть точными.
### 4. Проверьте атрибуты в subject
Проверьте созданный запрос командой:
`openssl req -config openssl_INNLE.cnf -noout -text -in Company.csr`
**Пример корректного ответа:**
```text
Subject: C=RU, L=Moscow, O=Company Name, CN=Ivanov Ivan Ivanovich/emailAddress=example@company.ru/INNLE=01234567890/CLIENT_ID=b95e04ed-91fe-430a-a101-894f06f3ab2a
```
### 5. Отправьте запрос в Банк
Отправьте файл `Company.csr` на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
- **Тема:** «Запрос на сертификат».
- **Отправитель:** почта, указанная в Договоре.
- **Имя файла:** название организации на латинице.
- **В письме:** укажите e-mail для уведомлений об истечении срока сертификата.
> **Важно!** Никому и никогда не передавайте файл закрытого ключа (`.key`).
### 6. Получите сертификат
Банк пришлет сертификат с адреса `alfa_api@alfabank.ru`.
- **Срок действия:** 375 дней. По истечении нужно выпустить новый.
### 7. Сборка файла контейнера pfx
Для установки в систему соберите контейнер командой:
`openssl pkcs12 -export -out Company.pfx -inkey Company.key -in Company.cer -certfile keys\root_apica_2022.cer -certfile keys\sub_root_apica_2022.cer`
### 8. Действия при компрометации
Если закрытый ключ был украден или утерян, немедленно напишите на [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru) для отзыва и перевыпуска.
---
## Требования к сертификату
### Global Subject (Обязательные поля)
| Атрибут | Значение |
| :------------------- | :--------------------------------- |
| **CountryName** | Код страны (ISO). Для России: `RU` |
| **OrganizationName** | Название организации |
| **CommonName** | ФИО представителя организации |
| **EmailAddress** | Служебный адрес для связи |
### Variable Subject (Зависит от формы собственности)
| Атрибут | Значение |
| :------------------------ | :------------------------------------ |
| Для ЮЛ в России | `INNLE = 1.2.643.100.4` |
| Для иностранных партнёров | `FOREIGNID = 1.3.6.1.4.1.16745.100.1` |
| Идентификатор сервиса | `CLIENT_ID = 1.3.6.1.4.1.16745.100.2` |
---
## Настройка UTF-8 для кириллицы
### Windows
1. **Панель управления** > **Часы и регион** > **Регион**.
2. Вкладка **Дополнительно** > **Изменить язык системы**.
3. Включите чекбокс: «Бета-версия: Использовать Юникод (UTF-8) для поддержки языка во всем мире».
4. Перезагрузите ПК.
### MacOS
1. Откройте **Терминал**.
2. В меню: **Terminal** > **Настройки**.
3. Вкладка **Кодировки**: убедитесь, что выбрана «Unicode (UTF-8)».
---
## Использование сертификата
Использование TLS-сертификата обязательно для установки mTLS-соединения. Пример запроса через **cURL**:
```bash
curl -X GET https://baas.alfabank.ru/api/endpoint \
-v --cert Company.cer \
--key Company.key \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json'
```
---
## Повторный выпуск сертификата
За **1 месяц** до истечения срока вам придет уведомление. Необходимо сформировать новый запрос по инструкции выше.
> **Внимание**
> При перевыпуске рекомендуем:
>
> - Установить защиту на удаление закрытого ключа.
> - Перезаписать старый закрытый ключ на новый.
_В случае утери сертификата или несвоевременного обновления, ответственность за простой API возлагается на сторону клиента._
---
← [Client ID](/products/alfa-api/documentation/articles/connection/articles/clientid/clientid) | [Client secret](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret) →
]]>
</tls_cert_md>
</Подключение_к_Alfa_API>
<Портал_разработчика>
<access_rights_md>
<![CDATA[
# Права доступа
По умолчанию доступ к Порталу разработчика имеет только руководитель вашей организации.
Для предоставления доступа к Порталу разработчика другим пользователям руководителю необходимо в **Альфа-Бизнес** создать роль с правами на управление настройками Alfa API и присвоить её пользователю.
> **Внимание**
> В случае если у вас ИП, права разработчика можно назначить:
>
> - от имени самого индивидуального предпринимателя с ролью «Руководитель»;
> - от имени любого другого сотрудника ИП с ролью «Руководитель». В таком случае потребуется подтверждение назначения от владельца ИП. Подробнее в инструкции ниже.
---
## Инструкция по настройке прав
### Шаг 1. Перейдите в раздел «Пользователи и роли»
1. На главном экране Альфа-Бизнес перейдите в настройки компании.
2. В разделе **Моя компания** выберите карточку **Пользователи и роли**.
### Шаг 2. Создайте новую роль
> **Внимание:** Если ранее вы уже создавали роль с правами на управление Alfa API, этот шаг можно пропустить.
1. Нажмите **Создать роль**.
2. Укажите название роли.
3. Настройте права: новую роль рекомендуется создавать на основании прав руководителя, сбросив лишнее.
4. Нажмите **Снять все**, чтобы сбросить текущие права.
5. В разделе **Обслуживание бизнеса** выберите **Alfa API** и укажите необходимые полномочия.
6. При необходимости добавьте права из других разделов.
7. Нажмите **Создать роль** для сохранения.
### Шаг 3. Назначьте роль разработчику
> **Примечание:** Если пользователь еще не подключен к компании, нажмите «Подключить пользователя», заполните данные и выберите созданную роль.
1. В разделе **Пользователи** нажмите на три точки справа от нужного сотрудника.
2. Выберите **Сменить роль**.
3. В открывшейся форме выберите созданную роль и нажмите **Сменить**.
4. Подтвердите смену роли кодом из СМС.
- _Для ИП:_ Если роль назначает не сам владелец, будет создано заявление, которое владелец должен подписать в своем личном кабинете.
5. После успешного назначения статус пользователя изменится на **Подключён**.
---
## Требования к полномочиям для корректной авторизации
Для корректной работы H2H-интеграций ключ доступа (`access_token` / `API Key`) должен получать пользователь, у которого есть полномочия на использование выбранных сервисов и продуктов.
### Особенности способов авторизации:
- **При использовании ACF H2H:** Авторизацию в Alfa ID должен проходить пользователь, у которого в Альфа-Бизнес настроены соответствующие полномочия на использование выбранных `scopes`. Если вы хотите использовать учетные данные разработчика, руководитель должен выдать ему соответствующие права в разделе «Пользователи и роли».
- **При использовании авторизации по API Key:** Выпускать ключ должен пользователь, имеющий права на выбранные продукты. Если у пользователя нет прав (например, на просмотр выписок), то выпущенный им `API Key` не будет работать для этого сервиса.
**Пример:**
Если вы выдали разработчику права на _редактирование интеграций_, но не дали прав на _просмотр выписки_, то созданный им `API Key` для сервиса выписок (`transactions`) работать не будет. Ключ должен выпускать либо руководитель, либо сотрудник с полным доступом к нужным данным.
]]>
</access_rights_md>
<api_key_managment_md>
<![CDATA[
# Управление API Key
Портал разработчика позволяет управлять `API Key` – ключами доступа для упрощённой авторизации запросов в H2H-интеграциях. Подробнее о ключе и доступных по нему сервисах [на странице API Key](/products/alfa-api/documentation/articles/api-key/api-key).
Для настройки авторизации с помощью `API Key` вам необходимо выпустить ключ для H2H-интеграции, скопировать его и вручную добавить в свои рабочие инструменты. Значение ключа передаётся в заголовке: `Authorization: ApiKey {API Key}`:
### Пример запроса с использованием API Key
```bash
curl -X GET https://baas.alfabank.ru/api/endpoint \
-H 'Authorization: ApiKey akytnps_YfSpCMb0_Uat5NX4p3c7A50hf27Qapk7nXYQ81h659tSwKml87xA5IhpBXXnpKSVypV60dI2l_2918090335' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
```
---
## Выпуск API Key для прома
Перед выпуском `API Key` для промышленной H2H-интеграции рекомендуется сначала пройти описанные ниже шаги для тестовой H2H-интеграции в рабочей среде «Песочница» и протестировать ключ, и только после этого приступать к выпуску ключа для промышленной H2H-интеграции.
> **Важно**
> Выпускать `API Key` необходимо пользователю, у которого в Альфа-Бизнес настроены соответствующие полномочия на использование выбранных при выпуске ключа продуктов и сервисов. Если у пользователя отсутствуют эти полномочия, руководителю организации необходимо выдать их пользователю в Альфа-Бизнес (в разделе **Профиль** – **Пользователи и роли**) или выпустить ключ самому.
### Шаг 1. Нажмите "Выпустить API Key"
Нажмите **Выпустить ключ** в правой части карточки H2H-интеграции.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/issue_1.png)
### Шаг 2. Заполните данные для API Key
Укажите IP-адреса, с которых будут отправляться запросы с использованием `API Key`. Отправка запросов с использованием `API Key` будет доступна только с указанных IP-адресов.
Для одного API Key вы можете указать не более 20 IP-адресов.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/issue_2.png)
Укажите сервисы и продукты, доступ к которым вы хотите получать с помощью `API Key`. Вам будут доступны сервисы и продукты из набора `scopes` редактируемой H2H-интеграции, доступ к которым возможен с помощью `API Key`.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/issue_3.png)
Далее проверьте и сохраните внесённые изменения.
### Шаг 3. Скопируйте и сохраните API Key
После завершения выпуска `API Key` вы получите уведомление. Скопируйте его и вручную добавьте в ваши рабочие инструменты так, чтобы при отправке запросов по H2H-интеграции в запросах передавался заголовок `Authorization: ApiKey {API Key}`.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/issue_4.png)
**Срок действия:** Срок действия `API Key` неограничен, но ключ будет автоматически отозван, если с момента последнего запроса прошло более **30 дней**.
В случае потери данных либо компрометации ключа вы можете перевыпустить его. Также вы всегда можете отозвать `API Key`, если больше не хотите использовать упрощённый способ авторизации.
---
## Перевыпуск API Key
### Шаг 1. Нажмите "Перевыпустить API Key"
Нажмите на три точки в правом верхнем углу карточки H2H-интеграции и выберите **Перевыпустить API Key**.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/reissue_1.png)
### Шаг 2. Отредактируйте данные для API Key
При необходимости отредактируйте данные для `API Key`.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/reissue_2.png)
Далее проверьте внесённые изменения и нажмите «Перевыпустить».
### Шаг 3. Скопируйте и сохраните API Key
После перевыпуска `API Key` вы получите уведомление. Вам будет необходимо скопировать его и заменить в ваших рабочих инструментах. При перевыпуске `API Key` старый ключ, привязанный к этой интеграции, будет автоматически отозван.
Срок действия `API Key` неограничен, но ключ будет автоматически отозван, если с момента последнего запроса прошло более 30 дней.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/reissue_3.png)
---
## Отзыв API Key
Для отзыва ключа доступа нажмите на три точки в правом верхнем углу карточки интеграции, выберите **Отозвать API Key** и подтвердите свои действия.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/revoke_1.png)
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/api-key/files/revoke_2.png)
В результате отзыва ключа упрощённая авторизация будет недоступна. При необходимости вы всегда можете выпустить новый `API Key`.
]]>
</api_key_managment_md>
<creating_prod_integration_md>
<![CDATA[
# Создание интеграции в проме
**Метки:** `β-ТЕСТ` `B2B` `B2C` `H2H`
После успешного тестирования продуктов и сервисов в песочнице вам станет доступно создание интеграций в проме.
## Создание промышленной интеграции
### Шаг 1. Нажмите «Создать интеграцию»
> **Внимание**
> Одновременно у вас может быть не более 5 промышленных интеграций.
Нажмите **Создать интеграцию** в степпере или в списке интеграций, находясь в рабочей среде «Пром» (для выбора рабочей среды используйте переключатель в правом верхнем углу Портала разработчика).
**Важно!** В случае если вы работаете в режиме группы компаний, перед созданием новой интеграции необходимо перейти в профиль пользователя и выбрать компанию, для которой вы хотите создать интеграцию.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/1.png)
---
### Шаг 2. Выберите тип интеграции
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/2.png)
---
### Шаг 3. Заполните основную информацию
Укажите название интеграции (рекомендуется использовать то же название, что и у соответствующей тестовой интеграции), `redirect_uri` и тип клиентов (выбор типа клиентов доступен только для партнёрских интеграций).
В одной интеграции вы можете указать не более 20 `redirect_uri`.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/3.png)
---
### Шаг 4. Выберите сервисы и продукты
> **Важно**
> Вам будут доступны сервисы и продукты, по которым при тестировании было выполнено не менее одного успешного запроса в песочнице.
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/4.png)
---
### Шаг 5. Завершите создание промышленной интеграции
Проверьте параметры интеграции перед её сохранением.
Для создания интеграции потребуется некоторое время. После завершения создания промышленной интеграции вы получите уведомление:
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/5.png)
---
### Шаг 6. Разблокируйте промышленную интеграцию
После создания интеграция отображается в статусе **«Заблокирована»**.
Для разблокирования интеграции создайте запрос на TLS-сертификат и отправьте его на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). Подробнее [на странице TLS-сертификат](/products/alfa-api/documentation/articles/connection/articles/tls/tls).
Если вы уже выпускали сертификат, повторно выпускать его не нужно. Вместо этого необходимо сообщить о готовности к промышленной интеграции на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). После этого интеграция будет разблокирована и перейдёт в статус **«Новая»**.
---
### Шаг 7. Активируйте промышленную интеграцию
Чтобы активировать интеграцию, необходимо получить `client_secret`. Для этого нажмите на иконку в карточке интеграции:
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/6.png)
Скопируйте `client_secret` и добавьте его в ваши рабочие инструменты. Получить его можно также с помощью [метода](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret).
![image](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/prod/files/7.png)
После того как вы получите `client_secret`, интеграция перейдет в статус **«Активна»** и будет доступна к использованию в промышленной среде.
---
## Подключение новых продуктов к текущей промышленной интеграции
Для подключения новых продуктов и сервисов к промышленной интеграции сначала добавьте новые `scopes` в режиме редактирования тестовой интеграции и протестируйте их в песочнице.
После успешного тестирования отредактируйте промышленную интеграцию, добавив новые `scopes`. После этого новые продукты или сервисы будут доступны в промышленной среде.
]]>
</creating_prod_integration_md>
<testing_md>
<![CDATA[
# Тестирование
**Метки:** `β-ТЕСТ` `B2B` `B2C` `H2H`
Перед созданием первой промышленной интеграции или подключением новых продуктов и сервисов к текущей промышленной интеграции необходимо проверить работу интеграций в песочнице.
При входе на Портал разработчика вы увидите две тестовые интеграции: одна для тестирования партнёрской интеграции, другая — для тестирования H2H-интеграции. В зависимости от ваших целей вы редактируете нужную интеграцию в рабочей среде «Песочница» и тестируете её.
---
### Шаг 1. Настройте тестовую интеграцию
Для редактирования тестовой интеграции нажмите на три точки в правом верхнем углу карточки и выберите **Редактировать интеграцию**.
![Редактирование интеграции](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/test/files/1.png)
1. **Вкладка «Информация»**:
- При необходимости отредактируйте название интеграции.
- Укажите необходимые `redirect_uri` для переадресации пользователя после авторизации через Alfa ID.
- _Пример redirect_uri:_ [https://romashka.ru](https://romashka.ru).
- **Важно:** В одной интеграции вы можете указать не более 20 `redirect_uri`.
![Настройка информации](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/test/files/2.png)
2. **Вкладка «Scopes»**:
- Выберите продукты и сервисы, которые вы хотите подключить в Alfa API.
- Если вы не нашли нужные `scopes`, напишите на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
![Выбор Scopes](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/test/files/3.png)
3. **Сохранение**:
- После завершения редактирования тестовой интеграции необходимо сохранить внесённые изменения.
![Сохранение изменений](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/test/files/4.png)
---
### Шаг 2. Протестируйте интеграцию
Выполните запросы по выбранным `scopes` в тестовой среде в соответствии с [инструкцией по тестированию](/products/alfa-api/documentation/articles/sandbox/sandbox), используя учётные данные тестовой интеграции.
После успешного тестирования в песочнице вам станет доступно создание промышленной интеграции со `scopes`, по которым было выполнено не менее одного успешного запроса в песочнице.
---
### Дополнительная информация
Вы можете использовать текущие интеграции в песочнице для тестирования новых сервисов и продуктов, добавляя новые `scopes` в режиме редактирования тестовой интеграции. После успешного тестирования в песочнице вы сможете добавить новые `scopes` в промышленную интеграцию и использовать их в своих сервисах.
---
**Навигация:**
- [← Права доступа](/products/alfa-api/documentation/articles/selfservice/articles/access-rights/access-rights)
- [Создание интеграции в проме →](/products/alfa-api/documentation/articles/selfservice/articles/prod/prod)
]]>
</testing_md>
<what_is_for_md>
<![CDATA[
# Для чего нужен Портал разработчика
**Портал разработчика** предназначен для управления интеграциями Alfa API. С помощью него вы можете создавать новые и редактировать текущие интеграции, подключать новые продукты и сервисы, а также активировать упрощённую авторизацию запросов с помощью API Key.
Портал разработчика станет доступен после того, как вы [подключите Alfa API](/products/alfa-api/documentation/articles/connection/articles/onboarding/onboarding).
> **Внимание**
> Для работы с порталом вашему разработчику необходимо получить права на управление интеграциями Alfa API. Как их назначить, описано [в статье Права доступа](/products/alfa-api/documentation/articles/selfservice/articles/access-rights/access-rights).
---
## Запуск первой промышленной интеграции
1. **Войдите на Портал разработчика**
Вход осуществляется через Портал документации по кнопке **Войти** и возможен только под учётной записью сотрудника организации, подключённой к Alfa API.
![Интерфейс входа](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/intro/files/enter.png)
2. **Проверьте тестовую интеграцию**
[Как настроить интеграцию в песочнице и протестировать её](/products/alfa-api/documentation/articles/selfservice/articles/test/test)
3. **Создайте интеграцию в проме**
[Как создать промышленную интеграцию](/products/alfa-api/documentation/articles/selfservice/articles/prod/prod)
4. **Выпустите промышленный TLS-сертификат**
[Как выпустить TLS-сертификат](/products/alfa-api/documentation/articles/connection/articles/tls/tls)
5. **Используйте промышленную интеграцию в своих сервисах**
При необходимости вы можете подключать новые продукты и сервисы к текущей интеграции и создавать новые интеграции на Портале разработчика. Также вы можете настроить упрощённую авторизацию по H2H-интеграциям с помощью [API Key](/products/alfa-api/documentation/articles/selfservice/articles/api-key/api-key).
---
## Выбор рабочей среды
На Портале разработчика предусмотрены две рабочие среды:
- **«Песочница»** — для редактирования тестовых интеграций.
- **«Пром»** — для управления промышленными интеграциями.
Выбор рабочей среды осуществляется с помощью переключателя в правом верхнем углу портала.
![Выбор среды](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/intro/files/mode.png)
---
## Работа с группой компаний
Пользователи с доступом к интеграциям нескольких компаний могут работать в двух режимах: группы компаний или одной выбранной компании. Это позволяет работать с интеграциями всех доступных компаний в едином окне.
### Как переключить режим:
1. Перейдите в профиль пользователя в правом верхнем углу Портала разработчика.
![Профиль пользователя](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/intro/files/profile.png)
2. Выберите режим отображения компаний:
- Карточка **Все компании** — чтобы работать с интеграциями всех компаний одновременно. В этом режиме доступна единая таблица со всеми интеграциями.
- Карточка **конкретной компании** — чтобы работать только с интеграциями выбранной организации.
![Выбор компании](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/intro/files/holding.png)
![Единая таблица](/assets/developers-portal.docs.alfa-api/articles/selfservice/articles/intro/files/expanded-view.png)
---
**Далее:** [Права доступа](/products/alfa-api/documentation/articles/selfservice/articles/access-rights/access-rights) | [Client secret](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret)
]]>
</what_is_for_md>
</Портал_разработчика>
<продукты_и_сервисы>
<Номинальные_счета>
<get_nominal_accounts_md>
<![CDATA[
# Получение списка номинальных счетов
**H2H**
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :-------------------------------------------------------------- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/nominal-accounts` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/nominal-accounts` |
## Scope
`beneficiaries`
## Описание
Метод позволяет получить список номинальных счетов, зарегистрированных в системе.
## Параметры запроса
### HEADERS
| Атрибут | Тип | Описание |
| :---------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | `string` (required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` (required) | application/json |
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/nominal-accounts' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 (OK)
#### Пример ответа
```json
[
{
"accountNumber": "40817810306050000000",
"isActive": true
}
]
```
#### Тело ответа (BODY)
| Атрибут | Тип | Описание |
| :---------------- | :------------------- | :------------------------------------------------------------------------------------------------------------- |
| **accountNumber** | `string` (required) | Номер номинального счёта |
| **isActive** | `boolean` (required) | Статус активности номинального счёта. Принимает значения:<br>• `true` — активен;<br>• `false` — деактивирован. |
---
### Ошибки
#### 400 (Bad Request)
| Атрибут | Тип | Описание |
| :-------------------- | :------------------ | :------------------------------------------------------------------------- |
| **error** | `string` (required) | Код ошибки. Значения:<br>• `invalid_request` — неверные параметры запроса. |
| **error_description** | `string` (optional) | Описание ошибки. |
#### 401 (Unauthorized)
| Атрибут | Тип | Описание |
| :-------------------- | :------------------ | :----------------------------------------------------------------------------------------------- |
| **error** | `string` (required) | Код ошибки. Значения:<br>• `invalid_token` — токен просрочен, отозван или имеет неверный формат. |
| **error_description** | `string` (optional) | Описание ошибки. |
#### 403 (Forbidden)
| Атрибут | Тип | Описание |
| :-------------------- | :------------------ | :--------------------------------------------------------------------------------------------------- |
| **error** | `string` (required) | Код ошибки. Значения:<br>• `insufficient_scope` — недостаточно прав (несоответствие настроек scope). |
| **error_description** | `string` (optional) | Описание ошибки. |
#### 404 (Not Found)
| Атрибут | Тип | Описание |
| :-------------------- | :------------------ | :-------------------------------------------------------------------------------- |
| **error** | `string` (required) | Код ошибки. Значения:<br>• `unknown_endpoint` — эндпоинт не найден или неактивен. |
| **error_description** | `string` (optional) | Описание ошибки. |
#### 429 (Too Many Requests)
_Нет тела ответа._
#### 500 (Internal Server Error)
| Атрибут | Тип | Описание |
| :-------------------- | :------------------ | :----------------------------------------------------------------------- |
| **error** | `string` (required) | Код ошибки. Значения:<br>• `internal_error` — внутренняя ошибка сервиса. |
| **error_description** | `string` (optional) | Описание ошибки. |
#### 503 (Service Unavailable)
_Нет тела ответа._
---
## Навигация
- ← [Как сформировать подпись](/products/alfa-api/documentation/articles/nominal-accounts/articles/signature/signature)
- → [Контрагенты: Как это работает](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/intro/intro)
]]>
</get_nominal_accounts_md>
<how_to_encrypt_your_card_number_eg_cardtoken_md>
<![CDATA[
Вот преобразованный контур документа в формате Markdown. Я сохранил структуру, технические подробности и примеры кода, очистив их от лишней разметки и служебных скриптов.
---
# Номинальные счета / Как зашифровать номер карты
**H2H**
## Как зашифровать номер карты
При проведении выплат по номеру карты в поле `pan` необходимо передавать токен номера карты. Для этого номер карты необходимо зашифровать с помощью алгоритма `RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING`.
### Примеры шифрования
#### Python с использованием Crypto.Cipher в PyCryptodome
```python
import sys
from Crypto.Hash import SHA256, SHA1
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_OAEP
from base64 import b64decode, b64encode
from Crypto.Signature import pss
pubkey = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwj9k2lFfc/EE2zYdRoRLZF5B42V6n8OHKfxLBLMk/0qpP2ZEYYoCqgbD9xsmLbQMTCxQ8JWj/V08JGpFjuNKJ2hRfRzLUfjTm5ReZJVPDhJa4B0QtUEvCS2R4aMqMpnQ1a1aywGAJoM5ift0apCNGKuZZYrGuFkQXeBw85lSYYNwrVmNUm55RI+tcb'
msg = "4779642610000010"
keyDER = b64decode(pubkey)
keyPub = RSA.importKey(keyDER)
cipher = PKCS1_OAEP.new(keyPub, SHA256, mgfunc=lambda x,y: pss.MGF1(x,y, SHA1))
cipher_text = cipher.encrypt(msg.encode())
encodedCard = b64encode(cipher_text)
sys.stdout.buffer.write(encodedCard)
```
#### C# с использованием библиотеки Chilkat .NET for the 4.8.* Frameworks
```csharp
Chilkat.Rsa rsa = new Chilkat.Rsa();
Chilkat.PublicKey pubkey = new Chilkat.PublicKey();
pubkey.LoadFromFile("C://cardbankkey-sandbox.pub");
string cardNumber = "4779642610000010";
rsa.ImportPublicKeyObj(pubkey);
rsa.OaepPadding = true;
rsa.OaepHash = "sha256";
string encCard = rsa.EncryptStringENC(cardNumber, false);
Console.WriteLine(encCard);
```
#### Java с базовыми библиотеками crypto
```java
import lombok.SneakyThrows;
import ru.alfabank.csp.api.decryptor.properties.CryptoServiceProperties;
import javax.crypto.Cipher;
import java.security.KeyStore;
import java.security.KeyStoreException;
import java.security.PublicKey;
public class CryptoServiceImpl {
private KeyStore keyStore;
private CryptoServiceProperties properties;
private PublicKey getPublicKey() throws KeyStoreException {
return keyStore.getCertificate(properties.getAlias()).getPublicKey();
}
@SneakyThrows
public byte[] encrypt(byte[] data) {
var rsaCipher = Cipher.getInstance("RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING");
rsaCipher.init(Cipher.ENCRYPT_MODE, getPublicKey());
return rsaCipher.doFinal(data);
}
}
```
#### PHP
```php
public function createCypher(string $pan): FunctionResult {
$publicKey = PublicKeyLoader::load(file_get_contents($this->cardBankKey));
$algo = $publicKey->withPadding(RSA::ENCRYPTION_OAEP)->withHash('sha256')->withMGFHash('sha1');
return FunctionResult::success(base64_encode($algo->encrypt($pan)));
}
```
---
### Навигация
* ← [Введение](/products/alfa-api/documentation/articles/nominal-accounts/articles/intro/intro)
* → [Как сформировать подпись](/products/alfa-api/documentation/articles/nominal-accounts/articles/signature/signature)
]]>
</how_to_encrypt_your_card_number_eg_cardtoken_md>
<intro_md>
<![CDATA[
# Номинальные счета: Введение
**Метка документа:** `H2H`
> **Внимание**
> Для использования сервиса у вас должен быть открыт номинальный счёт в Альфа-Банке.
Сервис позволяет владельцам номинального счета совершать операции с денежными средствами, права на которые принадлежат другому лицу — бенефициару.
### Кому подойдёт сервис
- Финансовым и инвестиционным платформам;
- Маркетплейсам;
- Платформам, работающим с самозанятыми и фрилансерами;
- Для индивидуальных проектов, где требуется обеспечить безопасность проведения расчётов между участниками сделки.
### Как это работает
Владелец счёта добавляет сведения о бенефициарах номинального счёта и универсальных реципиентах — [раздел Контрагенты](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/intro/intro), после чего может совершать операции с денежными средствами номинального счёта:
- Идентифицировать поступаемые на номинальный счёт денежные средства — раздел [Идентификация пополнений номинального счёта](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/intro/intro).
- Осуществлять выплаты с номинального счёта удобным ему способом:
- [Безопасные сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/intro/intro): деньги перейдут получателю только после выполнения условий сделки.
- [Прямые выплаты](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/intro/intro): выплаты без создания сделки – с биллингом (например, вывод средств бенефициара или уплата налога за исполнителя), или без биллинга (например, перевод зарегистрированному контрагенту).
> **Важно**
> Для работы с сервисом необходимо использовать электронную подпись. Допускается использование сертификата, выпущенного с помощью [сервиса Электронная подпись](/products/alfa-api/documentation/articles/signature/articles/intro/intro), или сертификата УКЭП, выпущенного в любом аккредитованном УЦ. Процесс формирования подписи описан [в статье Как сформировать подпись](/products/alfa-api/documentation/articles/nominal-accounts/articles/signature/signature).
### Термины и определения
**Номинальный счёт** — это специальный банковский счёт, открытый владельцем номинального счёта для совершения операций с денежными средствами, права на которые принадлежат другому лицу – бенефициару.
**Владелец номинального счёта (клиент банка)** — лицо, которое открыло номинальный счёт и имеет право распоряжаться денежными средствами, получать информацию о движении денежных средств и закрыть номинальный счёт.
**Бенефициар** — лицо, которому принадлежат права на денежные средства, находящиеся на номинальном счёте. У одного номинального счёта может быть как один, так и несколько бенефициаров, но каждый из них имеет права только на свою часть денежных средств.
**Универсальный реципиент** — лицо, которое не является бенефициаром и не имеет права на денежные средства, находящиеся на номинальном счёте. Может выступать только в качестве реципиента (получателя) в безопасных сделках и при выплатах с номинального счёта.
---
### Навигация
- ← [Получение подписанного реестра](/products/alfa-api/documentation/articles/factoring/articles/documents/v1/documents)
- → [Как зашифровать номер карты](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken)
---
_Медиа-материалы:_
- [Видео-презентация сервиса](/assets/developers-portal.docs.alfa-api/articles/nominal-accounts/articles/intro/files/nominal-accounts.mp4)
]]>
</intro_md>
<signature_md>
<![CDATA[
# Как сформировать подпись
**H2H**
### Подписание алгоритмом RSA
> **Внимание**
> Для подписания необходимо использовать RSA-сертификат, выпущенный с помощью [сервиса Электронная подпись](/products/alfa-api/documentation/articles/signature/signature).
Для подписания алгоритмом RSA необходимо выполнить следующие шаги:
#### 1. Подготовьте данные для подписи в формате JSON
Подписываться должен весь блок данных тела запроса, исключая `digestSignatures`.
#### 2. Выполните каноникализацию JSON-данных
Используйте правила [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785).
**Пример каноникализированного JSON-сообщения:**
```json
{
"company": { "accountNumber": "40702810201400022055" },
"externalId": "eb19f3ef-ca6a-4f84-a28f-c6e7b469b486",
"requisite": [
{
"payoutId": "b766f52d-f6e6-4a47-bd71-ab332bd0d314",
"payoutRequisite": {
"byPan": {
"comment": "Курьерские услуги за период с 1.12.2020-20.12.2020",
"pan": "JSv++SDzmKNPIBrLc0G2k3W8lx6DjsHwSFptBCGvUAkq7hVe7KWeACIjjTOAeFKujHQguSIKcqmX93rakldGsTa6c5iZTEAsyhBp5dcPLti8F9x90iXNvCUgvPEXGclqBNvTCuVGaNbmAWrGbogHTn4LKmxxrmzeMIL+e51/YFdTpTnJ384xhiYzAzX4XxFY2CsgNOlyN5xCesOjgeYz+UBlW0MCcY9c8AJBh7+DwU09+zlS0GNtpti7GoETeQrjUv6aPqqu2IMGfO116/xVheUdwLNhcDCT2uvbRpmk9B7pMuLuekGhaA1odvoTghjvY1d1RWnjyO4ZrHpBMpVesg=="
},
"payoutTotalAmount": "24.00",
"payoutType": "CARD"
},
"selfemployed": {
"name": "Диогенович",
"patronymic": "Камень",
"surname": "Безукоризненный"
}
}
]
}
```
#### 3. Сформируйте контейнер электронной подписи в формате PKCS#7 (CMS)
Контейнер в виде структуры `ContentInfo` должен соответствовать стандарту [RFC 5652](https://www.ietf.org/rfc/rfc5652.txt).
Для создания структуры, вычисления хэша и подписи используйте криптографические провайдеры (например, Bouncy Castle или OpenSSL).
**Технические требования:**
1. **Тип:** Рекомендуется присоединённая подпись.
2. **Формат:** [RFC 5652](https://www.ietf.org/rfc/rfc5652.txt) (PKCS#7/CMS).
3. **Алгоритм хэш-функции:** SHA-256 (OID 2.16.840.1.101.3.4.2.1).
4. **Алгоритм подписи:** `sha256WithRSAEncryption`.
Структура `SignedData`:
```asn1
SignedData ::= SEQUENCE {
version CMSVersion,
digestAlgorithms DigestAlgorithmIdentifiers,
encapContent Info EncapsulatedContentInfo,
certificates [0] IMPLICIT CertificateSet OPTIONAL,
crls [1] IMPLICIT Revocation InfoChoices OPTIONAL,
signerInfos SignerInfos
}
```
Структура `SignerInfo`:
```asn1
SignerInfo ::= SEQUENCE {
version CMSVersion,
sid SignerIdentifier,
digestAlgorithm DigestAlgorithmIdentifier,
signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL,
signatureAlgorithm SignatureAlgorithmIdentifier,
signature SignatureValue,
unsignedAttrs [1] IMPLICIT UnsignedAttributes OPTIONAL
}
```
**Обязательные атрибуты в `signedAttrs`:**
- ContentType = OID 1.2.840.113549.1.7.1
- SigningTime = OID 1.2.840.113549.1.9.5
- CMSAlgorithmProtection = OID 1.2.840.113549.1.9.52 (RFC 6211)
- messageDigest = OID 1.2.840.113549.1.9.4
_Примечание: Атрибут `unsignedAttrs` не используется._
#### 4. Закодируйте контейнер и передайте подпись в запросе
Полученный PKCS#7-контейнер закодируйте в `base64` и передайте в параметре `base64Encoded` массива `digestSignatures` в теле запроса.
---
### Примеры кода
#### Пример формирования подписи на Java
```java
@Override
public RsaSignResponse sign(RsaSignRequest request) throws Exception {
Security.addProvider(new BouncyCastleProvider());
BouncyCastleProvider provider = (BouncyCastleProvider) Security.getProvider("BC");
PrivateKey key = (PrivateKey) keyStore.getKey(KEYSTORE_ALIAS, KEYSTORE_PWD.toCharArray());
X509Certificate cert = (X509Certificate) keyStore.getCertificate(KEYSTORE_ALIAS);
CMSTypedData msg = new CMSProcessableByteArray(request.getDataToSign().getBytes());
CMSSignedDataGenerator signedDataGen = new CMSSignedDataGenerator();
X509CertificateHolder signCert = new X509CertificateHolder(cert.getEncoded());
ContentSigner signer = new JcaContentSignerBuilder("sha256WithRSAEncryption")
.setProvider(provider)
.build(key);
signedDataGen.addSignerInfoGenerator(new JcaSignerInfoGeneratorBuilder(
new JcaDigestCalculatorProviderBuilder().setProvider(provider).build()
).setDirectSignature(true).build(signer, signCert));
// добавляем сертификат в подпись
JcaCertStore certs = new JcaCertStore(Collections.singletonList(cert));
signedDataGen.addCertificates(certs);
CMSSignedData signedData = signedDataGen.generate(msg, true);
byte[] signatureBytes = signedData.getEncoded("DER");
MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
byte[] hashedString = messageDigest.digest(request.getDataToSign().getBytes());
return new RsaSignResponse()
.base64Encoded(new String(Base64.getEncoder().encode(signatureBytes)));
}
```
#### Пример формирования подписи на PHP
```php
public function sign(string $data, string $password = null): string
{
$key = file_get_contents($this->private_key);
$cert = file_get_contents($this->certificate);
$privateKey = openssl_pkey_get_private($key, $password ?: $this->private_key_password);
$certid = openssl_x509_read($cert);
$inputTmpFile = tmpfile();
fwrite($inputTmpFile, $data);
fseek($inputTmpFile, 0);
$outputTmpFile = tmpfile();
openssl_pkcs7_sign(
stream_get_meta_data($inputTmpFile)['uri'],
stream_get_meta_data($outputTmpFile)['uri'],
$certid,
$privateKey,
[],
PKCS7_ATTACHED
);
fseek($outputTmpFile, 0);
$signature = fread($outputTmpFile, filesize(stream_get_meta_data($outputTmpFile)['uri']));
$signature = trim(explode("\n\n", $signature, 2)[1]);
fclose($inputTmpFile);
fclose($outputTmpFile);
return str_replace("\n", '', $signature);
}
```
---
### Подписание алгоритмом ГОСТ с использованием сертификата УКЭП
Для подписания может использоваться сертификат УКЭП, выпущенный любым аккредитованным УЦ. Если сертификат выдан уполномоченному лицу (не руководителю по уставу), дополнительно потребуется машиночитаемая доверенность (МЧД).
1. Сформируйте электронную подпись с использованием криптопровайдера **КриптоПро CSP**.
2. Закодируйте полученное значение **отсоединённой** электронной подписи в формат `base64`.
3. Передайте значение в параметре `base64Encoded` массива `digestSignatures`.
---
**Навигация:**
- [Как зашифровать номер карты](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken)
- [Получение списка номинальных счетов](/products/alfa-api/documentation/articles/nominal-accounts/articles/get-accounts/v1/get-accounts)
]]>
</signature_md>
<Безопасные_сделки>
<add_deal_md>
<![CDATA[
# Регистрация сделки
**Тип интеграции:** H2H
## Эндпоинты
- **Песочница:** `POST https://sandbox.alfabank.ru/api/na/jp/v1/deals`
- **Пром:** `POST https://baas.alfabank.ru/api/na/jp/v1/deals`
## Scope
`deals`
## Описание
Метод позволяет зарегистрировать новую сделку в статусе `DRAFT`.
> **Важно:** Для создания сделки необходимо наличие открытого номинального счёта в Банке.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
| **Content-Type** | string | required | application/json |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :------------------- | :----- | :------------- | :----------------------------------------------- |
| **accountNumber** | string | required | Номер номинального счёта |
| **expireDate** | string | required | Дата истечения сделки |
| **digestSignatures** | array | required | Электронная подпись УЛ клиента (массив объектов) |
| — **base64Encoded** | string | required | Значение электронной подписи в Base64 |
| — **signatureType** | string | required | Тип подписи: `rsa` (RSA) или `kep` (КЭП) |
---
## Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/deals' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"accountNumber": "40817810306050000000",
"expireDate": "2032-03-02",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Обязательность | Описание |
| :------------- | :------ | :------------- | :--------------------------------------------- |
| **dealId** | string | required | Идентификатор сделки |
| **status** | string | required | Статус сделки: `DRAFT` (принята для обработки) |
| **expireDate** | string | required | Дата истечения сделки |
| **isValid** | boolean | required | Флаг валидности сделки |
**Пример JSON:**
```json
{
"dealId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "DRAFT",
"expireDate": "2032-03-02",
"isValid": false
}
```
---
## Коды ошибок
| Код | Ошибка | Описание |
| :------ | :------------------- | :------------------------------------------------------------ |
| **400** | `invalid_request` | Неверные входные параметры запроса |
| **401** | `invalid_token` | Токен просрочен, отозван или недействителен |
| **403** | `insufficient_scope` | Нет прав на использование сервиса (ошибка в настройках scope) |
| **404** | `unknown_endpoint` | Эндпоинт не найден или неактивен |
| **429** | — | Слишком много запросов (Too Many Requests) |
| **500** | `internal_error` | Внутренняя ошибка сервиса |
| **503** | — | Сервис временно недоступен |
---
**Навигация:**
- [← Как это работает](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/intro/intro)
- [Получение списка сделок →](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deals/v1/get-deals)
]]>
</add_deal_md>
<add_step_md>
<![CDATA[
# Выполнение действия по этапам сделки
tags: `H2H`
### Эндпоинты
- **Песочница:** `POST https://sandbox.alfabank.ru/api/na/jp/v1/deals/steps`
- **Пром:** `POST https://baas.alfabank.ru/api/na/jp/v1/deals/steps`
### Scope
`deals`
### Описание
> **Важно**
>
> - Создание этапа сделки происходит в синхронном режиме.
> - Завершение этапа сделки происходит в асинхронном режиме.
Метод позволяет создать и завершить этап сделки.
#### Создание этапа сделки
После [регистрации сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-deal/v1/add-deal) необходимо создать этапы сделки для совершения финансовых операций. Этап сделки можно создать только для сделок в статусе `DRAFT`.
- Если сделка предполагает совершение переводов денежных средств одновременно всем реципиентам, то достаточно создать один этап сделки.
- Если переводы денежных средств должны совершаться последовательно в несколько этапов, то следует создать соответствующее количество этапов сделки.
#### Завершение этапа сделки
При наступлении момента проведения расчётов по этапу сделки необходимо инициировать завершение этапа сделки. При завершении этапа сделки происходят все финансовые операции между участниками этапа сделки, и он переходит в статус `COMPLETED`.
- Если при [добавлении реципиента](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/step-contractors/v1/step-contractors) в этап сделки был проставлен признак `keepOnNominalAccount = false`, то денежные средства переводятся с захолдированного кошелька депонента на основной и налоговый кошельки реципиента, холдируются там, а затем производится выплата по реквизитам реципиента с номинального счёта.
- Если был проставлен признак `keepOnNominalAccount = true`, то денежные средства переводятся на кошельки реципиента внутри системы без фактического перевода с номинального счёта.
Завершить этап сделки можно только после [подтверждения сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-actions/v1/deal-actions).
---
### Параметры запроса
#### Headers
| Атрибут | Описание | Тип | Обязательность |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | :------------- |
| **Authorization** | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) | string | required |
| **Accept** | application/json | string | required |
| **Content-Type** | application/json | string | required |
#### Body
| Атрибут | Описание | Тип | Обязательность |
| :------------------- | :------------------------------------------------------------------- | :--------------- | :------------- |
| **dealId** | Идентификатор сделки | string | required |
| **stepId** | Идентификатор этапа сделки | string | optional |
| **action** | Действие по этапу сделки: `CREATE` (создать), `COMPLETE` (завершить) | string | required |
| **description** | Описание этапа сделки (при создании) | string | optional |
| **digestSignatures** | Массив объектов: Электронная подпись УЛ клиента | array of objects | required |
| └ **base64Encoded** | Значение электронной подписи в Base64 | string | required |
| └ **signatureType** | Тип подписи: `rsa` или `kep` | string | required |
---
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/deals/steps' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"dealId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"stepId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"action": "CREATE",
"description": "Этап 1",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
### Параметры ответа
#### Успешное создание (200 OK)
| Атрибут | Описание | Тип |
| :-------------- | :------------------------- | :------ |
| **dealId** | Идентификатор сделки | string |
| **stepId** | Идентификатор этапа сделки | string |
| **stepNumber** | Порядковый номер этапа | integer |
| **description** | Описание этапа | string |
**Пример ответа 200:**
```json
{
"dealId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"stepId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"stepNumber": 1,
"description": "Этап 1"
}
```
#### Запрос принят (202 Accepted) — при завершении этапа
| Атрибут | Описание | Тип |
| :------------ | :----------------------------------------------------------------------------------------------- | :----- |
| **status** | Статус запроса: `FAILED`, `TIMEOUT`, `PENDING`, `PAYMENT_FAILED`, `TRANSFER_FAILED`, `COMPLETED` | string |
| **requestId** | Идентификатор запроса | string |
---
### Ошибки
| Код | Описание (error / error_description) |
| :-------------------------- | :------------------------------------------------------- |
| **400 Bad Request** | `invalid_request` — неверные входные параметры |
| **401 Unauthorized** | `invalid_token` — токен просрочен или недействителен |
| **403 Forbidden** | `insufficient_scope` — нет прав на использование сервиса |
| **404 Not Found** | `unknown_endpoint` — эндпоинт не найден |
| **429 Too Many Requests** | Превышен лимит запросов (тело ответа отсутствует) |
| **500 Internal Error** | `internal_error` — внутренняя ошибка сервиса |
| **503 Service Unavailable** | Сервис недоступен (тело ответа отсутствует) |
---
**Навигация:**
- Предыдущий раздел: [Выполнение действия по сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-actions/v1/deal-actions)
- Следующий раздел: [Получение статуса запроса на завершение этапа сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal-request-status/v1/get-deal-request-status)
]]>
</add_step_md>
<deal_actions_md>
<![CDATA[
# Выполнение действия по сделке
tags: **H2H**
### Эндпоинты
- **Песочница:** `PATCH https://sandbox.alfabank.ru/api/na/jp/v1/deals/action`
- **Пром:** `PATCH https://baas.alfabank.ru/api/na/jp/v1/deals/action`
---
### Scope
`deals`
### Описание
Метод позволяет подтвердить, отменить или завершить сделку.
#### Подтверждение сделки
При успешном подтверждении сделки денежные средства депонентов холдируются в сумме, необходимой для проведения расчётов в рамках текущей сделки для каждого этапа сделки, и сделка переходит из статуса `DRAFT` в статус `ACTIVE`.
#### Отмена сделки
При успешной отмене сделки ранее захолдированные денежные средства депонентов расхолдируются и становятся доступны для использования в расчётах (если сделка была ранее подтверждена), и сделка переходит в статус `CLOSED`.
#### Завершение сделки
При успешном завершении сделка переходит в статус `COMPLETED`.
> **Важно**
> Завершить сделку можно, только если все [этапы сделки завершены](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-step/v1/add-step).
---
### Параметры запроса
#### HEADERS
| Атрибут | Описание |
| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** <br> _string, required_ | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** <br> _string, required_ | application/json |
| **Content-Type** <br> _string, required_ | application/json |
#### BODY
| Атрибут | Описание |
| :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **dealId** <br> _string, required_ | Идентификатор сделки |
| **action** <br> _string, required_ | Действие по сделке. Возможные значения: <ul><li>`ACCEPT` — подтвердить сделку;</li><li>`COMPLETE` — завершить сделку;</li><li>`CANCEL` — отменить сделку.</li></ul> |
| **digestSignatures** <br> _array of objects, required_ | Электронная подпись УЛ клиента |
| **└ base64Encoded** <br> _string, required_ | Значение электронной подписи, закодированное в Base64 |
| **└ signatureType** <br> _string, required_ | Тип электронной подписи. Возможные значения: <ul><li>`rsa` — RSA;</li><li>`kep` — КЭП.</li></ul> |
---
### Пример запроса
```bash
curl --location --request PATCH 'https://baas.alfabank.ru/api/na/jp/v1/deals/action' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"dealId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"action": "ACCEPT",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
### Параметры ответа
**204 No Content**
_Нет тела ответа_
**400 Bad Request**
| Атрибут | Описание |
| :--- | :--- |
| **error** <br> _string, required_ | Код ошибки: `invalid_request` — неверные входные параметры запроса |
| **error_description** <br> _string, optional_ | Описание ошибки |
**401 Unauthorized**
| Атрибут | Описание |
| :--- | :--- |
| **error** <br> _string, required_ | Код ошибки: `invalid_token` — токен просрочен, отозван или недействителен |
| **error_description** <br> _string, optional_ | Описание ошибки |
**403 Forbidden**
| Атрибут | Описание |
| :--- | :--- |
| **error** <br> _string, required_ | Код ошибки: `insufficient_scope` — нет прав на использование сервиса (настройки scope) |
| **error_description** <br> _string, optional_ | Описание ошибки |
**404 Not Found**
| Атрибут | Описание |
| :--- | :--- |
| **error** <br> _string, required_ | Код ошибки: `unknown_endpoint` — эндпоинт не найден или неактивен |
| **error_description** <br> _string, optional_ | Описание ошибки |
**429 Too Many Requests**
_Нет тела ответа_
**500 Internal Server Error**
| Атрибут | Описание |
| :--- | :--- |
| **error** <br> _string, required_ | Код ошибки: `internal_error` — внутренняя ошибка сервиса |
| **error_description** <br> _string, optional_ | Описание ошибки |
**503 Service Unavailable**
_Нет тела ответа_
---
### Навигация
- [← Получение списка платежей по сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal-payoffs/v1/get-deal-payoffs)
- [Выполнение действия по этапам сделки →](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-step/v1/add-step)
]]>
</deal_actions_md>
<deal_is_valid_md>
<![CDATA[
# Проверка возможности осуществления выплат по сделке
tags: `H2H`
## Эндпоинты
**Песочница**
`PATCH https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}/is-valid`
**Пром**
`PATCH https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/is-valid`
## Scope
`deals`
## Описание
Метод позволяет проверить возможность осуществления платежей по сделке по `dealId`:
- проверяет правильность формирования сделки;
- проверяет балансы бенефициаров;
- сверяет суммы участников сделки.
> **Важно**
> Проверка доступна только для сделок в статусе `DRAFT`.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Описание |
| :---------------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string (required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string (required) | application/json |
### PATH
| Атрибут | Тип | Описание |
| :--------- | :---------------- | :------------------- |
| **dealId** | string (required) | Идентификатор сделки |
### Пример запроса (cURL)
```bash
curl --location --globoff --request PATCH 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/is-valid' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 OK
**Пример ответа:**
```json
{
"dealId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isValid": true,
"description": [
"Неверная сумма депонированных средств по этапу сделки ab9cbb96-360a-4462-a683-955cc29f7f54;"
]
}
```
**Структура тела (BODY):**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **dealId** | string (required) | Идентификатор сделки |
| **isValid** | boolean (required) | Результат прохождения проверки: `true` — сделка прошла валидацию; `false` — сделка не прошла валидацию. |
| **description** | array of strings (optional) | Описание ошибок. Возвращается при неудачном прохождении валидации. |
---
### Коды ошибок
| Код | Описание | Атрибуты ответа |
| :------ | :------------------ | :-------------------------------------------------------------------------- |
| **400** | Bad Request | `error`: `invalid_request` — неверные входные параметры запроса. |
| **401** | Unauthorized | `error`: `invalid_token` — токен просрочен, отозван или недействителен. |
| **403** | Forbidden | `error`: `insufficient_scope` — недостаточно прав на использование сервиса. |
| **404** | Not Found | `error`: `unknown_endpoint` — эндпоинт не найден или неактивен. |
| **429** | Too Many Requests | Нет тела ответа. |
| **500** | Internal Error | `error`: `internal_error` — внутренняя ошибка сервиса. |
| **503** | Service Unavailable | Нет тела ответа. |
---
## Навигация
- **Назад:** [Получение информации о сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal/v1/get-deal)
- **Вперед:** [Получение списка платежей по сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal-payoffs/v1/get-deal-payoffs)
]]>
</deal_is_valid_md>
<get_contractors_md>
<![CDATA[
# Получение информации об участниках этапа сделки
tags: `H2H`
Метод позволяет получить информацию об участниках этапа сделки по `dealId` и `stepId`.
## Эндпоинты
| Окружение | Метод и URL |
| :------------ | :--------------------------------------------------------------------------------------- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps/{stepId}/contractors` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps/{stepId}/contractors` |
**Scope:** `deals`
---
## Параметры запроса
### HEADERS
| Атрибут | Описание | Тип | Обязательность |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | :------------- |
| **Authorization** | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) | string | required |
| **Accept** | application/json | string | required |
### QUERY
| Атрибут | Описание | Тип | Обязательность |
| :--------------- | :----------------------------------------------------------------------------------------------------------- | :----- | :------------- |
| **contractorId** | Идентификатор участника сделки | string | optional |
| **role** | Роль участника этапа сделки. Возможные значения:<br>• `DEPONENT` — плательщик;<br>• `RECIPIENT` — получатель | string | optional |
### PATH
| Атрибут | Описание | Тип | Обязательность |
| :--------- | :------------------------- | :----- | :------------- |
| **dealId** | Идентификатор сделки | string | required |
| **stepId** | Идентификатор этапа сделки | string | required |
---
## Пример запроса
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps/{stepId}/contractors?contractorId=ab9cbb96-360a-4462-a683-955cc29f7f54&role={role}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Пример ответа 200 (OK)
```json
[
{
"beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"role": "DEPONENT",
"amount": "10.00",
"purpose": "Назначение платежа",
"requisiteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"keepOnNominalAccount": true,
"amounts": [
{
"walletType": "MAIN",
"amount": "10.00"
}
]
}
]
```
### BODY (Успешный ответ)
| Атрибут | Описание | Тип | Обязательность |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :--------------- | :------------- |
| **beneficiaryId** | Идентификатор бенефициара или универсального реципиента | string | optional |
| **role** | Роль участника этапа сделки: `DEPONENT` (плательщик), `RECIPIENT` (получатель) | string | optional |
| **amount** | Сумма депонирования в рублях | string | optional |
| **purpose** | Назначение платежа реципиента | string | optional |
| **requisiteId** | Идентификатор платёжного реквизита реципиента | string | optional |
| **keepOnNominalAccount** | Признак вывода денег на виртуальный счёт:<br>• `true` — оставить в рамках номинального счёта;<br>• `false` — вывести по ID реквизита | boolean | optional |
| **amounts** | Массив объектов: Суммы реципиента | array of objects | optional |
**Вложенные поля `amounts`:**
- **walletType** (string, optional): Тип суммы (`MAIN` — основная, `TAX` — налоговая).
- **amount** (string, optional): Сумма в рублях.
---
## Коды ошибок
| Код | Описание | Возможные значения `error` |
| :------ | :------------------ | :------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
]]>
</get_contractors_md>
<get_deal_md>
<![CDATA[
Приношу извинения, в предыдущем ответе могли проскочить остаточные элементы структуры. Вот полностью очищенный от HTML-тегов, спецсимволов и лишней разметки текст в формате Markdown.
---
# Получение информации о сделке
**Тип интеграции:** H2H
**Scope:** `deals`
## Эндпоинты
* **Песочница:** `GET https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}`
* **Пром:** `GET https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}`
## Описание
Метод позволяет получить детальную информацию о сделке по идентификатору `dealId`.
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| Authorization | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| Accept | string | Да | application/json |
### PATH
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| dealId | string | Да | Идентификатор сделки |
## Пример запроса
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа (200 OK)
### Пример тела ответа
```json
{
"dealId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "DRAFT",
"expireDate": "2032-03-02",
"isValid": false,
"steps": [
{
"id": "f099f9dd-d5e7-4ab3-89f5-24932aa808ad",
"description": "Этап 1",
"stepNumber": 1,
"status": "NEW",
"isValid": false
}
]
}
```
### Структура ответа (BODY)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **dealId** | string | Да | Идентификатор сделки |
| **status** | string | Да | Статус сделки. Возможные значения: `DRAFT` (принята), `ACTIVE` (успешно обработана), `BLOCKED` (ошибка обработки), `PAYMENT_FAILED` (ошибка платежа), `CLOSED` (отменена), `COMPLETED` (успешно завершена) |
| **expireDate** | string | Да | Дата истечения сделки |
| **isValid** | boolean | Да | Флаг валидности сделки |
| **steps** | array | Нет | Данные об этапах сделки (список объектов) |
### Параметры этапа сделки (внутри массива steps)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **id** | string | Да | Идентификатор этапа |
| **description** | string | Да | Описание этапа |
| **stepNumber** | integer | Да | Порядковый номер этапа |
| **status** | string | Да | Статус этапа: `NEW` (принят), `IN_PROGRESS` (в обработке), `PAYMENT_FAILED` (ошибка платежа), `COMPLETED` (завершен) |
| **isValid** | string | Да | Флаг валидности этапа |
---
## Коды ответов и ошибок
| Код | Описание | Значение error / error_description |
| :--- | :--- | :--- |
| **200** | OK | Успешное получение информации |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или неверный формат |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса (проверьте scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Превышено количество запросов (без тела ответа) |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Сервис временно недоступен (без тела ответа) |
---
**Навигация:**
[← Получение списка сделок](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deals/v1/get-deals) | [Проверка возможности выплат →](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-is-valid/v1/deal-is-valid)
]]>
</get_deal_md>
<get_deal_payoffs_md>
<![CDATA[
# Получение списка платежей по сделке
tags: `H2H`
Метод позволяет получить список выплат по сделке по идентификатору `dealId`.
## Эндпоинты
- **Песочница:** `GET https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}/payoffs`
- **Пром:** `GET https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/payoffs`
## Scope
`deals`
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--------- | :----- | :------------- | :------------------- |
| **dealId** | string | required | Идентификатор сделки |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/payoffs' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа (200 OK)
### BODY (JSON)
| Атрибут | Тип | Обязательность | Описание |
| :-------------- | :----- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **stepId** | string | required | Идентификатор этапа сделки |
| **payoffId** | string | required | Идентификатор платежа |
| **payoffType** | string | required | Тип платежа:<br>• `EXTERNAL` — внешний (выплата с номинального счёта)<br>• `INTERNAL` — внутренний (выплата внутри номинального счёта) |
| **deponentId** | string | required | Идентификатор депонента |
| **recipientId** | string | required | Идентификатор реципиента |
| **amount** | string | required | Сумма в рублях |
| **status** | string | required | Статус запроса:<br>• `PENDING` — запрос в процессе обработки<br>• `MANUAL_ACCEPTANCE` — ожидание ручного подтверждения запроса-дубля<br>• `AWAIT_EXTERNAL` — ожидание исполнения внешнего платежа<br>• `FAILED` — ошибка обработки<br>• `FAILED_DUPLICATE` — дубль отклонен<br>• `COMPLETE` — успешно завершено |
### Пример ответа 200
```json
[
{
"stepId": "f099f9dd-d5e7-4ab3-89f5-24932aa808ad",
"payoffId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payoffType": "EXTERNAL",
"deponentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": "100.00",
"status": "PENDING"
}
]
```
---
## Коды ошибок
| Код | Описание | Тело ответа (основные атрибуты) |
| :------ | :------------------ | :---------------------------------------------------- |
| **400** | Bad Request | `error`: `invalid_request` — неверные параметры |
| **401** | Unauthorized | `error`: `invalid_token` — токен недействителен |
| **403** | Forbidden | `error`: `insufficient_scope` — нет прав доступа |
| **404** | Not Found | `error`: `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `error`: `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
- Предыдущий метод: [Проверка возможности осуществления выплат по сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-is-valid/v1/deal-is-valid)
- Следующий метод: [Выполнение действия по сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-actions/v1/deal-actions)
]]>
</get_deal_payoffs_md>
<get_deal_request_status_md>
<![CDATA[
# Получение статуса запроса на завершение этапа сделки
tags: **H2H**
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :---------------------------------------------------------------------------------------- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}/requests/{requestId}/status` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/requests/{requestId}/status` |
## Scope
`deals`
## Описание
Метод позволяет получить статус запроса на завершение этапа сделки по `requestId`.
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :------------ | :----- | :------------- | :-------------------- |
| **dealId** | string | required | Идентификатор сделки |
| **requestId** | string | required | Идентификатор запроса |
## Пример запроса
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/requests/{requestId}/status' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
## Параметры ответа
### 200 (OK)
**Пример тела ответа:**
```json
{
"requestId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "COMPLETE",
"description": "Произошла техническая ошибка. Обратитесь в службу поддержки и сообщите код ошибки afc9b019-77ac-49ef-afb9-688b38b74cc2"
}
```
**Описание полей (BODY):**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **requestId** | string | required | Идентификатор запроса |
| **status** | string | required | Статус запроса. Возможные значения:
`FAILED` — ошибка обработки;
`TIMEOUT` — превышено время ожидания;
`PENDING` — в процессе обработки;
`PAYMENT_FAILED` — неудача внешнего платежа;
`TRANSFER_FAILED` — неудача внутреннего платежа (внутри НС);
`COMPLETED` — успешно завершено. |
| **description** | string | optional | Описание причины, по которой запрос завершился неудачей. Возвращается, если статус равен `FAILED`. |
---
### Ошибки
#### 400 Bad Request
| Атрибут | Тип | Описание |
| :-------------------- | :----- | :----------------------------------------------------- |
| **error** | string | `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | Описание ошибки |
#### 401 Unauthorized
| Атрибут | Тип | Описание |
| :-------------------- | :----- | :------------------------------------------------------------ |
| **error** | string | `invalid_token` — токен просрочен, отозван или недействителен |
| **error_description** | string | Описание ошибки |
#### 403 Forbidden
| Атрибут | Тип | Описание |
| :-------------------- | :----- | :----------------------------------------------------------------------------- |
| **error** | string | `insufficient_scope` — нет прав на использование сервиса (недостаточный scope) |
| **error_description** | string | Описание ошибки |
#### 404 Not Found
| Атрибут | Тип | Описание |
| :-------------------- | :----- | :---------------------------------------------------- |
| **error** | string | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **error_description** | string | Описание ошибки |
#### 429 Too Many Requests
Нет тела ответа. Превышен лимит запросов.
#### 500 Internal Server Error
| Атрибут | Тип | Описание |
| :-------------------- | :----- | :------------------------------------------- |
| **error** | string | `internal_error` — внутренняя ошибка сервиса |
| **error_description** | string | Описание ошибки |
#### 503 Service Unavailable
Нет тела ответа. Сервис временно недоступен.
]]>
</get_deal_request_status_md>
<get_deals_md>
<![CDATA[
# Получение списка сделок
**H2H**
Метод позволяет получить список всех сделок (независимо от статуса) по номинальному счёту с момента его открытия.
## Эндпоинты
| Окружение | Метод | URL |
| :--- | :--- | :--- |
| **Песочница** | `GET` | `https://sandbox.alfabank.ru/api/na/jp/v1/deals` |
| **Пром** | `GET` | `https://baas.alfabank.ru/api/na/jp/v1/deals` |
**Scope:** `deals`
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **accountNumber** | string | required | Номер номинального счёта |
| **limit** | integer | optional | Количество объектов на одной странице |
| **offset** | integer | optional | Количество объектов в списке, которые необходимо пропустить |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals?accountNumber={accountNumber}&limit=100&offset={offset}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 OK
Пример тела ответа:
```json
{
"pagination": {
"limit": 100,
"offset": 0,
"totalCount": 1
},
"deals": [
{
"dealId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "DRAFT",
"expireDate": "2032-03-02",
"isValid": false,
"steps": [
{
"id": "f099f9dd-d5e7-4ab3-89f5-24932aa808ad",
"description": "Этап 1",
"stepNumber": 1,
"status": "NEW",
"isValid": false
}
]
}
]
}
```
#### Описание полей ответа (200 OK)
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **pagination** | object | optional | Данные пагинации |
| ∟ **limit** | number | optional | Количество записей на одной странице |
| ∟ **offset** | number | optional | Количество записей в списке, которые были пропущены |
| ∟ **totalCount** | number | optional | Общее количество записей |
| **deals** | array | optional | Данные о сделках |
| ∟ **dealId** | string | required | Идентификатор сделки |
| ∟ **status** | string | required | Статус сделки: `DRAFT`, `ACTIVE`, `BLOCKED`, `PAYMENT_FAILED`, `CLOSED`, `COMPLETED` |
| ∟ **expireDate** | string | required | Дата истечения сделки |
| ∟ **isValid** | boolean | required | Флаг валидности сделки |
| ∟ **steps** | array | optional | Данные об этапах сделки |
| ∟ ∟ **id** | string | required | Идентификатор этапа сделки |
| ∟ ∟ **description** | string | required | Описание этапа сделки |
| ∟ ∟ **stepNumber** | integer | required | Порядковый номер этапа сделки |
| ∟ ∟ **status** | string | required | Статус этапа: `NEW`, `IN_PROGRESS`, `PAYMENT_FAILED`, `COMPLETED` |
| ∟ ∟ **isValid** | boolean | required | Флаг валидности этапа сделки |
---
## Ошибки
| Код | Описание (error) | error_description |
| :--- | :--- | :--- |
| **400** | `invalid_request` | Неверные входные параметры запроса |
| **401** | `invalid_token` | Токен просрочен, отозван или имеет неправильный формат |
| **403** | `insufficient_scope` | Нет прав на использование сервиса (настройки scope) |
| **404** | `unknown_endpoint` | Эндпоинт не найден или неактивен |
| **429** | — | Слишком много запросов (нет тела ответа) |
| **500** | `internal_error` | Внутренняя ошибка сервиса |
| **503** | — | Сервис недоступен (нет тела ответа) |
---
**Навигация:**
[← Регистрация сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-deal/v1/add-deal) | [Получение информации о сделке →](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal/v1/get-deal)
]]>
</get_deals_md>
<get_step_md>
<![CDATA[
# Получение информации об этапе сделки
**Тип интеграции:** H2H
**Scope:** `deals`
Метод позволяет получить детальную информацию об этапе сделки по `dealId` и `stepId`.
---
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :--------------------------------------------------------------------------- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps/{stepId}` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps/{stepId}` |
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
### PATH (Путь)
| Атрибут | Тип | Обязательность | Описание |
| :--------- | :----- | :------------- | :------------------------- |
| **dealId** | string | required | Идентификатор сделки |
| **stepId** | string | required | Идентификатор этапа сделки |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps/{stepId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**Пример тела ответа:**
```json
{
"stepId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"stepNumber": 1,
"description": "Этап 1",
"status": "DRAFT",
"isValid": false
}
```
**Описание полей:**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **stepId** | string | required | Идентификатор этапа сделки |
| **stepNumber** | integer | required | Порядковый номер этапа сделки |
| **description** | string | required | Описание этапа сделки |
| **status** | string | required | Статус этапа сделки (см. ниже) |
| **isValid** | boolean | required | Флаг валидности этапа сделки |
#### Возможные значения статуса (`status`):
- `DRAFT` — принят для последующей обработки;
- `ACTIVE` — успешно обработан;
- `BLOCKED` — ошибка в процессе обработки;
- `IN_PROGRESS` — в процессе обработки;
- `PAYMENT_FAILED` — платёж завершился неудачей;
- `CLOSED` — отменен;
- `COMPLETED` — успешно завершен.
---
## Ошибки
| Код | Описание (error) | Детали (error_description) |
| :------ | :------------------- | :-------------------------------------------- |
| **400** | `invalid_request` | Неверные входные параметры запроса |
| **401** | `invalid_token` | Токен просрочен, отозван или недействителен |
| **403** | `insufficient_scope` | У пользователя нет прав (недостаточный scope) |
| **404** | `unknown_endpoint` | Эндпоинт не найден или неактивен |
| **429** | — | Слишком много запросов (нет тела ответа) |
| **500** | `internal_error` | Внутренняя ошибка сервиса |
| **503** | — | Сервис недоступен (нет тела ответа) |
---
_Документация Alfa API_
]]>
</get_step_md>
<get_steps_md>
<![CDATA[
# Получение списка этапов сделки
**Тип интеграции:** H2H
**Scope:** `deals`
Метод позволяет получить список этапов сделки по `dealId`.
---
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :------------------------------------------------------------------ |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps` |
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Описание |
| :---------------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string (required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string (required) | `application/json` |
### QUERY
| Атрибут | Тип | Описание |
| :--------- | :----------------- | :--------------------------------------------------------------------------------------- |
| **offset** | integer (optional) | Количество элементов в списке, которое необходимо пропустить. Значение по умолчанию: `0` |
| **limit** | integer (optional) | Количество элементов в списке, которое необходимо вывести. Значение по умолчанию: `50` |
### PATH
| Атрибут | Тип | Описание |
| :--------- | :---------------- | :------------------- |
| **dealId** | string (required) | Идентификатор сделки |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/deals/{dealId}/steps?offset={offset}&limit={limit}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Пример ответа 200 (OK)
```json
[
{
"stepId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"stepNumber": 1,
"description": "Этап 1",
"status": "DRAFT",
"isValid": false
}
]
```
### BODY (200 OK)
| Атрибут | Тип | Описание |
| :-------------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **stepId** | string (required) | Идентификатор этапа сделки |
| **stepNumber** | integer (required) | Порядковый номер этапа сделки |
| **description** | string (required) | Описание этапа сделки |
| **status** | string (required) | Статус этапа сделки. Возможные значения:<br>• `DRAFT` — принят для последующей обработки;<br>• `ACTIVE` — успешно обработан;<br>• `BLOCKED` — ошибка в процессе обработки;<br>• `IN_PROGRESS` — в процессе обработки;<br>• `PAYMENT_FAILED` — платёж завершился неудачей;<br>• `CLOSED` — отменен;<br>• `COMPLETED` — успешно завершен |
| **isValid** | boolean (required) | Флаг валидности этапа сделки |
---
## Ошибки
| Код | Описание | Тело ответа (error) |
| :------ | :-------------------- | :----------------------------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса (недостаточный scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
- Предыдущий метод: [Получение статуса запроса на завершение этапа сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal-request-status/v1/get-deal-request-status)
- Следующий метод: [Получение информации об этапе сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-step/v1/get-step)
]]>
</get_steps_md>
<intro_md>
<![CDATA[
# Как это работает
**Теги:** H2H
> **Примечание**
> Депонент — это участник сделки, который выступает в качестве плательщика, реципиент — это получатель денежных средств.
Механизм безопасных сделок используется для осуществления расчётов, при которых средства депонента временно холдируются и переходят к реципиенту только после выполнения условия сделки. При этом Банк ведет учёт (биллинг) денежных средств каждого бенефициара.
Для работы с безопасными сделками предварительно необходимо:
1. [Зарегистрировать контрагентов, участвующих в сделке, и их платёжные реквизиты](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/intro/intro).
2. [Идентифицировать денежные средства, поступившие на номинальный счёт](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/intro/intro).
> **Важно**
> В рамках этапа сделки выполнять платежи от бенефициара самому себе нельзя. Совершить такой перевод можно напрямую без создания сделки, используя метод [«Создание запроса на выплату с номинального счёта»](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff/v1/payoff).
---
### Механизм работы сделок
1. **Зарегистрируйте сделку**
Создайте черновик сделки для дальнейшего её наполнения этапами и участниками с помощью метода [«Регистрация сделки»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-deal/v1/add-deal).
2. **Создайте этапы сделки**
Используйте метод [«Выполнение действия по этапам сделки»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-step/v1/add-step).
_Внимание!_ Каждая сделка должна содержать не менее одного этапа.
3. **Добавьте депонента в этапы сделки**
Добавьте информацию о бенефициаре (плательщике) этапа с помощью метода [«Выполнение действия по участникам этапа сделки»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/step-contractors/v1/step-contractors).
_Внимание!_ В одном этапе сделки может быть указан только один депонент (плательщик).
4. **Добавьте реципиентов в этапы сделки**
Добавьте информацию о получателях денежных средств с помощью метода [«Выполнение действия по участникам этапа сделки»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/step-contractors/v1/step-contractors). Реципиентами могут быть бенефициары или универсальные реципиенты.
_Внимание!_ В одном этапе сделки может быть несколько реципиентов.
5. **Проверьте возможность выплат по сформированной сделке**
Проверьте правильность наполнения с помощью метода [«Проверка возможности осуществления выплат по сделке»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-is-valid/v1/deal-is-valid). Для перехода к следующему шагу необходимо получить в ответе `isValid = true`.
6. **Подтвердите сделку**
Подтвердите создание с помощью метода [«Выполнение действия по сделке»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-actions/v1/deal-actions). Статус изменится с `DRAFT` на `ACTIVE`.
_Внимание!_ При подтверждении сделки денежные средства депонентов холдируются.
7. **Завершите этапы сделки**
Для проведения расчётов инициируйте завершение этапа через метод [«Выполнение действия по этапам сделки»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-step/v1/add-step).
Для контроля используйте метод [«Получение статуса запроса на завершение этапа сделки»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal-request-status/v1/get-deal-request-status). При завершении этапа осуществляются выплаты.
8. **Завершите сделку**
Используйте метод [«Выполнение действия по сделке»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-actions/v1/deal-actions). Статус изменится с `ACTIVE` на `COMPLETED`.
---
### Отмена сделки
Для отмены используйте метод [«Выполнение действия по сделке»](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/deal-actions/v1/deal-actions).
> **Важно**
> Отменить сделку можно только при условии, что ни один из её этапов не был завершён. При отмене ранее захолдированные средства депонентов будут расхолдированы.
---
### Информация о сделках и выплатах по ним
**По сделкам:**
- [Получение информации о сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal/v1/get-deal)
- [Получение списка сделок](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deals/v1/get-deals)
**По этапам:**
- [Получение информации об этапе сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-step/v1/get-step)
- [Получение списка этапов сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-steps/v1/get-steps)
**По участникам:**
- [Получить информацию об участниках этапа сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-contractors/v1/get-contractors)
**По переводам (платежам):**
- [Получение списка платежей по сделке](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/get-deal-payoffs/v1/get-deal-payoffs)
---
**Навигация:**
- Назад: [Получение статуса запроса на возврат неидентифицированного пополнения](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-transaction-refund-request-status/v1/get-transaction-refund-request-status)
- Вперед: [Регистрация сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-deal/v1/add-deal)
]]>
</intro_md>
<step_contractors_md>
<![CDATA[
# Выполнение действия по участникам этапа сделки
**Метка:** `H2H`
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :----------------------------------------------------------------------- |
| **Песочница** | `PATCH https://sandbox.alfabank.ru/api/na/jp/v1/deals/steps/contractors` |
| **Пром** | `PATCH https://baas.alfabank.ru/api/na/jp/v1/deals/steps/contractors` |
**Scope:** `deals`
## Описание
> **Внимание**
> Действия с участниками сделки возможны только для сделки в статусе `DRAFT`.
Метод позволяет добавить, изменить или удалить участника сделки.
### Добавление участника сделки
Каждый этап сделки должен содержать участников. При добавлении необходимо учитывать:
- В рамках одного этапа может быть добавлен только один депонент, реципиентов может быть несколько.
- В качестве депонента может выступать только бенефициар, в качестве реципиента – бенефициар или универсальный реципиент.
- При добавлении универсального реципиента необходимо передавать его идентификатор `universalRecipientId` в параметр `beneficiaryId`.
- Если не указан идентификатор платёжного реквизита `requisiteId`, система будет использовать [ранее зарегистрированный платёжный реквизит](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-requisites/v1/add-requisites), который считается основным (`isMain = true`).
### Изменение участника сделки
- **Для депонента:** можно изменить сумму депонированных средств.
- **Для реципиента:** можно изменить суммы, назначение платежа, признак вывода денег на виртуальный счёт и идентификатор платёжных реквизитов.
### Удаление участника сделки
Позволяет удалить депонента или реципиента из этапа сделки.
---
## Параметры запроса
### Headers
| Атрибут | Тип | Описание |
| :---------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | `string` (required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` (required) | application/json |
| **Content-Type** | `string` (required) | application/json |
### Body
| Атрибут | Тип | Описание |
| :----------------------- | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| **action** | `string` (required) | Тип действия: `ADD_DEPONENT`, `ADD_RECIPIENT`, `DELETE_DEPONENT`, `DELETE_RECIPIENT`, `UPDATE_DEPONENT`, `UPDATE_RECIPIENT` |
| **dealId** | `string` (required) | Идентификатор сделки |
| **stepId** | `string` (required) | Идентификатор этапа сделки |
| **beneficiaryId** | `string` (required) | Идентификатор бенефициара или универсального реципиента |
| **amount** | `string` (optional) | Сумма депонирования в рублях. Доступно только для депонента |
| **purpose** | `string` (optional) | Назначение платежа реципиента. Доступно только для реципиента |
| **amounts** | `array of objects` (optional) | Суммы реципиента. Доступно только для реципиента (см. ниже) |
| **keepOnNominalAccount** | `boolean` (optional) | Признак вывода на вирт. счёт: `true` — оставить на ном. счёте; `false` — вывести на реквизиты |
| **requisiteId** | `string` (optional) | Идентификатор платёжного реквизита контрагента |
| **digestSignatures** | `array of objects` (required) | Электронная подпись УЛ Клиента (см. ниже) |
#### Объект `amounts` (внутри Body)
| Атрибут | Тип | Описание |
| :------------- | :------------------ | :------------------------------------------------- |
| **walletType** | `string` (optional) | Тип кошелька: `MAIN` (основной), `TAX` (налоговый) |
| **amount** | `string` (optional) | Сумма в рублях |
#### Объект `digestSignatures` (внутри Body)
| Атрибут | Тип | Описание |
| :---------------- | :------------------ | :------------------------------------ |
| **base64Encoded** | `string` (required) | Значение подписи в Base64 |
| **signatureType** | `string` (required) | Тип подписи: `rsa` (RSA), `kep` (КЭП) |
---
## Пример запроса (cURL)
```bash
curl --location --request PATCH 'https://baas.alfabank.ru/api/na/jp/v1/deals/steps/contractors' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"action": "ADD_DEPONENT",
"dealId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"stepId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": "10.00",
"purpose": "Назначение платежа",
"amounts": [
{
"walletType": "MAIN",
"amount": "10.00"
}
],
"keepOnNominalAccount": true,
"requisiteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
| Код | Статус | Описание |
| :------ | :-------------------- | :-------------------------------------------- |
| **204** | No Content | Успешное выполнение. Тело ответа отсутствует. |
| **400** | Bad Request | Неверные входные параметры. |
| **401** | Unauthorized | Токен просрочен или недействителен. |
| **403** | Forbidden | Недостаточно прав (insufficient_scope). |
| **404** | Not Found | Эндпоинт не найден. |
| **429** | Too Many Requests | Слишком много запросов. |
| **500** | Internal Server Error | Внутренняя ошибка сервиса. |
| **503** | Service Unavailable | Сервис временно недоступен. |
### Структура ошибки (400, 401, 403, 404, 500)
| Атрибут | Тип | Описание |
| :-------------------- | :------- | :------------------------------------------------------------------------------ |
| **error** | `string` | Код ошибки (например, `invalid_request`, `invalid_token`, `insufficient_scope`) |
| **error_description** | `string` | Подробное описание ошибки |
---
_Документация Alfa API_
]]>
</step_contractors_md>
</Безопасные_сделки>
<Выплаты>
<get_payoff_md>
<![CDATA[
# Получение информации о платеже
**Контекст:** Номинальные счета / Выплаты
**Тип интеграции:** H2H
**Scope:** `beneficiary-payments`
## Эндпоинты
| Окружение | Метод | URL |
| :------------ | :---- | :------------------------------------------------------------ |
| **Песочница** | `GET` | `https://sandbox.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}` |
| **Пром** | `GET` | `https://baas.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}` |
## Описание
Метод позволяет получить информацию о платеже по его идентификатору `payoffId`.
---
## Параметры запроса
### Headers
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
### Path
| Атрибут | Тип | Обязательность | Описание |
| :----------- | :----- | :------------- | :-------------------- |
| **payoffId** | string | required | Идентификатор платежа |
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
#### Тело ответа (JSON)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------- |
| **dealId** | string | optional | Идентификатор сделки |
| **stepId** | string | optional | Идентификатор этапа |
| **paymentType** | string | optional | Тип платежа: `REGULAR` (обычный), `DEAL` (выплата внутри сделки), `TAX` (налоговый) |
| **requisiteType** | string | optional | Тип реквизита: `ACCOUNT` (счёт), `CARD` (токен карты), `PHONE` (номер телефона) |
| **payer** | object | optional | Информация о плательщике (см. ниже) |
| **recipient** | object | optional | Информация о получателе (см. ниже) |
| **amount** | string | optional | Сумма в рублях |
| **purpose** | string | optional | Назначение платежа |
| **status** | string | optional | Статус: `IN_PROGRESS` (в обработке), `FAILED` (ошибка), `READY` (успешно завершён) |
#### Объект `payer` (Плательщик)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :----------------------- |
| **accountNumber** | string | required | Номер счёта |
| **name** | string | required | Наименование организации |
| **inn** | string | required | ИНН |
| **kpp** | string | required | КПП |
#### Объект `recipient` (Получатель)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :------------------------ |
| **beneficiaryId** | string | optional | Идентификатор бенефициара |
| **accountNumber** | string | optional | Номер счёта |
| **bik** | string | optional | БИК банка |
| **name** | string | optional | ФИО реципиента |
| **inn** | string | optional | ИНН |
### Пример успешного ответа
```json
{
"dealId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"stepId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"paymentType": "REGULAR",
"requisiteType": "ACCOUNT",
"payer": {
"accountNumber": "40817810306050000000",
"name": "Акционерное общество «Ромашка»",
"inn": "1122334455",
"kpp": "123456789"
},
"recipient": {
"beneficiaryId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"name": "Иванов Иван Иванович",
"inn": "112233445566"
},
"amount": "10.00",
"purpose": "Назначение платежа",
"status": "IN_PROGRESS"
}
```
---
## Коды ошибок
| Код | Описание | Возможные значения `error` |
| :------ | :-------------------- | :--------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав (проверьте scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа (превышен лимит запросов) |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа (сервис временно недоступен) |
---
_Документация Alfa API_
]]>
</get_payoff_md>
<get_payoff_request_status_md>
<![CDATA[
# Получение статуса запроса на выплату с номинального счёта
**Тип интеграции:** H2H
**Scope:** `beneficiary-payments`
## Описание
Метод позволяет получить статус запроса на выплату с номинального счёта по идентификатору `payoffId`.
---
## Эндпоинты
| Окружение | Метод | URL |
| :--- | :--- | :--- |
| **Песочница** | `GET` | `https://sandbox.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}/status` |
| **Пром** | `GET` | `https://baas.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}/status` |
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | `string` | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` | required | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **payoffId** | `string` | required | Идентификатор запроса, полученный с помощью метода [«Создание запроса на выплату с номинального счёта»](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff/v1/payoff) |
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}/status' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**Пример тела ответа:**
```json
{
"payoffId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "PENDING",
"description": "Произошла техническая ошибка. Обратитесь в службу поддержки и сообщите код ошибки afc9b019-77ac-49ef-afb9-688b38b74cc2"
}
```
**Описание полей BODY:**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **payoffId** | `string` | required | Идентификатор запроса |
| **status** | `string` | required | Статус запроса (см. ниже) |
| **description** | `string` | optional | Описание причины, по которой запрос завершился неудачей. Возвращается, если статус равен `FAILED` |
#### Возможные значения поля `status`:
* `PENDING` — запрос в процессе обработки;
* `MANUAL_ACCEPTANCE` — ожидание ручного подтверждения отправки запроса-дубля на обработку;
* `AWAIT_EXTERNAL` — ожидание исполнения внешнего платежа;
* `FAILED` — обработка запроса завершилась ошибкой;
* `FAILED_DUPLICATE` — обработка запроса-дубля отклонена;
* `COMPLETE` — обработка запроса завершилась успешно.
---
## Коды ошибок
| Код | Описание | Возможные значения `error` / Примечание |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав (scope) на использование сервиса |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа. Превышен лимит запросов |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа. Сервис временно недоступен |
---
## Дополнительные ссылки
* [Предыдущий шаг: Создание запроса на выплату](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff/v1/payoff)
* [Следующий шаг: Подтверждение или отклонение запроса-дубля](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff-accept/v1/payoff-accept)
]]>
</get_payoff_request_status_md>
<get_tax_refund_request_status_md>
<![CDATA[
# Получение статуса запроса на возврат налоговых денежных средств
**Тип интеграции:** H2H
**Продукт:** Номинальные счета
**Scope:** `beneficiary-payments`
## Эндпоинты
| Среда | Метод | URL |
| :------------ | :---- | :------------------------------------------------------------------------- |
| **Песочница** | `GET` | `https://sandbox.alfabank.ru/api/na/jp/v1/tax-refund/{taxRefundId}/status` |
| **Пром** | `GET` | `https://baas.alfabank.ru/api/na/jp/v1/tax-refund/{taxRefundId}/status` |
---
## Описание
Метод позволяет получить статус запроса на возврат бенефициару его денежных средств с налогового кошелька по идентификатору `taxRefundId`.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :-------------- | :----- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **taxRefundId** | string | required | Идентификатор запроса, полученный с помощью метода [«Создание запроса на возврат денежных средств с налогового виртуального кошелька»](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/tax-refund/v1/tax-refund) |
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/tax-refund/{taxRefundId}/status' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**Пример тела ответа:**
```json
{
"taxRefundId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "FAILED",
"description": "Произошла техническая ошибка. Обратитесь в службу поддержки и сообщите код ошибки afc9b019-77ac-49ef-afb9-688b38b74cc2"
}
```
**Описание полей BODY:**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **taxRefundId** | string | required | Идентификатор запроса |
| **status** | string | required | Статус запроса (см. ниже) |
| **description** | string | optional | Описание причины неудачи. Возвращается только при статусе `FAILED` |
#### Возможные значения статуса (`status`):
- `PENDING` — запрос в процессе обработки;
- `MANUAL_ACCEPTANCE` — ожидание ручного подтверждения отправки запроса-дубля на обработку;
- `AWAIT_EXTERNAL` — ожидание исполнения внешнего платежа;
- `FAILED` — обработка запроса завершилась ошибкой;
- `FAILED_DUPLICATE` — обработка запроса-дубля отклонена;
- `COMPLETE` — обработка запроса завершилась успешно.
---
## Ошибки
| Код | Описание | Тело ответа (error) |
| :------ | :-------------------- | :------------------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав (проверьте настройки scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
## Навигация
- **Предыдущий метод:** [Создание запроса на возврат налоговых денежных средств](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/tax-refund/v1/tax-refund)
- **Следующий метод:** [Подтверждение или отклонение запроса-дубля на возврат налоговых денежных средств](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/tax-refund-accept/v1/tax-refund-accept)
]]>
</get_tax_refund_request_status_md>
<intro_md>
<![CDATA[
# Как это работает
_Номинальные счета / Выплаты / Как это работает_
Для осуществления выплат с номинального счёта предварительно необходимо [зарегистрировать контрагента](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/intro/intro), участвующего в выплате.
## Общий механизм выплат с номинального счёта
1. **Создайте запрос на выплату**
Метод [«Создание запроса на выплату с номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff/v1/payoff)
2. **Получите статус запроса на выплату**
Метод [«Получение статуса запроса на выплату с номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-payoff-request-status/v1/get-payoff-request-status)
3. **Подтвердите или отклоните обработку запроса-дубля на выплату**
В случае, если статус запроса на выплату уже был создан ранее, он примет статус `MANUAL_ACCEPTANCE` и его нужно будет подтвердить или отклонить.
Метод [«Подтвердить или отклонить запрос-дубль на выплату»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff-accept/v1/payoff-accept)
4. **Получите информацию о платеже по его идентификатору**
Метод [«Получение информации о платеже»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-payoff/v1/get-payoff)
---
Выплаты с номинального счёта делятся на два типа:
- выплаты без биллинга на стороне Банка;
- выплаты с биллингом на стороне Банка.
## Выплаты без биллинга на стороне Банка
Данный тип выплаты позволяет произвести выплату с номинального счёта в пользу зарегистрированного контрагента без создания сделки.
Необходимо учитывать:
- На номинальном счёте должен быть положительный баланс.
- Если выплата производится в пользу универсального реципиента, то для него предварительно необходимо зарегистрировать платёжные реквизиты с помощью метода [«Добавление платёжных реквизитов универсального реципиента»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/add-requisites/v1/add-requisites).
В качестве платёжных реквизитов получателя могут быть указаны:
- реквизиты счёта;
- номер телефона (СБП);
- зашифрованный номер карты (как зашифровать номер карты, описано [здесь](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken));
- идентификатор платёжных реквизитов контрагента.
## Выплаты с биллингом на стороне Банка
> **Важно**
>
> У бенефициара должен быть положительный баланс на налоговом виртуальном счёте.
- **Вывод собственных средств бенефициара с номинального счёта.** Позволяет вывести с номинального счёта денежные средства бенефициара без создания сделки.
- **Выплата с целью уплаты налога на профессиональный доход за исполнителя.** Позволяет аккумулировать денежные средства на виртуальном налоговом счёте исполнителя и перевести денежные средства бенефициара, задепонированные с целью уплаты налога на профессиональный доход за исполнителя, на счёт в управление казначейства.
- **Возврат денежных средств с налогового виртуального кошелька.** Позволяет вернуть денежные средства бенефициара, задепонированные с целью уплаты налога на профессиональный доход за исполнителя, если оплата налога не потребовалась.
### Механизм возврата денежных средств с налогового виртуального кошелька
1. **Создайте запрос на возврат денежных средств с налогового виртуального кошелька**
Метод [«Создание запроса на возврат денежных средств с налогового виртуального кошелька»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/tax-refund/v1/tax-refund)
2. **Получите статус запроса на возврат налоговых денежных средств**
Метод [«Получение статуса запроса на возврат налоговых денежных средств»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-tax-refund-request-status/v1/get-tax-refund-request-status)
3. **Подтвердите или отклоните обработку запроса-дубля на возврат денежных средств с налогового виртуального кошелька**
В случае, если статус запроса на выплату уже был создан ранее, он примет статус `MANUAL_ACCEPTANCE` и его нужно будет подтвердить или отклонить.
Метод [«Подтверждение или отклонение запроса-дубля на возврат денежных средств с налогового виртуального кошелька»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/tax-refund-accept/v1/tax-refund-accept)
]]>
</intro_md>
<payoff_accept_md>
<![CDATA[
Ниже представлен очищенный и структурированный анализ документа в формате Markdown.
---
# Подтверждение или отклонение запроса-дубля на выплату
**Тип интеграции:** H2H
**Продукт:** Номинальные счета / Выплаты
**Метод:** `PATCH`
## Эндпоинты
| Среда | URL |
| :--- | :--- |
| **Песочница** | `https://sandbox.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}/accept` |
| **Пром** | `https://baas.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}/accept` |
## Scope
`beneficiary-payments`
## Описание
Метод позволяет подтвердить или отклонить запрос на создание выплаты, находящийся в статусе `MANUAL_ACCEPTANCE`, по идентификатору `payoffId`. Это необходимо для обработки ситуаций, когда система зафиксировала потенциальный дубль запроса.
---
## Параметры запроса
### Headers (Заголовки)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | Да | `Bearer {access_token}`, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | `application/json` |
| **Content-Type** | string | Да | `application/json` |
### Path (Путь)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **payoffId** | string | Да | Идентификатор запроса, полученный методом [«Создание запроса на выплату с номинального счёта»](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff/v1/payoff) |
### Body (Тело запроса)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **accept** | boolean | Да | Флаг обработки запроса-дубля:<br>• `true` – продолжить обработку;<br>• `false` – завершить (отклонить) обработку. |
### Пример запроса (cURL)
```bash
curl --location --globoff --request PATCH 'https://baas.alfabank.ru/api/na/jp/v1/payoffs/{payoffId}/accept' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"accept": true
}'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **result** | boolean | Да | Статус обработки:<br>• `true` – обработка продолжена;<br>• `false` – обработка завершена. |
**Пример JSON:**
```json
{
"result": true
}
```
### Ошибки
| Код | Описание (error) | Описание (error_description) |
| :--- | :--- | :--- |
| **400** | `invalid_request` | Неверные входные параметры запроса. |
| **401** | `invalid_token` | Токен просрочен, отозван или имеет неверный формат. |
| **403** | `insufficient_scope` | Нет прав на использование сервиса (недостаточный scope). |
| **404** | `unknown_endpoint` | Эндпоинт не найден или неактивен. |
| **429** | — | Too Many Requests (слишком много запросов). Тело ответа отсутствует. |
| **500** | `internal_error` | Внутренняя ошибка сервиса. |
| **503** | — | Service Unavailable (сервис недоступен). Тело ответа отсутствует. |
---
## Навигация
* **Назад:** [Получение статуса запроса на выплату с номинального счёта](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-payoff-request-status/v1/get-payoff-request-status)
* **Вперед:** [Получение информации о платеже](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-payoff/v1/get-payoff)
]]>
</payoff_accept_md>
<payoff_md>
<![CDATA[
Вот очищенная и структурированная версия документа в формате Markdown.
---
# Создание запроса на выплату с номинального счёта
**Тип интеграции:** H2H
**Scope:** `beneficiary-payments`
## Эндпоинты
* **Песочница:** `POST https://sandbox.alfabank.ru/api/na/jp/v1/payoffs`
* **Пром:** `POST https://baas.alfabank.ru/api/na/jp/v1/payoffs`
## Описание
Метод позволяет вывести собственные средства бенефициара с номинального счёта по заранее зарегистрированным платёжным реквизитам (с биллингом) или осуществить выплату зарегистрированным контрагентам (без биллинга).
> [!IMPORTANT]
> **Важно**
> Если идентичный запрос на выплату уже был создан ранее, то текущий запрос примет статус `MANUAL_ACCEPTANCE`. Его нужно будет подтвердить или отклонить с помощью метода [«Подтверждение или отклонение запроса-дубля на выплату»](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/payoff-accept/v1/payoff-accept).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | `application/json` |
| **Content-Type** | string | Да | `application/json` |
### BODY
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **type** | string | Да | Тип платежа: `REGULAR` (обычный), `TAX` (налоговый) |
| **accountNumber** | string | Да | Номер номинального счёта |
| **deponent** | string | Нет | Идентификатор бенефициара-плательщика |
| **recipient** | object | Да | **Получатель** (см. ниже) |
| **payoutRequisite** | object | Да | **Реквизиты обычного платежа** (см. ниже) |
| **requisites** | object | Нет | **Реквизиты для налогового платежа** (см. ниже) |
| **amount** | string | Да | Сумма в рублях |
| **purpose** | string | Да | Назначение платежа |
| **tax** | object | Нет | **Параметры для налогового платежа** (см. ниже) |
| **digestSignatures** | array | Да | **Электронная подпись УЛ клиента** (см. ниже) |
#### Вложенный объект: recipient (Получатель)
* **type** (string, обязат.): Тип получателя. Значения: `BENEFICIARY` (контрагент), `SIMPLE_PAYEE` (простой получатель).
* **name** (string, опц.): Наименование (ФИО для ФЛ, название для ЮЛ/ИП). Обязательно для `SIMPLE_PAYEE`.
* **inn** (string, опц.): ИНН (12 цифр для ФЛ/ИП, 10 для ЮЛ). Обязательно для `SIMPLE_PAYEE`.
* **kpp** (string, опц.): КПП получателя.
* **beneficiaryId** (string, опц.): Идентификатор контрагента. Обязательно для `BENEFICIARY`.
#### Вложенный объект: payoutRequisite (Реквизиты выплаты)
* **type** (string, обязат.): Тип реквизита: `ACCOUNT`, `CARD`, `PHONE`, `BENEFICIARY_REQUISITE`.
* **requisiteId** (string, опц.): ID реквизитов контрагента. Обязательно для `BENEFICIARY_REQUISITE`.
* **pan** (string, опц.): Токен номера карты. Обязательно для `CARD`. [Инструкция по токенизации](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken).
* **phoneNumber** (string, опц.): Номер телефона. Обязательно для `PHONE`.
* **bankId** (string, опц.): ID банка получателя. Обязательно для `PHONE`.
* **accountNumber** (string, опц.): Номер счёта. Обязательно для `ACCOUNT`.
* **bik** (string, опц.): БИК банка. Обязательно для `ACCOUNT`.
#### Вложенный объект: tax (Налоговые параметры)
* **uin** (string, обязат.): УИН (поле 22).
* **payerStatus** (string, обязат.): Статус составителя (поле 101). Примеры: `01`, `02`, `08`, `13` и др.
* **kbk** (string, обязат.): КБК (поле 104).
* **oktmo** (string, обязат.): ОКТМО (поле 105).
* **reason** (string, обязат.): Основание платежа (поле 106). Примеры: `ТП`, `ЗД`, `0`.
* **period** (string, обязат.): Налоговый период (поле 107). Формат ДД.ММ.ГГГГ или `0`.
* **docNumber** (string, обязат.): Номер документа (поле 108).
* **docDate** (string, обязат.): Дата документа (поле 109).
* **paymentKind** (string, опц.): Код типа платежа (поле 110). `ПЕ`, `ПЦ` или `0`.
#### Вложенный объект: digestSignatures (Подписи)
* **base64Encoded** (string, обязат.): Значение подписи в Base64.
* **signatureType** (string, обязат.): Тип подписи: `rsa` или `kep`.
---
## Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/payoffs' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"type": "REGULAR",
"accountNumber": "40817810306050000000",
"deponent": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recipient": {
"type": "BENEFICIARY",
"name": "Иванов Иван Иванович",
"inn": "112233445566",
"kpp": "123456789",
"beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"payoutRequisite": {
"type": "ACCOUNT",
"requisiteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593"
},
"amount": "10.00",
"purpose": "Назначение платежа",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### Успешный ответ (202 Accepted)
```json
{
"payoffId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "PENDING"
}
```
**Описание полей ответа:**
* **payoffId** (string): Уникальный идентификатор платежа.
* **status** (string): Статус запроса. Возможные значения:
* `PENDING` — в процессе обработки.
* `MANUAL_ACCEPTANCE` — ожидание ручного подтверждения (для дублей).
* `AWAIT_EXTERNAL` — ожидание исполнения внешнего платежа.
* `FAILED` — ошибка обработки.
* `FAILED_DUPLICATE` — запрос-дубль отклонен.
* `COMPLETE` — успешно завершено.
---
## Коды ошибок
| Код | Описание | Тело ответа (error) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные параметры |
| **401** | Unauthorized | `invalid_token` — токен недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав доступа |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
* [Как это работает](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/intro/intro)
* [Получение статуса запроса на выплату](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-payoff-request-status/v1/get-payoff-request-status)
]]>
</payoff_md>
<tax_refund_accept_md>
<![CDATA[
# Подтверждение или отклонение запроса-дубля на возврат налоговых денежных средств
Данный метод API предназначен для управления запросами на возврат налоговых средств, которые получили статус `MANUAL_ACCEPTANCE` (требуют ручного подтверждения из-за обнаружения дубликата).
## Общая информация
- **Тип документа:** H2H
- **Метод:** `PATCH`
- **Scope:** `beneficiary-payments`
## Эндпоинты
| Среда | URL |
| :------------ | :------------------------------------------------------------------------- |
| **Песочница** | `https://sandbox.alfabank.ru/api/na/jp/v1/tax-refund/{taxRefundId}/accept` |
| **Пром** | `https://baas.alfabank.ru/api/na/jp/v1/tax-refund/{taxRefundId}/accept` |
## Описание
Метод позволяет подтвердить или отклонить запрос на возврат налоговых денежных средств, находящийся в статусе `MANUAL_ACCEPTANCE`, используя уникальный идентификатор `taxRefundId`.
---
## Параметры запроса
### Headers (Заголовки)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
### PATH (Путь)
| Атрибут | Тип | Обязательность | Описание |
| :-------------- | :----- | :------------- | :------------------------------- |
| **taxRefundId** | string | required | Идентификатор запроса на возврат |
### QUERY (Параметры строки)
| Атрибут | Тип | Обязательность | Описание |
| :--------- | :------ | :------------- | :-------------------------------------------------------------------------------------------------------- |
| **accept** | boolean | required | Флаг обработки дубля:<br>• `true` – продолжить обработку;<br>• `false` – завершить (отклонить) обработку. |
---
## Пример запроса (cURL)
```bash
curl --location --globoff --request PATCH \
'https://baas.alfabank.ru/api/na/jp/v1/tax-refund/{taxRefundId}/accept?accept={accept}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**Тело ответа (JSON):**
```json
{
"result": true
}
```
**Описание полей:**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **result** | boolean | required | Статус обработки: `true` — продолжена, `false` — завершена. |
---
## Коды ошибок
| Код | Статус | Ошибка (`error`) | Описание |
| :------ | :------------------ | :------------------- | :----------------------------------------------------- |
| **400** | Bad Request | `invalid_request` | Неверные входные параметры запроса. |
| **401** | Unauthorized | `invalid_token` | Токен просрочен, отозван или имеет неверный формат. |
| **403** | Forbidden | `insufficient_scope` | Нет прав на использование сервиса (не настроен scope). |
| **404** | Not Found | `unknown_endpoint` | Эндпоинт не найден или неактивен. |
| **429** | Too Many Requests | — | Слишком много запросов (нет тела ответа). |
| **500** | Internal Error | `internal_error` | Внутренняя ошибка сервиса. |
| **503** | Service Unavailable | — | Сервис временно недоступен (нет тела ответа). |
---
## Навигация
- **Предыдущий шаг:** [Получение статуса запроса на возврат налоговых денежных средств](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-tax-refund-request-status/v1/get-tax-refund-request-status)
- **Раздел:** Номинальные счета / Выплаты
]]>
</tax_refund_accept_md>
<tax_refund_md>
<![CDATA[
# Создание запроса на возврат налоговых денежных средств
**Продукт:** Alfa API / Номинальные счета / Выплаты
**Тип интеграции:** H2H
**Scope:** `beneficiary-payments`
## Эндпоинты
| Окружение | Метод | URL |
| :------------ | :----- | :---------------------------------------------------- |
| **Песочница** | `POST` | `https://sandbox.alfabank.ru/api/na/jp/v1/tax-refund` |
| **Пром** | `POST` | `https://baas.alfabank.ru/api/na/jp/v1/tax-refund` |
## Описание
Метод позволяет создать запрос на возврат бенефициару его денежных средств с налогового кошелька, если оплата налога не потребовалась.
- Если нужно вернуть налоговые средства на основной виртуальный счёт бенефициара без вывода с номинального счёта, передавайте `keepOnNominalAccount = true`.
- Если нужно вернуть налоговые средства бенефициару с выводом с номинального счёта, передавайте `keepOnNominalAccount = false`.
> [!IMPORTANT]
> **Важно**
> Если идентичный запрос на возврат налоговых денежных средств уже был создан ранее, то текущий запрос примет статус `MANUAL_ACCEPTANCE`. Его нужно будет подтвердить или отклонить с помощью метода [«Подтверждение или отклонение запроса-дубля на возврат налоговых денежных средств»](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/tax-refund-accept/v1/tax-refund-accept).
## Параметры запроса
### Заголовки (Headers)
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | required | `application/json` |
### Тело запроса (Body)
| Атрибут | Тип | Обязательность | Описание |
| :----------------------- | :------ | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **beneficiaryId** | string | required | Идентификатор бенефициара |
| **amount** | string | required | Сумма |
| **purpose** | string | required | Назначение платежа |
| **keepOnNominalAccount** | boolean | required | Признак вывода денег на основной виртуальный счёт. <br>• `true` — оставить в рамках номинального счёта; <br>• `false` — вывести по идентификатору платёжного реквизита бенефициара. |
| **requisiteId** | string | optional | Идентификатор платёжного реквизита бенефициара для вывода. Если не заполнено, используются основные реквизиты. |
| **digestSignatures** | array | required | Массив объектов электронной подписи УЛ клиента. |
**Объект в digestSignatures:**
- **base64Encoded** (string, required): Значение электронной подписи в Base64.
- **signatureType** (string, required): Тип подписи: `rsa` (RSA) или `kep` (КЭП).
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/tax-refund' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": "10.00",
"purpose": "Назначение платежа",
"keepOnNominalAccount": false,
"requisiteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### Успешный ответ (202 Accepted)
| Атрибут | Тип | Обязательность | Описание |
| :-------------- | :----- | :------------- | :--------------------------------------- |
| **taxRefundId** | string | required | Идентификатор возврата налоговых средств |
| **status** | string | required | Статус запроса (см. ниже) |
**Возможные значения статуса:**
- `PENDING` — запрос в процессе обработки;
- `MANUAL_ACCEPTANCE` — ожидание ручного подтверждения запроса-дубля;
- `AWAIT_EXTERNAL` — ожидание исполнения внешнего платежа;
- `FAILED` — ошибка обработки;
- `FAILED_DUPLICATE` — запрос-дубль отклонен;
- `COMPLETE` — успешно завершено.
**Пример ответа 202:**
```json
{
"taxRefundId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "PENDING"
}
```
---
## Ошибки
| Код | Описание | Тело ответа (error) |
| :------ | :------------------ | :---------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен недействителен или просрочен |
| **403** | Forbidden | `insufficient_scope` — нет прав (недостаточный scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Связанные методы:**
- [Получение информации о платеже](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-payoff/v1/get-payoff)
- [Получение статуса запроса на возврат налоговых денежных средств](/products/alfa-api/documentation/articles/nominal-accounts/articles/na-payments/articles/get-tax-refund-request-status/v1/get-tax-refund-request-status)
]]>
</tax_refund_md>
</Выплаты>
<Идентификация_пополнений>
<get_identify_request_status_md>
<![CDATA[
# Получение статуса запроса на идентификацию пополнения номинального счёта
**Тип интеграции:** H2H
---
### Эндпоинты
**Песочница**
`GET https://sandbox.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/identify/{identifyId}`
**Пром**
`GET https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/identify/{identifyId}`
---
### Scope
`beneficiary-payments`
---
### Описание
Метод позволяет получить статус запроса на идентификацию операции пополнения по `identifyId`.
---
### Параметры запроса
#### HEADERS
| Атрибут | Описание |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** _string, required_ | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** _string, required_ | application/json |
#### PATH
| Атрибут | Описание |
| :-------------------------------- | :--------------------------------------------------------- |
| **id** _string, required_ | Идентификатор операции пополнения |
| **identifyId** _string, required_ | Идентификатор запроса на идентификацию операции пополнения |
---
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/identify/{identifyId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
### Параметры ответа
#### 200 (OK) — BODY
| Атрибут | Описание |
| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **identifyId** _string, required_ | Идентификатор запроса на идентификацию операции пополнения |
| **status** _string, required_ | Статус запроса. Возможные значения: `PENDING` - в процессе обработки;`VALIDATED` - провалидирован;`FAILED` - возникла ошибка;`COMPLETE` - обработан успешно |
| **description** _string, optional_ | Описание причины, по которой запрос завершился неудачей. Возвращается, если статус запроса равен `FAILED` |
#### Пример ответа 200 (OK)
```json
{
"identifyId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "PENDING",
"description": "Произошла техническая ошибка. Обратитесь в службу поддержки и сообщите код ошибки afc9b019-77ac-49ef-afb9-688b38b74cc2"
}
```
---
### Ошибки
| Код | Описание |
| :-------------------------- | :------------------------------------------------------------------- |
| **400 Bad Request** | `invalid_request` — неверные входные параметры запроса |
| **401 Unauthorized** | `invalid_token` — предоставленный токен просрочен или недействителен |
| **403 Forbidden** | `insufficient_scope` — недостаточно прав (не настроен scope) |
| **404 Not Found** | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429 Too Many Requests** | Превышен лимит запросов (тело ответа отсутствует) |
| **500 Internal Error** | `internal_error` — внутренняя ошибка сервиса |
| **503 Service Unavailable** | Сервис временно недоступен (тело ответа отсутствует) |
---
**Навигация:**
- [Предыдущий метод: Создание запроса на идентификацию](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/identify/v1/identify)
- [Следующий метод: Создание запроса на возврат](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/transaction-refund/v1/transaction-refund)
]]>
</get_identify_request_status_md>
<get_transaction_refund_request_status_md>
<![CDATA[
# Получение статуса запроса на возврат неидентифицированного пополнения
**Тип интеграции:** H2H
## Эндпоинты
**Песочница**
`GET https://sandbox.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/refunds/{refundId}`
**Пром**
`GET https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/refunds/{refundId}`
## Scope
`beneficiary-payments`
## Описание
Метод позволяет получить статус запроса на возврат неидентифицированного пополнения по `refundId`.
## Параметры запроса
### HEADERS
| Атрибут | Описание |
| :--- | :--- |
| **Authorization** <br>`string`, required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** <br>`string`, required | application/json |
### PATH
| Атрибут | Описание |
| :--- | :--- |
| **id** <br>`string`, required | Идентификатор операции пополнения, по которой необходимо вернуть денежные средства |
| **refundId** <br>`string`, required | Идентификатор запроса на возврат неидентифицированного пополнения, полученный с помощью метода [«Создание запроса на возврат неидентифицированного пополнения»](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/transaction-refund/v1/transaction-refund) |
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/refunds/{refundId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 (OK)
**BODY**
| Атрибут | Описание |
| :--- | :--- |
| **refundId** <br>`string`, required | Уникальный идентификатор запроса на возврат неидентифицированного пополнения |
| **status** <br>`string`, required | Статус запроса. Принимает возможные значения: <br>• `PENDING` - запрос в процессе обработки;<br>• `FAILED` - обработка запроса завершилась ошибкой;<br>• `COMPLETE` - обработка запроса завершилась успешно |
| **description** <br>`string`, optional | Описание причины, по которой запрос завершился ошибкой. <br>**Примечание:** поле доступно только при статусе запроса `FAILED` |
#### Пример ответа 200 (OK)
```json
{
"refundId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "FAILED",
"description": "Произошла техническая ошибка. Обратитесь в службу поддержки и сообщите код ошибки afc9b019-77ac-49ef-afb9-688b38b74cc2"
}
```
---
## Коды ошибок
| Код | Описание | Возможные значения `error` |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав (отсутствует нужный scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
* Предыдущий метод: [Создание запроса на возврат неидентифицированного пополнения](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/transaction-refund/v1/transaction-refund)
* Следующий раздел: [Безопасные сделки: Как это работает](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/intro/intro)
]]>
</get_transaction_refund_request_status_md>
<get_unidentified_transactions_md>
<![CDATA[
# Получение списка неидентифицированных пополнений номинального счёта
**Тип интеграции:** H2H
Метод позволяет получить информацию о транзакциях пополнения номинального счёта, которые не проходили процедуру идентификации.
---
## Эндпоинты
### Песочница
`GET https://sandbox.alfabank.ru/api/na/jp/v1/unidentified-transactions`
### Пром
`GET https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions`
---
## Scope
`beneficiary-payments`
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **accountNumber** | string | required | Номер номинального счёта |
| **limit** | integer | optional | Количество объектов на одной странице |
| **offset** | integer | optional | Количество объектов в списке, которые необходимо пропустить |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions?accountNumber=40817810306050000000&limit=100&offset={offset}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Ответ 200 (OK) — BODY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **offset** | integer | required | Порядковый номер первого неидентифицированного пополнения в списке |
| **limit** | integer | required | Порядковый номер последнего неидентифицированного пополнения в списке |
| **totalCount** | integer | required | Всего неидентифицированных пополнений |
| **unidentifiedTransactions** | array of objects | optional | Список неидентифицированных пополнений |
#### Объект unidentifiedTransactions:
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **id** | string | required | ID операции пополнения |
| **documentNumber** | string | optional | Номер платёжного поручения |
| **date** | string | optional | Дата и время пополнения по МСК |
| **amount** | string | required | Сумма пополнения в рублях |
| **purpose** | string | optional | Назначение платежа |
| **payer** | object | optional | Информация о плательщике |
#### Объект payer:
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **inn** | string | optional | ИНН плательщика |
| **kpp** | string | optional | КПП плательщика |
| **accountNumber** | string | optional | Номер счёта плательщика |
| **name** | string | optional | Имя плательщика |
| **bankAccount** | string | optional | Номер счёта банка плательщика |
| **bankBik** | string | optional | БИК банка плательщика |
| **bankName** | string | optional | Наименования банка плательщика |
### Пример ответа 200
```json
{
"offset": 0,
"limit": 100,
"totalCount": 1,
"unidentifiedTransactions": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentNumber": "Номер платёжного поручения",
"date": "2025-04-08T10:47:17.927Z",
"amount": "10.00",
"purpose": "Назначение платежа",
"payer": {
"inn": "221284672706",
"kpp": "641914992",
"accountNumber": "87149728127096890679",
"name": "Имя плательщика",
"bankAccount": "3932755239052037086628",
"bankBik": "108997635",
"bankName": "Наименования банка плательщика"
}
}
]
}
```
---
## Ошибки
| Код | Описание (error) | error_description / Комментарий |
| :--- | :--- | :--- |
| **400** | `invalid_request` | неверные входные параметры запроса |
| **401** | `invalid_token` | предоставленный токен просрочен, отозван или недействителен |
| **403** | `insufficient_scope` | у пользователя нет прав на использование сервиса (настройки scope) |
| **404** | `unknown_endpoint` | эндпоинт не найден или неактивен |
| **429** | — | Too Many Requests (Нет тела ответа) |
| **500** | `internal_error` | внутренняя ошибка сервиса |
| **503** | — | Service Unavailable (Нет тела ответа) |
]]>
</get_unidentified_transactions_md>
<how_it_works_intro_md>
<![CDATA[
# Как это работает
**Теги:** `H2H`
Депонент (бенефициар) может пополнить номинальный счёт удобным ему способом, после чего владелец номинального счёта должен идентифицировать поступившие денежные средства.
Для этого владельцу счёта необходимо:
1. **Получить информацию обо всех неидентифицированных пополнениях**
- Метод [«Получение списка неидентифицированных пополнений номинального счёта»](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-unidentified-transactions/v1/get-unidentified-transactions)
2. **Создать запрос на идентификацию денежных средств**
- Метод [«Создание запроса на идентификацию пополнения номинального счёта»](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/identify/v1/identify)
3. **Получить статус запроса на идентификацию денежных средств**
- Метод [«Получение статуса запроса на идентификацию пополнения номинального счёта»](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-identify-request-status/v1/get-identify-request-status)
---
### Навигация
- ← [Изменение признаков платёжных реквизитов универсального реципиента](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/change-requisites/v1/change-requisites)
- → [Получение списка неидентифицированных пополнений номинального счёта](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-unidentified-transactions/v1/get-unidentified-transactions)
]]>
</how_it_works_intro_md>
<identify_md>
<![CDATA[
Вот очищенная и структурированная версия документации в формате Markdown:
# Создание запроса на идентификацию пополнения номинального счёта
**Тип интеграции:** H2H
## Эндпоинты
**Песочница:**
`POST https://sandbox.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/identify`
**Пром:**
`POST https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/identify`
---
## Scope
`beneficiary-payments`
## Описание
Метод позволяет создать запрос на идентификацию одной из операций пополнения с помощью распределения суммы по бенефициарам.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | application/json |
| **Content-Type** | string | Да | application/json |
### PATH
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **id** | string | Да | Идентификатор операции пополнения, которую необходимо распределить между бенефициарами |
### BODY
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **transactionId** | string | Да | Идентификатор операции пополнения |
| **accountNumber** | string | Да | Номер номинального счёта |
| **amountDistribution** | array of objects | Да | Распределение денежных средств (список бенефициаров) |
| └─ **beneficiaryId** | string | Да | Идентификатор бенефициара |
| └─ **amount** | string | Да | Сумма пополнения в рублях |
| **digestSignatures** | array of objects | Да | Электронная подпись УЛ клиента |
| └─ **base64Encoded** | string | Да | Значение электронной подписи в Base64 |
| └─ **signatureType** | string | Да | Тип подписи: `rsa` (RSA) или `kep` (КЭП) |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/identify' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accountNumber": "40817810306050000000",
"amountDistribution": [
{
"beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": "10.00"
}
],
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### 202 Accepted (Успешно принято)
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **identifyId** | string | Идентификатор созданного запроса |
| **status** | string | Статус запроса: `PENDING` (в процессе), `VALIDATED` (провалидирован), `FAILED` (ошибка), `COMPLETE` (успешно) |
**Пример ответа 202:**
```json
{
"identifyId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "PENDING"
}
```
### Ошибки
* **400 Bad Request:** `invalid_request` — неверные входные параметры.
* **401 Unauthorized:** `invalid_token` — токен просрочен или недействителен.
* **403 Forbidden:** `insufficient_scope` — нет прав на использование сервиса.
* **404 Not Found:** `unknown_endpoint` — эндпоинт не найден.
* **429 Too Many Requests:** Превышен лимит запросов (тело ответа отсутствует).
* **500 Internal Server Error:** `internal_error` — внутренняя ошибка сервиса.
* **503 Service Unavailable:** Сервис временно недоступен (тело ответа отсутствует).
---
**Навигация:**
* [Предыдущая: Получение списка неидентифицированных пополнений](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-unidentified-transactions/v1/get-unidentified-transactions)
* [Следующая: Получение статуса запроса на идентификацию](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-identify-request-status/v1/get-identify-request-status)
]]>
</identify_md>
<transaction_refund_md>
<![CDATA[
# Создание запроса на возврат неидентифицированного пополнения
**Тип интеграции:** H2H
**Продукт:** Номинальные счета
## Эндпоинты
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/refunds` |
| **Пром** | `POST https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/refunds` |
## Scope
`beneficiary-payments`
## Описание
Метод позволяет создать запрос на возврат неидентифицированного пополнения.
---
## Параметры запроса
### Headers
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
| **Content-Type** | string | required | application/json |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **id** | string | required | Идентификатор операции пополнения, по которой необходимо вернуть денежные средства |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **accountNumber** | string | required | Номер номинального счета |
| **id** | string | required | Идентификатор операции пополнения, по которой необходимо вернуть денежные средства |
| **digestSignatures** | array of objects | required | Электронная подпись УЛ клиента (см. детали ниже) |
#### Детали объекта digestSignatures
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **base64Encoded** | string | required | Значение электронной подписи, закодированное в Base64 |
| **certificateUuid** | string | optional | Идентификатор сертификата, использованного при создании электронной подписи |
| **signatureType** | string | required | Тип электронной подписи. Возможные значения: `rsa` (RSA), `kep` (КЭП) |
| **poaNumber** | string | optional | Номер машиночитаемой доверенности |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions/{id}/refunds' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"accountNumber": "40817810306050000000",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"certificateUuid": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"signatureType": "rsa",
"poaNumber": "DOVER_CBR_7702235133_20211102_1"
}
]
}'
```
---
## Параметры ответа
### 202 (Accepted)
Запрос успешно принят в обработку.
**Пример тела ответа:**
```json
{
"refundId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "PENDING"
}
```
**Описание полей:**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **refundId** | string | required | Уникальный идентификатор запроса на возврат неидентифицированного пополнения |
| **status** | string | required | Статус запроса: `PENDING` (в процессе), `FAILED` (ошибка), `COMPLETE` (успешно) |
---
## Коды ошибок
| Код | Описание | Тело ответа (error) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Превышено количество запросов (нет тела ответа) |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Сервис недоступен (нет тела ответа) |
---
**Следующие шаги:**
* [Получение статуса запроса на возврат неидентифицированного пополнения](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-transaction-refund-request-status/v1/get-transaction-refund-request-status)
* [Получение статуса запроса на идентификацию пополнения](/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-identify-request-status/v1/get-identify-request-status)
]]>
</transaction_refund_md>
</Идентификация_пополнений>
<Контрагенты>
<get_request_status_md>
<![CDATA[
# Получение статуса запроса
**Тип интеграции:** H2H
**Scope:** `beneficiaries`
Метод позволяет получить статус запроса на регистрацию, изменение или проверку контрагента (бенефициара или универсального реципиента) по идентификатору соответствующего запроса.
---
## Эндпоинты
### Песочница
`GET https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/requests/{requestId}/status`
### Пром
`GET https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/requests/{requestId}/status`
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :------------ | :----- | :------------- | :-------------------------------------------------------------------------------------------------------- |
| **requestId** | string | required | Идентификатор запроса, полученный при создании запроса на регистрацию, изменение или проверку контрагента |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/requests/{requestId}/status' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**Пример тела ответа:**
```json
{
"requestId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "COMPLETE",
"beneficiaryId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"universalRecipientId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"description": "Произошла техническая ошибка. Обратитесь в службу поддержки и сообщите код ошибки afc9b019-77ac-49ef-afb9-688b38b74cc2",
"resultData": "Данные субъекта не прошли проверку: N05 PBS0023\nСубъект не прошел скоринг и деактивирован в системе.\n"
}
```
**Описание полей BODY:**
| Атрибут | Тип | Обязательность | Описание |
| :----------------------- | :----- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **requestId** | string | required | Идентификатор запроса |
| **status** | string | required | Статус запроса. Возможные значения:<br>• `PENDING` – запрос в процессе обработки;<br>• `FAILED` – обработка запроса завершилась ошибкой;<br>• `COMPLETE` – обработка запроса завершилась успешно |
| **beneficiaryId** | string | optional | Идентификатор бенефициара. Возвращается при получении статуса запроса на регистрацию бенефициара |
| **universalRecipientId** | string | optional | Идентификатор универсального реципиента. Возвращается при получении статуса запроса на регистрацию универсального реципиента |
| **description** | string | optional | Описание причины, по которой запрос завершился неудачей. Возвращается, если статус запроса равен `FAILED` |
| **resultData** | string | optional | Результаты прохождения проверки. Возвращается при получении статуса запроса на проверку бенефициара |
---
## Ошибки
| Код | Описание | Ошибка (`error`) | Детали |
| :------ | :-------------------- | :------------------- | :--------------------------------------------------- |
| **400** | Bad Request | `invalid_request` | Неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` | Токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` | Нет прав на использование сервиса (настройки scope) |
| **404** | Not Found | `unknown_endpoint` | Эндпоинт не найден или неактивен |
| **429** | Too Many Requests | — | Превышен лимит запросов (тело ответа отсутствует) |
| **500** | Internal Server Error | `internal_error` | Внутренняя ошибка сервиса |
| **503** | Service Unavailable | — | Сервис временно недоступен (тело ответа отсутствует) |
---
**Навигация:**
- [← Как это работает](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/intro/intro)
- [Создание запроса на регистрацию бенефициара →](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-beneficiary/v1/add-beneficiary)
]]>
</get_request_status_md>
<intro_md>
<![CDATA[
Вот преобразованный текст из HTML-файла в формат Markdown. Я сохранил структуру, иерархию заголовков, важные примечания и все ссылки.
---
# Как это работает
При проведении расчётов через номинальные счета необходимо обмениваться информацией о контрагентах: бенефициарах и универсальных реципиентах. Для этого необходимо предварительно зарегистрировать контрагентов и их платёжные реквизиты.
## Регистрация контрагентов и платёжных реквизитов
Перед проведением расчётов через номинальные счета пройдите следующие шаги:
### 1. Зарегистрируйте контрагентов
**Бенефициары**
До совершения расчётов с участием бенефициара необходимо предоставить в Банк сведения о бенефициаре и зарегистрировать его в системе.
Каждому бенефициару в рамках номинального счёта будет присвоен уникальный идентификатор — `beneficiaryId`.
Для этого используются методы:
* [«Создание запроса на регистрацию бенефициара»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-beneficiary/v1/add-beneficiary)
* [«Получение статуса запроса»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status)
**Универсальные реципиенты**
При осуществлении переводов с номинального счёта, помимо бенефициаров, получателем денежных средств может быть универсальный реципиент. Для участия универсального реципиента в сделке его также необходимо зарегистрировать.
Каждому универсальному реципиенту в рамках номинального счёта будет присвоен уникальный идентификатор — `universalRecipientId`.
Для этого используются методы:
* [«Создание запроса на регистрацию универсального реципиента»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/add-ur/v1/add-ur)
* [«Получение статуса запроса»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status)
### 2. Зарегистрируйте платёжные реквизиты контрагентов
После регистрации бенефициара или универсального реципиента необходимо указать платёжные реквизиты, на которые он будет получать денежные средства.
Для этого используются методы:
* [«Добавление платёжных реквизитов бенефициара»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-requisites/v1/add-requisites)
* [«Добавление платёжных реквизитов универсального реципиента»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/add-requisites/v1/add-requisites)
---
## Изменение информации о бенефициаре
Изменить данные о бенефициаре можно с помощью методов:
* [«Создание запроса на изменение информации о бенефициаре»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/change-beneficiary/v1/change-beneficiary)
* [«Получение статуса запроса»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status)
В случае, если бенефициар больше не является участником расчётов и на его виртуальных счетах не осталось денежных средств, необходимо направить запрос на деактивацию бенефициара. Если в дальнейшем на номинальный счёт деактивированного бенефициара снова поступят денежные средства, его необходимо будет активировать.
## Проверка актуальности данных бенефициара
Проверить актуальность ранее зарегистрированных данных о бенефициаре можно с помощью методов:
* [«Создание запроса на проверку бенефициара»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/beneficiary-scoring/v1/beneficiary-scoring)
* [«Получение статуса запроса»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status)
## Изменение признаков платёжных реквизитов контрагентов
Изменить признаки платёжных реквизитов контрагентов можно с помощью методов:
* [«Изменение признаков платёжных реквизитов бенефициара»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/change-requisites/v1/change-requisites)
* [«Изменение признаков платёжных реквизитов универсального реципиента»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/change-requisites/v1/change-requisites)
---
## Учёт денежных средств бенефициара
> **Важно**
> Биллинг для универсальных реципиентов не проводится, поскольку они не являются бенефициарами и не могут иметь собственных средств на номинальном счёте.
> **Внимание**
> Учёт денежных средств на виртуальных счетах бенефициаров будет вестись корректно только при условии, что владелец номинального счёта не использует другие каналы вывода средств (банк-клиент, бумажные поручения и др.).
Для учёта денежных средств бенефициара — биллинга на стороне Банка — используются **виртуальные счета**.
При регистрации бенефициара по умолчанию создается **основной виртуальный счёт**. На нём учитываются денежные средства, права на которые принадлежат бенефициару. В случае необходимости уплаты налога (при [добавлении бенефициара в качестве реципиента в этап сделки](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/step-contractors/v1/step-contractors)) дополнительно создаётся **налоговый виртуальный счёт**.
Виртуальный счёт состоит из доступных и захолдированных денежных средств:
* **Доступные денежные средства** не обременены обязательствами, их можно использовать при проведении расчётов или вывести с номинального счёта.
* **Захолдированные денежные средства** — деньги, которые уже участвуют в незавершенной сделке, их нельзя использовать для других целей или вывести.
### Информация о балансе и операциях бенефициара
* Узнать балансы по виртуальным счетам можно с помощью метода [«Получение информации о балансе бенефициара»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-balance/v1/get-balance).
* Получить список денежных операций бенефициара можно с помощью метода [«Получение списка денежных операций бенефициара»](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-transactions/v1/get-transactions).
]]>
</intro_md>
<Бенефициары>
<add_beneficiary_md>
<![CDATA[
# Создание запроса на регистрацию бенефициара
**H2H**
### Эндпоинты
| Среда | Метод и URL |
| :------------ | :------------------------------------------------------------ |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries` |
| **Пром** | `POST https://baas.alfabank.ru/api/na/jp/v1/beneficiaries` |
### Scope
`beneficiaries`
### Описание
Метод позволяет зарегистрировать бенефициара (контрагента с признаком `isBeneficiary = TRUE`) в системе.
> **Важно**
> В зависимости от типа бенефициара необходимо по-разному заполнять поля запроса.
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
| **Content-Type** | string | required | application/json |
#### BODY
| Атрибут | Тип | Обязательность | Описание |
| :------------------------ | :------ | :------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| **accountNumber** | string | required | Номер номинального счёта |
| **type** | string | required | Тип бенефициара. Возможные значения: `FL_RESIDENT`, `FL_NONRESIDENT`, `UL_RESIDENT`, `UL_NONRESIDENT`, `IP_RESIDENT`, `IP_NONRESIDENT` |
| **taxResidentUS** | boolean | required | Признак налогового резидента США |
| **foreignTaxResident** | boolean | required | Признак иностранного налогового резидента |
| **financialActivities** | boolean | optional | Признак осуществления финансовой деятельности. Обязательно для `UL_RESIDENT` и `UL_NONRESIDENT` |
| **countryOfTaxResidence** | string | required | Страна налогового резидентства (ISO 3166-1 alpha-2) |
| **name** | string | optional | Наименование организации. Обязательно для `UL_RESIDENT` и `UL_NONRESIDENT` |
| **registrationDate** | string | optional | Дата регистрации. Обязательно для `UL_RESIDENT` и `UL_NONRESIDENT` |
| **inn** | string | optional | ИНН. Обязательно для `UL_RESIDENT` и `UL_NONRESIDENT`. Для ФЛ/ИП указывается в `personalInformation` |
| **kpp** | string | optional | КПП. Обязательно для `UL_RESIDENT` |
| **ogrn** | string | optional | ОГРН. Обязательно для `UL_RESIDENT` |
| **personalInformation** | object | optional | Персональные данные. Заполняется только для ФЛ и ИП |
| **phoneNumber** | string | optional | Телефон |
| **email** | string | optional | Адрес электронной почты |
| **addresses** | array | required | Список адресов бенефициара |
| **documents** | array | optional | Документы (подробнее ниже) |
| **digestSignatures** | array | required | Электронная подпись УЛ клиента |
---
### Детальное описание объектов
#### personalInformation (для ФЛ и ИП)
| Атрибут | Тип | Описание |
| :-------------- | :----- | :------------------------------------------------ |
| **inn** | string | ИНН. Обязательно для резидентов и нерезидентов ИП |
| **firstName** | string | Имя |
| **middleName** | string | Отчество (optional) |
| **lastName** | string | Фамилия |
| **citizenship** | string | Гражданство: `RU`, `BY`, `AM`, `KZ`, `KG` |
| **birthDate** | string | Дата рождения |
| **birthPlace** | string | Место рождения |
| **snils** | string | СНИЛС. Обязательно для резидентов |
#### addresses
| Атрибут | Тип | Описание |
| :---------- | :----- | :------------------------------------------------------------------ |
| **type** | string | `REGISTRATION_ADDRESS`, `RESIDENCE_ADDRESS`, `LEGAL_ENTITY_ADDRESS` |
| **address** | string | Текстовый адрес |
| **country** | string | Код страны (ISO 3166-1 alpha-2) |
#### documents
_Для резидентов обязателен `PASSPORT`. Для граждан РБ — `FOREIGN_PASSPORT`. Для остальных нерезидентов — не менее 2 документов._
| Атрибут | Тип | Описание |
| :--------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **type** | string | `PASSPORT`, `FOREIGN_PASSPORT`, `RESIDENCE_PERMIT`, `STATELESS_RESIDENCE_CERTIFICATE`, `TEMPORARY_RESIDENCE_PERMIT`, `MIGRATION_CARD` |
| **serial** | string | Серия (optional) |
| **number** | string | Номер |
| **issueDate** | string | Дата выдачи |
| **expireDate** | string | Дата истечения (optional) |
| **division** | string | Код подразделения (optional) |
| **organization** | string | Орган, выдавший документ |
---
### Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"accountNumber": "40817810306050000000",
"type": "FL_RESIDENT",
"taxResidentUS": false,
"foreignTaxResident": false,
"financialActivities": false,
"countryOfTaxResidence": "RU",
"name": "Акционерное общество «Ромашка»",
"registrationDate": "2025-12-18",
"inn": "0123456789",
"kpp": "0123456789",
"ogrn": "0123456789101",
"personalInformation": {
"inn": "112233445566",
"firstName": "Иван",
"middleName": "Иванoвич",
"lastName": "Иванов",
"citizenship": "RU",
"birthDate": "2000-03-02",
"birthPlace": "Г. Иркутск",
"snils": "12345678910"
},
"phoneNumber": "79130000011",
"email": "IvanovIvan@mail.ru",
"addresses": [
{
"type": "REGISTRATION_ADDRESS",
"address": "ул. Максима Горького 55",
"country": "RU"
}
],
"documents": [
{
"type": "PASSPORT",
"serial": "6953",
"number": "987435",
"issueDate": "2022-03-02",
"expireDate": "2022-03-02",
"division": "123-321",
"organization": "ОВД Иркутской области по Г. Иркутску по Октябрьскому району"
}
],
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
### Параметры ответа
#### 202 Accepted
Запрос принят в обработку.
| Атрибут | Тип | Описание |
| :------------ | :----- | :---------------------------------------------------------------------- |
| **requestId** | string | Идентификатор запроса |
| **status** | string | Статус: `PENDING` (в процессе), `FAILED` (ошибка), `COMPLETE` (успешно) |
**Пример ответа 202:**
```json
{
"requestId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "COMPLETE"
}
```
#### Коды ошибок
- **400 Bad Request**: `invalid_request` — неверные параметры.
- **401 Unauthorized**: `invalid_token` — токен недействителен.
- **403 Forbidden**: `insufficient_scope` — нет прав доступа (недостаточный scope).
- **404 Not Found**: `unknown_endpoint` — эндпоинт не найден.
- **429 Too Many Requests**: Превышен лимит запросов.
- **500 Internal Server Error**: `internal_error` — внутренняя ошибка сервера.
- **503 Service Unavailable**: Сервис временно недоступен.
]]>
</add_beneficiary_md>
<add_requisites_md>
<![CDATA[
# Добавление платёжных реквизитов бенефициара
tags: `H2H`
## Эндпоинты
| Среда | Метод и URL |
| :------------ | :--------------------------------------------------------------------------------------- |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites` |
| **Пром** | `POST https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites` |
## Scope
`beneficiaries`
## Описание
Метод позволяет добавить платёжные реквизиты бенефициара по `beneficiaryId`.
> **Важно**
> Первые добавленные реквизиты автоматически назначаются основными для бенефициара.
---
## Параметры запроса
### Headers
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :----- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | `application/json` |
| **Content-Type** | string | Да | `application/json` |
### Path
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :----- | :---- | :------------------------ |
| **beneficiaryId** | string | Да | Идентификатор бенефициара |
### Body
| Атрибут | Тип | Обяз. | Описание |
| :------------------- | :------ | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **beneficiaryId** | string | Нет | Идентификатор бенефициара |
| **type** | string | Да | Тип платёжного реквизита. Возможные значения:<br>• `ACCOUNT` — реквизиты счёта;<br>• `CARD` — номер карты (токен);<br>• `PHONE` — номер телефона |
| **pan** | string | Нет | Токен номера карты. Поле обязательно при типе `CARD`. [Как сформировать токен](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken) |
| **phoneNumber** | string | Нет | Номер телефона. Поле обязательно при типе `PHONE` |
| **bankId** | string | Нет | Идентификатор банка контрагента-получателя. Поле обязательно при типе `PHONE` |
| **accountNumber** | string | Нет | Номер счёта. Поле обязательно при типе `ACCOUNT` |
| **bik** | string | Нет | БИК банка. Поле обязательно при типе `ACCOUNT` |
| **name** | string | Нет | Тип контрагента |
| **inn** | string | Нет | ИНН организации или физического лица |
| **kpp** | string | Нет | КПП организации (только для юридических лиц) |
| **isMain** | boolean | Нет | Признак основных реквизитов. По умолчанию для первых — `true`, для следующих — `false` |
| **digestSignatures** | array | Да | Электронная подпись УЛ клиента (список объектов) |
| └ **base64Encoded** | string | Да | Значение электронной подписи в Base64 |
| └ **signatureType** | string | Да | Тип подписи: `rsa` или `kep` |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"beneficiaryId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"type": "ACCOUNT",
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"name": "ООО Ромашка",
"inn": "1234567890",
"kpp": "123456789",
"isMain": true,
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Обяз. | Описание |
| :----------- | :------ | :---- | :-------------------------------------------- |
| **id** | string | Да | Идентификатор платёжного реквизита |
| **isMain** | boolean | Да | Признак основного реквизита (`true`/`false`) |
| **isActive** | boolean | Да | Признак активности реквизита (`true`/`false`) |
**Пример ответа:**
```json
{
"id": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"isMain": true,
"isActive": true
}
```
---
## Ошибки
| Код | Описание | Тело ответа (error) |
| :------ | :------------------ | :------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
← [Создание запроса на проверку бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/beneficiary-scoring/v1/beneficiary-scoring) | [Получение платёжных реквизитов бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-requisites/v1/get-requisites) →
]]>
</add_requisites_md>
<beneficiary_scoring_md>
<![CDATA[
# Создание запроса на проверку бенефициара
**Метка:** `H2H`
## Эндпоинты
| Окружение | Метод и URL |
| :------------ | :------------------------------------------------------------------------------------ |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/scoring` |
| **Пром** | `POST https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/scoring` |
## Scope
`beneficiaries`
## Описание
Метод позволяет проверить актуальность данных бенефициара по `beneficiaryId`.
> **Важно**
> Если бенефициар не пройдет проверку, он будет деактивирован в системе.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | `string` | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` | required | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :------- | :------------- | :------------------------ |
| **beneficiaryId** | `string` | required | Идентификатор бенефициара |
### Пример запроса (cURL)
```bash
curl --location --globoff --request POST 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/scoring' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 202 (Accepted)
Успешное принятие запроса в обработку.
**BODY**
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **requestId** | `string` | required | Идентификатор запроса |
| **status** | `string` | required | Статус запроса. Возможные значения:<br>• `PENDING` – запрос в процессе обработки;<br>• `FAILED` – обработка запроса завершилась ошибкой;<br>• `COMPLETE` – обработка запроса завершилась успешно |
**Пример ответа:**
```json
{
"requestId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "COMPLETE"
}
```
---
## Ошибки
| Код | Описание | Тело ответа (error) |
| :------ | :------------------ | :------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные параметры |
| **401** | Unauthorized | `invalid_token` — токен недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав (scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
## Навигация
- **Предыдущий метод:** [Создание запроса на изменение информации о бенефициаре](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/change-beneficiary/v1/change-beneficiary)
- **Следующий метод:** [Добавление платёжных реквизитов бенефициара](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-requisites/v1/add-requisites)
]]>
</beneficiary_scoring_md>
<change_beneficiary_md>
<![CDATA[
# Создание запроса на изменение информации о бенефициаре
**H2H**
## Эндпоинты
| Окружение | Метод и URL |
| :------------ | :--------------------------------------------------------------------------- |
| **Песочница** | `PUT https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}` |
| **Пром** | `PUT https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}` |
### Scope
`beneficiaries`
### Описание
Метод позволяет изменить информацию о бенефициаре по `beneficiaryId`.
---
## Параметры запроса
### HEADERS
| Атрибут | Описание |
| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** <br/>_string, required_ | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** <br/>_string, required_ | `application/json` |
| **Content-Type** <br/>_string, required_ | `application/json` |
### PATH
| Атрибут | Описание |
| :---------------------------------------- | :------------------------ |
| **beneficiaryId** <br/>_string, required_ | Идентификатор бенефициара |
### BODY
| Атрибут | Тип | Описание |
| :---------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type** | _string, required_ | Тип контрагента. Возможные значения: <ul><li>`FL_RESIDENT` — физ. лицо, резидент;</li><li>`UL_RESIDENT` — юр. лицо, резидент.</li></ul> |
| **name** | _string, optional_ | Наименование организации. Поле обязательно для бенефициаров с типом `UL_RESIDENT`. |
| **registrationDate** | _string, optional_ | Дата регистрации. Поле обязательно для бенефициаров с типом `UL_RESIDENT`. |
| **personalInformation** | _object, optional_ | Обновленные персональные данные. Заполняется для бенефициаров с типом `FL_RESIDENT`. |
| ∟ **firstName** | _string, optional_ | Имя |
| ∟ **middleName** | _string, optional_ | Отчество |
| ∟ **lastName** | _string, optional_ | Фамилия |
| ∟ **birthDate** | _string, optional_ | Дата рождения |
| ∟ **birthPlace** | _string, optional_ | Место рождения |
| **phoneNumber** | _string, optional_ | Телефон |
| **email** | _string, optional_ | Адрес электронной почты |
| **addresses** | _array of objects, optional_ | Адрес бенефициара |
| ∟ **type** | _string, required_ | Тип адреса: `REGISTRATION_ADDRESS` (адрес регистрации) или `LEGAL_ENTITY_ADDRESS` (адрес юр. лица). |
| ∟ **address** | _string, required_ | Строка адреса |
| **documents** | _array of objects, optional_ | Документы. Заполняется, если `citizenship` равен `RU`. |
| ∟ **type** | _string, required_ | Тип документа: `PASSPORT`, `FOREIGN_PASSPORT`, `RESIDENCE_PERMIT`, `STATELESS_RESIDENCE_CERTIFICATE`, `TEMPORARY_RESIDENCE_PERMIT`, `MIGRATION_CARD`. |
| ∟ **serial** | _string, required_ | Серия документа |
| ∟ **number** | _string, required_ | Номер документа |
| ∟ **issueDate** | _string, required_ | Дата выдачи |
| ∟ **division** | _string, required_ | Код подразделения |
| ∟ **organization** | _string, required_ | Орган, выдавший документ |
| **isActive** | _boolean, optional_ | Статус активности бенефициара |
| **digestSignatures** | _array of objects, required_ | Электронная подпись УЛ клиента |
| ∟ **base64Encoded** | _string, required_ | Значение электронной подписи в Base64 |
| ∟ **signatureType** | _string, required_ | Тип подписи: `rsa` или `kep`. |
---
## Пример запроса (cURL)
```bash
curl --location --globoff --request PUT 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"type": "FL_RESIDENT",
"name": "Акционерное общество «Ромашка»",
"registrationDate": "2025-12-23",
"personalInformation": {
"firstName": "Иван",
"middleName": "Иванoвич",
"lastName": "Иванов",
"birthDate": "2000-03-02",
"birthPlace": "Г. Иркутск"
},
"phoneNumber": "79130000011",
"email": "IvanovIvan@mail.ru",
"addresses": [
{
"type": "REGISTRATION_ADDRESS",
"address": "ул. Максима Горького 55"
}
],
"documents": [
{
"type": "PASSPORT",
"serial": "6953",
"number": "987435",
"issueDate": "2022-03-02",
"division": "123-321",
"organization": "ОВД Иркутской области по Г. Иркутску по Октябрьскому району"
}
],
"isActive": true,
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### Успешный ответ (202 Accepted)
```json
{
"requestId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "COMPLETE"
}
```
| Атрибут | Тип | Описание |
| :------------ | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| **requestId** | _string, required_ | Идентификатор запроса |
| **status** | _string, required_ | Статус запроса: <ul><li>`PENDING` — в процессе обработки;</li><li>`FAILED` — ошибка обработки;</li><li>`COMPLETE` — успешно завершено.</li></ul> |
### Коды ошибок
| Код | Описание | Тело ответа (основные атрибуты) |
| :------ | :------------------ | :------------------------------ |
| **400** | Bad Request | `error`: `invalid_request` |
| **401** | Unauthorized | `error`: `invalid_token` |
| **403** | Forbidden | `error`: `insufficient_scope` |
| **404** | Not Found | `error`: `unknown_endpoint` |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `error`: `internal_error` |
| **503** | Service Unavailable | Нет тела ответа |
---
### Навигация
- [← Получение информации о бенефициаре](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-beneficiary/v1/get-beneficiary)
- [Создание запроса на проверку бенефициара →](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/beneficiary-scoring/v1/beneficiary-scoring)
]]>
</change_beneficiary_md>
<change_requisites_md>
<![CDATA[
# Изменение признаков платёжных реквизитов бенефициара
**H2H**
### Эндпоинты
**Песочница**
`PATCH https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites/{requisiteId}`
**Пром**
`PATCH https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites/{requisiteId}`
---
### Scope
`beneficiaries`
### Описание
Метод позволяет изменить признаки платёжных реквизитов бенефициара по `beneficiaryId` и `requisiteId`.
> **Важно**
> Необходимо, чтобы хотя бы один из активных реквизитов бенефициара был основным.
---
### Параметры запроса
#### HEADERS
| Атрибут | Тип | Описание |
| :---------------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string (required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Content-Type** | string (required) | application/json |
#### PATH
| Атрибут | Тип | Описание |
| :---------------- | :---------------- | :--------------------------------- |
| **beneficiaryId** | string (required) | Идентификатор бенефициара |
| **requisiteId** | string (required) | Идентификатор платёжного реквизита |
#### BODY
| Атрибут | Тип | Описание |
| :------------------- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **pan** | string (optional) | Токен номера карты контрагента. [Как сформировать токен номера карты](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken) |
| **keyId** | string (optional) | Идентификатор публичного ключа для расшифровки токена номера карты |
| **phoneNumber** | string (optional) | Номер телефона контрагента |
| **bankId** | string (optional) | Идентификатор банка контрагента |
| **accountNumber** | string (optional) | Номер счёта контрагента |
| **bik** | string (optional) | БИК банка контрагента |
| **isMain** | boolean (optional) | Признак основного платёжного реквизита. <br> • `true` - основной; <br> • `false` - неосновной |
| **isActive** | boolean (optional) | Признак активности платёжного реквизита. <br> • `true` - активен; <br> • `false` - деактивирован |
| **digestSignatures** | array of objects (required) | Электронная подпись УЛ клиента |
**Объект digestSignatures:**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **base64Encoded** | string (required) | Значение электронной подписи, закодированное в Base64 |
| **signatureType** | string (required) | Тип электронной подписи: <br> • `rsa` - RSA; <br> • `kep` - КЭП |
---
### Пример запроса (cURL)
```bash
curl --location --globoff --request PATCH 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites/{requisiteId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"keyId": "1",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"isMain": true,
"isActive": true,
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
### Параметры ответа
**204 No Content**
_Нет тела ответа_
**400 Bad Request**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | string (required) | `invalid_request` — неверные входные параметры запроса |
| **error_description** | string (optional) | Описание ошибки |
**401 Unauthorized**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | string (required) | `invalid_token` — токен просрочен, отозван или недействителен |
**403 Forbidden**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | string (required) | `insufficient_scope` — у пользователя нет прав на использование сервиса |
**404 Not Found**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | string (required) | `unknown_endpoint` — эндпоинт не найден или неактивен |
**429 Too Many Requests**
_Превышен лимит запросов. Нет тела ответа._
**500 Internal Server Error**
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **error** | string (required) | `internal_error` — внутренняя ошибка сервиса |
**503 Service Unavailable**
_Сервис временно недоступен._
---
**Навигация:**
- Предыдущая статья: [Получение платёжных реквизитов бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-requisites/v1/get-requisites)
- Следующая статья: [Получение информации о балансе бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-balance/v1/get-balance)
]]>
</change_requisites_md>
<get_balance_md>
<![CDATA[
# Получение информации о балансе бенефициара
**Метка:** `H2H`
## Эндпоинты
### Песочница
`GET https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/balance`
### Пром
`GET https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/balance`
---
## Scope
`beneficiaries`
## Описание
Метод позволяет получить баланс счёта бенефициара по `beneficiaryId` на определённую дату.
---
## Параметры запроса
### HEADERS
| Атрибут | Описание | Тип | Обязательность |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | :------------- |
| **Authorization** | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) | string | required |
| **Accept** | application/json | string | required |
### QUERY
| Атрибут | Описание | Тип | Обязательность |
| :---------------- | :----------------------- | :----- | :------------- |
| **accountNumber** | Номер номинального счёта | string | required |
| **date** | Дата | string | required |
### PATH
| Атрибут | Описание | Тип | Обязательность |
| :---------------- | :------------------------ | :----- | :------------- |
| **beneficiaryId** | Идентификатор бенефициара | string | required |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/balance?accountNumber=40817810306050000000&date=2024-01-01' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 (OK) — Тело ответа (BODY)
| Атрибут | Описание | Тип | Обязательность |
| :---------------- | :------------------------ | :--------------- | :------------- |
| **beneficiaryId** | Идентификатор бенефициара | string | required |
| **accountNumber** | Номер счёта | string | required |
| **date** | Дата | string | required |
| **balances** | Балансы бенефициара | array of objects | optional |
#### Вложенные атрибуты `balances`:
- **walletType** (string, optional): Тип кошелька. Принимает значения:
- `MAIN` — основной кошелек;
- `TAX` — налоговый кошелек.
- **freeBalance** (string, optional): Свободные денежные средства в рублях.
- **heldBalance** (string, optional): Захолдированные денежные средства в рублях.
#### Пример ответа 200:
```json
{
"beneficiaryId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"accountNumber": "40817810306050000000",
"date": "2024-01-01",
"balances": [
{
"walletType": "MAIN",
"freeBalance": "10.00",
"heldBalance": "10.00"
}
]
}
```
---
## Ошибки
### 400 (Bad Request)
- **error** (string): `invalid_request` — неверные входные параметры запроса.
- **error_description** (string, optional): Описание ошибки.
### 401 (Unauthorized)
- **error** (string): `invalid_token` — предоставленный токен просрочен, отозван или недействителен.
- **error_description** (string, optional): Описание ошибки.
### 403 (Forbidden)
- **error** (string): `insufficient_scope` — у пользователя нет прав на использование запрашиваемого сервиса.
- **error_description** (string, optional): Описание ошибки.
### 404 (Not Found)
- **error** (string): `unknown_endpoint` — эндпоинт не найден или неактивен.
- **error_description** (string, optional): Описание ошибки.
### 429 (Too Many Requests)
- Тело ответа отсутствует.
### 500 (Internal Server Error)
- **error** (string): `internal_error` — внутренняя ошибка сервиса.
- **error_description** (string, optional): Описание ошибки.
### 503 (Service Unavailable)
- Тело ответа отсутствует.
---
**Навигация:**
- Предыдущий метод: [Изменение признаков платёжных реквизитов бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/change-requisites/v1/change-requisites)
- Следующий метод: [Получение списка денежных операций бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-transactions/v1/get-transactions)
]]>
</get_balance_md>
<get_beneficiaries_md>
<![CDATA[
Вот обновленное, максимально полное и структурированное описание API в формате Markdown. Я добавил детали из всех скриншотов, расширил описание ошибок и структурировал данные для лучшей читаемости.
---
# Получение списка бенефициаров номинального счёта
**Тип интеграции:** H2H (Host-to-Host)
**Раздел:** [Номинальные счета](#) / Получение списка бенефициаров номинального счёта
## 1. Общая информация
Метод позволяет получить подробный список всех бенефициаров, привязанных к конкретному номинальному счёту, с возможностью фильтрации и пагинации.
### Конечные точки (Endpoints)
| Среда | Метод | URL |
| :--- | :--- | :--- |
| **Песочница** | `GET` | `https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries` |
| **Пром** | `GET` | `https://baas.alfabank.ru/api/na/jp/v1/beneficiaries` |
**Требуемый Scope:** `beneficiaries`
---
## 2. Параметры запроса
### Заголовки (Headers)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | `STRING` | Да | `Bearer {access_token}`, полученный по схеме Authorization Code Flow H2H. |
| **Accept** | `STRING` | Да | Должен быть `application/json`. |
### Параметры строки запроса (Query)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **accountNumber** | `STRING` | **Да** | Номер номинального счёта (20 знаков). |
| **type** | `STRING` | **Да** | Тип бенефициара: `FL_RESIDENT`, `FL_NONRESIDENT`, `UL_RESIDENT`, `UL_NONRESIDENT`, `IP_RESIDENT`, `IP_NONRESIDENT`. |
| **limit** | `INTEGER` | Нет | Кол-во объектов на странице (по умолчанию обычно 100). |
| **offset** | `INTEGER` | Нет | Смещение (кол-во пропускаемых объектов). |
| **inn** | `STRING` | Нет | ИНН (10 цифр для ЮЛ, 12 — для ФЛ/ИП). |
| **lastName** | `STRING` | Нет | Фамилия (для ФЛ и ИП). |
| **firstName** | `STRING` | Нет | Имя (для ФЛ и ИП). |
| **middleName** | `STRING` | Нет | Отчество (для ФЛ и ИП). |
| **kpp** | `STRING` | Нет | КПП (только для `UL_RESIDENT`). |
| **name** | `STRING` | Нет | Название организации (для ЮЛ). |
| **ogrn** | `STRING` | Нет | ОГРН (только для `UL_RESIDENT`). |
| **isVpr** | `BOOLEAN` | Нет | `true` — является выгодоприобретателем, `false` — нет. |
| **isActive** | `BOOLEAN` | Нет | Статус: `true` — активен, `false` — деактивирован. |
| **date** | `STRING` | Нет | Дата выборки. |
**Пример вызова (cURL):**
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries?accountNumber=40817810306050000000&type=FL_RESIDENT' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## 3. Параметры ответа (200 OK)
В случае успеха возвращается объект со списком бенефициаров и данными пагинации.
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **pagination** | `OBJECT` | Информация о страницах: `limit`, `offset`, `totalCount`. |
| **accountNumber**| `STRING` | Номер счёта, по которому сделан запрос. |
| **beneficiaries** | `ARRAY` | Массив объектов бенефициаров (включает ФИО, ИНН, адреса, документы и балансы). |
---
## 4. Обработка ошибок
Ниже приведен полный перечень возможных ошибок с описанием их причин.
### Сводная таблица кодов
| Код | Описание | Тело ответа |
| :--- | :--- | :--- |
| **400** | Bad Request | Ошибка в параметрах запроса. |
| **401** | Unauthorized | Проблемы с токеном доступа. |
| **403** | Forbidden | Недостаточно прав (Scope). |
| **404** | Not Found | Ресурс или эндпоинт не найден. |
| **429** | Too Many Requests | Превышен лимит запросов (без тела). |
| **500** | Internal Server Error | Внутренняя ошибка сервера. |
| **503** | Service Unavailable | Сервис временно недоступен (без тела). |
---
### Детальное описание бизнес-ошибок
#### 400 Bad Request
Возникает при передаче невалидных данных (например, неверный формат номера счета).
* `error`: `invalid_request`
* `error_description`: Описание конкретной ошибки валидации.
#### 401 Unauthorized
Проблема с авторизационным заголовком или самим токеном.
* `error`: `invalid_token`
* `error_description`: Предоставленный токен просрочен, отозван, имеет неправильный формат или недействителен.
#### 403 Forbidden
Доступ к методу ограничен настройками безопасности.
* `error`: `insufficient_scope`
* `error_description`: У пользователя нет прав на использование сервиса (отсутствует нужный scope в токене).
#### 404 Not Found
Запрашиваемый адрес API не существует или отключен.
* `error`: `unknown_endpoint`
* `error_description`: Эндпоинт не найден или неактивен.
#### 500 Internal Server Error
Непредвиденная ошибка на стороне банка.
* `error`: `internal_error`
* `error_description`: Внутренняя ошибка сервиса при выполнении обработки запроса.
---
## 5. Навигация
← [Создание запроса на регистрацию бенефициара](#) | [Получение информации о бенефициаре](#) →
]]>
</get_beneficiaries_md>
<get_beneficiary_md>
<![CDATA[
Вот преобразованная документация в формате Markdown. Я сохранил структуру, таблицы параметров, примеры кода и ссылки.
---
# Получение информации о бенефициаре `H2H`
Метод позволяет получить информацию о бенефициаре по `beneficiaryId`.
## Эндпоинты
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}` |
## Scope
`beneficiaries`
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | application/json |
### PATH
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **beneficiaryId** | string | Да | Идентификатор бенефициара |
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
#### Пример тела ответа
```json
{
"beneficiaryId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"type": "FL_RESIDENT",
"personalInformation": {
"inn": "112233445566",
"firstName": "Иван",
"middleName": "Иванoвич",
"lastName": "Иванов",
"citizenship": "RU",
"birthDate": "2000-03-02",
"birthPlace": "Г. Иркутск",
"snils": 12345678910
},
"countryOfTaxResidence": "RU",
"phoneNumber": "79130000011",
"email": "IvanovIvan@mail.ru",
"addresses": [
{
"type": "REGISTRATION_ADDRESS",
"address": "ул. Пушкина 55",
"index": "123456",
"region_code": "77",
"uin": "550e8400-e29b-41d4-a716-446655440000",
"municipal_district": {
"type_code": 1,
"name": "Ленинский муниципальный район"
},
"settlement": {
"type_code": 1,
"name": "Городское поселение Ленинское"
},
"locality": {
"type": "город",
"name": "Ленинск"
},
"planning_structure": {
"type": "микрорайон",
"name": "Центральный"
},
"street_network": {
"type": "улица",
"name": "Ленина"
},
"buildings": [
{
"type": "дом",
"name": "3"
}
],
"building_premises": {
"type": "квартира",
"name": "42"
},
"flat_premises": {
"type": "комната",
"name": "гостиная"
}
}
],
"documents": [
{
"type": "PASSPORT",
"serial": "6953",
"number": "987435",
"issueDate": "2022-03-02",
"expireDate": "2022-03-02",
"division": "123-321",
"organization": "ОВД Иркутской области по Г. Иркутску по Октябрьскому району"
}
],
"name": "Акционерное общество «Ромашка»",
"registrationDate": "2025-12-18",
"inn": "0123456789",
"kpp": "0123456789",
"ogrn": "0123456789101",
"isActive": true,
"actualizationDateExpire": "2025-12-18",
"balances": [
{
"walletType": "MAIN",
"freeBalance": "10.00",
"heldBalance": "10.00"
}
],
"isBeneficiary": true,
"isVpr": true
}
```
#### Описание полей (BODY)
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **beneficiaryId** | string | Идентификатор бенефициара |
| **type** | string | Тип контрагента: `FL_RESIDENT`, `FL_NONRESIDENT`, `UL_RESIDENT`, `UL_NONRESIDENT`, `IP_RESIDENT`, `IP_NONRESIDENT` |
| **personalInformation** | object | Персональные данные (только для ФЛ и ИП) |
| ∟ **inn** | string | ИНН |
| ∟ **firstName** | string | Имя |
| ∟ **lastName** | string | Фамилия |
| ∟ **citizenship** | string | Гражданство: `RU`, `BY`, `AM`, `KZ`, `KG` |
| **countryOfTaxResidence**| string | Страна налогового резидентства (ISO 3166-1 alpha-2) |
| **addresses** | array | Список адресов |
| ∟ **type** | string | `REGISTRATION_ADDRESS`, `RESIDENCE_ADDRESS`, `LEGAL_ENTITY_ADDRESS` |
| **documents** | array | Список документов (Для резидентов обязателен `PASSPORT`) |
| **name** | string | Наименование организации (для UL) |
| **isActive** | boolean | Статус активности бенефициара (`true`/`false`) |
| **balances** | array | Балансы бенефициара |
| ∟ **walletType** | string | Тип кошелька: `MAIN` (основной), `TAX` (налоговый) |
| **isBeneficiary** | boolean | `true` — бенефициар, `false` — универсальный реципиент |
| **isVpr** | boolean | Признак выгодоприобретателя (ВПР) |
---
## Ошибки
| Код | Описание | Возможные причины (`error`) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав (проверьте scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Превышен лимит запросов (нет тела ответа) |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Сервис временно недоступен |
---
**Навигация:**
* [← Получение списка бенефициаров номинального счёта](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-beneficiaries/v1/get-beneficiaries)
* [Создание запроса на изменение информации о бенефициаре →](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/change-beneficiary/v1/change-beneficiary)
]]>
</get_beneficiary_md>
<get_requisites_md>
<![CDATA[
# Получение платёжных реквизитов бенефициара
tags: `H2H`
**Продукт:** Номинальные счета / Бенефициары
**Scope:** beneficiaries
---
## Эндпоинты
**Песочница:**
`GET https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites`
**Пром:**
`GET https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites`
---
## Описание
Метод позволяет получить платёжные реквизиты бенефициара по идентификатору `beneficiaryId`.
---
## Параметры запроса
### Заголовки (Headers)
| Атрибут | Описание |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** (string, required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** (string, required) | application/json |
### Путь (PATH)
| Атрибут | Описание |
| :----------------------------------- | :------------------------ |
| **beneficiaryId** (string, required) | Идентификатор бенефициара |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/requisites' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ: 200 (OK)
**Пример тела ответа:**
```json
[
{
"Id": "cba2888c-71ad-4211-9420-a85f6e4c10f9",
"type": "ACCOUNT",
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"isMain": true,
"isActive": true
}
]
```
**Описание полей (BODY):**
| Атрибут | Тип | Описание |
| :---------------- | :----------------- | :----------------------------------------------------------------------------------------- |
| **Id** | string (required) | Идентификатор платёжного реквизита |
| **type** | string (required) | Тип платёжного реквизита: ACCOUNT (счёт), CARD (номер карты/токен), PHONE (номер телефона) |
| **pan** | string (optional) | Токен номера карты. Заполняется при типе CARD |
| **phoneNumber** | string (optional) | Номер телефона. Заполняется при типе PHONE |
| **bankId** | string (optional) | Идентификатор банка контрагента-получателя. Заполняется при типе PHONE |
| **accountNumber** | string (optional) | Номер счёта. Заполняется при типе ACCOUNT |
| **bik** | string (optional) | БИК банка. Заполняется при типе ACCOUNT |
| **isMain** | boolean (required) | Признак основного реквизита: true — основной, false — неосновной |
| **isActive** | boolean (required) | Признак активности: true — активен, false — деактивирован |
---
## Ошибки
| Код | Статус | Код ошибки (error) и описание |
| :------ | :------------------ | :------------------------------------------------------ |
| **400** | Bad Request | invalid_request — неверные входные параметры |
| **401** | Unauthorized | invalid_token — токен недействителен или просрочен |
| **403** | Forbidden | insufficient_scope — нет прав доступа к сервису (scope) |
| **404** | Not Found | unknown_endpoint — эндпоинт не найден |
| **429** | Too Many Requests | Превышено количество запросов (без тела ответа) |
| **500** | Internal Error | internal_error — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Сервис временно недоступен (без тела ответа) |
---
**Навигация:**
- [Добавление платёжных реквизитов бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-requisites/v1/add-requisites)
- [Изменение признаков платёжных реквизитов бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/change-requisites/v1/change-requisites)
]]>
</get_requisites_md>
<get_transactions_md>
<![CDATA[
# Получение списка денежных операций бенефициара
**Тип интеграции:** H2H
**Scope:** `beneficiaries`
## Описание
Метод позволяет получить список денежных операций бенефициара за заданный период по `beneficiaryId`.
---
## Эндпоинты
| Среда | URL |
| :--- | :--- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/transactions` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/transactions` |
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **limit** | integer | required | Количество объектов на одной странице |
| **offset** | integer | required | Количество объектов в списке, которые необходимо пропустить |
| **dateFrom** | string | required | Дата начала выборки (ГГГГ-ММ-ДД) |
| **dateTo** | string | required | Дата конца выборки (ГГГГ-ММ-ДД) |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **beneficiaryId** | string | required | Идентификатор бенефициара |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/beneficiaries/{beneficiaryId}/transactions?limit=100&offset={offset}&dateFrom=2024-01-01&dateTo=2024-01-01' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 OK
#### BODY (Object)
* **pagination** (object, optional): Данные пагинации
* **limit** (number, optional): Количество записей на одной странице
* **offset** (number, optional): Количество записей в списке, которые были пропущены
* **totalCount** (number, optional): Общее количество записей
* **transactionsList** (array of objects, optional): Список операций
* **type** (string, required): Тип операции. Возможные значения:
* `Пополнение` — увеличение денежных средств бенефициара на номинальном счёте;
* `Вывод` — уменьшение денежных средств бенефициара на номинальном счёте;
* `Заморозка` — холдирование денежных средств бенефициара на номинальном счёте;
* `Разморозка` — расхолдирование замороженных денежных средств бенефициара на номинальном счёте;
* `Исходящий перевод` — перевод денежных средств другому бенефициару;
* `Входящий перевод` — поступление денежных средств от другого бенефициара.
* **amount** (string, required): Сумма операции в рублях.
* **comment** (string, optional): Комментарий к операции.
### Пример ответа 200
```json
{
"pagination": {
"limit": 100,
"offset": 0,
"totalCount": 10000
},
"transactionsList": [
{
"type": "Пополнение",
"amount": "10.00",
"comment": "Ручное выравнивание баланса"
}
]
}
```
---
## Коды ошибок
| Код | Описание | Тело ответа (error / error_description) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав (не настроен scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
* Предыдущий метод: [Получение информации о балансе бенефициара](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-balance/v1/get-balance)
* Следующий раздел: [Создание запроса на регистрацию универсального реципиента](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/add-ur/v1/add-ur)
]]>
</get_transactions_md>
</Бенефициары>
<Универсальные_реципиенты>
<add_requisites_md>
<![CDATA[
# Добавление платёжных реквизитов универсального реципиента
**Тип интеграции:** H2H
## Эндпоинты
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites` |
| **Пром** | `POST https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites` |
## Scope
`beneficiaries`
## Описание
Метод позволяет добавить платёжные реквизиты универсального реципиента по `universalRecipientId`.
> **Важно**
> Первые добавленные реквизиты автоматически назначаются основными для универсального реципиента.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **Authorization** | `string` (required) | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` (required) | application/json |
| **Content-Type** | `string` (required) | application/json |
### PATH
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **universalRecipientId** | `string` (required) | Идентификатор универсального реципиента |
### BODY
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **type** | `string` (required) | Тип платёжного реквизита. Возможные значения:<br>• `ACCOUNT` — реквизиты счёта;<br>• `CARD` — номер карты (токен);<br>• `PHONE` — номер телефона |
| **pan** | `string` (optional) | Токен номера карты. Поле обязательно при типе реквизитов `CARD`. [Как сформировать токен номера карты](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken) |
| **phoneNumber** | `string` (optional) | Номер телефона. Поле обязательно при типе реквизитов `PHONE` |
| **bankId** | `string` (optional) | Идентификатор банка контрагента-получателя. Поле обязательно при типе реквизитов `PHONE` |
| **accountNumber** | `string` (optional) | Номер счёта. Поле обязательно при типе реквизитов `ACCOUNT` |
| **bik** | `string` (optional) | БИК банка. Поле обязательно при типе реквизитов `ACCOUNT` |
| **name** | `string` (required) | Наименование получателя. Наименование организации (для юр. лиц), либо ФИО (для физ. лиц и ИП) |
| **inn** | `string` (required) | ИНН получателя. 10 цифр — для юр.лиц, 12 цифр — для физ.лиц и ИП |
| **kpp** | `string` (optional) | КПП получателя. Поле обязательно, если тип универсального реципиента `UL_RESIDENT` |
| **isMain** | `boolean` (optional) | Признак основных платежных реквизитов. По умолчанию для первых реквизитов — `true`, для последующих — `false`. |
| **digestSignatures** | `array of objects` (required) | Электронная подпись УЛ клиента |
| **└ base64Encoded** | `string` (required) | Значение электронной подписи, закодированное в Base64 |
| **└ signatureType** | `string` (required) | Тип электронной подписи: `rsa` (RSA) или `kep` (КЭП) |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"type": "ACCOUNT",
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"name": "Иванов Иван Иванович",
"inn": "112233445566",
"kpp": "123456789",
"isMain": true,
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### 200 (OK)
| Атрибут | Тип | Описание |
| :--- | :--- | :--- |
| **id** | `string` (required) | Идентификатор платёжного реквизита |
| **isMain** | `boolean` (required) | Признак основного платёжного реквизита (`true` — основной, `false` — неосновной) |
| **isActive** | `boolean` (required) | Признак активности платёжного реквизита (`true` — активен, `false` — деактивирован) |
**Пример ответа 200:**
```json
{
"id": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"isMain": true,
"isActive": true
}
```
### Ошибки
| Код | Описание | Текст ошибки (error) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса (scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
* [Предыдущая: Получение информации об универсальном реципиенте](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/get-ur/v1/get-ur)
* [Следующая: Получение платёжных реквизитов универсального реципиента](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/get-requisites/v1/get-requisites)
]]>
</add_requisites_md>
<add_universal_recipient_md>
<![CDATA[
# Создание запроса на регистрацию универсального реципиента
**Тип интеграции:** H2H
## Эндпоинты
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `POST https://sandbox.alfabank.ru/api/na/jp/v1/universal-recipients` |
| **Пром** | `POST https://baas.alfabank.ru/api/na/jp/v1/universal-recipients` |
### Scope
`beneficiaries`
---
## Описание
Метод позволяет зарегистрировать универсального реципиента (контрагента с признаком `isBeneficiary = FALSE`) в системе.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | `application/json` |
| **Content-Type** | string | Да | `application/json` |
### BODY
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **accountNumber** | string | Да | Номер номинального счёта |
| **type** | string | Да | Тип универсального реципиента. Возможные значения:<br>• `FL_RESIDENT` — физ. лицо, резидент;<br>• `UL_RESIDENT` — юр. лицо, резидент |
| **digestSignatures** | array of objects | Да | Электронная подпись УЛ клиента |
**Объект digestSignatures:**
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **base64Encoded** | string | Да | Значение электронной подписи, закодированное в Base64 |
| **signatureType** | string | Да | Тип электронной подписи. Возможные значения:<br>• `rsa` — RSA;<br>• `kep` — КЭП |
---
## Пример запроса (cURL)
```bash
curl --location 'https://baas.alfabank.ru/api/na/jp/v1/universal-recipients' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"accountNumber": "40817810306050000000",
"type": "FL_RESIDENT",
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### Успешный ответ: 202 (Accepted)
**Пример тела ответа:**
```json
{
"requestId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"status": "COMPLETE"
}
```
**Описание атрибутов:**
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **requestId** | string | Да | Идентификатор запроса |
| **status** | string | Да | Статус запроса. Принимает значения:<br>• `PENDING` – запрос в процессе обработки;<br>• `FAILED` – ошибка обработки;<br>• `COMPLETE` – успешно завершено |
---
## Коды ошибок
| Код | Описание | Тело ответа (error) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав (недостаточный scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
---
**Навигация:**
* Предыдущая статья: [Получение списка денежных операций бенефициара](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/get-transactions/v1/get-transactions)
* Следующая статья: [Получение списка универсальных реципиентов номинального счёта](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/get-urs/v1/get-urs)
]]>
</add_universal_recipient_md>
<change_requisites_md>
<![CDATA[
# Изменение признаков платёжных реквизитов универсального реципиента
**Тип интеграции:** H2H
---
## Эндпоинты
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `PATCH https://sandbox.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites/{requisiteId}` |
| **Пром** | `PATCH https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites/{requisiteId}` |
---
## Общая информация
* **Scope:** `beneficiaries`
* **Описание:** Метод позволяет изменить признаки платёжных реквизитов универсального реципиента по `universalRecipientId` и `requisiteId`.
> **Важно:** Необходимо, чтобы хотя бы один из активных реквизитов универсального реципиента был основным.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Content-Type** | string | required | `application/json` |
### PATH
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **universalRecipientId** | string | required | Идентификатор универсального реципиента |
| **requisiteId** | string | required | Идентификатор платёжного реквизита |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **pan** | string | optional | Токен номера карты контрагента. [Как сформировать токен номера карты](/products/alfa-api/documentation/articles/nominal-accounts/articles/cardtoken/cardtoken) |
| **keyId** | string | optional | Идентификатор публичного ключа для расшифровки токена номера карты |
| **phoneNumber** | string | optional | Номер телефона контрагента |
| **bankId** | string | optional | Идентификатор банка контрагента |
| **accountNumber** | string | optional | Номер счета контрагента |
| **bik** | string | optional | БИК банка контрагента |
| **name** | string | optional | Наименование получателя |
| **inn** | string | optional | ИНН получателя |
| **kpp** | string | optional | КПП получателя |
| **isMain** | boolean | optional | Признак основного платёжного реквизита: `true` — основной; `false` — неосновной |
| **isActive** | boolean | optional | Признак активности платёжного реквизита: `true` — активен; `false` — деактивирован |
| **digestSignatures** | array of objects | **required** | Электронная подпись УЛ клиента (см. ниже) |
#### Струтура объекта digestSignatures:
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **base64Encoded** | string | required | Значение электронной подписи, закодированное в Base64 |
| **signatureType** | string | required | Тип электронной подписи: `rsa` (RSA) или `kep` (КЭП) |
---
## Пример запроса
```bash
curl --location --globoff --request PATCH 'https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites/{requisiteId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"keyId": "1",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"name": "Иванов Иван Иванович",
"inn": "112233445566",
"kpp": "123456789",
"isMain": true,
"isActive": true,
"digestSignatures": [
{
"base64Encoded": "SEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2VudGVyIDICExIAVH4YMX0u3fEONSkAAQBUfhgwCgYIKoUDBwEBAQEEQBU0EntPGWz8EfJ5CFL2m10xeBrkAEeWDglGQDZWLKQ0ff4TyBT9X1NhG/+ETj4TcQhExy6k+WZ9w/CpF5FjyyA=",
"signatureType": "rsa"
}
]
}'
```
---
## Параметры ответа
### 204 No Content
Успешное выполнение запроса. Тело ответа отсутствует.
### 400 Bad Request
| Атрибут | Описание |
| :--- | :--- |
| **error** | `invalid_request` — неверные входные параметры запроса |
| **error_description** | Описание ошибки |
### 401 Unauthorized
| Атрибут | Описание |
| :--- | :--- |
| **error** | `invalid_token` — токен просрочен, отозван или недействителен |
### 403 Forbidden
| Атрибут | Описание |
| :--- | :--- |
| **error** | `insufficient_scope` — нет прав (проверьте настройки scope) |
### 404 Not Found
| Атрибут | Описание |
| :--- | :--- |
| **error** | `unknown_endpoint` — эндпоинт не найден или неактивен |
### 429 Too Many Requests
Превышен лимит запросов. Тело ответа отсутствует.
### 500 Internal Server Error
| Атрибут | Описание |
| :--- | :--- |
| **error** | `internal_error` — внутренняя ошибка сервиса |
### 503 Service Unavailable
Сервис временно недоступен. Тело ответа отсутствует.
]]>
</change_requisites_md>
<get_requisites_md>
<![CDATA[
# Получение платёжных реквизитов универсального реципиента
**H2H**
## Эндпоинты
| Среда | Метод и URL |
| :--- | :--- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites` |
## Scope
`beneficiaries`
## Описание
Метод позволяет получить платёжные реквизиты универсального реципиента по `universalRecipientId`.
## Параметры запроса
### HEADERS
| Атрибут | Описание | Тип | Обязательность |
| :--- | :--- | :--- | :--- |
| **Authorization** | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) | string | required |
| **Accept** | application/json | string | required |
### PATH
| Атрибут | Описание | Тип | Обязательность |
| :--- | :--- | :--- | :--- |
| **universalRecipientId** | Идентификатор универсального реципиента | string | required |
### Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}/requisites' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 OK (Пример тела ответа)
```json
[
{
"type": "ACCOUNT",
"pan": "wS7fElYo8VWeJ8KelaJ0XA==",
"phoneNumber": "79130000011",
"bankId": "012345678910",
"accountNumber": "40817810306050000000",
"bik": "044525593",
"name": "Иванов Иван Иванович",
"inn": "112233445566",
"kpp": "123456789",
"isMain": true,
"isActive": true
}
]
```
### BODY (Описание полей)
| Атрибут | Описание | Тип | Обязательность |
| :--- | :--- | :--- | :--- |
| **type** | Тип платёжного реквизита. Возможные значения:<br>• `ACCOUNT` — реквизиты счёта;<br>• `CARD` — номер карты (токен);<br>• `PHONE` — номер телефона | string | required |
| **pan** | Токен номера карты. Возвращается, если тип реквизитов `CARD` | string | optional |
| **phoneNumber** | Номер телефона. Возвращается, если тип реквизитов `PHONE` | string | optional |
| **bankId** | Идентификатор банка контрагента-получателя. Возвращается, если тип реквизитов `PHONE` | string | optional |
| **accountNumber** | Номер счёта. Возвращается, если тип реквизитов `ACCOUNT` | string | optional |
| **bik** | БИК банка. Возвращается, если тип реквизитов `ACCOUNT` | string | optional |
| **name** | Наименование получателя. Наименование организации (для ЮЛ), либо ФИО (для ФЛ и ИП) | string | required |
| **inn** | ИНН получателя (10 цифр для ЮЛ, 12 цифр для ФЛ и ИП) | string | required |
| **kpp** | КПП получателя. Возвращается, если тип универсального реципиента `UL_RESIDENT` | string | optional |
| **isMain** | Признак основного платёжного реквизита:<br>• `true` — основной;<br>• `false` — неосновной | boolean | required |
| **isActive** | Признак активности платёжного реквизита:<br>• `true` — активен;<br>• `false` — деактивирован | boolean | required |
---
## Ошибки
| Код | Описание | Тело ответа (error) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса (недостаточный scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен |
| **429** | Too Many Requests | Нет тела ответа |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Нет тела ответа |
]]>
</get_requisites_md>
<get_universal_recipient_md>
<![CDATA[
# Получение информации об универсальном реципиенте
**Тип интеграции:** H2H
**Продукт:** Номинальные счета
---
## Эндпоинты
| Среда | URL |
| :--- | :--- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}` |
---
## Scope
`beneficiaries`
---
## Описание
Метод позволяет получить информацию об универсальном реципиенте по `universalRecipientId`.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | Да | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | Да | application/json |
### PATH
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **universalRecipientId** | string | Да | Идентификатор универсального реципиента |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/universal-recipients/{universalRecipientId}' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### 200 (OK) — Тело ответа (BODY)
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **universalRecipientId** | string | Да | Идентификатор универсального реципиента |
| **accountNumber** | string | Да | Номер номинального счёта |
| **isBeneficiary** | boolean | Да | Признак бенефициара:<br>• `true` — является бенефициаром;<br>• `false` — является универсальным реципиентом. |
| **type** | string | Да | Тип контрагента:<br>• `FL_RESIDENT` — физ. лицо, резидент;<br>• `UL_RESIDENT` — юр. лицо, резидент. |
| **isActive** | boolean | Да | Признак активности бенефициара:<br>• `true` — активен;<br>• `false` — деактивирован. |
**Пример успешного ответа:**
```json
{
"universalRecipientId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"accountNumber": "40817810306050000000",
"isBeneficiary": false,
"type": "FL_RESIDENT",
"isActive": true
}
```
---
## Ошибки
### 400 — Bad Request
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | Да | `invalid_request` — неверные входные параметры запроса |
| **error_description** | string | Нет | Описание ошибки |
### 401 — Unauthorized
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | Да | `invalid_token` — токен просрочен, отозван или неверный формат |
### 403 — Forbidden
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | Да | `insufficient_scope` — нет прав на использование сервиса (настройки scope) |
### 404 — Not Found
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | Да | `unknown_endpoint` — эндпоинт не найден или неактивен |
### 429 — Too Many Requests
Нет тела ответа. Слишком много запросов.
### 500 — Internal Server Error
| Атрибут | Тип | Обяз. | Описание |
| :--- | :--- | :--- | :--- |
| **error** | string | Да | `internal_error` — внутренняя ошибка сервиса |
### 503 — Service Unavailable
Нет тела ответа. Сервис временно недоступен.
---
## Навигация
* **Назад:** [Получение списка универсальных реципиентов номинального счёта](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/get-urs/v1/get-urs)
* **Вперед:** [Добавление платёжных реквизитов универсального реципиента](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/add-requisites/v1/add-requisites)
]]>
</get_universal_recipient_md>
<get_universal_recipients_list_md>
<![CDATA[
# Получение списка универсальных реципиентов номинального счёта
**Тип интеграции:** H2H
---
## Конечные точки (Endpoints)
| Окружение | Метод и URL |
| :--- | :--- |
| **Песочница** | `GET https://sandbox.alfabank.ru/api/na/jp/v1/universal-recipients` |
| **Пром** | `GET https://baas.alfabank.ru/api/na/jp/v1/universal-recipients` |
---
## Scope
`beneficiaries`
## Описание
Метод позволяет получить список универсальных реципиентов номинального счёта.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | application/json |
### QUERY
| Атрибут | Тип | Обязательность | Описание |
| :--- | :--- | :--- | :--- |
| **limit** | integer | optional | Количество объектов на одной странице |
| **offset** | integer | optional | Количество объектов в списке, которые необходимо пропустить |
| **accountNumber** | string | required | Номер номинального счёта |
| **type** | string | required | Тип универсального реципиента. Возможные значения: `FL_RESIDENT` (физ. лицо), `UL_RESIDENT` (юр. лицо), `IP_RESIDENT` (ИП) |
| **isActive** | boolean | optional | Признак активности: `true` — активен; `false` — деактивирован |
| **date** | string | optional | Дата выборки |
---
## Пример запроса (cURL)
```bash
curl --location --globoff 'https://baas.alfabank.ru/api/na/jp/v1/universal-recipients?limit=100&offset={offset}&accountNumber=40817810306050000000&type={type}&isActive={isActive}&date=2024-01-01' \
--header 'Authorization: Bearer {access-token}' \
--header 'Accept: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
**Пример тела ответа:**
```json
{
"pagination": {
"limit": 100,
"offset": 0,
"totalCount": 1
},
"accountNumber": "40817810306050000000",
"date": "2024-01-01",
"universalRecipients": [
{
"universalRecipientId": "ab9cbb96-360a-4462-a683-955cc29f7f54",
"isBeneficiary": false,
"type": "FL_RESIDENT",
"isActive": true
}
]
}
```
**Описание полей BODY:**
* **pagination** (object, optional): Данные пагинации.
* `limit` (number): Количество записей на странице.
* `offset` (number): Количество пропущенных записей.
* `totalCount` (number): Общее количество записей.
* **accountNumber** (string, required): Номер номинального счёта.
* **date** (string, optional): Дата.
* **universalRecipients** (array of objects, required): Информация об универсальных реципиентах.
* `universalRecipientId` (string): Идентификатор реципиента.
* `isBeneficiary` (boolean): `true` — бенефициар, `false` — универсальный реципиент.
* `type` (string): Тип контрагента (`FL_RESIDENT`, `UL_RESIDENT`).
* `isActive` (boolean): Статус активности.
---
## Ошибки
| Код | Описание | Код ошибки (error) |
| :--- | :--- | :--- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав (scope) |
| **404** | Not Found | `unknown_endpoint` — эндпоинт не найден |
| **429** | Too Many Requests | Превышен лимит запросов (нет тела ответа) |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
| **503** | Service Unavailable | Сервис временно недоступен (нет тела ответа) |
---
## Навигация по разделу
* **Назад:** [Создание запроса на регистрацию универсального реципиента](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/add-ur/v1/add-ur)
* **Далее:** [Получение информации об универсальном реципиенте](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/universal-recipients/articles/get-ur/v1/get-ur)
]]>
</get_universal_recipients_list_md>
</Универсальные_реципиенты>
</Контрагенты>
</Номинальные_счета>
</продукты_и_сервисы>
<Транспортная_подпись_и_шифрование>
<encription>
<json_ghost_md>
<![CDATA[
# Шифрование JSON ГОСТ-сертификатом
Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).
> [!IMPORTANT]
> **Внимание**
> Для шифрования и подписания сообщения необходимо предварительно загрузить сертификат, используя следующий [метод](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/post-certificates/post-certificates). Если вы уже загружали сертификат, используя данный метод — повторно выполнять эту операцию не нужно.
---
## Подпись и шифрование JSON
### 1. Подготовить сообщение в формате JSON
**Пример сообщения:**
```json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1657882689,
"exp": 1657886289
}
```
### 2. Подписать запрос
Тело запроса сформировать алгоритмом **ГОСТ Р 34.10-2012 256 бит** в виде компактной сериализации в соответствии с [JSON Web Signature](https://www.rfc-editor.org/rfc/rfc7515#section-3.1) и подписать тело запроса закрытым ключом сертификата.
**Формат JWS:**
`BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)`
**Структура тела запроса (Header):**
- `"alg": "GOST3410_2012_256"`
- `"typ": "JWT"`
- `"cty": "JWS"`
- `"kid": "серийный номер сертификата"`
- `"b64": true`
**Пример JWS:**
```text
ewogICJhbGciIDogIkdPU1QzNDEwXzIwMTJfMjU2IiwKICAidHlwIiA6ICJKV1QiLAogICJjdHkiIDogIkpXUyIsCiAgImtpZCIgOiAiNmQzOGI4ZTAwNjFiMGY5YTk0ZjEwNGJlNTdlNzdhYTE4IiwKICAiYjY0IiA6IHRydWUKfQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.ByCkNenTTtZQrnZplNOo9WyqPTxb6vFq0iExNHpuPCV6LUeXDFTe8tNBZCy1WvpdUCQBrKK447s3NJCC5hNLhA
```
Для тестовой проверки можно использовать [https://token.dev/](https://token.dev/).
### 3. Зашифровать запрос
Зашифруйте полученный на шаге два JWS-контейнер алгоритмом **ГОСТ 34.12.2015** (блочный шифр с длиной блока n = 64 бит «Магма») открытым ключом сертификата Альфа-Банка, чтобы получился **PKCS7-контейнер**, и передайте его в теле запроса. Для получения сертификата напишите на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
**Информация об используемых стандартах ТК 26:**
- **Алгоритм экспорта ключей KExp15** на основе симметричного блочного шифра "Магма". OID: `1.2.643.7.1.1.7.1.1`
- **Алгоритм шифрования послания "Магма"** в режиме гаммирования CTR с механизмом преобразования ключа ACPKM с вычислением имитовставки. OID: `1.2.643.7.1.1.5.1.2`
**Пример PKCS7:**
```text
MIITdQYJKoZIhvcNAQcDoIITZjCCE2ICAQAxggIAMIIB/AIBADCCASIwggELMRgwFgYFKoUDZAESDTEwMjc3MDAwNjczMjgxGjAYBggqhQMDgQMBARIMMDA3NzI4MTY4OTcxMQswCQYDVQQGEwJSVTEYMBYGA1UECAwPNzcg0JzQvtGB0LrQstCwMRUwEwYDVQQHDAzQnNC+0YHQutCy0LAxKjAoBgNVBAkMIdCj0LsuINCa0LDQu9Cw0L3Rh9C10LLRgdC60LDRjyAyNzEPMA0GA1UECwwG0KPQmNCRMSEwHwYDVQQKDBjQkNCeINCQ0JvQrNCk0JAt0JHQkNCd0JoxNTAzBgNVBAMMLNCi0JXQodCiINCj0KYgMi4wINCQ0J4gItCQ0JvQrNCk0JAt0JHQkNCd0JoiAhEG04uOAGGw+alPEEvlfneqGDAXBgkqhQMHAQEHAQEwCgYIKoUDBwEBBgEEgbcwgbQEKLyfbBL4H33ZmcqKiO1B85UCDlnD2qk05vlU+4dEg34KWZLsLQv05MYwZjAfBggqhQMHAQEBATATBgcqhQMCAiQABggqhQMHAQECAgNDAARAMyQte/ak3j94OBDlA+o+CC/y4VldsMsFTA0z9zqXFR5LFLmyVop7VDJkzeXwk/BM+YIXwbWG0GnbebS3ZjuP/wQgKo8O42NksPcsAGvRWKaYYtk3RQfL9zrMZwdBtDroNjIwghE8BgkqhkiG9w0BBwEwGwYJKoUDBwEBBQECMA4EDJzOZEVIxIU3bLczkICCERA02+pMp1hYBL6KVvGmWD7NOqN0kOF5lrhPg+4Jwk2hbQiod2WFOmK0jOf3wUwF549eNMCRP5Clkz61K9b4p8CEFuodPJ65fetCUi7t1+EmSNwzBKRNzB8gNM4M12KIIJbCGpDAxyWHWe98ZgqDgCe7d/u8Lh5lqKrfrXrwHwqi+Ivdqe5ubpU37jZr1QvoWdyLocdBBoz3musKUDfuwM+tFoEydK9gK86knMXsD7ZJ3LJngy4ztGGdjBRjbF+Pg+RmR1UhCnDLEtCiJnMNN75735pXpFAgLVcUo2oexLRGh8Jw3Uh9+UthY2tRt11/e6iyrkGPmrMlcHd1poj/XC0bsIP6+kNwHMxITO2lkEKIL3B3CRZlNKMPx4dfnLt4u+cMCm+qyLqtXilxSDZp0yETzHy76ee+UdXr0kb3eGPcBidHPNpeb2EqjAE8UCuwmVfOpznl4kioEUNfCcrnPZDqHQTpNs35lQlQocyWPQOugP0OB6BC5/9kXKf5VPHcIMLeWzvor3cuac+nBaRNB4PzvwiAdBvwKp4asbvZak/MPf8I23gpdXGVtMajbUzJUlGd6Bz+G6Kz4vpUUW8IoVwXL/vPU+3N1jKbNyGvrPFrdaIoUJHu+9B92/LlmOpcxF5GssrM9MsC9e6cEl4Cq82QQn3w7AJCdHMDzgANk04cmNKDTl5DPL2YNjcmirXaVXKzO7W4Oa4PIyKAaR811tT9kKAxsJvAWODjM1wdDMSCUlK1C1DHfJdZneXY61sbbpYQoHGuC/Uo+5Z1xdLTYjjVMY5mJ/444zdWGY0Aa2BiS+vd28hx/uSlg0T93eLpJcuWvT5B5aDuBrSFPpMRCeC/VCpwfSbAAekVHGjMb1B/ABLLgbPGnTLH5RCJOUiImihn7LPhlGSop705d9TSwvItP4XO3xebqd0vpr0YvTXy8VRTzSI8UGAs+lzoGbDnqYdPYND5XR+P0vpPA3m5Yd2kBCJJoU9Z8Clzw5+Q/6X3bsa/aLmT4V3L5TZWX169gIip77EqtLUPEGEFHVUE+rmBWKcx6IBDazEsxJ4OAHkRZq7Ls6k5g3P30fwhHmXaTWGTIjRr78LHFPN15MbTthakEoAD4sMnXCmOnZtSskGyNY1U1C1Al0REql4U2dpUDebNcmTqAqwv6rPLCCA69brcXQ8ZFbyuWq39Fz4oN6OulVNNtQ6lhuTOyPCRiEIRWdW5bIROuWs1BD9M/xZOzCIJxuA/t5xusCk1BYx1D4e6cqiwpbPSAJZMDnWlNu1WT1QPEk55ihbTYGwfUmP4SUIJL8DWJvZgs7aD1ZZq5LxjZoghem8TlpwB+dlZ96geD1T6qez0DFSSL6NJkjFGkH1WYYZcTtomUrwg4yqjDlWbZOzSPAWcKwd1vkEruViOOH892FbxRUMC9EXRg4fTaRIfcgtfEO3fGAeB6fJv1pZMdNdLUOOHViuAZrhNDgBnWblqlIbl6HMmiWCoW7JryN2WXl/L1RybXO9QALAaNCmyN0zk+baqXz2ipne3CFkohucv1T++iC+SwQ+iNoxb3DfkRdBQfXPbdY75od4+g0YPN68XW3nAze1NT8kZw7Z5/bs+ZStilJTCfKx9VZaeHF+N7k4J9ll683UYp64gtxVcNx/1MQYkf6hgesh0YRtcf35HBUAilaF+1EStQHdN6tlfaB9rNwAehoHIegset/NeWBekVpo3DKLKX0qf3+J1qBr2q3nYKdApYJwgLRCtR46b865tu8puZAPLTqCk0gp0ay52kHsYxGPAeTyQsygMCQxGjcHsHJEJCEa+NvPNkBsYfick9PKe4gFJPyDiaM4yPPk6YE755Ow8OByHbSE6c4scL1CtinWIQWZJMdtN+77au7nyDwfVvIrQehnT0gWAiTZJcwsJjxpnhdhAsGkm7j1VeT4yCAAX0OvV55LVmGVVBINAJObCsybLuKA0MIPeLH4BPa/aMBGM/XigYPFVbW01PQheuWMTkGF1ru2gc2aqGKbiFY2XSbJ3u14fPUiTpLzV9bdyi15XDpVe9T4b6ioEAHzOjsTlMpwvQZOgyKw8KAyiJ1H+S8DzNlTrbzmpJyVYw8iiLceXepHMToFLnCnmey244g2dOKmMKHZT+xyMjSgiKQ8bNI7hIPhymjeQxxmYfwmfmXxSXX5bfjDuKo7Upt0GnbfKRUGKpJnm0bsK084Lxxy4XBrFQt0aNPTfAyhEylqhkctdpteIMM7gdWwQZrLhrKxJdFaU5HK0aFaIMfE4ANSC93Grpz31NgWlTKd1ZeTbnbP3vRE9wS6N+i/xI6Vmn0v928h/DPMDoiWkCx11+Ey1fAnR3inBTmVnM3j9+SIuo1tNaX2Xq4zoHXTMr5yaY9pvPPMCYrCLxX8J28bUmqR/cA5b+ot4fWyQDh0ascRk2wB2PptjcjQjxWED4vRWj/2oDNMx1lCuwPmagXAYWbDUql4LyknJUZGjePhP+7mDX6AtTtX+70jltAUlC5orD8L+IDKeRU2y+lCvdV8OfrE892XiFfOvPd6t+Pal0a0ML/Kbp7ZH642L5I73RyTFzAv06UPybwdpvEa8rssicVd3sjI5BJnJ2x3Jkl7QcSUqkk28Werjl0+/5F6C+xlJOgZ2tEX4SyiNxfVGd7dn0jsFzAzrfVqFp5tJ3f6IZ3hG4MetoQS2R3PXfETAoHz4qUE0XJ95OTxY9DCmDXtR5ce/5BC0EaJLnAexxwe+TC/kMjqUZTCKla3hhfZCG0ylGc4u8d6MtijTzkKZNiC9ww5q4T392uzltL4jp/YiHGNSvQMtgfjOeFKtNWHGMWJ/8hjYqTG5jEPWNnYwCNmxCW9Ut7jZPAnKomRiO4+cIEavgKiyiYqTBGHMDV6PZ5SvKOTATr3swLHBzSgqoczp992fWocAD9MSc+CK5oULQs2oduBWFJ5zQRuRGpjxqTjh64m1w0Ci2imHX9AY30ccpNjp/g5znWUexmioupdnZGMchy2RnFNMpflGrTGiyXgqsSSykwCLqB56pF/Qqg1v3Eq0NCWt9VKkFIi27SXfPW/jXTBs/r1EkZu2C8DqaTynjWmlo3L1yTrs1ZyXTDSiuQCzLKPEJoYHVIboZ8za1C6oVEnluh7b4rn5DLAgTgHcU2oZbu2qVePSCZwXj6tz9d74dU8DBbowTn33443YAC04VeSA8A+jsT4YKMdhCK8AkTQSAEtUjBj3Mb++T3XKEVth639oEfZ6mioIcjQ8ePu2|... (длинная строка сокращена)
```
### 4. Выполнить запрос
- Если добавить заголовки `Content-Type: application/json` + `X-Request-ChannelSecurity: NO` и отправить запрос, то запрос **не будет** расшифрован и подпись запроса не будет проверяться.
- Если добавить заголовки `Content-Type: application/jose` + `X-Request-ChannelSecurity: ENCRYPTION` и отправить запрос, то запрос **будет** расшифрован и подпись будет проверяться.
Банк дешифрует запрос и проверяет подпись. Если подпись валидна — запрос обрабатывается, если невалидна — Банк определяет запрос как неподлинный и возвращает ошибку. Ошибка также будет подписана и зашифрована. Любые другие комбинации заголовков приведут к ошибке.
---
## Дешифрование и проверка подписи JSON
### 1. Дешифровать ответ
- При заголовках `Accept: application/json` + `X-Response-ChannelSecurity: NO` ответ **не будет** подписан и зашифрован.
- При заголовках `Accept: application/jose` + `X-Response-ChannelSecurity: ENCRYPTION` ответ (включая ошибки) **будет** подписан и зашифрован.
Полученный ответ будет в виде PKCS7-контейнера. Расшифруйте его с использованием вашего закрытого ключа. Используются те же стандарты ТК 26 (Магма, OID: `1.2.643.7.1.1.7.1.1` и `1.2.643.7.1.1.5.1.2`).
### 2. Обработать дешифрованный ответ
Полученный ответ будет представлен в виде компактной сериализации JWS (три части через точку): `Base64URL(Header)`, `Base64URL(Payload)`, `Base64URL(Signature)`.
**Пример декодированного JWS:**
| Закодированный | Раскодированный |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `ewogICJhbGciIDog...` | **Header:** `{"alg": "GOST3410_2012_256", "typ": "JWT", "cty": "JWS", "kid": "6d38b8e0061b0f9a94f104be57e77aa18", "b64": true}` |
| `eyJkZWJpdFR1cm5vdmVyI...` | **Payload:** `{"debitTurnover": {"amount": 0, "currencyName": "RUR"}}` |
### 3. Проверить подпись ответа от Банка
Используйте открытый ключ сертификата Банка для проверки подписи. Для получения сертификата напишите на [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). В поле `kid` заголовка JWS будет указан серийный номер сертификата Банка.
### 4. Обработать ответ в формате JSON
**Пример итогового ответа:**
```json
{
"debitTurnover": {
"amount": 0,
"currencyName": "RUR"
}
}
```
]]>
</json_ghost_md>
<json_rsa_md>
<![CDATA[
# Шифрование JSON RSA-сертификатом
**Метки:** `B2B` `B2C` `H2H`
Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).
> [!IMPORTANT]
> **Внимание**
> Для шифрования сообщения необходимо предварительно выпустить сертификат в УЦ Альфа-Банка, используя сервис [«Электронная подпись»](/products/alfa-api/documentation/articles/signature/signature). Если Вы уже выпускали сертификат — повторно выпускать не нужно.
---
## Подписание и шифрование JSON
### 1. Подготовить сообщение в формате JSON
**Пример сообщения:**
```json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1657882689,
"exp": 1657886289
}
```
### 2. Подписать запрос
Тело запроса сформировать алгоритмом **RS256** в виде компактной сериализации в соответствии с [JSON Web Signature](https://www.rfc-editor.org/rfc/rfc7515#section-3.1) и подписать тело запроса закрытым ключом сертификата.
**Формат JWS:**
`BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)`
**Структура тела запроса:**
- **Заголовок (Header):**
- `"kid"`: "серийный номер сертификата"
- `"typ"`: "JWT"
- `"alg"`: "RS256"
- **JSON-документ (Payload)**
- **Подпись запроса (Signature)**
**Пример JWS:**
`eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxMDAwMzYzY2NiNzU5Y2I0NDg2MDc4NjVkMDAwMTAwMDM2M2NjIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTY1Nzg4MjY4OSwiZXhwIjoxNjU3ODg2Mjg5fQ.ApKNzZ9kLMtBY3LzReSHQ7_AyDnzocGo9GTQFRmxTiRS7Lj7a55Kr4ziwZAmmwloF1063JJMOaU0lS947q6_hSct9pxzPdZ9tTmpIDGnQL-ks0oB7zz9vUSUd3G00UZXSYnuhI9BBRXvmmTaue5Y2j5zVZofLdO2dqPWCnsQULyLn_vYf8PeABhnAQ29z1Bq42uxfRFTM35cF40Tp4VBSqXDI1vxfleLusQlOZM-5Sk7O3Vy4Sf-UB03RrRGSBerZjdoMRh7dgEyoYAXS6c4MejCm2vmXKqSd7pu2V2TxOM9UTchkCS16DL-RIJtnfMjznmznU5SoMCpncvs6gRNeQ`
Для тестовой проверки можно использовать [https://token.dev/](https://token.dev/).
### 3. Зашифровать запрос
Преобразуйте полученный JWS-контейнер алгоритмом **RS256** в соответствии с [JSON Web Encryption](https://datatracker.ietf.org/doc/html/rfc7516) и зашифруйте [открытым ключом](/assets/developers-portal.docs.alfa-api/articles/signature-encryption/articles/encryption/articles/json-rsa/files/cert.cer) сертификата.
**Формат JWE:**
`BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag)`
**Структура заголовка (Protected Header):**
- `"kid"`: "серийный номер сертификата"
- `"enc"`: "A256GCM"
- `"alg"`: "RSA-OAEP-256"
**Пример JWE:**
`eyJlbmiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.eFcY1Fv_xN6cFDNxnMoxCjEpVTmAjhrHuB2oW1hYapBXE02qOtdKrC3W7FGVjLFlgV3... (урезано для краткости) ...ZfAY-M8w-t9l9gErE1vQFg`
### 4. Выполнить запрос
Необходимо передать специфические HTTP-заголовки:
- **Без шифрования:**
`Content-Type: application/json` + `X-Request-ChannelSecurity: NO`
- **С шифрованием:**
`Content-Type: application/jose` + `X-Request-ChannelSecurity: ENCRYPTION`
Банк дешифрует запрос и проверяет подпись. Любые другие комбинации заголовков приведут к ошибке.
---
## Дешифрование и проверка подписи JSON
### 1. Дешифровать ответ
Для получения зашифрованного ответа используйте заголовки:
`Accept: application/jose` + `X-Response-ChannelSecurity: ENCRYPTION`
Необходимо дешифровать ответ с помощью вашего закрытого ключа.
**Структура JWE (компактная сериализация):**
1. **Protected Header** (не зашифровано)
2. **Encrypted Key** (зашифровано)
3. **Initialization Vector** (зашифровано)
4. **Ciphertext** (зашифровано)
5. **Authentication Tag** (зашифровано)
| Закодированный JWE (пример) | Раскодированный (Protected Header) |
| :------------------------------------------------------- | :-------------------------------------------- |
| `eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0...` | `{ "enc": "A256GCM", "alg": "RSA-OAEP-256" }` |
### 2. Обработать дешифрованный ответ
После дешифрования JWE вы получите компактную сериализацию **JWS**, состоящую из трех частей:
`Base64URL(Header) . Base64URL(Payload) . Base64URL(Signature)`
**Пример раскодированного JWS:**
- **Header:**
```json
{
"kid": "alfa-test-jwt",
"typ": "JWT",
"alg": "RS256"
}
```
- **Payload:**
```json
{
"debitTurnover": {
"amount": 0,
"currencyName": "RUR"
}
}
```
### 3. Проверить подпись ответа от Банка
Используйте [открытый ключ](/assets/developers-portal.docs.alfa-api/articles/signature-encryption/articles/encryption/articles/json-rsa/files/cert.cer) сертификата Банка для проверки подписи. Серийный номер сертификата Банка указан в поле `kid` заголовка JWS.
### 4. Обработать ответ в формате JSON
Итоговый результат:
```json
{
"debitTurnover": {
"amount": 0,
"currencyName": "RUR"
}
}
```
---
**Ссылки для навигации:**
- ← [Подписание TXT ГОСТ-сертификатом](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/text-gost/text-gost)
- → [Шифрование JSON ГОСТ-сертификатом](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/articles/json-gost/json-gost)
]]>
</json_rsa_md>
</encription>
<managing_certificates>
<get_certificates_md>
<![CDATA[
# Получение сертификатов
**Теги:** `B2B` `B2C` `H2H`
## Эндпоинты
### Песочница
`GET https://sandbox.alfabank.ru/api/gd/v1/crypto-service/certificates`
### Пром
`GET https://baas.alfabank.ru/api/gd/v1/crypto-service/certificates`
---
## Описание
Метод позволяет получить информацию по всем сертификатам, выпущенным вне УЦ Альфа-Банка и далее загруженным с помощью метода [«Добавление нового сертификата»](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/post-certificates/post-certificates).
> **Внимание**
> Для получения сертификата, выпущенного через сервис [«Электронная подпись»](/products/alfa-api/documentation/articles/signature/signature), используйте метод [«Получение RSA-сертификата»](/products/alfa-api/documentation/articles/signature/articles/get-rsa/v2/get-rsa).
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обяз. | Описание |
| :---------------- | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | `string` | required | Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` | required | `application/json` |
| **Content-Type** | `string` | optional | `application/json` |
### Пример запроса
```bash
curl -X GET https://baas.alfabank.ru/api/gd/v1/crypto-service/certificates \
-H 'Authorization: Bearer {access-token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Обяз. | Описание |
| :------------------- | :------------- | :------- | :--------------------------------------------------------------------------------------------------------- |
| **id** | `string(uuid)` | required | ID сертификата |
| **clientId** | `string(uuid)` | required | Идентификатор партнёрского сервиса |
| **ownerName** | `string` | required | Имя владельца |
| **fingerprint** | `string` | required | Отпечаток сертификата |
| **organizationName** | `string` | optional | Наименование организации |
| **beginDateTime** | `string` | required | Дата начала действия сертификата |
| **expireDateTime** | `string` | required | Дата окончания действия сертификата |
| **status** | `string` | optional | Статус. Возможные значения:<br>• `ACTIVE` - активен;<br>• `REVOKED` - аннулирован;<br>• `DELETED` - удалён |
| **certificateBody** | `string` | required | Тело сертификата в виде base64-строки |
| **type** | `string` | required | Тип сертификата. Возможные значения:<br>• `SIGNATURE` - для подписи;<br>• `ENCRYPTION` - для шифрования |
| **algorithm** | `string` | required | Алгоритм сертификата |
| **serialNumber** | `string` | required | Серийный номер сертификата |
### Пример ответа 200 (OK)
```json
[
{
"id": "9610bc6b-f06b-41b6-bae9-6bb5b06a54dd",
"clientId": "4aa56f35-abb1-4ebe-9697-389cca4a4475",
"ownerName": "Кудрявцев Ермолай Игоревич",
"fingerprint": "333773d77ef05aa9f7b7bae8e2779418b2aedb6a",
"organizationName": "ООО 'Ромашка'",
"beginDateTime": "2023-07-28T15:11:14Z",
"expireDateTime": "2025-06-19T11:48:06Z",
"status": "ACTIVE",
"certificateBody": "MIIGATCCBLWgAwIBAgITYQADiqqgHk1/OTmNhAABAAOKqjBBBgkqhkiG9w0BAQowNKAPMA0GCWCGSAFlAwQCAwUAoRwwGgYJKoZIhvcNAQEIMA0GCWCGSAFlAwQCAwUAogMCAUAwWzELMAkGA1UEBhMCUlUxEjAQBgNVBAoTCUFsZmEtQmFuazELMAkGA1UECxMCSVQxKzApBgNVBAMTIkFsZmEtQmFuayBJc3N1aW5nIFN1Ym9yZGluYXRlIENBIDEwHhcNMjMwNzI4MTUxMTE0WhcNMjUwNjE5MTE0ODA2WjCBpzEXMBUGA1UEKgwO0JXRgNC80L7Qu9Cw0LkxGzAZBgNVBAQMEtCa0YPQtNGA0Y/QstGG0LXQsjELMAkGA1UEBhMCUlUxOzA5BgNVBAMMMtCa0YPQtNGA0Y/QstGG0LXQsiDQldGA0LzQvtC70LDQuSDQmNCz0L7RgNC10LLQuNGHMSUwIwYJKoZIhvcNAQkBFhZVc2VyNTA0QHBvY2h0b2Noa2EuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0ZM3Ztf+Ro4e64R8yI4qDV/zLdJjUCx5WNBx6gcp1pJ4uhQixw+ASy4Oxu0Xp7OxmpXtvDJFi4kr6QymtzMNYqJA3GZk85p+Iobkwo5zHKyBf0tX5HwmFWjJx9CqZKp8iZAFw9nqz1uqronxyzTgULPL6eE9igVSzaVf5msV8sXXfl87guVHF+Ph18hsdng1WiCJ7Mi14ETdI9O0R5eJiPZztLIHRnXuBtB1Oa1YiiWtvkZNnpLKONwxljdTZlH7h7KfaXUwW3kX8r0p7jvO7gNhMXvOSK1JPXWevmBHrjONVlG2atWoxT2IHs2ZDz+BLxgSwLc9NIQK+qKhIMfA1wIDAQABo4ICBzCCAgMwJQYDVR0RBB4wHIILZXhhbXBsZS5jb22CDSouZXhhbXBsZS5jb20wHQYDVR0OBBYEFGbczU3B6IZhHwKsC8ODg8r4xi3nMB8GA1UdIwQYMBaAFMkXMx6bqZSglhhLbnFMgdvpc/5lMIG7BgNVHR8EgbMwgbAwga2ggaqggaeGOWh0dHBzOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybIYwaHR0cDovL3Zsa3dzNjo5MDgxL2Rpc3RycG9pbnQvQWxmYS1CYW5rX1NDQTEuY3JshjhodHRwOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybDCB2wYIKwYBBQUHAQEEgc4wgcswRQYIKwYBBQUHMAKGOWh0dHBzOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNydDA8BggrBgEFBQcwAoYwaHR0cDovL3Zsa3dzNjo5MDgxL2Rpc3RycG9pbnQvQWxmYS1CYW5rX1NDQTEuY3J0MEQGCCsGAQUFBzAChjhodHRwOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNydDBBBgkqhkiG9w0BAQowNKAPMA0GCWCGSAFlAwQCAwUAoRwwGgYJKoZIhvcNAQEIMA0GCWCGSAFlAwQCAwUAogMCAUADggEBAHTjDmxldqWkRgpT5gXKuIzyqIHjlDZMMfahcWBxqWV9XC46bcPx8gvlpzb8N+oK+X6AqDt3+vneAiGQn8iNs9ajDKtes9ulZzMUJBwzwv26DsiI3s4/0phypAcqQVHJQxvU+rdrh5FgqJcNZsuOtOaJhiO/i/3J7hoL/oxVwSk+lX4m+X5u76/Vdqk9ydKXNNnzMi12F4FvD+igTrezzLjPHQRx5vLY0cWwLEdBxLJmBwd1u7EBT3j+v9Pyh0pTzXsJC0BY1BIt6VOh6QGKGTKT3cBB6zbIOrY7UTOkYdCqtyB9vhayAyti3aO37PANUQ7dUwUEZyf64/D4/HRlhqI=",
"type": "ENCRYPTION",
"algorithm": "RS256",
"serialNumber": "2163173489423972678179275487230070851350268586"
}
]
```
---
## Ошибки
| Код | Описание | Возможные значения `error` |
| :------ | :------------- | :------------------------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры запроса |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — нет прав на использование сервиса (настройки scope) |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
_Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок._
---
**Навигация:**
[← Добавление нового сертификата](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/post-certificates/post-certificates) | [Обновление сертификата →](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/patch-certificates/patch-certificates)
]]>
</get_certificates_md>
<patch_certificates_md>
<![CDATA[
# Обновление сертификата
**Метки:** `B2B` | `B2C` | `H2H`
## Эндпоинты
| Окружение | Метод и URL |
| :------------ | :----------------------------------------------------------------------------- |
| **Песочница** | `PATCH https://sandbox.alfabank.ru/api/gd/v1/crypto-service/certificates/{id}` |
| **Пром** | `PATCH https://baas.alfabank.ru/api/gd/v1/crypto-service/certificates/{id}` |
## Описание
Метод позволяет отозвать или активировать ранее отозванный сертификат, выпущенный вне УЦ Альфа-Банка. Отозванный сертификат не может использоваться для криптографических операций.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Описание |
| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | `string` | **Required**. Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | `string` | **Required**. `application/json` |
| **Content-Type** | `string` | **Required**. `application/json` |
### PATH
| Атрибут | Тип | Описание |
| :------ | :------- | :--------------------------- |
| **id** | `string` | **Required**. ID сертификата |
### BODY
| Атрибут | Тип | Описание |
| :-------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **op** | `string` | **Optional**. Тип операции. Возможные значения: `replace` — замена |
| **path** | `string` | **Optional**. Путь до изменяемого параметра. Возможные значения: `/status` |
| **value** | `string` | **Optional**. Новое значение. Возможные значения: <br>• `ACTIVE` — сертификат активен;<br>• `REVOKED` — сертификат аннулирован |
### Пример запроса
```bash
curl -X PATCH https://baas.alfabank.ru/api/gd/v1/crypto-service/certificates/{id} \
-H 'Authorization: Bearer {access-token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"op": "replace",
"path": "/status",
"value": "ACTIVE"
}'
```
---
## Параметры ответа
### Успешный ответ (200 OK)
| Атрибут | Тип | Описание |
| :------------------- | :------------- | :-------------------------------------------------------------------------- |
| **id** | `string(uuid)` | **Required**. ID сертификата |
| **clientId** | `string(uuid)` | **Required**. Идентификатор партнёрского сервиса |
| **ownerName** | `string` | **Required**. Имя владельца |
| **fingerprint** | `string` | **Required**. Отпечаток сертификата |
| **organizationName** | `string` | **Optional**. Наименование организации |
| **beginDateTime** | `string` | **Required**. Дата начала действия сертификата |
| **expireDateTime** | `string` | **Required**. Дата окончания действия сертификата |
| **status** | `string` | **Required**. Статус: `ACTIVE` (активен), `REVOKED` (аннулирован) |
| **certificateBody** | `string` | **Required**. Тело сертификата в виде base64-строки |
| **type** | `string` | **Required**. Тип: `SIGNATURE` (для подписи), `ENCRYPTION` (для шифрования) |
| **algorithm** | `string` | **Required**. Алгоритм сертификата |
| **serialNumber** | `string` | **Required**. Серийный номер сертификата |
#### Пример ответа 200
```json
{
"id": "9610bc6b-f06b-41b6-bae9-6bb5b06a54dd",
"clientId": "4aa56f35-abb1-4ebe-9697-389cca4a4475",
"ownerName": "Кудрявцев Ермолай Игоревич",
"fingerprint": "333773d77ef05aa9f7b7bae8e2779418b2aedb6a",
"organizationName": "ООО 'Ромашка'",
"beginDateTime": "2023-07-28T15:11:14Z",
"expireDateTime": "2025-06-19T11:48:06Z",
"status": "ACTIVE",
"certificateBody": "MIIGATCCBLWgAwIBAgITYQADiqqgHk1/OTmNhAABAAOKqjBB...",
"type": "ENCRYPTION",
"algorithm": "RS256",
"serialNumber": "2163173489423972678179275487230070851350268586"
}
```
---
## Ошибки
| Код | Описание | Код ошибки (`error`) |
| :------ | :------------- | :------------------------------------------------------------ |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав для вызова сервиса |
| **500** | Internal Error | `internal_error` — внутренняя ошибка сервиса |
### Примеры сообщений об ошибках
**400 Bad Request**
```json
{
"error": "invalid_request",
"error_description": "Authorization header is not present in request headers"
}
```
**401 Unauthorized**
```json
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}
```
> **Важно:** Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации.
---
_Документация Alfa API_
]]>
</patch_certificates_md>
<post_certificates_md>
<![CDATA[
# Добавление нового сертификата
**Теги:** `B2B` `B2C` `H2H`
## Эндпоинты
### Песочница
`POST https://sandbox.alfabank.ru/api/gd/v1/crypto-service/certificates`
### Пром
`POST https://baas.alfabank.ru/api/gd/v1/crypto-service/certificates`
## Описание
Метод позволяет загрузить сертификат, выпущенный вне УЦ Альфа-Банка, для проверки подписи запроса Банком и шифрования ответа от Банка.
---
## Параметры запроса
### HEADERS
| Атрибут | Тип | Обязательность | Описание |
| :---------------- | :----- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | required | Bearer {access_token}, полученный по [Authorization Code Flow](/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/intro/intro) / [Authorization Code Flow H2H](/products/alfa-api/documentation/articles/alfa-id/articles/acf-h2h/articles/intro/intro) |
| **Accept** | string | required | `application/json` |
| **Content-Type** | string | required | `application/json` |
### BODY
| Атрибут | Тип | Обязательность | Описание |
| :------------------ | :----- | :------------- | :------------------------------------------------------------------------------------------------------- |
| **type** | string | required | Тип сертификата. Возможные значения:<br>• `SIGNATURE` — для подписи;<br>• `ENCRYPTION` — для шифрования. |
| **certificateBody** | string | required | Тело сертификата в виде base64-строки. |
### Пример запроса
```bash
curl -X POST https://baas.alfabank.ru/api/gd/v1/crypto-service/certificates \
-H 'Authorization: Bearer {access-token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"type": "ENCRYPTION",
"certificateBody": "MIIGATCCBLWgAwIBAgITYQADiqqgHk1/OTmNhAABAAOKqjBBBgkqhkiG9w0BAQowNKAPMA0GCWCGSAFlAwQCAwUAoRwwGgYJKoZIhvcNAQEIMA0GCWCGSAFlAwQCAwUAogMCAUAwWzELMAkGA1UEBhMCUlUxEjAQBgNVBAoTCUFsZmEtQmFuazELMAkGA1UECxMCSVQxKzApBgNVBAMTIkFsZmEtQmFuayBJc3N1aW5nIFN1Ym9yZGluYXRlIENBIDEwHhcNMjMwNzI4MTUxMTE0WhcNMjUwNjE5MTE0ODA2WjCBpzEXMBUGA1UEKgwO0JXRgNC80L7Qu9Cw0LkxGzAZBgNVBAQMEtCa0YPQtNGA0Y/QstGG0LXQsjELMAkGA1UEBhMCUlUxOzA5BgNVBAMMMtCa0YPQtNGA0Y/QstGG0LXQsiDQldGA0LzQvtC70LDQuSDQmNCz0L7RgNC10LLQuNGHMSUwIwYJKoZIhvcNAQkBFhZVc2VyNTA0QHBvY2h0b2Noa2EuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0ZM3Ztf+Ro4e64R8yI4qDV/zLdJjUCx5WNBx6gcp1pJ4uhQixw+ASy4Oxu0Xp7OxmpXtvDJFi4kr6QymtzMNYqJA3GZk85p+Iobkwo5zHKyBf0tX5HwmFWjJx9CqZKp8iZAFw9nqz1uqronxyzTgULPL6eE9igVSzaVf5msV8sXXfl87guVHF+Ph18hsdng1WiCJ7Mi14ETdI9O0R5eJiPZztLIHRnXuBtB1Oa1YiiWtvkZNnpLKONwxljdTZlH7h7KfaXUwW3kX8r0p7jvO7gNhMXvOSK1JPXWevmBHrjONVlG2atWoxT2IHs2ZDz+BLxgSwLc9NIQK+qKhIMfA1wIDAQABo4ICBzCCAgMwJQYDVR0RBB4wHIILZXhhbXBsZS5jb22CDSouZXhhbXBsZS5jb20wHQYDVR0OBBYEFGbczU3B6IZhHwKsC8ODg8r4xi3nMB8GA1UdIwQYMBaAFMkXMx6bqZSglhhLbnFMgdvpc/5lMIG7BgNVHR8EgbMwgbAwga2ggaqggaeGOWh0dHBzOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybIYwaHR0cDovL3Zsa3dzNjo5MDgxL2Rpc3RycG9pbnQvQWxmYS1CYW5rX1NDQTEuY3JshjhodHRwOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybDCB2wYIKwYBBQUHAQEEgc4wgcswRQYIKwYBBQUHMAKGOWh0dHBzOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNydDA8BggrBgEFBQcwAoYwaHR0cDovL3Zsa3dzNjo5MDgxL2Rpc3RycG9pbnQvQWxmYS1CYW5rX1NDQTEuY3J0MEQGCCsGAQUFBzAChjhodHRwOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNydDBBBgkqhkiG9w0BAQowNKAPMA0GCWCGSAFlAwQCAwUAoRwwGgYJKoZIhvcNAQEIMA0GCWCGSAFlAwQCAwUAogMCAUADggEBAHTjDmxldqWkRgpT5gXKuIzyqIHjlDZMMfahcWBxqWV9XC46bcPx8gvlpzb8N+oK+X6AqDt3+vneAiGQn8iNs9ajDKtes9ulZzMUJBwzwv26DsiI3s4/0phypAcqQVHJQxvU+rdrh5FgqJcNZsuOtOaJhiO/i/3J7hoL/oxVwSk+lX4m+X5u76/Vdqk9ydKXNNnzMi12F4FvD+igTrezzLjPHQRx5vLY0cWwLEdBxLJmBwd1u7EBT3j+v9Pyh0pTzXsJC0BY1BIt6VOh6QGKGTKT3cBB6zbIOrY7UTOkYdCqtyB9vhayAyti3aO37PANUQ7dUwUEZyf64/D4/HRlhqI="
}'
```
---
## Параметры ответа
### Успешный ответ: 201 Created
| Атрибут | Тип | Обязательность | Описание |
| :------------------- | :----------- | :------------- | :---------------------------------------------------------------------- |
| **id** | string(uuid) | required | ID сертификата |
| **clientId** | string | required | Идентификатор партнёрского сервиса |
| **ownerName** | string | required | Имя владельца |
| **fingerprint** | string | required | Отпечаток сертификата |
| **organizationName** | string | optional | Наименование организации |
| **beginDateTime** | string | required | Дата начала действия сертификата |
| **expireDateTime** | string | required | Дата окончания действия сертификата |
| **status** | string | required | Статус: `ACTIVE` (активен), `REVOKED` (аннулирован), `DELETED` (удалён) |
| **certificateBody** | string | required | Тело сертификата в виде base64-строки |
| **type** | string | required | Тип сертификата (`SIGNATURE` или `ENCRYPTION`) |
| **algorithm** | string | required | Алгоритм сертификата |
| **serialNumber** | string | required | Серийный номер сертификата |
#### Пример ответа 201
```json
{
"id": "9610bc6b-f06b-41b6-bae9-6bb5b06a54dd",
"clientId": "4aa56f35-abb1-4ebe-9697-389cca4a4475",
"ownerName": "Кудрявцев Ермолай Игоревич",
"fingerprint": "333773d77ef05aa9f7b7bae8e2779418b2aedb6a",
"organizationName": "ООО 'Ромашка'",
"beginDateTime": "2023-07-28T15:11:14Z",
"expireDateTime": "2025-06-19T11:48:06Z",
"status": "ACTIVE",
"certificateBody": "MIIGATCCBLWgAwIBAgITYQADiqqgHk1/OTmNhAABAAOKqjBBBgkqhkiG9w0BAQowNKAPMA0GCWCGSAFlAwQCAwUAoRwwGgYJKoZIhvcNAQEIMA0GCWCGSAFlAwQCAwUAogMCAUAwWzELMAkGA1UEBhMCUlUxEjAQBgNVBAoTCUFsZmEtQmFuazELMAkGA1UECxMCSVQxKzApBgNVBAMTIkFsZmEtQmFuayBJc3N1aW5nIFN1Ym9yZGluYXRlIENBIDEwHhcNMjMwNzI4MTUxMTE0WhcNMjUwNjE5MTE0ODA2WjCBpzEXMBUGA1UEKgwO0JXRgNC80L7Qu9Cw0LkxGzAZBgNVBAQMEtCa0YPQtNGA0Y/QstGG0LXQsjELMAkGA1UEBhMCUlUxOzA5BgNVBAMMMtCa0YPQtNGA0Y/QstGG0LXQsiDQldGA0LzQvtC70LDQuSDQmNCz0L7RgNC10LLQuNGHMSUwIwYJKoZIhvcNAQkBFhZVc2VyNTA0QHBvY2h0b2Noa2EuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0ZM3Ztf+Ro4e64R8yI4qDV/zLdJjUCx5WNBx6gcp1pJ4uhQixw+ASy4Oxu0Xp7OxmpXtvDJFi4kr6QymtzMNYqJA3GZk85p+Iobkwo5zHKyBf0tX5HwmFWjJx9CqZKp8iZAFw9nqz1uqronxyzTgULPL6eE9igVSzaVf5msV8sXXfl87guVHF+Ph18hsdng1WiCJ7Mi14ETdI9O0R5eJiPZztLIHRnXuBtB1Oa1YiiWtvkZNnpLKONwxljdTZlH7h7KfaXUwW3kX8r0p7jvO7gNhMXvOSK1JPXWevmBHrjONVlG2atWoxT2IHs2ZDz+BLxgSwLc9NIQK+qKhIMfA1wIDAQABo4ICBzCCAgMwJQYDVR0RBB4wHIILZXhhbXBsZS5jb22CDSouZXhhbXBsZS5jb20wHQYDVR0OBBYEFGbczU3B6IZhHwKsC8ODg8r4xi3nMB8GA1UdIwQYMBaAFMkXMx6bqZSglhhLbnFMgdvpc/5lMIG7BgNVHR8EgbMwgbAwga2ggaqggaeGOWh0dHBzOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybIYwaHR0cDovL3Zsa3dzNjo5MDgxL2Rpc3RycG9pbnQvQWxmYS1CYW5rX1NDQTEuY3JshjhodHRwOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybDCB2wYIKwYBBQUHAQEEgc4wgcswRQYIKwYBBQUHMAKGOWh0dHBzOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNydDA8BggrBgEFBQcwAoYwaHR0cDovL3Zsa3dzNjo5MDgxL2Rpc3RycG9pbnQvQWxmYS1CYW5rX1NDQTEuY3J0MEQGCCsGAQUFBzAChjhodHRwOi8vdGVzdGptYi5hbGZhYmFuay5ydS9kaXN0cnBvaW50L0FsZmEtQmFua19TQ0ExLmNybDBBBgkqhkiG9w0BAQowNKAPMA0GCWCGSAFlAwQCAwUAoRwwGgYJKoZIhvcNAQEIMA0GCWCGSAFlAwQCAwUAogMCAUADggEBAHTjDmxldqWkRgpT5gXKuIzyqIHjlDZMMfahcWBxqWV9XC46bcPx8gvlpzb8N+oK+X6AqDt3+vneAiGQn8iNs9ajDKtes9ulZzMUJBwzwv26DsiI3s4/0phypAcqQVHJQxvU+rdrh5FgqJcNZsuOtOaJhiO/i/3J7hoL/oxVwSk+lX4m+X5u76/Vdqk9ydKXNNnzMi12F4FvD+igTrezzLjPHQRx5vLY0cWwLEdBxLJmBwd1u7EBT3j+v9Pyh0pTzXsJC0BY1BIt6VOh6QGKGTKT3cBB6zbIOrY7UTOkYdCqtyB9vhayAyti3aO37PANUQ7dUwUEZyf64/D4/HRlhqI=",
"type": "ENCRYPTION",
"algorithm": "RS256",
"serialNumber": "2163173489423972678179275487230070851350268586"
}
```
---
## Ошибки
| Код | Описание | Код ошибки (в теле) |
| :------ | :-------------------- | :--------------------------------------------------------- |
| **400** | Bad Request | `invalid_request` — неверные входные параметры |
| **401** | Unauthorized | `invalid_token` — токен просрочен или недействителен |
| **403** | Forbidden | `insufficient_scope` — недостаточно прав (настройки scope) |
| **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса |
> Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации.
---
### Навигация
← [Для чего это нужно](/products/alfa-api/documentation/articles/signature-encryption/articles/intro/intro) | [Получение сертификатов](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/get-certificates/get-certificates) →
]]>
</post_certificates_md>
</managing_certificates>
<signature_encryption_intro_md>
<![CDATA[
# Для чего это нужно
**Теги:** `B2B` `B2C` `H2H`
Использование транспортной подписи и шифрования с использованием ГОСТ- или RSA-сертификата даёт следующие возможности:
### **Конфиденциальность**
Шифрование сообщений обеспечивает защиту данных от посторонних глаз. Это важно, так как в API могут передаваться конфиденциальные данные, такие как номера счетов или личная информация.
### **Безопасность**
Подписание сообщений подтверждает подлинность и целостность информации. Если сообщение было изменено или подделано, подпись становится недействительной.
### **Доверие**
Подписание и шифрование помогают укрепить доверие между сторонами API, поскольку они подтверждают, что данные не были изменены или подделаны во время передачи.
### **Соответствие требованиям**
В некоторых отраслях, таких как финансовые услуги, подписание и шифрование являются обязательными требованиями для соблюдения регуляторных норм и защиты данных.
### **Аутентификация**
Подписание сообщения может также использоваться для аутентификации источника данных, тем самым предотвращая фальсификацию или манипуляции с данными.
---
## Навигация по разделу
- ← [Загрузка файла](/products/alfa-api/documentation/articles/secure-file-transfer/articles/upload/v1/upload)
- → [Добавление нового сертификата](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/post-certificates/post-certificates)
---
### Справочная информация (из структуры документа)
Данная статья является частью раздела **Транспортная подпись и шифрование**. В этом разделе также доступны:
1. [Управление сертификатами для подписи и шифрования](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/managing-certificates)
2. [Транспортная подпись](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/signature)
3. [Шифрование](/products/alfa-api/documentation/articles/signature-encryption/articles/encryption/encryption)
]]>
</signature_encryption_intro_md>
<transport_signature>
<json_ghost_md>
<![CDATA[
# Подписание JSON ГОСТ-сертификатом
**B2B | B2C | H2H**
Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).
> **Внимание**
> Для подписания сообщения необходимо предварительно загрузить сертификат, используя следующий [метод](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/post-certificates/post-certificates). Если Вы уже загружали сертификат, используя данный метод — повторно выполнять эту операцию не нужно.
## Подписание JSON
### 1. Подготовить сообщение в формате JSON
**Пример сообщения:**
```json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1657882689,
"exp": 1657886289
}
```
### 2. Подписать запрос
Тело запроса сформировать алгоритмом ГОСТ Р 34.10-2012 256 бит в виде компактной сериализации в соответствии с [JSON Web Signature](https://www.rfc-editor.org/rfc/rfc7515#section-3.1) и подписать тело запроса закрытым ключом сертификата.
**Формат JWS:**
`BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)`
**Структура тела запроса:**
- **Заголовок (Header)**
- `"alg": "GOST3410_2012_256"`
- `"typ": "JWT"`
- `"cty": "JWS"`
- `"kid": "серийный номер сертификата"`
- `"b64": true`
- **JSON-документ (Payload)**
- **Подпись запроса (Signature)**
**Пример JWS:**
```text
ewogICJhbGciIDogIkdPU1QzNDEwXzIwMTJfMjU2IiwKICAidHlwIiA6ICJKV1QiLAogICJjdHkiIDogIkpXUyIsCiAgImtpZCIgOiAiNmQzOGI4ZTAwNjFiMGY5YTk0ZjEwNGJlNTdlNzdhYTE4IiwKICAiYjY0IiA6IHRydWUKfQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.ByCkNenTTtZQrnZplNOo9WyqPTxb6vFq0iExNHpuPCV6LUeXDFTe8tNBZCy1WvpdUCQBrKK447s3NJCC5hNLhA
```
Для тестовой проверки можно использовать [https://token.dev/](https://token.dev/).
### 3. Выполнить запрос
- Если добавить заголовки `Content-Type: application/json` + `X-Request-ChannelSecurity: NO` и отправить запрос, то подпись запроса не будет проверяться.
- Если добавить заголовки `Content-Type: application/jose` + `X-Request-ChannelSecurity: SIGNATURE` и отправить запрос, то подпись запроса будет проверяться.
- Если подпись валидна — запрос обрабатывается, если невалидна — Банк определяет запрос как неподлинный и возвращает ошибку.
Любые другие комбинации заголовков `Content-Type + X-Request-ChannelSecurity` приведут к ошибке.
---
## Проверка подписи JSON
### 1. Получить ответ
- Если добавить заголовки `Accept: application/json` + `X-Response-ChannelSecurity: NO`, то ответ не будет подписан.
- Если добавить заголовки `Accept: application/jose` + `X-Response-ChannelSecurity: SIGNATURE`, то полученный ответ (в том числе ошибки) будет подписан и представлен в виде компактной сериализации.
Любые другие комбинации заголовков `Accept + X-Response-ChannelSecurity` приведут к ошибке.
**Декодирование компактной сериализации JWS**
JWS формируется из трёх составляющих и представляет структуру вида:
1. Base64URL(Header);
2. Base64URL(Payload);
3. Base64URL(Signature).
**Пример JWS:**
| Закодированный | Раскодированный |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ewogICJhbGciIDogIkdPU1QzNDEwXzIwMTJfMjU2IiwKICAidHlwIiA6ICJKV1QiLAogICJjdHkiIDogIkpXUyIsCiAgImtpZCIgOiAiNmQzOGI4ZTAwNjFiMGY5YTk0ZjEwNGJlNTdlNzdhYTE4IiwKICAiYjY0IiA6IHRydWUKfQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.ByCkNenTTtZQrnZplNOo9WyqPTxb6vFq0iExNHpuPCV6LUeXDFTe8tNBZCy1WvpdUCQBrKK447s3NJCC5hNLhA` | **header** `json { "alg": "GOST3410_2012_256", "typ": "JWT", "cty": "JWS", "kid": "6d38b8e0061b0f9a94f104be57e77aa18", "b64": true } ` **payload** `json { "debitTurnover": { "amount": 0, "currencyName": "RUR" } } ` **verify signature** `text HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), ) ` |
### 2. Проверить подпись ответа от Банка
Используйте открытый ключ сертификата Банка для проверки подписи. Для получения сертификата напишите на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru).
Проверьте подпись в соответствии с данными, указанными в Заголовке (Header). В поле `kid` заголовка JWS будет записан серийный номер сертификата Банка.
### 3. Обработать ответ в формате JSON
**Пример ответа:**
```json
{
"debitTurnover": {
"amount": 0,
"currencyName": "RUR"
}
}
```
---
[← Подписание JSON RSA-сертификатом](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/json-rsa/json-rsa) | [Подписание XML RSA-сертификатом →](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/xml-rsa/xml-rsa)
]]>
</json_ghost_md>
<json_rsa_md>
<![CDATA[
# Подписание JSON RSA-сертификатом
**B2B** | **B2C** | **H2H**
Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [alfa_api@alfabank.ru](mailto:alfa_api@alfabank.ru). При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).
> **Внимание**
> Для подписания сообщения необходимо предварительно выпустить сертификат в УЦ Альфа-Банка, используя сервис ["Электронная подпись"](/products/alfa-api/documentation/articles/signature/signature). Если Вы уже выпускали сертификат - повторно выпускать не нужно.
---
## Подписание JSON
### 1. Подготовить сообщение в формате JSON
**Пример сообщения**
```json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1657882689,
"exp": 1657886289
}
```
### 2. Подписать запрос
Тело запроса сформировать алгоритмом **RS256** в виде компактной сериализации в соответствии с [JSON Web Signature](https://www.rfc-editor.org/rfc/rfc7515#section-3.1) и подписать тело запроса закрытым ключом сертификата, выпущенным в сервисе "Электронная подпись".
**Формат JWS**
`BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)`
**Структура тела запроса**
- **Заголовок (Header)**
- `"kid"`: "серийный номер сертификата"
- `"typ"`: "JWT"
- `"alg"`: "RS256"
- **JSON-документ (Payload)**
- **Подпись запроса (Signature)**
**Пример JWS**
```text
eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxMDAwMzYzY2NiNzU5Y2I0NDg2MDc4NjVkMDAwMTAwMDM2M2NjIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTY1Nzg4MjY4OSwiZXhwIjoxNjU3ODg2Mjg5fQ.ApKNzZ9kLMtBY3LzReSHQ7_AyDnzocGo9GTQFRmxTiRS7Lj7a55Kr4ziwZAmmwloF1063JJMOaU0lS947q6_hSct9pxzPdZ9tTmpIDGnQL-ks0oB7zz9vUSUd3G00UZXSYnuhI9BBRXvmmTaue5Y2j5zVZofLdO2dqPWCnsQULyLn_vYf8PeABhnAQ29z1Bq42uxfRFTM35cF40Tp4VBSqXDI1vxfleLusQlOZM-5Sk7O3Vy4Sf-UB03RrRGSBerZjdoMRh7dgEyoYAXS6c4MejCm2vmXKqSd7pu2V2TxOM9UTchkCS16DL-RIJtnfMjznmznU5SoMCpncvs6gRNeQ
```
Для тестовой проверки можно использовать [https://token.dev/](https://token.dev/).
### 3. Выполнить запрос
- Если добавить заголовки `Content-Type: application/json` + `X-Request-ChannelSecurity: NO` и отправить запрос, то подпись запроса **не будет** проверяться.
- Если добавить заголовки `Content-Type: application/jose` + `X-Request-ChannelSecurity: SIGNATURE` и отправить запрос, то подпись запроса **будет** проверяться.
Если подпись валидна — запрос обрабатывается, если невалидна — Банк определяет запрос как неподлинный и возвращает ошибку. Любые другие комбинации заголовков `Content-Type + X-Request-ChannelSecurity` приведут к ошибке.
---
## Проверка подписи JSON
### 1. Получить ответ
- Если добавить заголовки `Accept: application/json` + `X-Response-ChannelSecurity: NO`, то ответ **не будет** подписан.
- Если добавить заголовки `Accept: application/jose` + `X-Response-ChannelSecurity: SIGNATURE`, то полученный ответ (в том числе ошибки) **будет подписан** и представлен в виде компактной сериализации.
Любые другие комбинации заголовков `Accept + X-Response-ChannelSecurity` приведут к ошибке.
**Декодирование компактной сериализации JWS**
JWS формируется из трёх составляющих:
- Base64URL(Header);
- Base64URL(Payload);
- Base64URL(Signature).
**Пример JWS**
| ЗАКОДИРОВАННЫЙ | РАСКОДИРОВАННЫЙ |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.`<br>`eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.`<br>`Y1NqCkRjjtJ2GrVsW-a627g6ObfpEaKw-H92QVgVWqL9i7d1SHyaXVghF4ZNZAlrFasKySnKYZf2Ik8zVIlLN7hqeYxoeTdE2OLbiQdvPrD-JnI2Qzh0K32vcImwgGcpq2lt_QKx1f_YmaSRhH9O3xZePVcmFGCqhl_0prQSwcR4g-yuhidvspaF48QlUHcEaZ65Cr8hdyc6g9HPZDy7ipU-zCAZGgK0enxfWn4Osyqch8RRDIsfLG7OJ4wbYwYB22LYO5UaxX8Zy_R2jSnKlNghxQwSqJGxizMFhFhdCrATGTo-ysI-7OtfremD8YNj7z_iYciyYbtAgV0ZodEvMA` | **header**<br>`{"kid": "alfa-test-jwt", "typ": "JWT", "alg": "RS256"}`<br><br>**payload**<br>`{"debitTurnover": {"amount": 0, "currencyName": "RUR"}}`<br><br>**verify signature**<br>`RSASHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload))` |
### 2. Проверить подпись ответа от Банка
Используйте [открытый ключ](/assets/developers-portal.docs.alfa-api/articles/signature-encryption/articles/signature/articles/json-rsa/files/cert.cer) сертификата для проверки подписи.
Проверьте подпись в соответствии с данными, указанными в Заголовке (Header). В поле `kid` заголовка JWS будет записан серийный номер сертификата Банка.
### 3. Обработать ответ в формате JSON
**Пример ответа**
```json
{
"debitTurnover": {
"amount": 0,
"currencyName": "RUR"
}
}
```
---
**← [Обновление сертификата](/products/alfa-api/documentation/articles/signature-encryption/articles/managing-certificates/articles/patch-certificates/patch-certificates)** | **[Подписание JSON ГОСТ-сертификатом](/products/alfa-api/documentation/articles/signature-encryption/articles/signature/articles/json-gost/json-gost) →**
]]>
</json_rsa_md>
</transport_signature>
</Транспортная_подпись_и_шифрование>
</payin_and_kyc>
View Git Blame Copy Permalink