**Примечание** > Наличие приложения Альфа-Бизнес Мобайл (АБМ) является условием входа по 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) ]]> **Внимание** > Токен обновления действует 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) ]]> **Внимание** > > - Токен доступа действует **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 | ]]> **Важно:** При формировании ссылки указывайте весь доступный `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. Пользователь проходит процедуру аутентификации.  2. Пользователь выбирает организацию (для ЮЛ; для ФЛ шаг пропускается).  3. Пользователь подписывает форму согласия.  --- ### Шаг 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) ]]> Для каждого Партнёра 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 | ]]> **Внимание** > Токен доступа действует **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) ]]> **Внимание** > Не забывайте заменить `{client_id}` на реальное значение, полученное после регистрации приложения на стороне Банка. --- ### Шаг 2. Аутентификация 1. В окне браузера отобразится страница аутентификации Alfa ID для ввода логина/пароля пользователя:  2. После ввода логина/пароля пользователя отобразится страница второго фактора аутентификации для ввода otp-кода (sms, push):  3. Необходимо ввести полученный на телефон otp-код (sms, push), и в адресной строке браузера отобразится код авторизации (`code`):  --- ### Шаг 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) ]]> [!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** | Массив операций области применения. | ]]> **Внимание** > > - Токен обновления действует **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) ]]> **Внимание** > Код авторизации по умолчанию действует **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) ]]> **⚠️ Внимание** > > - Токен доступа действует **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_ ]]> **Важно:** 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)_ ]]> • `access_token` — токен доступа;
• `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 | Код ошибки. Возможные значения:
• `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 / Расширение сценариев_ ]]> **Внимание для ИП:** > Права разработчика можно назначить от имени самого ИП (роль «Руководитель») или от имени любого другого сотрудника с ролью «Руководитель» (потребуется подтверждение от владельца ИП). ### Шаг 1. Перейдите в раздел «Пользователи и роли» На главном экране Альфа-Бизнес перейдите в настройки компании.   В разделе **Моя компания** выберите карточку **Пользователи и роли**.  ### Шаг 2. Создайте новую роль Нажмите **Создать роль**.  Укажите название роли (например, «Разработчик API»).  Далее настройте права. Рекомендуется создавать роль на основании прав руководителя, сбросив лишнее: 1. Нажмите **Снять все**, чтобы сбросить права руководителя.  2. В разделе **Обслуживание бизнеса** выберите **Alfa API**, указав необходимые права.  3. Нажмите **Создать роль** для сохранения. ### Шаг 3. Назначьте роль разработчику В разделе **Пользователи** нажмите на три точки справа от нужного сотрудника и выберите **Сменить роль**.  Выберите созданную роль и нажмите **Сменить**.  Подтвердите смену роли кодом из СМС.  После успешной смены в записи пользователя отобразится статус **Подключён**. Теперь пользователь может работать с Порталом разработчика.  --- ## Требования к полномочиям для авторизации Для корректной работы H2H-интеграций ключ доступа (`access_token` / `API Key`) должен получать пользователь, обладающий правами на конкретные сервисы: - **При использовании ACF H2H:** Авторизацию в Alfa ID должен проходить пользователь, у которого в Альфа-Бизнес настроены полномочия на использование выбранных `scopes`. - **При использовании API Key:** Выпускать ключ должен пользователь, имеющий права на те продукты, которые выбраны при выпуске ключа. **Пример:** Если у разработчика есть права на редактирование интеграций, но нет прав на «Просмотр выписки», то выпущенный им API Key для сервиса `transactions` работать не будет. ]]> <Вебхуки> • `ul_transaction_default` — получение выписки;
• `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) → ]]> • `ul_transaction_default` — получение выписки;
• `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 | Код ошибки:
• `insufficient_scope` — нет прав (настройки scope);
• `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) ]]> • `ul_transaction_default` — получение выписки;
• `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) ]]> • `ul_transaction_default` — получение выписки;
• `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_ ]]> • `ul_transaction_default` — получение выписки;
• `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) → ]]> **Важно:** Для предотвращения отправки Банком лишних 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**). ]]> **Важно** > Для создания вебхука с другим хостом необходимо удалить уже существующий вебхук. --- ### Допустимые значения 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) ]]> <Обмен_файлами> <Общая_информация> `GET /jp/v2/accounts/{accountNumber}/transactions/1C`
`GET /jp/v1/accounts/{accountNumber}/transactions/MT940`
`GET /jp/v1/correspondent-accounts/{accountNumber}/transactions`
`GET /jp/v1/statement/summary`
`POST /jp/v1/accounts/{accountNumber}/transactions/files/requests`
`GET /jp/v1/accounts/transactions/files/requests/{requestId}` | | escrow | Эскроу-счета 214-ФЗ. Резервирование | `GET /build-projects`
`POST /escrow-orders`
`GET /jp/v1/escrow-orders/{referenceID}`
`GET /jp/v1/escrow-orders`
`PATCH /escrow-orders/{referenceID}/execute`
`DELETE /escrow-orders/{referenceID}`
`POST /jp/v1/escrow-orders/{referenceID}/cancel`
`POST /jp/v1/escrow-orders-full` | | escrow-reports | Эскроу-счета 214-ФЗ. Формирование отчётов | `GET /jp/v1/escrow-reports/developers/build-projects`
`POST /jp/v1/escrow-reports` | | customer | Профиль организации | `GET /jp/v2/customer-info` | | payment | Платёжные поручения | `POST /jp/v2/payments`
`GET /jp/v2/payments/{externalId}/state`
`GET /jp/v1/payments/{externalId}`
`GET /jp/v1/payments/{externalId}/print-form`
`GET /jp/v1/payments/{externalId}/print-form/download`
`PATCH /jp/v2/payments/{externalId}/state` | | as-operation-with-selfemployed | Добавление самозанятых, получение справочных данных | `POST /semp/v1/agreement-pages`
`POST /semp/v1/selfemployed/registries/add-selfemployed`
`GET /semp/v1/selfemployed/registries/add-selfemployed/{requestId}`
`GET /semp/v1/dictionary/activities`
`GET /semp/v1/dictionary/regions`
`GET /semp/v1/selfemployed/lists`
`GET /semp/v1/selfemployed/{vatin}`
`PUT /semp/v1/selfemployed/{vatin}` | | as-selfemployed-fts-status | Статус самозанятого | `POST /semp/v1/selfemployed/taxpayer-statuses`
`GET /semp/v1/selfemployed/taxpayer-statuses/{requestId}` | | as-accrual-and-debt | Налоговые начисления, задолженности и пени самозанятого | `POST /semp/v1/selfemployed/accruals-and-debts`
`GET /semp/v1/selfemployed/accruals-and-debts/{requestId}`
`POST /semp/v1/selfemployed/payment-documents`
`GET /semp/v1/selfemployed/payment-documents/{requestId}`
`POST /semp/v1/selfemployed/income-for-period`
`GET /semp/v1/selfemployed/income-for-period/{requestId}`
`POST /semp/v1/selfemployed/income`
`GET /semp/v1/selfemployed/income/{requestId}`
`POST /semp/v1/selfemployed/taxpayer-account-info`
`GET /semp/v1/selfemployed/taxpayer-account-info/{requestId}` | | as-receipt-and-payout | Проведение выплат и формирование чеков, список банков-участников СБП | `POST /semp/v1/payouts/registries/receipts-and-payouts`
`GET /semp/v1/payouts/registries/{requestId}`
`GET /semp/v1/payouts`
`GET /semp/v1/dictionary/sbp-banks`
`GET /semp/v1/payouts/lists`
`GET /semp/v1/payouts/selfemployed/{vatin}`
`POST /semp/v1/payouts/registries/cancel-receipts`
`POST /semp/v1/payouts/registries/accept/{requestId}` | | as-receipt | Декларация доходов, аннулирование чеков | `POST /semp/v1/payouts/registries/receipts`
`POST /semp/v1/payouts/registries/cancel-receipts`
`GET /semp/v1/payouts/registries/cancel-receipts/{requestId}`
`GET /semp/v1/payouts/registries/{requestId}`
`GET /semp/v1/payouts`
`GET /semp/v1/payouts/lists`
`GET /semp/v1/payouts/selfemployed/{vatin}`
`POST /semp/v1/payouts/registries/accept/{requestId}` | | as-payout-with-check-status | Проведение выплат самозанятым, список банков-участников СБП | `POST /semp/v1/payouts/registries/with-selfemployed-check-status`
`GET /semp/v1/payouts/registries/{requestId}`
`GET /semp/v1/payouts`
`GET /semp/v1/dictionary/sbp-banks`
`GET /semp/v1/payouts/lists`
`GET /semp/v1/payouts/selfemployed/{vatin}`
`POST /semp/v1/payouts/registries/accept/{requestId}` | | as-payout | Осуществление выплат самозанятым | `POST /semp/v1/payouts/registries/payouts`
`GET /semp/v1/payouts/registries/{requestId}`
`GET /semp/v1/payouts`
`GET /semp/v1/dictionary/sbp-banks`
`GET /semp/v1/payouts/lists`
`GET /semp/v1/payouts/selfemployed/{vatin}`
`POST /semp/v1/payouts/registries/accept/{requestId}` | | sbp_terminals_reg | Приём оплаты через СБП | `GET /jp/v1/legal`
`GET /jp/v1/merchants/{merchantId}`
`POST /jp/v1/terminals` | | loan-applications | Кредиты | `POST /smart-loans/jp/v1/loan-applications`
`POST /loan-applications`
`GET /smart-loans/jp/v1/loan-applications/{dealId}/status` | | signature | Электронная подпись | `GET /jp/v3/signature/dn`
`GET /jp/v3/signature/dn/file`
`POST /jp/v3/signature/rsa-certificates/requests/issue`
`POST /jp/v3/signature/requests/{id}/operations`
`PUT /jp/v3/signature/requests/operations/{id}`
`GET /jp/v3/signature/requests/{id}`
`GET /jp/v3/signature/rsa-certificates/{id}`
`POST /jp/v3/signature/rsa-certificates/{id}/requests/activation`
`PUT /jp/v3/signature/sign-settings`
`POST /jp/v3/signature/rsa-certificates/{Id}/requests/switch`
`POST /jp/v3/signature/rsa-certificates/{Id}/requests/reissue`
`POST /jp/v3/signature/rsa-certificates/{Id}/requests/revocation`
`POST /jp/v3/signature/qes/requests`
`POST /jp/v3/signature/qes/requests/{Id}`
`PATCH /jp/v3/signature/qes/requests/{Id}`
`POST /jp/v3/signature/powers-of-attorney/requests`
`GET /jp/v3/signature/powers-of-attorney/requests/{id}/status`
`GET /jp/v3/signature/powers-of-attorney/requests/{id}` | | accounts | Счета | `GET /pp/v1/accounts`
`GET /pp/v1/accounts/{accountNumber}`
`GET /pp/v1/accounts/{accountNumber}/requisites`
`GET /jp/open-banking/v1.3/accounts`
`GET /jp/open-banking/v1.3/accounts/{accountId}/statements`
`POST /jp/open-banking/v1.3/statements`
`GET /jp/open-banking/v1.3/statements/{statementId}` | | cards | Карты | `GET /pp/v1/cards`
`GET /pp/v1/cards/{cardId}/tariffs`
`GET /pp/v1/cards/{cardId}/subscriptions` | | card-sec-actions | Тарифы и операции по карте | `GET /pp/v1/cards/{cardId}/actions`
`POST /pp/v1/cards/{cardId}/actions`
`PUT /pp/v1/cards/{cardId}/actions` | | operations-history | Истории операций | `GET /pp/v1/operations`
`GET /pp/v1/operations/{id}` | | reports-downloading | Получение документов | `GET /pp/v1/reports`
`GET /pp/v1/reports/{reportId}/body` | | debit-statements | Выписки по счёту | `POST /pp/v1/reports/type/account`
`POST /pp/v1/reports/type/account/balance/eng`
`POST /pp/v1/reports/type/account/balance/rus` | | credit-statements | Справки по кредитам | `POST /pp/v1/reports/type/credit/closed`
`POST /pp/v1/reports/type/credit/info`
`POST /pp/v1/reports/type/credit/statement` | | deposit-statements | Справка по депозиту | `POST /pp/v1/reports/type/deposit` | | limits-control | Лимиты по операциям | `GET /pp/v1/limits/general`
`GET /pp/v1/cards/{cardId}/user-limits`
`POST /pp/v1/cards/{cardId}/user-limits`
`DELETE /pp/v1/cards/{cardId}/user-limits/{limitId}` | | loyalty | Программа лояльности | `POST /pp/v1/bonus-accounts-transactions`
`GET /pp/v1/bonus-accounts`
`GET /pp/v1/bonus-accounts/{accountNumber}` | | b2c_sbp_payments | Платежи через СБП | `POST /b2cpay/jp/v1/payments`
`GET /b2cpay/jp/v1/payments`
`GET /b2cpay/jp/v1/payments/packages/{packageId}`
`POST /b2cpay/jp/v1/clients/checks`
`GET /b2cpay/jp/v1/clients/checks/{checkId}`
`GET /b2cpay/jp/v1/clients/info`
`GET /b2cpay/jp/v1/banks`
`GET /b2cpay/jp/v1/payments/download/{transactionId}` | | credit | Кредитные предложения | `GET /pp/v1/credit-offers` | | c2b-sbp | Оплата покупок через СБП | `POST /sbp/jp/v1/qrcs`
`POST /sbp/jp/v1/subscriptions`
`GET /sbp/jp/v1/qrc-status`
`POST /sbp/jp/v1/petitions`
`POST /sbp/jp/v1/terminals/{termNo}/cash-qrcs`
`POST /sbp/jp/v1/terminals/{termNo}/cash-qrcs/{qrcId}/activation`
`DELETE /sbp/jp/v1/terminals/{termNo}/cash-qrcs/{qrcId}/activation`
`POST /sbp/jp/v1/refund`
`GET /sbp/jp/v1/refund/status` | | b2b-sbp | Операции СБП для юрлиц | `POST /sbp/jp/v1/payment-urls/one-time-use`
`POST /sbp/jp/v1/payment-urls/reusable`
`GET /sbp/jp/v1/payment-urls`
`GET /sbp/jp/v1/payment-urls/{qrcId}/data`
`GET /sbp/jp/v1/incoming-payments`
`POST /sbp/jp/v1/outgoing-payments/one-pay`
`GET /sbp/jp/v1/outgoing-payments`
`GET /sbp/jp/v1/outgoing-payments/{outgoingPaymentId}/status`
`POST /sbp/jp/v1/payment-urls/batch`
`GET /sbp/jp/v1/payment-urls/batch/{batchId}`
`PATCH /sbp/jp/v1/payment-urls` | | digital-tariff | Дебетовая анкета | `POST /pp/v1/debit-cards/forms`
`POST /pp/v1/debit-cards/forms/{formId}/verification-sms`
`POST /pp/v1/debit-cards/forms/{formId}/resending-sms`
`POST /pp/v1/debit-cards/forms/{formId}/verification-passport` | | plastic-delivery | Доставка дебетовой карты | `POST /pp/v1/debit-cards/forms/{formId}/verification-sms`
`POST /pp/v1/debit-cards/forms/{formId}/resending-sms`
`GET /pp/v1/debit-cards/forms/{formId}/draft`
`GET /pp/v1/debit-cards/forms/{formId}/delivery-type`
`GET /pp/v1/debit-cards/forms/{formId}/time-slots`
`POST /pp/v1/debit-cards/forms/{formId}/time-slots`
`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`
`GET /jp/v1/salary-project/accounts/applications/{applicationId}`
`POST /jp/v1/salary-project/payroll/applications`
`GET /jp/v1/salary-project/payroll/applications/{applicationId}` | | loyalty-program | Получение бонусных номеров | `GET /pp/v1/bonus-numbers` | | payment-registries | Реестры рублёвых платежей | `POST /jp/v2/payments/registries`
`GET /jp/v2/payments/registries/{registryId}` | | invoices | Выставление счёта клиенту | `POST /jp/v1/payments/from-invoice`
`POST /jp/v2/payments/from-invoice-budget` | | factoring | Факторинг | `GET /aff/jp/v1/creditors/compliance`
`POST /aff/jp/v1/payments`
`POST /aff/jp/v1/registers`
`POST /aff/jp/v1/registers/sign`
`GET /aff/jp/v1/payments/{paymentId}`
`GET /aff/jp/v1/registers/{registerId}`
`GET /aff/jp/v1/registers/{registerId}/documents` | | beneficiaries | Информация о номинальных счетах и их контрагенты | `GET /na/jp/v1/nominal-accounts`
`GET /na/jp/v1/beneficiaries/requests/{requestId}/status`
`POST /na/jp/v1/beneficiaries`
`GET /na/jp/v1/beneficiaries`
`GET /na/jp/v1/beneficiaries/{beneficiaryId}`
`PUT /na/jp/v1/beneficiaries/{beneficiaryId}`
`POST /na/jp/v1/beneficiaries/{beneficiaryId}/scoring`
`POST /na/jp/v1/beneficiaries/{beneficiaryId}/requisites`
`GET /na/jp/v1/beneficiaries/{beneficiaryId}/requisites`
`PATCH /na/jp/v1/beneficiaries/{beneficiaryId}/requisites/{requisiteId}`
`GET /na/jp/v1/beneficiaries/{beneficiaryId}/balance`
`GET /na/jp/v1/beneficiaries/{beneficiaryId}/transactions`
`POST /na/jp/v1/universal-recipients`
`GET /na/jp/v1/universal-recipients`
`GET/na/jp/v1/universal-recipients/{universalRecipientId}`
`POST /na/jp/v1/universal-recipients/{universalRecipientId}/requisites`
`GET /na/jp/v1/universal-recipients/{universalRecipientId}/requisites`
`PATCH /na/jp/v1/universal-recipients/{universalRecipientId}/requisites/{requisiteId}` | | deals | Безопасные сделки | `POST /na/jp/v1/deals`
`GET /na/jp/v1/deals`
`GET /na/jp/v1/deals/{dealId}`
`PATCH /na/jp/v1/deals/{dealId}/is-valid`
`GET /na/jp/v1/deals/{dealId}/payoffs`
`PATCH /na/jp/v1/deals/action`
`POST /na/jp/v1/deals/steps`
`GET /na/jp/v1/deals/{dealId}/requests/{requestId}/status`
`GET /na/jp/v1/deals/{dealId}/steps`
`GET /na/jp/v1/deals/{dealId}/steps/{stepId}`
`PATCH /na/jp/v1/deals/steps/contractors`
`GET /na/jp/v1/deals/{dealId}/steps/{stepId}/contractors` | | beneficiary-payments | Идентификация пополнений номинального счёта и выплаты с него | `GET /na/jp/v1/unidentified-transactions`
`POST /na/jp/v1/unidentified-transactions/{id}/identify`
`GET /na/jp/v1/unidentified-transactions/{id}/identify/{identifyId}`
`POST /na/jp/v1/unidentified-transactions/{id}/refunds`
`GET /na/jp/v1/unidentified-transactions/{id}/refunds/{refundId}`
`POST /na/jp/v1/payoffs`
`GET /na/jp/v1/payoffs/{payoffId}/status`
`PATCH /na/jp/v1/payoffs/{payoffId}/accept`
`GET /na/jp/v1/payoffs/{payoffId}`
`POST /na/jp/v1/tax-refund`
`GET /na/jp/v1/tax-refund/{taxRefundId}/status`
`PATCH /na/jp/v1/tax-refund/{taxRefundId}/accept` | ]]> <Сертификаты_Минцифры> «Terminal», чтобы открыть терминал.  2. Убедитесь, что файлы сертификатов «russian_trusted_root_ca_pem.crt» и «russian_trusted_sub_ca_pem.crt» находятся в директории «Downloads». Для проверки перейдите в неё с помощью `cd` и вызовите команду `ls` для отображения списка файлов.  3. Скопируйте корневой сертификат в каталог `/usr/share/pki/ca-trust-source/anchors/` . Выполните команду `sudo cp russian_trusted_root_ca_pem.crt /usr/share/pki/ca-trust-source/anchors` . 4. Введите пароль суперпользователя.  5. Cкопируйте в этот же каталог выпускающий сертификат. Выполните команду `sudo cp russian_trusted_sub_ca_pem.crt /usr/share/pki/ca-trust-source/anchors` . 6. Обновите общесистемное хранилище сертификатов командой `sudo update-ca-trust` .  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».  Очистите кэш вашего браузераОчистите кэш браузера на устройстве, с которого осуществляется доступ. Это необходимо для корректной работы с ресурсами, защищёнными сертификатами безопасности Минцифры. ## 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».  Очистите кэш вашего браузераОчистите кэш браузера на устройстве, с которого осуществляется доступ. Это необходимо для корректной работы с ресурсами, защищёнными сертификатами безопасности Минцифры. [Сертификаты для 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) ]]> <Песочница> • `ul_transaction_default` — получение выписки;
• `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) → ]]> **Внимание** > Обработка негативных сценариев (например, ошибки валидации или доступа) **в песочнице** может отличаться от обработки в промышленной среде и спецификации тестируемого метода. --- ## Подготовка к работе в песочнице Для начала работы в песочнице пройдите следующие шаги: 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) ]]> **Внимание** > Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [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) ]]> **⚠️ Внимание** > Способ защиты данных определяется настройками интеграции. Для уточнения настроек или их изменения напишите на [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 | Детальное описание ошибки | --- *Примечание: Значения параметров ошибок могут изменяться. Рекомендуется предусмотреть стандартную обработку ошибок.* ]]> **Внимание** > Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке вашей интеграции или запроса для установления нужных настроек необходимо написать на почту [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 XmlElementValue2 H6jGW+bKLwvQ9xxbhZ6jNYRHtupT4aJ4jjlLh4W8svK0w5G7ZXf4OxqRR0t2l6aYOpNBdN2Q0+2T 1LXyadtnz7XJ7QYXNXrnWNcq7mOxM5Lj5bBQa2JPZSiMkp1lsnAV/LFDAJ+Uhruj3mFQxjiFpJLR W/vRJzmRv925xXWopb94PFvP9mjtAwPXtBGEL5rqJICabzVo8+1BfPwFF5+8sqYzT74mmJIQmeFm FiYVMNive5lRxlt7nXEgS4iENF1dXq5+prCPloms8hIX6I4HQo3Jn+G37Os57nv8g61gk4jnu2OK bOsZasIzXSLVG2GrCbDQ+HFjWs3Fgg4JOkULfw== xgVcc1UZhuWRp4/8K0OAVLuQUhySUtJg7mYo78Od+WWidnIZr2XZUvPqwxOpFwRY MIIGATCCBLWgAwIBAgITYQADiqqgHk1/OTmNhAABAAOKqjBBBgkqhkiG9w0BAQowNKAPMA0GCWCG... (урезано для краткости) XmlElementValue1 ``` --- ### Ошибки | Код | Описание | Возможные значения `Error` | | :------ | :-------------------- | :------------------------------------------------------------ | | **400** | Bad Request | `invalid_request` — неверные входные параметры | | **401** | Unauthorized | `invalid_token` — токен просрочен, отозван или недействителен | | **404** | Not Found | `unknown_endpoint` — эндпоинт не найден или неактивен | | **500** | Internal Server Error | `internal_error` — внутренняя ошибка сервиса | #### Пример ошибки 400 ```xml invalid_request Authorization header is not present in request headers ``` --- _Значения параметров ошибок могут изменяться. Рекомендуем предусмотреть стандартную обработку ошибок, не описанных в текущей версии документации._ ]]> <Подключение_к_Alfa_API> [!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_ ]]> ### Внимание > Если вы ещё не являетесь клиентом Альфа-Банка, то для подключения к 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) ]]> **Внимание** > Данный файл уже содержит все необходимые атрибуты и не требует внесения изменений. Все остальные параметры будут введены вручную через терминал в процессе генерации закрытого ключа и запроса на сертификат. > **Важно** > Если возникает ошибка `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) → ]]> <Портал_разработчика> **Внимание** > В случае если у вас ИП, права разработчика можно назначить: > > - от имени самого индивидуального предпринимателя с ролью «Руководитель»; > - от имени любого другого сотрудника ИП с ролью «Руководитель». В таком случае потребуется подтверждение назначения от владельца ИП. Подробнее в инструкции ниже. --- ## Инструкция по настройке прав ### Шаг 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`) работать не будет. Ключ должен выпускать либо руководитель, либо сотрудник с полным доступом к нужным данным. ]]> **Важно** > Выпускать `API Key` необходимо пользователю, у которого в Альфа-Бизнес настроены соответствующие полномочия на использование выбранных при выпуске ключа продуктов и сервисов. Если у пользователя отсутствуют эти полномочия, руководителю организации необходимо выдать их пользователю в Альфа-Бизнес (в разделе **Профиль** – **Пользователи и роли**) или выпустить ключ самому. ### Шаг 1. Нажмите "Выпустить API Key" Нажмите **Выпустить ключ** в правой части карточки H2H-интеграции.  ### Шаг 2. Заполните данные для API Key Укажите IP-адреса, с которых будут отправляться запросы с использованием `API Key`. Отправка запросов с использованием `API Key` будет доступна только с указанных IP-адресов. Для одного API Key вы можете указать не более 20 IP-адресов.  Укажите сервисы и продукты, доступ к которым вы хотите получать с помощью `API Key`. Вам будут доступны сервисы и продукты из набора `scopes` редактируемой H2H-интеграции, доступ к которым возможен с помощью `API Key`.  Далее проверьте и сохраните внесённые изменения. ### Шаг 3. Скопируйте и сохраните API Key После завершения выпуска `API Key` вы получите уведомление. Скопируйте его и вручную добавьте в ваши рабочие инструменты так, чтобы при отправке запросов по H2H-интеграции в запросах передавался заголовок `Authorization: ApiKey {API Key}`.  **Срок действия:** Срок действия `API Key` неограничен, но ключ будет автоматически отозван, если с момента последнего запроса прошло более **30 дней**. В случае потери данных либо компрометации ключа вы можете перевыпустить его. Также вы всегда можете отозвать `API Key`, если больше не хотите использовать упрощённый способ авторизации. --- ## Перевыпуск API Key ### Шаг 1. Нажмите "Перевыпустить API Key" Нажмите на три точки в правом верхнем углу карточки H2H-интеграции и выберите **Перевыпустить API Key**.  ### Шаг 2. Отредактируйте данные для API Key При необходимости отредактируйте данные для `API Key`.  Далее проверьте внесённые изменения и нажмите «Перевыпустить». ### Шаг 3. Скопируйте и сохраните API Key После перевыпуска `API Key` вы получите уведомление. Вам будет необходимо скопировать его и заменить в ваших рабочих инструментах. При перевыпуске `API Key` старый ключ, привязанный к этой интеграции, будет автоматически отозван. Срок действия `API Key` неограничен, но ключ будет автоматически отозван, если с момента последнего запроса прошло более 30 дней.  --- ## Отзыв API Key Для отзыва ключа доступа нажмите на три точки в правом верхнем углу карточки интеграции, выберите **Отозвать API Key** и подтвердите свои действия.   В результате отзыва ключа упрощённая авторизация будет недоступна. При необходимости вы всегда можете выпустить новый `API Key`. ]]> **Внимание** > Одновременно у вас может быть не более 5 промышленных интеграций. Нажмите **Создать интеграцию** в степпере или в списке интеграций, находясь в рабочей среде «Пром» (для выбора рабочей среды используйте переключатель в правом верхнем углу Портала разработчика). **Важно!** В случае если вы работаете в режиме группы компаний, перед созданием новой интеграции необходимо перейти в профиль пользователя и выбрать компанию, для которой вы хотите создать интеграцию.  --- ### Шаг 2. Выберите тип интеграции  --- ### Шаг 3. Заполните основную информацию Укажите название интеграции (рекомендуется использовать то же название, что и у соответствующей тестовой интеграции), `redirect_uri` и тип клиентов (выбор типа клиентов доступен только для партнёрских интеграций). В одной интеграции вы можете указать не более 20 `redirect_uri`.  --- ### Шаг 4. Выберите сервисы и продукты > **Важно** > Вам будут доступны сервисы и продукты, по которым при тестировании было выполнено не менее одного успешного запроса в песочнице.  --- ### Шаг 5. Завершите создание промышленной интеграции Проверьте параметры интеграции перед её сохранением. Для создания интеграции потребуется некоторое время. После завершения создания промышленной интеграции вы получите уведомление:  --- ### Шаг 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`. Для этого нажмите на иконку в карточке интеграции:  Скопируйте `client_secret` и добавьте его в ваши рабочие инструменты. Получить его можно также с помощью [метода](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret).  После того как вы получите `client_secret`, интеграция перейдет в статус **«Активна»** и будет доступна к использованию в промышленной среде. --- ## Подключение новых продуктов к текущей промышленной интеграции Для подключения новых продуктов и сервисов к промышленной интеграции сначала добавьте новые `scopes` в режиме редактирования тестовой интеграции и протестируйте их в песочнице. После успешного тестирования отредактируйте промышленную интеграцию, добавив новые `scopes`. После этого новые продукты или сервисы будут доступны в промышленной среде. ]]> **Внимание** > Для работы с порталом вашему разработчику необходимо получить права на управление интеграциями Alfa API. Как их назначить, описано [в статье Права доступа](/products/alfa-api/documentation/articles/selfservice/articles/access-rights/access-rights). --- ## Запуск первой промышленной интеграции 1. **Войдите на Портал разработчика** Вход осуществляется через Портал документации по кнопке **Войти** и возможен только под учётной записью сотрудника организации, подключённой к Alfa API.  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). --- ## Выбор рабочей среды На Портале разработчика предусмотрены две рабочие среды: - **«Песочница»** — для редактирования тестовых интеграций. - **«Пром»** — для управления промышленными интеграциями. Выбор рабочей среды осуществляется с помощью переключателя в правом верхнем углу портала.  --- ## Работа с группой компаний Пользователи с доступом к интеграциям нескольких компаний могут работать в двух режимах: группы компаний или одной выбранной компании. Это позволяет работать с интеграциями всех доступных компаний в едином окне. ### Как переключить режим: 1. Перейдите в профиль пользователя в правом верхнем углу Портала разработчика.  2. Выберите режим отображения компаний: - Карточка **Все компании** — чтобы работать с интеграциями всех компаний одновременно. В этом режиме доступна единая таблица со всеми интеграциями. - Карточка **конкретной компании** — чтобы работать только с интеграциями выбранной организации.   --- **Далее:** [Права доступа](/products/alfa-api/documentation/articles/selfservice/articles/access-rights/access-rights) | [Client secret](/products/alfa-api/documentation/articles/connection/articles/clientsecret/clientsecret) ]]> <продукты_и_сервисы> <Номинальные_счета> • `true` — активен;
• `false` — деактивирован. | --- ### Ошибки #### 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` — недостаточно прав (несоответствие настроек scope). | | **error_description** | `string` (optional) | Описание ошибки. | #### 404 (Not Found) | Атрибут | Тип | Описание | | :-------------------- | :------------------ | :-------------------------------------------------------------------------------- | | **error** | `string` (required) | Код ошибки. Значения:
• `unknown_endpoint` — эндпоинт не найден или неактивен. | | **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/nominal-accounts/articles/signature/signature) - → [Контрагенты: Как это работает](/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/intro/intro) ]]> 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) ]]> **Внимание** > Для использования сервиса у вас должен быть открыт номинальный счёт в Альфа-Банке. Сервис позволяет владельцам номинального счета совершать операции с денежными средствами, права на которые принадлежат другому лицу — бенефициару. ### Кому подойдёт сервис - Финансовым и инвестиционным платформам; - Маркетплейсам; - Платформам, работающим с самозанятыми и фрилансерами; - Для индивидуальных проектов, где требуется обеспечить безопасность проведения расчётов между участниками сделки. ### Как это работает Владелец счёта добавляет сведения о бенефициарах номинального счёта и универсальных реципиентах — [раздел Контрагенты](/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) ]]> **Внимание** > Для подписания необходимо использовать 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) ]]> <Безопасные_сделки> **Важно:** Для создания сделки необходимо наличие открытого номинального счёта в Банке. --- ## Параметры запроса ### 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) ]]> **Важно** > > - Создание этапа сделки происходит в синхронном режиме. > - Завершение этапа сделки происходит в асинхронном режиме. Метод позволяет создать и завершить этап сделки. #### Создание этапа сделки После [регистрации сделки](/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) ]]> **Важно** > Завершить сделку можно, только если все [этапы сделки завершены](/products/alfa-api/documentation/articles/nominal-accounts/articles/deals/articles/add-step/v1/add-step). --- ### Параметры запроса #### 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 | Атрибут | Описание | | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **dealId**
_string, required_ | Идентификатор сделки | | **action**
_string, required_ | Действие по сделке. Возможные значения:

• `ACCEPT` — подтвердить сделку;
• `COMPLETE` — завершить сделку;
• `CANCEL` — отменить сделку.

| | **digestSignatures**
_array of objects, required_ | Электронная подпись УЛ клиента | | **└ base64Encoded**
_string, required_ | Значение электронной подписи, закодированное в Base64 | | **└ signatureType**
_string, required_ | Тип электронной подписи. Возможные значения:

• `rsa` — RSA;
• `kep` — КЭП.

| --- ### Пример запроса ```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**
_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` — нет прав на использование сервиса (настройки scope) | | **error_description**
_string, optional_ | Описание ошибки | **404 Not Found** | Атрибут | Описание | | :--- | :--- | | **error**
_string, required_ | Код ошибки: `unknown_endpoint` — эндпоинт не найден или неактивен | | **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/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) ]]> **Важно** > Проверка доступна только для сделок в статусе `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) ]]> • `DEPONENT` — плательщик;
• `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** | Признак вывода денег на виртуальный счёт:
• `true` — оставить в рамках номинального счёта;
• `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 | Нет тела ответа | ]]> • `EXTERNAL` — внешний (выплата с номинального счёта)
• `INTERNAL` — внутренний (выплата внутри номинального счёта) | | **deponentId** | string | required | Идентификатор депонента | | **recipientId** | string | required | Идентификатор реципиента | | **amount** | string | required | Сумма в рублях | | **status** | string | required | Статус запроса:
• `PENDING` — запрос в процессе обработки
• `MANUAL_ACCEPTANCE` — ожидание ручного подтверждения запроса-дубля
• `AWAIT_EXTERNAL` — ожидание исполнения внешнего платежа
• `FAILED` — ошибка обработки
• `FAILED_DUPLICATE` — дубль отклонен
• `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) ]]> • `DRAFT` — принят для последующей обработки;
• `ACTIVE` — успешно обработан;
• `BLOCKED` — ошибка в процессе обработки;
• `IN_PROGRESS` — в процессе обработки;
• `PAYMENT_FAILED` — платёж завершился неудачей;
• `CLOSED` — отменен;
• `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) ]]> **Примечание** > Депонент — это участник сделки, который выступает в качестве плательщика, реципиент — это получатель денежных средств. Механизм безопасных сделок используется для осуществления расчётов, при которых средства депонента временно холдируются и переходят к реципиенту только после выполнения условия сделки. При этом Банк ведет учёт (биллинг) денежных средств каждого бенефициара. Для работы с безопасными сделками предварительно необходимо: 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) ]]> **Внимание** > Действия с участниками сделки возможны только для сделки в статусе `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_ ]]> <Выплаты> **Важно** > > У бенефициара должен быть положительный баланс на налоговом виртуальном счёте. - **Вывод собственных средств бенефициара с номинального счёта.** Позволяет вывести с номинального счёта денежные средства бенефициара без создания сделки. - **Выплата с целью уплаты налога на профессиональный доход за исполнителя.** Позволяет аккумулировать денежные средства на виртуальном налоговом счёте исполнителя и перевести денежные средства бенефициара, задепонированные с целью уплаты налога на профессиональный доход за исполнителя, на счёт в управление казначейства. - **Возврат денежных средств с налогового виртуального кошелька.** Позволяет вернуть денежные средства бенефициара, задепонированные с целью уплаты налога на профессиональный доход за исполнителя, если оплата налога не потребовалась. ### Механизм возврата денежных средств с налогового виртуального кошелька 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) ]]> • `true` – продолжить обработку;
• `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 | Да | Статус обработки:
• `true` – обработка продолжена;
• `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) ]]> [!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) ]]> • `true` – продолжить обработку;
• `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) - **Раздел:** Номинальные счета / Выплаты ]]> [!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 | Признак вывода денег на основной виртуальный счёт.
• `true` — оставить в рамках номинального счёта;
• `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) ]]> <Идентификация_пополнений> `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 | Идентификатор операции пополнения, по которой необходимо вернуть денежные средства | | **refundId**
`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**
`string`, required | Уникальный идентификатор запроса на возврат неидентифицированного пополнения | | **status**
`string`, required | Статус запроса. Принимает возможные значения:
• `PENDING` - запрос в процессе обработки;
• `FAILED` - обработка запроса завершилась ошибкой;
• `COMPLETE` - обработка запроса завершилась успешно | | **description**
`string`, optional | Описание причины, по которой запрос завершился ошибкой.
**Примечание:** поле доступно только при статусе запроса `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) ]]> <Контрагенты> • `PENDING` – запрос в процессе обработки;
• `FAILED` – обработка запроса завершилась ошибкой;
• `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) ]]> **Важно** > Биллинг для универсальных реципиентов не проводится, поскольку они не являются бенефициарами и не могут иметь собственных средств на номинальном счёте. > **Внимание** > Учёт денежных средств на виртуальных счетах бенефициаров будет вестись корректно только при условии, что владелец номинального счёта не использует другие каналы вывода средств (банк-клиент, бумажные поручения и др.). Для учёта денежных средств бенефициара — биллинга на стороне Банка — используются **виртуальные счета**. При регистрации бенефициара по умолчанию создается **основной виртуальный счёт**. На нём учитываются денежные средства, права на которые принадлежат бенефициару. В случае необходимости уплаты налога (при [добавлении бенефициара в качестве реципиента в этап сделки](/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). ]]> <Бенефициары> **Важно** > В зависимости от типа бенефициара необходимо по-разному заполнять поля запроса. --- ### Параметры запроса #### 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**: Сервис временно недоступен. ]]> **Важно** > Первые добавленные реквизиты автоматически назначаются основными для бенефициара. --- ## Параметры запроса ### 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 | Да | Тип платёжного реквизита. Возможные значения:
• `ACCOUNT` — реквизиты счёта;
• `CARD` — номер карты (токен);
• `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) → ]]> **Важно** > Если бенефициар не пройдет проверку, он будет деактивирован в системе. --- ## Параметры запроса ### 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 | Статус запроса. Возможные значения:
• `PENDING` – запрос в процессе обработки;
• `FAILED` – обработка запроса завершилась ошибкой;
• `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) ]]> _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 | Атрибут | Описание | | :---------------------------------------- | :------------------------ | | **beneficiaryId**
_string, required_ | Идентификатор бенефициара | ### BODY | Атрибут | Тип | Описание | | :---------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | **type** | _string, required_ | Тип контрагента. Возможные значения:

• `FL_RESIDENT` — физ. лицо, резидент;
• `UL_RESIDENT` — юр. лицо, резидент.

| | **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_ | Статус запроса:

• `PENDING` — в процессе обработки;
• `FAILED` — ошибка обработки;
• `COMPLETE` — успешно завершено.

| ### Коды ошибок | Код | Описание | Тело ответа (основные атрибуты) | | :------ | :------------------ | :------------------------------ | | **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) ]]> **Важно** > Необходимо, чтобы хотя бы один из активных реквизитов бенефициара был основным. --- ### Параметры запроса #### 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) | Признак основного платёжного реквизита.
• `true` - основной;
• `false` - неосновной | | **isActive** | boolean (optional) | Признак активности платёжного реквизита.
• `true` - активен;
• `false` - деактивирован | | **digestSignatures** | array of objects (required) | Электронная подпись УЛ клиента | **Объект digestSignatures:** | Атрибут | Тип | Описание | | :--- | :--- | :--- | | **base64Encoded** | string (required) | Значение электронной подписи, закодированное в Base64 | | **signatureType** | string (required) | Тип электронной подписи:
• `rsa` - RSA;
• `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) ]]> <Универсальные_реципиенты> **Важно** > Первые добавленные реквизиты автоматически назначаются основными для универсального реципиента. --- ## Параметры запроса ### 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) | Тип платёжного реквизита. Возможные значения:
• `ACCOUNT` — реквизиты счёта;
• `CARD` — номер карты (токен);
• `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) ]]> • `FL_RESIDENT` — физ. лицо, резидент;
• `UL_RESIDENT` — юр. лицо, резидент | | **digestSignatures** | array of objects | Да | Электронная подпись УЛ клиента | **Объект digestSignatures:** | Атрибут | Тип | Обяз. | Описание | | :--- | :--- | :--- | :--- | | **base64Encoded** | string | Да | Значение электронной подписи, закодированное в Base64 | | **signatureType** | string | Да | Тип электронной подписи. Возможные значения:
• `rsa` — RSA;
• `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 | Да | Статус запроса. Принимает значения:
• `PENDING` – запрос в процессе обработки;
• `FAILED` – ошибка обработки;
• `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) ]]> **Важно:** Необходимо, чтобы хотя бы один из активных реквизитов универсального реципиента был основным. --- ## Параметры запроса ### 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 Сервис временно недоступен. Тело ответа отсутствует. ]]> • `ACCOUNT` — реквизиты счёта;
• `CARD` — номер карты (токен);
• `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** | Признак основного платёжного реквизита:
• `true` — основной;
• `false` — неосновной | boolean | required | | **isActive** | Признак активности платёжного реквизита:
• `true` — активен;
• `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 | Нет тела ответа | ]]> • `true` — является бенефициаром;
• `false` — является универсальным реципиентом. | | **type** | string | Да | Тип контрагента:
• `FL_RESIDENT` — физ. лицо, резидент;
• `UL_RESIDENT` — юр. лицо, резидент. | | **isActive** | boolean | Да | Признак активности бенефициара:
• `true` — активен;
• `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) ]]> <Транспортная_подпись_и_шифрование> [!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" } } ``` ]]> [!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) ]]> **Внимание** > Для получения сертификата, выпущенного через сервис [«Электронная подпись»](/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 | Статус. Возможные значения:
• `ACTIVE` - активен;
• `REVOKED` - аннулирован;
• `DELETED` - удалён | | **certificateBody** | `string` | required | Тело сертификата в виде base64-строки | | **type** | `string` | required | Тип сертификата. Возможные значения:
• `SIGNATURE` - для подписи;
• `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) ]]> • `ACTIVE` — сертификат активен;
• `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_ ]]> • `SIGNATURE` — для подписи;
• `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) → ]]> **Внимание** > Для подписания сообщения необходимо предварительно загрузить сертификат, используя следующий [метод](/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) ]]> **Внимание** > Для подписания сообщения необходимо предварительно выпустить сертификат в УЦ Альфа-Банка, используя сервис ["Электронная подпись"](/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.`
`eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.`
`Y1NqCkRjjtJ2GrVsW-a627g6ObfpEaKw-H92QVgVWqL9i7d1SHyaXVghF4ZNZAlrFasKySnKYZf2Ik8zVIlLN7hqeYxoeTdE2OLbiQdvPrD-JnI2Qzh0K32vcImwgGcpq2lt_QKx1f_YmaSRhH9O3xZePVcmFGCqhl_0prQSwcR4g-yuhidvspaF48QlUHcEaZ65Cr8hdyc6g9HPZDy7ipU-zCAZGgK0enxfWn4Osyqch8RRDIsfLG7OJ4wbYwYB22LYO5UaxX8Zy_R2jSnKlNghxQwSqJGxizMFhFhdCrATGTo-ysI-7OtfremD8YNj7z_iYciyYbtAgV0ZodEvMA` | **header**
`{"kid": "alfa-test-jwt", "typ": "JWT", "alg": "RS256"}`

**payload**
`{"debitTurnover": {"amount": 0, "currencyName": "RUR"}}`

**verify signature**
`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) →** ]]>