Подписание и отправка в АБС (v2)

Завершающий шаг электронного подписания: проверка переданного фактора подтверждения (SMS-код / ЭЦП / др.) в EDS-сервисе, простановка подписи на платежах, перевод их по статусной модели и — при необходимости — отправка в АБС.

Endpoint	POST /domestic-payment/api/v2/signature/sign
Content-Type	application/json
Авторизация	OAuth2 / JWT (Bearer token)
Response status	200 OK

Поток платежа v2

Шаг 3 (финальный). После инициализации подписания. Проверить результат — получение платежа.

Параметры запроса

Параметр	Тип	Обяз.	Описание
needToSendToAbs	boolean	Нет (default true)	Если true — полностью подписанные платежи асинхронно отправляются в АБС (при наличии прав accessService.canSendToAbs()). Если false — платёж подписывается, но в АБС не отправляется

Тело запроса

Поле	Тип	Обяз.	Описание
authFactorType	enum (AuthFactorType)	Да	Тип фактора аутентификации, которым выполняется подпись
code	String	Условно	Код подтверждения (SMS-код / OTP). Сохраняется в state-machine как SIGN_VALUE_CODE
details[i].documentId	Long	Да	Идентификатор платежа, который подписывается
details[i].requestId	String	Условно	Идентификатор запроса в EDS, полученный на шаге init
details[i].certificateSN	String	Условно	Серийный номер сертификата ЭЦП (для подписи сертификатом). Сохраняется как CERTIFICATE_CN
details[i].signature	String	Условно	Значение подписи (подписанные данные) — для подписи через ЭЦП

Ответ

Поле	Тип	Описание
signingInfoList[i].documentId	String	Идентификатор документа (платежа)
signingInfoList[i].documentType	String	Тип документа
signingInfoList[i].documentSignStatus	enum (DocumentSignStatus)	Статус подписания документа
signingInfoList[i].initializedAuthFactor	enum (AuthFactorType)	Использованный фактор аутентификации
signingInfoList[i].signatureRuleSchemaFactors	LinkedHashSet<AuthFactorType>	Набор факторов, требуемых правилом/схемой подписи
signingInfoList[i].requestId	String	Идентификатор запроса в EDS
signingInfoList[i].phoneNumber	String	Маскированный номер телефона (если применимо)
signingInfoList[i].errorMessage	String	Текст ошибки, если подписание не удалось
signingInfoList[i].payload	String	Данные/полезная нагрузка документа
signingInfoList[i].signLevelComplete	boolean	Признак завершения текущего уровня подписи

Пример запроса

Показать запрос (SMS)

cURL

curl --location \
  'https://api-test.business-t.berekebank.kz/domestic-payment/api/v2/signature/sign?needToSendToAbs=true' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "authFactorType": "SMS",
  "code": "123456",
  "details": [
    { "documentId": 1001, "requestId": "a1b2c3d4-0000-1111-2222-333344445555" },
    { "documentId": 1002, "requestId": "b2c3d4e5-1111-2222-3333-444455556666" }
  ]
}'

Показать запрос (подпись сертификатом ЭЦП)

{
  "authFactorType": "Signature",
  "details": [
    {
      "documentId": 2001,
      "requestId": "c3d4e5f6-2222-3333-4444-555566667777",
      "certificateSN": "00112233445566778899AABBCCDDEEFF00112233",
      "signature": "<base64_signature>"
    }
  ]
}

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

Показать ответ

200 OK

{
  "signingInfoList": [
    {
      "documentId": "1001",
      "documentType": "PaymentOrder",
      "documentSignStatus": "SIGNED",
      "initializedAuthFactor": "SMS",
      "signLevelComplete": true
    },
    {
      "documentId": "1002",
      "documentType": "PaymentOrder",
      "documentSignStatus": "SIGNED_NEED_NEXT",
      "initializedAuthFactor": "SMS",
      "signLevelComplete": false
    }
  ]
}

Коды ошибок

Код	Условие
401 Unauthorized	Отсутствует/невалиден JWT
403 Forbidden	Нет доступа (нет привилегии)
409 Conflict	Нет привилегии или прав подписи: payments cannot be signed, check if you have sufficient access rights

Логика статусной модели

Статус	Категория	Действие
SIGNED	fullySignedIds	Подпись завершена → событие SIGN (IS_SIGN_COMPLETED=true), опц. отправка в АБС
SIGNED_NEED_NEXT	partiallySignedIds	Подписан текущий уровень, нужен следующий → событие SIGN (IS_SIGN_COMPLETED=false)
прочие	—	Не переводятся; результат отражается в ответе

Кейс	Поведение
Нет прав хотя бы на один платёж	SignatureValidationException
Не найдено ни одного валидного платежа	signingInfoList = []
Исключение при обращении к EDS	signingInfoList = []; статусы платежей не меняются
Многоуровневая подпись	При SIGNED_NEED_NEXT платёж ждёт следующего уровня, в АБС не отправляется
needToSendToAbs=false	Полностью подписанный платёж не отправляется в АБС
Нет прав canSendToAbs()	Даже при needToSendToAbs=true отправка в АБС не выполняется

Справочники

DocumentSignStatus

Значение	success	Описание
SIGNED	true	Документ полностью подписан
SIGNED_NEED_NEXT	true	Подписан текущим уровнем, требуется следующая подпись
INITIALIZED	true	Подписание инициализировано
POSTPONED	true	Подписание отложено
VALIDATION_FAILED	false	Не пройдена валидация (например, неверный код)
CURRENT_CUSTOMER_INVALID_CREDENTIALS	false	Неверные учётные данные пользователя
SIGN_EVENT_NOT_FOUND	false	Событие подписи не найдено
MISMATCH_SIGN_LEVEL	false	Несоответствие уровня подписи
CURRENT_CUSTOMER_LEVEL_ALREADY_SIGNED	false	Текущий уровень уже подписан данным пользователем
AUTH_FACTOR_NOT_FOUND	false	Фактор аутентификации не найден
RULE_ERROR	false	Ошибка правила подписи

AuthFactorType

Password, SMS, Signature, Generator, Phone, MySignSMS, MySignOTP, MySignPassword, Device, Biometry, QR.