ym88659208ym87991671
Письма свободного формата | Документация SmartMarket
Skip to main content

Письма свободного формата

Для обращения к ресурсу необходимо отправлять запрос на:

  • Тестовый контур https://edupirfintech.sberbank.ru:9443

  • Промышленный контур https://fintech.sberbank.ru:9443

Создание документа

Ресурс /v1/generic-letters/to-bank позволяет создавать документ «Письмо в Банк по собственной/дочерней организации».

Шаги

1. Получить AccessToken.

2. Сформировать ЭП.

3. Отправить запрос.

4. Получить статус.

5. Получить документ.

Для создания рублевого платежного поручения необходимо отправить POST-запрос (/v1/generic-letters/to-bank), в котором передать авторизационный токен к данным собственной (дочерней) организации (Access Token) и реквизиты одного платежного поручения. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис GENERIC_LETTER_TO_BANK.

Модель запроса

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token собственной (дочерней) организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
GenericLetter {
attachments (Array[Attachment], optional)Вложенные документы,
bankComment (string, optional, read only)Банковский комментарий к статусу документа,
bankStatus (string, optional, read only)Статус документа,
bfAttachments (Array[BfAttachment])Идентификатор (-ы) больших файлов,
crmNumber (string, optional, read only)Номер ПСФ в CRM,
date (string)Дата составления документа,
digestSignatures (Array[Signature], optional)Электронные подписи по дайджесту документа,
externalId (string)Идентификатор документа, присвоенный партнёром (UUID),
integrationId (string, optional, read only)Идентификатор цепочки,
number (string, optional)Номер документа,
text (string)Текст письма. По умолчанию заполняется шаблоном в соответствии с справочником "GenericLetterType" из поля "template" либо в свободном формате, если шаблон отсутствует в справочнике,
typeCode (string)Тема письма. Заполняется из справочника "GenericLetterType" из поля systemName в соответствии с требуемой темой описанной в поле "letterType",
typeName (string, optional, read only)Тип письма
}Attachment {Вложенные документы. Допустимость заполнения определяется значением "attachmentsEnabled"=1 из справочника "GenericLetterType"
content (Array[string], optional)Вложение закодированное в Base64,
mimeType (string, optional)Тип формат файла,
name (string, optional)Имя файла
}BfAttachment {Большие файлы. Допустимость заполнения определяется значением "attachmentsEnabledBF"=1 из справочника "GenericLetterType"
fileId (string, optional)Уникальный идентификатор файла,
fileName (string, optional, read only)Имя файла
}Signature {
base64Encoded (string)Значение электронной подписи, закодированное в Base64,
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
"attachments":[
{
"content":"dGVzdA==",
"mimeType":"image/jpeg",
"name":"тест.jpg"
}
],
"bankComment":"string",
"bankStatus":"string",
"bfAttachments":[
{
"fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"fileName":"SB_7718830000_40702810038290010000_T18.txt"
}
],
"crmNumber":"190410-0033-142400",
"date":"2018-12-31",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"integrationId":"55daccdf-de87-3879-976c-8b8415c8caf9",
"number":"1",
"text":"У меня все хорошо",
"typeCode":"payment_recall",
"typeName":"Направить запрос по 115-ФЗ"
}

Передача электронной подписи

Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature (все поля обязательны):

Наименования поляОписания поляПример
base64Encoded (string)Значение ЭП документаHlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==
certificateUuid (string)Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto)22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

Для документов можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа.

Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля, когда пользователь Партнера создается в Банке.

Алгоритм сортировки дайджеста

danger

Теги дайджеста должны быть отсортированы по алфавиту.

В таблице bfAttachments UUID-ы сортируются по возрастанию.
В дайджесте не указываются значения Number и блок linkedDocs.

Формат дайджеста

Наименование поляОписание поляПример
dateДата документа2019-10-17
externalIdИдентификатор документа в организации-партнёре42a6dd89-103a-4d7a-8e9b-1ba4b521f5f6
textТекст письмаТекст письма
typeCodeТип ПСФpayment_recall
TABLESЗначение указывается при наличии UUID-ов больших файлов
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов8e9d6ce6-d5d7-4d81-96b8-9af0e7e17694
#Разделитель значений UUID-ов больших файлов
fileIdUUID больших файлов13d32a7b-28c9-4895-b0e1-9848a8988db9
#Разделитель значений UUID-ов больших файлов

Пример дайджеста

date=2019-10-17
externalId=42a6dd89-103a-4d7a-8e9b-1ba4b521f5f6
text=Текст письма
typeCode=payment_recall
TABLES
Table=BfAttachments
fileId=8e9d6ce6-d5d7-4d81-96b8-9af0e7e17694
#
fileId=13d32a7b-28c9-4895-b0e1-9848a8988db9
#

Получение статуса документа

Ресурс /v1/generic-letters/to-bank/{externalId}/state позволяет получить статус ранее отправленного электронного документа.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения статуса документа необходимо отправить GET-запрос (/v1/generic-letters/to-bank/{externalId}/state),в котором передать авторизационный токен к данным (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис GENERIC_LETTER_TO_BANK.

Модель запроса

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId (String)Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: /' --header 
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/generic-letters/to-bank/ffffffff-fffa-458e-ad92-fff9497303ba/state'

Модель ответа

НаименованиеОписание
DocState {
bankComment (string, optional, read only)Банковский комментарий к статусу документа,
bankStatus (string, optional)Статус документа,
channelInfo (string, optional, read only)Комментарий, специфичный для документа, полученного по данному каналу,
}

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

{
"bankStatus": "string",
"bankComment": "string",
"channelInfo": "string",
}

Статусы обработки документов

Код состояние документаНаименование статусаНазначение кода состояния
Промежуточные статусы/Продолжать опрашивать
ACCEPTEDПринятЭлектронный документ принят на стороне Банка
ACCEPTED_BY_ABSПринят АБСЭлектронный документ был принят к обработке в АБС Банка
CREATEDСозданДокумент записан в БД, проверки не выполнялись
DELIVEREDДоставленЗапрос доставлен в ДБО и взят в обработку
EXPORTEDВыгруженЭлектронный документ выгружен Банком в АБС
IN_WORKВ работеДокумент в работе
PARTSIGNEDЧастично подписанЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей.
PREPARING_ANSWERПодготовка ответаПодготовка ответа
RECEIVED_BY_CRMПринят CRMДокумент принят CRM
REGISTERED_CRMЗарегистрирован в CRMДокумент зарегистрирован CRM
SIGNEDПодписанЭД подписан предусмотренным для него комплектом подписей. Документ с этим статусом может быть отправлен для исполнения в банк либо с документа может быть снята подпись (ЭД возвращается к статусу "Частично подписан").
Окончательные статусы/Прекратить опрос
CHECKERRORОшибка контроляЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками.
REQUISITEERRORОшибка реквизитовЭД не прошел проверки при приеме на стороне Банка
REFUSEDBYABSОтказан АБСДокумент отказан АБС
REFUSEDBYBANKОтвергнут БанкомДокумент отвергнут Банком
INVALIDEDSЭП/АСП не вернаПроверка ЭП под ЭД на стороне Банка дала отрицательный результат
DELETEDУдаленДокумент удален
Окончательные(Успешные) статусы/Прекратить опрос
PROCESSEDОбработанДокумент обработан

Получение номера обращения

Ресурс /v1/generic-letters/to-bank/{externalId} позволяет получить по ранее отправленному электронному документу информацию о номере обращения в CRM и идентификатор цепочки.

Данные реквизиты возвращаются для писем, имеющих наименование группы письма из справочника "GenericLetterType" (поле "groupName"):

  • Номер обращения в CRM - данный номер можно сообщить службе поддержки в случае возникновения спорных ситуаций.
  • Идентификатор цепочки - позволяет связать исходящее письмо в Банк с входящим письмом из Банка.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения статуса необходимо отправить GET-запрос (/v1/generic-letters/to-bank/{externalId}), в котором передать авторизационный токен к данным собственной (дочерней) организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис GENERIC_LETTER_TO_BANK.

Модель запроса

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId (String)Идентификатор документа, присвоенный партнером

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

curl -X GET --header 'Accept: /' --header 
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/generic-letters/to-bank/ffffffff-fffa-458e-ad92-fff9497303ba'

Модель ответа

НаименованиеОписание
GenericLetter {
attachments (Array[Attachment], optional)Вложенные документы,
bankComment (string, optional, read only)Банковский комментарий к статусу документа,
bankStatus (string, optional, read only)Статус документа,
bfAttachments (Array[BfAttachment])Идентификатор (-ы) больших файлов,
crmNumber (string, optional, read only)Номер ПСФ в CRM,
date (string)Дата составления документа,
digestSignatures (Array[Signature], optional)Электронные подписи по дайджесту документа,
externalId (string)Идентификатор документа, присвоенный партнёром (UUID),
integrationId (string, optional, read only)Идентификатор цепочки,
number (string, optional)Номер документа,
text (string)Текст сообщения,
typeCode (string)Системное имя темы письма,
typeName (string, optional, read only)Тип письма
}Attachment {
content (Array[string], optional)Вложение закодированное в Base64,
mimeType (string, optional)Тип формат файла,
name (string, optional)Имя файла
}BfAttachment {
fileId (string, optional)Уникальный идентификатор файла,
fileName (string, optional, read only)Имя файла
}Signature {
base64Encoded (string)Значение электронной подписи, закодированное в Base64,
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
"attachments":[
{
"content":"dGVzdA==",
"mimeType":"image/jpeg",
"name":"тест.jpg"
}
],
"bankComment":"string",
"bankStatus":"string",
"bfAttachments":[
{
"fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"fileName":"SB_7718830000_40702810038290010000_T18.txt"
}
],
"crmNumber":"190410-0033-142400",
"date":"2018-12-31",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"integrationId":"55daccdf-de87-3879-976c-8b8415c8caf9",
"number":"1",
"text":"У меня все хорошо",
"typeCode":"payment_recall",
"typeName":"Направить запрос по 115-ФЗ"
}

Получение документа по организации

Ресурс /v1/generic-letters/from-bank позволяет получить документ из банка по собственной/дочерней организации.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения документа необходимо отправить GET-запрос (/v1/generic-letters/from-bank), в котором передать ключ доступа (Access Token), дату за которую необходимо получить письмо (messageDate) и номер запрашиваемой страницы (page=1).

Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис GENERIC_LETTER_FROM_BANK.

Модель запроса

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
messageDate (String)Дата письма
page (String)Номер запрашиваемой страницы

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

curl -X GET --header 'Accept: application/json' --header 
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/generic-letters/from-bank?messageDate=2019-10-10&page=1'

Модель ответа

НаименованиеОписание
GenericLetters {
_links (Array[Link], optional)Ссылки на связанные ресурсы,
letters (Array[GenericLetter], optional)Письма из Банка
}Link {
href (string)Абсолютный или относительный адрес,
rel (string)Отношение ссылки к текущей сущности (next, prev)
}GenericLetter {
attachments (Array[Attachment], optional)Вложенные документы,
bankComment (string, optional, read only)Банковский комментарий к статусу документа,
bankStatus (string, optional, read only)Статус документа,
bfAttachments (Array[BfAttachment])Идентификатор (-ы) больших файлов,
crmNumber (string, optional, read only)Номер ПСФ в CRM,
date (string)Дата составления документа,
digestSignatures (Array[Signature], optional)Электронные подписи по дайджесту документа,
externalId (string)Идентификатор документа, присвоенный партнёром (UUID),
integrationId (string, optional, read only)Идентификатор цепочки,
number (string, optional)Номер документа,
text (string)Текст сообщения,
typeCode (string)Системное имя темы письма,
typeName (string, optional, read only)Тип письма
}Attachment {
content (Array[string], optional)Вложение закодированное в Base64,
mimeType (string, optional)Тип формат файла,
name (string, optional)Имя файла
}BfAttachment {
fileId (string, optional)Уникальный идентификатор файла,
fileName (string, optional, read only)Имя файла
}Signature {
base64Encoded (string)Значение электронной подписи, закодированное в Base64,
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)

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

{
"_links":[
{
"href":"?messageDate=2019-10-10&page=1",
"rel":"next"
}
],
"letters":[
{
"attachments":[
{
"content":"dGVzdA==",
"mimeType":"image/jpeg",
"name":"тест.jpg"
}
],
"bankComment":"string",
"bankStatus":"string",
"bfAttachments":[
{
"fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"fileName":"SB_7718830000_40702810038290010000_T18.txt"
}
],
"crmNumber":"190410-0033-142400",
"date":"2018-12-31",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"integrationId":"55daccdf-de87-3879-976c-8b8415c8caf9",
"number":"1",
"text":"Документ из банка",
"typeCode":"payment_recall",
"typeName":"Направить запрос по 115-ФЗ"
}
]
}
note

Необходимо запрашивать постранично входящие данные, начиная с первой страницы и опрашивать следующую до того момента, как в полученном ответе перестанет приходить href c признаком "rel": "next"

Это будет означать, что следующей страницы нет.
На запрос первой страницы в ответе вернётся письмо (Если существуют входящее письмо за выбранную дату) и контейнер links с параметром (href) на следующую страницу и признаком "rel": "next".
На запрос второй страницы в ответе вернётся письмо из банка и контейнер links с параметром (href) на следующую и предыдущую страницы и признаками: "rel": "prev", "rel": "next".
Получение последующих страниц производится по аналогии.

Дополнительная информация

Подписание запроса транспортной подписью

Content-Type может содержать одно из двух значений:

  • application/json – запрос без подписи

  • application/jose – запрос, подписанный транспортной подписью

Если Content-Type имеет значение application/jose, то запрос должен содержать данные (реквизитный состав платежного документа) в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из:

1. Заголовка (Header)
2. JSON-документа с реквизитным составом платежного поручения (Payload)
3. Подписи запроса (Signature)

Формирование компактной сериализации JWS

JWS формируется из трех составляющих:

Base64Url(Header) || ’.’ ||  Base64Url(Payload) || ’.’ || Base64Url(Signature)

Signature - это подпись данных приватной частью ключевой пары клиента (используется приватный ключ парный сертификату клиента с UUID, указанному в Заголовке (Header) в параметре kid).
Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg, в данном случае gost34.10-2012, и вычисляется от исходных данных:

Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

Следует отметить, что при кодировании JWS используется преобразование Base64Url, отличающееся от Base64 преобразования.
Условно это преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

здесь функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x, функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование BASE64URL, отличается от BASE64 преобразования:

BASE64URLBASE64
- (minus)+
_ (underline)/
  • В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

Коды возврата

Код возвратаОписание кода возвратаПричина возникновения
200 (GET-запрос)ОК
201 (POST-запрос)CREATED
Создан
400DESERIALIZATION_FAULT
Неверный формат запросаНеверный формат запроса
WORKFLOW_FAULT
Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХДля внешнего сервиса недоступны операции по счету:

счет не добавлен в список разрешенных в оферте;
внешний сервис заблокирован в СББОЛ;
счет указан неверно.

Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
Документ с такими реквизитами уже существуетДокумент с такими реквизитами уже существует. Проверка по номер документа в течении года.
Не указан идентификатор сертификата подписиНе указан идентификатор сертификата подписи(параметр kid заголовка JWS)
Некорректный формат параметра kid заголовка JWSНекорректный формат параметра kid заголовка JWS(ожидается UUID)
VALIDATION_FAULT
Ошибка валидацииОшибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
SIGN_CHECK_EXCEPTION
Подлинность подписи не установлена/Сертификат не обнаружен или не является активнымОшибка возникает, если не удалось установить подлинность подписи
401UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан некорректный или просроченный access_token.
403ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещенУ пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404DATA_NOT_FOUND_EXCEPTION
Платежный документ не найденНеверное значение externalId
415JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact SerializationОшибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
Обновлено 05 июля 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней