Письма свободного формата
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
https://iftfintech.testsbi.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 или /v1/crypto/eio) | 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6 |
В документе можно передать одну или две электронных подписи вместе с реквизитами создаваемого документа. Если подписи переданы через API, то они сохраняются вместе с документом, а сам документ продолжает свой жизненный цикл. Если подписи не были переданы, то документ сохраняется в начальном статусе и ожидает дальнейшей подписи в интерфейсе СберБизнес.
Документ может быть подписан следующими наборами подписей:
- одна (единственная) подпись;
- первая и вторая подписи.
При этом нельзя сочетать подпись, имеющую единственное полномочие, с подписью, имеющей первую или вторую подписи.
Порядок наложения подписи не имеет значения при наложении первой и второй подписей. Состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля при создании пользователя в СберБизнес.
Подробнее о работе с ЭЦП в Sber API можно ознакомиться в соответствующем разделе документации.
Алгоритм сортировки дайджеста
Теги дайджеста должны быть отсортированы по алфавиту.
В таблице bfAttachments UUID-ы сортируются по возрастанию.
В дайджесте не указываются значения Number и блок linkedDocs.
Формат дайджеста
Наименование поля | Описание поля | Пример |
---|---|---|
date | Дата документа | 2019-10-17 |
externalId | Идентификатор документа в организации-партнере | 42a6dd89-103a-4d7a-8e9b-1ba4b521f5f6 |
text | Текст письма | Текст письма |
typeCode | Тип ПСФ | payment_recall |
TABLES | Значение указывается при наличии UUID-ов больших файлов | |
Table=BfAttachments | Значение указывается при наличии UUID-ов больших файлов | |
fileId | UUID больших файлов | 8e9d6ce6-d5d7-4d81-96b8-9af0e7e17694 |
# | Разделитель значений UUID-ов больших файлов | |
fileId | UUID больших файлов | 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://iftfintech.testsbi.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://iftfintech.testsbi.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://iftfintech.testsbi.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-ФЗ"
}
]
}
Необходимо запрашивать постранично входящие данные, начиная с первой страницы и опрашивать следующую до того момента, как в полученном ответе перестанет приходить 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 состоит из трёх частей:
- Заголовок (Header) - определяет алгоритм подписи и тип токена
- Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
- Электронная подпись (Signature) - вычисляется с использованием приватного ключа клиента
Base64Url(Header) || ’.’ || Base64Url(Payload) || ’.’ || Base64Url(Signature)
Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.
Signature - это подпись данных приватной частью ключевой пары клиента (используется приватный ключ парный сертификату клиента). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg (в нашем случае gost34.10-2012) и вычисляется от исходных данных:
Base64Url(Header) || ‘.’ || Base64Url(Payload).
Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).
При кодировании JWS используется преобразование Base64Url. Преобразование можно представить следующим образом:
Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)
- функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x,
- функция Replace(x,y) заменяет все вхождения символа x на символ y.
Преобразование Base64Url, отличается от Base64 преобразования:
- В Base64Url не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.
- Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.
BASE64URL | BASE64 |
---|---|
- (minus) | + |
_ (underline) | / |
Коды возврата
Код возврата | Описание кода возврата | Причина возникновения | |
---|---|---|---|
200 (GET-запрос) | ОК | ||
201 (POST-запрос) | CREATED | ||
Создан | |||
400 | DESERIALIZATION_FAULT | ||
Неверный формат запроса | Неверный формат запроса | ||
WORKFLOW_FAULT | |||
Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ | Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика | ||
Документ с такими реквизитами уже существует | Документ с такими реквизитами уже существует. Проверка по номер документа в течении года. | ||
Не указан идентификатор сертификата подписи | Не указан идентификатор сертификата подписи(параметр kid заголовка JWS) | ||
Некорректный формат параметра kid заголовка JWS | Некорректный формат параметра kid заголовка JWS(ожидается UUID) | ||
VALIDATION_FAULT | |||
Ошибка валидации | Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели. | ||
SIGN_CHECK_EXCEPTION | |||
Подлинность подписи не установлена/Сертификат не обнаружен или не является активным | Ошибка возникает, если не удалось установить подлинность подписи | ||
401 | UNAUTHORIZED | ||
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. | ||
403 | ACTION_ACCESS_EXCEPTION | ||
Операция не может быть выполнена: доступ к ресурсу запрещен | У пользователя нет прав на использование соответствующего сервиса Sber API, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом. | ||
404 | DATA_NOT_FOUND_EXCEPTION | ||
Платежный документ не найден | Неверное значение externalId | ||
415 | JWS_EXCEPTED | ||
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization | Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса" | ||
500 | UNKNOWN_EXCEPTION | ||
Внутренняя ошибка сервера |