Сервис передачи в банк документа для отправки по СПФС
C помощью данного API Клиент может настроить в ERP передачу в Банк документа для последующей отправки по СПФС.
Описание бизнес-процесса:
Клиент в своей ERP системе формирует конверт свободного формата (далее - SPFS_ENV) в соответствии со спецификацией канала.
Клиент подписывает конверт SPFS_ENV открепленной УКЭП в формате CMS.
2.1. для подписания рассчитывается хэш всех тегов конверта SPFS_ENV без пробелов между тегами и переносов строк, кроме DigitalSign. Подпись вкладывается в тег DigitalSign.
ERP Клиента вызывает API для аутентификации и авторизации.
Банк проводит аутентификацию и авторизацию. Генерирует access token.
Банк возвращает access token Клиенту.
ERP Клиента вызывает API для передачи SPFS_ENV.
Банк проводит форматно-логические контроли.
В случае успешной валидации сообщения и проверки access token Банк принимает запрос в обработку.
Проверки Центра обмена сообщениями СПФС Банка России, которые необходимо учесть при формировании сообщений для отправки по СПФС:
Регламентные контроли каждого финансового сообщения SWIFT в составе конверта: структурный, логический, специальный структурный контроль сообщений формата SWIFT.
В рамках структурного контроля для каждого сообщения формата SWIFT MT осуществляется контроль структуры блоков 1 (блок основного заголовка), 2 (блок заголовка приложения), 3 (блок заголовка пользователя) и 4 (текстовый блок) на соответствие требованиям стандарта SWIFT MT, в рамках которого проводится проверка синтаксиса, семантики (соотношения между полями) и использования кодовых слов. Другие блоки не проверяются на соответствие требованиям стандарта SWIFT MT.
При передаче документа в формате SWIFT, если предполагается подписание документа электронной подписью, то Блоки 1 и 2 не подписывать, т.к. при передаче по СПФС (по аналогии со SWIFT) документ преобразуется из исходящего во входящий. Подписание всего сообщения приведет к неуспешной проверке электронной подписи получателем финансового сообщения.
Не допускается шифрование и архивирование с использованием кодов доступа содержимого ProprietaryDocument сообщений SWIFT MT/FREEFORMAT. Такой документ будет отклонен СПФС.
Описание атрибутов запроса:
| Параметры | Описание | ||||
|---|---|---|---|---|---|
| Authorization (header) | Получение токена авторизации в методе Сервис получения токена авторизации | ||||
| RqUID (header) | Уникальный идентификатор сообщения, сгенерированный клиентом в формате [0-9A-Fa-f]{32}. Чтобы гарантировать уникальность, требуется использовать стандартные библиотеки и классы генерации UUID (https://ru.wikipedia.org/wiki/UUID),убрав из результата символ разделителя «-». Если заголовок отсутствует в запросе, идентификатор будет сгенерирован автоматически и передан клиенту в аналогичном заголовке ответа | ||||
| text (body) | Для передачи бизнес данных запроса предусмотрен формат JSON | ||||
| DocumentFreeFormat{ | |||||
| description: | конверт SPFS_ENV | ||||
| Sender | { | ||||
| description: | Отправитель сообщения | ||||
| UIS* | string | ||||
| maxLength: 10 | |||||
| pattern: ^[0-9]{0,10}$ | |||||
| example: 4525171000 | |||||
| УИС отправителя | |||||
| } | |||||
| Receiver* | { | ||||
| description: | Получатель сообщения | ||||
| UIS* | string | ||||
| maxLength: 10 | |||||
| pattern: ^[0-9]{0,10}$ | |||||
| example: 4525225000 | |||||
| УИС получателя | |||||
| } | |||||
| DocFormat* | { | ||||
| description: | Указывается формат документа | ||||
| oneOf -> | { | ||||
| description: | Заполняется при передаче финансового сообщения | ||||
| SWIFT_MT | { | ||||
| description: | Заполняется при передаче финансового сообщения | ||||
| ReceiverSWIFT* | string | ||||
| maxLength: 11 | |||||
| pattern: ^[A-Z0-9]{0,11}$ | |||||
| example: SABRRUMMXXX | |||||
| SWIFT BIC получателя | |||||
| SWIFTType* | string | ||||
| pattern: ^[0-9A-Z]{5}$ | |||||
| example: MT103 | |||||
| Тип сообщения SWIFT | |||||
| } | |||||
| }{ | |||||
| description: | Заполняется при передаче сообщения в формате ISO20022 | ||||
| ISO20022 | { | ||||
| description: | Заполняется при передаче сообщения в формате ISO20022 | ||||
| ISOType* | string | ||||
| maxLength: 15 | |||||
| pattern: ^[a-z]{4}(.)[0-9]{3}(.)[0-9]{3}(.)[0-9]{2}$ | |||||
| example: pain.001.001.09 | |||||
| тип ISO | |||||
| } | |||||
| } | |||||
| FREE_FORMAT string | |||||
| example: FREE_FORMAT | |||||
| Заполняется при передачи сообщения в формате пользователя | |||||
| Enum: | |||||
| [ FREE_FORMAT ] | |||||
| } | |||||
| DocType* | string | ||||
| example: PAYMENT-ORDER | |||||
| Указывается тип документа | |||||
| Enum: | |||||
| [ PAYMENT-ORDER, PAYROLL, CURRENCY-TRANSFER, FOREIGN-EXCHANGE, EXCHANGE-CONTROLS ] | |||||
| ProprietaryDocument* | string | ||||
| pattern: ^[+\/=0-9a-zA-Z]{0,990000}$ | |||||
| example: ezE6RjAxVEVTVFJVTU1YWFhYMTAwMDAwMDE3N317MjpJNTE2U0FCUlJVTU1YWFhYTn17NDoNCjoyMDoxMjEwMjI4MjVPRloxNDIzDQo6MjM6MTIxMDIyODI1T0ZaMTQyDQotfQ== | |||||
| Документ для отправки в кодировке base64 | |||||
| DigitalSign* | string | ||||
| pattern: ^[+\/=0-9a-zA-Z]{0,7000}$ | |||||
| example: MIIKwwYJKoZIhvcNAQcCoIIKtDCCCrACAQExDjAMBggqhQMHAQECAgUAMAsGCSqGS | |||||
| } |
Статусы http-запросов
Данные статусы распространяются на все типы запросов и свидетельствуют об успешности выполнения метода.
| Код | Статус | Причина возникновения |
|---|---|---|
| 200 | OK | OK |
| 400 | Bad request | Bad request |
| 401 | Unauthorized | Unauthorized |
| 403 | Forbidden | Contact your client manager |
| 405 | Method Not Allowed | Method Not Allowed |
| 409 | Conflict | Rquid is duplicate |
| 429 | Too Many Requests | Too Many Requests |
| 500 | Internal Server Error | Internal Server Error |
| 503 | Service Unavailable | Try again later |
| 504 | Gateway Timeout | Gateway Timeout |
Описание примеров сообщений
Вызов сервиса передачи в банк документа для отправки по СПФС:
Тип запроса POST
POST https://mc.api.sberbank.ru:443/prod/sberconnect/sbspfs/v1/spfs/init
Connection: keep-alive
Content-Type: application/json;charset=utf-8
RqUID: d5dd9b6932f1f3185bfa982d6f8b88bb
Authorization: Bearer 21de98b5-60ec-4d82-a0fd-149e79112fdb
Content-Length: 3417
Host: mc.api.sberbank.ru:443
User-Agent: Apache-HttpClient/4.5.10 (Java/1.8.0_321)
POST data:
{
"Receiver": {
"UIS": "4525225000"
},
"DocFormat": {
"SWIFT_MT": {
"ReceiverSWIFT": "SABRRUMMXXX",
"SWIFTType": "MT516"
}
},
"DocType": "PAYMENT-ORDER",
"ProprietaryDocument": "ezE6RjAxVEVTVFJVTU1YWFhYMTAwMDAwMDE3N317MjpJNTE2U0FCUlJVTU1YWFhYTn17NDoNCjoyMDoxMjEwMjI4MjVPRloxNDIzDQo6MjM6MTIxMDIyODI1T0ZaMTQyDQo6MzFQOjIyMDkyMA0KOjM1QjpJU0lOIFJVMDAwQTBKUzAwMA0KOjM1QTpCT04yNTI4MjEsDQo6MzFMOjIyMDkyMQ0KOjMxWDoyMjA5MjANCjozMDoyMjA5MjENCjozM1Q6UlVCMTAwLDk5MjUxNjQ4DQo6MzdKOjAsMDMNCjo3MjpTdGFuZGFyZCBDYXNoIGFuZCBTZWN1cml0aWVzDQpTU0kgYWNjb3JkaW5nIHRvIEdBIE4xMi8yMQ0KZGF0ZWQgMTYvMTIvMjAyMQ0KLX0=",
"DigitalSign": "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"
}
Ответ сервиса:
HTTP/1.1 200 OK
Server: nginx/1.20.1
Date: Thu, 13 Oct 2022 13:26:03 GMT
Content-Length: 0
Connection: keep-alive
X-Rate-Limit-Limit: 20
X-Rate-Limit-Remaining: 19
X-Rate-Limit-Reset: 1665667563159
Expires: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
RqUID: d5dd9b6932f1f3185bfa982d6f8b88bb
X-XSS-Protection: 1; mode=block
Pragma: no-cache
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Accept-Ranges: bytes