/fintech/api/v1/curr-control-messages/from-bank
Запрос позволяет получить входящие письма для целей валютного контроля (далее - ВК) от Банка.
Для получения входящих писем от ВК необходимо отправить GET-запрос /fintech/api/v1/curr-control-messages/from-bank с токеном доступа (access_token) пользователя в параметре Authorization заголовка и параметрами поиска в query-параметрах.
В параметре scope ссылки авторизации пользователя должен быть указан сервис CURR_CONTROL_MESSAGE_FROM_BANK для получения доступа к этому запросу.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443 - Промышленный контур
https://fintech.sberbank.ru:9443
Request
/fintech/api/v1/curr-control-messages/from-bank
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| HEADER | |||||
| Authorization | string | string | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
| QUERY PARAMETERS | |||||
| messageDate | date-time | ISO 8601 YYYY-MM-DD | ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ | required | Дата получения входящих писем. |
| page | integer | integer | ^[0-9]+$ | required | Номер страницы |
GET /fintech/api/v1/curr-control-messages/from-bank?messageDate=2024-10-10&page=1 HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*
Responses
200 (OK)
На запрос первой страницы в ответе вернется список входящих писем (если они существуют за выбранную дату) и контейнер links с параметром (href) на следующую страницу и признаком "rel": "next".
На запрос второй страницы в ответе вернется список входящих писем и контейнер links с параметром (href) на следующую и предыдущую страницы и признаками: "rel": "prev", "rel": "next". Получение последующих страниц производится по аналогии.
Если следующей страницы нет, в полученном ответе перестанет приходить href c признаком "rel": "next".
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| CurrControlMessagesFromBank { | |||
| _links | array[Link] | optional | Ссылки на связанные ресурсы, |
| messages | array[CurrControlMessageFromBank] | optional | Письма для целей ВК (из банка) |
| } | |||
| Link { | |||
| href | string | required | Абсолютный или относительный адрес |
| rel | string | required | Отношение ссылки к текущей сущности (next, prev) |
| } | |||
| CurrControlMessageFromBank { | |||
| attachments | array[Attachment] | optional | Вложенные документы, |
| bankComment | string | optional | Банковский комментарий к статусу документа, |
| bankStatus | string | optional | Статус документа, |
| bfAttachments | array[BfAttachment] | optional | Данные о файлах, связанных с письмом для целей ВК, |
| date | string | required | Дата составления документа, |
| digestSignatures | array[Signature] | optional | Электронные подписи по дайджесту документа, |
| externalId | string | required | Идентификатор документа, который вы присвоили ему при создании, |
| number | string | optional | Номер документа, |
| refDocument | LinkedDoc | optional | Документ ВК, по которому ведется переписка, |
| rootMessage | LinkedDoc | optional | Письмо ВК, на которое данное письмо является ответом, |
| subject | string | required | Тема письма, |
| text | string | required | Текст письма |
| } | |||
| 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 | Уникальный идентификатор сертификата ключа проверки электронной подписи |
| } | |||
| LinkedDoc { | |||
| docExtId | string | required | Идентификатор документа во внешней системе, |
| type | string | required | Тип связанного документа |
| } |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"_links": [
{
"href": "?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
"rel": "next"
}
],
"messages": [
{
"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"
}
],
"date": "2018-12-31",
"digestSignatures": [
{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"number": "1",
"refDocument": {
"docExtId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"type": "ExportContractInsure"
},
"rootMessage": {
"docExtId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"type": "ExportContractInsure"
},
"subject": "Досыл документа.",
"text": "Добрый день. Документ отправлен."
}
]
}
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": "VALIDATION_FAULT",
"referenceId": "0d6a80ba-7d35-4858-8443-9a77039ad9f1",
"message": "Параметр \"externalId\" не соответствует регулярному выражению: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
"checks": [],
"fieldNames": null
}
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, не указана операция CURR_CONTROL_MESSAGE_FROM_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": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}
404 (Not found)
| Cause | Message | Description |
|---|---|---|
| NOT_FOUND | Документ с указанным ID не найден |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"cause": "NOT_FOUND",
"referenceId": "1bd1b8b9-1bd3-4159-9909-d30536211114",
"message": "Документ с указанным ID не найден"
}
429 (Too Many Requests)
| Cause | Message | Description |
|---|---|---|
| TOO_MANY_REQUESTS | Превышен лимит запросов. Повторите операцию позже. | Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice{ | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
json HTTP/1.1 429 Too Many Requests Content-Type: application/json;charset=UTF-8
{ "cause": " TOO_MANY_REQUESTS ", "referenceId": "5650c1e4-5039-4038-8cad-afab64003f61", "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": "Внутренняя ошибка сервера"
}
503 (Service Temporarily Unavailable)
| Cause | Message | Description |
|---|---|---|
| UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
"message": "Внутренняя ошибка сервера"
}