/fintech/api/v1/generic-letters/to-bank
Запрос позволяет создавать документ «Письмо в Банк».
Для создания письма в банк необходимо отправить POST-запрос /fintech/api/v1/generic-letters/to-bank с токеном доступа (access_token) пользователя в параметре Authorization заголовка и данными письма в теле.
В параметре scope ссылки авторизации пользователя должен быть указан сервис GENERIC_LETTER_TO_BANK для получения доступа к этому запросу.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443 - Промышленный контур
https://fintech.sberbank.ru:9443
Request
/fintech/api/v1/generic-letters/to-bank
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| HEADER | |||||
| Authorization | string | string | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
| BODY | |||||
| GenericLetter { | |||||
| attachments | array[Attachment] | array[object] | optional | Вложенные документы, | |
| bfAttachments | array[BfAttachment] | array[object] | optional | Идентификатор (-ы) файлов, загруженные в Банк с помощью сервиса "Большие файлы, | |
| date | string | ISO 8601 YYYY-MM-DD | ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ | required | Дата составления документа, |
| digestSignatures | array[Signature] | array[object] | optional | Электронные подписи по дайджесту документа. Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу. Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес. О подписании дайджеста платежного документа подробно рассказали в соответствующем разделе документации, | |
| externalId | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | required | Идентификатор документа, который вы присваиваете самостоятельно, |
| number | string | string | ^[0-9]{1,7}$ | optional | Номер документа, |
| text | string | string | По умолчанию заполняется шаблоном в соответствии с справочником "GenericLetterType" из поля "template" либо в свободном формате, если шаблон отсутствует в справочнике | required | Текст сообщения, |
| typeCode | string | string | Заполняется из справочника "GenericLetterType" из поля systemName в соответствии с требуемой темой описанной в поле "letterType" | required | Системное имя темы письма |
| } | |||||
| Attachment { | |||||
| content | array[string] | array[string] | ^[a-zA-Z0-9]+$ | optional | Вложение закодированное в Base64, |
| mimeType | string | string | ??? | optional | Тип формат файла, |
| name | string | string | ??? | optional | Имя файла |
| } | |||||
| BfAttachment { | |||||
| fileId | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | optional | Уникальный идентификатор файла |
| } | |||||
| Signature { | |||||
| base64Encoded | string | base64 | ^[a-zA-Z0-9]+$ | required | Значение электронной подписи (ЭП), закодированное в Base64, |
| certificateUuid | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | required | Уникальный идентификатор сертификата ключа проверки электронной подписи |
| } |
POST /fintech/api/v1/generic-letters/to-bank HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
{
"attachments": [
{
"content": "dGVzdA==",
"mimeType": "image/jpeg",
"name": "тест.jpg"
}
],
"bfAttachments": [
{
"fileId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"date": "2018-12-31",
"digestSignatures": [
{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"number": "1",
"text": "У меня все хорошо",
"typeCode": "payment_recall"
}
digestSignatures
Формат дайджеста
- Формат
- Пример
| Наименование поля | Описание поля | Пример |
|---|---|---|
| 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
#
Responses
201 (Created)
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| GenericLetter { | |||
| attachments | array[Attachment] | optional | Вложенные документы, |
| bankComment | string | optional | Банковский комментарий к статусу документа, |
| bankStatus | string | optional | Статус документа, |
| bfAttachments | array[BfAttachment] | optional | Идентификатор (-ы) файлов, загруженные в Банк с помощью сервиса "Большие файлы, |
| crmNumber | string | optional | Номер письма в CRM, |
| date | string | required | Дата составления документа, |
| digestSignatures | array[Signature] | optional | Электронные подписи по дайджесту документа, |
| externalId | string | required | Идентификатор документа, который вы присваиваете самостоятельно, |
| integrationId | string | optional | Идентификатор цепочки писем, |
| number | string | optional | Номер документа, |
| text | string | required | Текст сообщения, |
| typeCode | string | required | Системное имя темы письма, |
| typeName | string | optional | Тип письма |
| } | |||
| Attachment { | |||
| content | array[string] | optional | Вложение закодированное в Base64, |
| mimeType | string | optional | Тип формат файла, |
| name | string | optional | Имя файла |
| } | |||
| BfAttachment { | |||
| fileId | string | optional | Уникальный идентификатор файла, |
| fileName | string | optional | Имя файла |
| } | |||
| Signature { | |||
| base64Encoded | string | required | Значение электронной подписи (ЭП), закодированное в Base64, |
| certificateUuid | string | required | Уникальный идентификатор сертификата ключа проверки электронной подписи |
| } |
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
{
"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-ФЗ"
}
400 (Bad request)
| Cause | Message | Description |
|---|---|---|
| DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос. |
| VALIDATION_FAULT | Ошибка валидации | Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| ResourceFault { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| checks | array[Check] | optional | Список проверок, приведших к ошибке, |
| fieldNames | array[string] | optional | Названия полей с некорректным значением (только для VALIDATION_FAULT) |
| } | |||
| Check { | |||
| level | string | optional | Уровень результата = ['ERROR', 'WARNING'], |
| message | string | optional | Сообщение, |
| fields | array[string] | optional | Названия полей (при наличии связи с моделью) |
| } |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"cause": "DESERIALIZATION_FAULT",
"referenceId": "4a0e6754-ad22-4d7d-ac82-810afd08b5b2",
"message": "Неверный формат запроса",
"checks": [
{
"level": "ERROR",
"message": "Cannot deserialize instance of `java.util.ArrayList<Signature>` out of START_OBJECT token",
"fields": [
"digestSignatures"
]
}
],
"fieldNames": [
"digestSignatures"
]
}
401 (Unauthorized Error)
| Cause | Message | Description |
|---|---|---|
| UNAUTHORIZED | accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAUTHORIZED",
"referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
"message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}
403 (Forbidden)
| Cause | Message | Description |
|---|---|---|
| ACTION_ACCESS_EXCEPTION | Операция не может быть выполнена: доступ к ресурсу запрещен | Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция GENERIC_LETTER_TO_BANK. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"cause": "ACTION_ACCESS_EXCEPTION",
"referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
"message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}
500 (Internal Server Error)
| Cause | Message | Description |
|---|---|---|
| UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}