openapi: 3.0.2 info: title: Pay-Doc-Cur Overview description: | ## Методы для работы с валютным платежным поручением (ВПП) * [Создание валютного платежного поручения](/ru/sber-api/specifications/pay-doc-cur/create) * [Получение статуса валютного платежного поручения](/ru/sber-api/specifications/pay-doc-cur/get-state) * [Получение деталей документа "Валютное платежное поручение"](/ru/sber-api/specifications/pay-doc-cur/get-document) version: 1.0.0 servers: - url: https://fintech-test.sberbank.ru:9443/fintech/api description: Песочница - url: https://iftfintech.testsbi.sberbank.ru:9443/fintech/api description: Тестовый контур - url: https://fintech.sberbank.ru:9443/fintech/api description: Промышленный контур tags: - name: currency-payments description: Валютное платежное поручение paths: /v1/pay-doc-cur: post: tags: - PaymentDocCur summary: Создание валютного платёжного поручения description: | Запрос на создание валютного платежного поручения. Должен содержать токен доступа (access_token) пользователя в параметре **Authorization** заголовка. Для доступа к этому методу в параметре `scope` ссылки авторизации пользователя должен быть указан сервис `PAY_DOC_CUR`. * Если в запросе на создание платежного документа передать ЭП к документу (объект **digestSignatures**), то Банк сразу начнет обработку документа. * Если в запросе не передавать ЭП к документу, то платежное поручение будет создано в статусе черновик. Для начала обработки документа Банком потребуется зайти в интерфейс СберБизнес и подписать его.
Дайджест Дайджест это текстовый документ, содержащий перечень и значения полей запроса, к которому он относится и предназначенный для подписания ЭП. Сохраняйте порядок и количество полей дайджеста, как показано в примере ниже, иначе подписать его не получится. Формат дайджеста запроса на создание валютного платёжного поручения (значения number и блок linkedDocs не используются): | **Наименование поля** | **Описание поля** | **Пример** | |---|---|---| | addInfo | Примечание | Примечание | | additionalInfo | Информация получателю платежа (поле 72) | /CCTFDR/ | | amountTransfer.amount | Сумма валютного перевода | 1.00 | | amountTransfer.currencyCode | Цифровой код валюты | 840 | | amountTransfer.currencyName | ISO-код валюты | USD | | authPersonName | ФИО ответственного лица | Иванов Алексей Сергеевич | | authPersonTelfax | Телефон ответственного лица | +74951234567 | | b77info | Информация для регулирующих органов | Информация для регулирующих органов | | beneficiaryAccount | Счет бенефициара | 40802840600000200000 | | beneficiaryAddress | Адрес бенефициара | UL.KUTUZOVSKAYA,D.2 | | beneficiaryBankAccount | Корреспондентский счет банка бенефициара | 40802840600000200000 | | beneficiaryBankAddress | Адрес банка бенефициара | ул. Вавилова, д. 19 | | beneficiaryBankBranchName | Наименование филиала банка бенефициара | (TREASURY DEPARTMENT) | | beneficiaryBankClearingCode.clearingCode | Клиринговый код банка бенефициара | 111111 | | beneficiaryBankClearingCode.countryCode | Обозначение национального клирингового кода банка бенефициара | UA | | beneficiaryBankClearingCode.shortName | Сокращенное наименование национального клирингового кода | Сокращенное наименование национального клирингового кода | | beneficiaryBankClearingCode.symbol | Клиринговый код банка бенефициара | UA | | beneficiaryBankCountryDigital | Цифровой код страны банка бенефициара | 643 | | beneficiaryBankCountryIso2 | 2х буквенный ISO-код страны банка бенефициара | RU | | beneficiaryBankName | Наименование банка бенефициара | ПАО СБЕРБАНК | | beneficiaryBankPlace | Местонахождение банка бенефициара | MOSKVA | | beneficiaryBankSwift | SWIFT-код банка бенефициара | ABNARUMMSPB | | beneficiaryBeiCode | BEI-код (SWIFT-код) | AAAAAAAA | | beneficiaryCountryDigital | Цифровой код страны бенефициара | 643 | | beneficiaryCountryIso2 | 2х буквенный ISO-код страны бенефициара | RU | | beneficiaryCountryName | Наименование страны бенефициара на русском языке (краткое наименование) | Россия | | beneficiaryInn | ИНН бенефициара | 222201236445 | | beneficiaryName | Наименование бенефициара | EMIRP | | beneficiaryPlace | Город (месторасположение) бенефициара | MOSKVA | | chargesType | Тип комиссии за перевод: BEN, SHA или OUR | BEN | | date | Дата документа | 2019-10-16 | | externalId | Идентификатор документа в организации-партнере (UUID) | 619e25cf-dc0b-4420-8957-1b94bf29f145 | | iMediaBankAddress | Адрес банка-посредника | SWEDEN HOUSE | | iMediaBankCountryDigital | Цифровой код страны банка-посредника | 643 | | iMediaBankCountryIso2 | 2х буквенный ISO-код страны банка-посредника | RU | | iMediaBankName | Наименование банка-посредника | ABN AMRO BANK A.O. | | iMediaBankPlace | Город банка-посредника | ST. PETERSBURG | | iMediaBankSwift | SWIFT-код банка-посредника | ABNARUMMSPB | | iMediaClearingCode.clearingCode | Клиринговый код банка посредника | 111111 | | iMediaClearingCode.countryCode | Обозначение национального клирингового кода банка-посредника | UA | | iMediaClearingCode.shortName | Сокращенное наименование национального клирингового кода | | | iMediaClearingCode.symbol | Обозначение национального клирингового кода банка-посредника | UA | | iMediaFilialBankName | Наименование филиала банка-посредника | ОСБ1 | | inn | ИНН клиента | 1182079004 | | option50a | Опция "K" для поля 50а | K | | option56a | Опция "A", "D" для поля 56а | A | | option57a | Опция "A", "D" для поля 57а | A | | option59a | Опция "А" для поля 59а или «без опции» | A | | orgName | Наименование организации клиента | Организация YUaegpVCyvHROOE | | payerAccount | Счет плательщика | 40702840775470463045 | | payerAddress | Адрес плательщика | UL.DOBROLIUBOVA,D.18,OF.III | | payerBankBic | БИК банка плательщика | 044525225 | | payerBankPlace | Местонахождение банка плательщика | MOSKVA | | payerCountryDigital | Цифровой код страны перевододателя | 643 | | payerCountryIso2 | 2х буквенный ISO-код страны перевододателя | RU | | payerCountryName | Наименование страны перевододателя на русском языке (краткое наименование) | Россия | | payerName | Международное наименование плательщика | LLC COMPANY | | payerPlace | Город (местонахождение) плательщика | MOSKVA | | paymentDetails | Назначение платежа | ABCD | | paymentDirection | Направление платежа (Платеж внутри или вне СБРФ): 1-внутри, 0-вне | 1 | | rateAgree | С курсом проведения конверсионной операции согласны | true | | urgent | Срочность | false | | **TABLES** | | | | Table | 23E: Код инструкции | Codes23e | | code | Код инструкции | TELE | | description | Описание | Описание | | info | Дополнительная информация | ИНФО | | # | Разделитель | | **Пример дайджеста** ```json addInfo=Примечание additionalInfo=Информация получателю платежа amountTransfer.amount=1.00 amountTransfer.currencyCode=840 amountTransfer.currencyName=USD authPersonName=Иванов Алексей Сергеевич authPersonTelfax=+74951234567 b77info=Информация для регулирующих органов beneficiaryAccount=40802840600000200000 beneficiaryAddress=UL.KUTUZOVSKAYA,D.2 beneficiaryBankAccount=40802840600000200000 beneficiaryBankAddress=ул. Вавилова, д. 19 beneficiaryBankBranchName=ОСБ1 beneficiaryBankClearingCode.clearingCode=111111 beneficiaryBankClearingCode.countryCode=UA beneficiaryBankClearingCode.shortName=Сокращенное наименование национального клирингового кода beneficiaryBankClearingCode.symbol=UA beneficiaryBankCountryDigital=643 beneficiaryBankCountryIso2=RU beneficiaryBankName=ПАО СБЕРБАНК beneficiaryBankPlace=MOSKVA beneficiaryBankSwift=ABNARUMMSPB beneficiaryBeiCode=AAAAAAAA beneficiaryCountryDigital=643 beneficiaryCountryIso2=RU beneficiaryCountryName=Россия beneficiaryInn=222201236445 beneficiaryName=EMIRP beneficiaryPlace=MOSKVA chargesType=BEN date=2019-11-26 externalId=fa1dabed-d7c4-42c3-9c59-25cbf4724765 iMediaBankAddress=SWEDEN HOUSE iMediaBankCountryDigital=643 iMediaBankCountryIso2=RU iMediaBankName=ABN AMRO BANK A.O. iMediaBankPlace=ST. PETERSBURG iMediaBankSwift=ABNARUMMSPB iMediaClearingCode.clearingCode=111111 iMediaClearingCode.countryCode=UA iMediaClearingCode.shortName=Сокращенное наименование национального клирингового кода iMediaClearingCode.symbol=UA iMediaFilialBankName=ОСБ1 inn=7494979410 option50a=K option56a=A option57a=A option59a=A orgName=Организация LCMdmYRFBCUflhq payerAccount=40702840459430282265 payerAddress=UL.DOBROLIUBOVA,D.18,OF.III payerBankBic=044525225 payerBankPlace=MOSKVA payerCountryDigital=643 payerCountryIso2=RU payerCountryName=Россия payerName=LLC COMPANY payerPlace=MOSKVA paymentDetails=НАЗНАЧЕНИЕ ПЛАТЕЖА paymentDirection=1 rateAgree=true urgent=false TABLES Table=Codes23e code=TELE description=Описание info=Дополнительная информация # ``` ### Заполнение клиринговых кодов Для задания массива клиринговых кодов банка бенефициара (`beneficiaryBankClearingCode`) или банка-посредника (`iMediaClearingCode`), используйте данные [справочников](/ru/sber-api/specifications/dicts/dicts-overview): * Справочник структур национальных клиринговых кодов [ClearingStructure](https://developers.sber.ru/docs/ru/sber-api/specifications/dicts/dicts-overview#perechen-spravochnikov) для заполнения `countryCode`, `shortName` и `symbol`; * Международный справочник банков [SwiftBic](https://developers.sber.ru/docs/ru/sber-api/specifications/dicts/dicts-overview#format-spravochnikov) для заполнения `clearingCode` и `countryCode`.
Рекомендации по тестированию в песочнице При тестировании создания валютного платёжного поручения в Песочнице соблюдайте правила: * **Генерируйте уникальный `externalId`** для каждого документа. * **Не нужно устанавливать промышленные сертификаты электронной подписи (ЭП)** — Песочница использует тестовые идентификаторы ЭП (certificateUuid). * Все остальные поля запроса заполняйте произвольными данными (реквизиты, суммы, назначение платежа) в соответствии с требованиями в документации. ## Сценарии тестирования Для тестирования сценариев используйте **фиксированные** значения `certificateUuid`. При использовании любых других значений `certificateUuid` вернется ошибка WORKFLOW_FAULT "Проверьте актуальность сертификата электронной подписи."
**1.** Чтобы создать неподписанное платежное поручение (черновик), отправьте запрос **без объекта `digestSignatures`**. **Статус в ответе:** `bankStatus: "CREATED"` --- **2.** Для отправки документа с единственной подписью передайте в объекте `digestSignatures` тестовый UUID единоличного исполнительного органа (ЕИО). **Параметры:** * `certificateUuid`: `bb014b5d-8159-40be-97c1-eafeed4a8c3d` **Статус в ответе:** `bankStatus: "IMPLEMENTED"` **Пример:** ```json "digestSignatures": [ { "certificateUuid": "bb014b5d-8159-40be-97c1-eafeed4a8c3d", "base64Encoded": "MIILDgYJKoZIhvcNAQcCoIIK..." } ], ``` --- **3.** Для отправки документа с двумя подписями передайте в объекте `digestSignatures` тестовые UUID первой **И** второй подписи. **Параметры:** * `certificateUuid`: `d5d4f811-f4d4-4205-a70f-58f772eeab72` (Первая подпись) * `certificateUuid`: `4f29c8ef-b55d-43c7-a321-f2b1303a29cd` (Вторая подпись) **Статус в ответе:** `bankStatus: "IMPLEMENTED"` **Пример:** ```json "digestSignatures": [ { "certificateUuid": "d5d4f811-f4d4-4205-a70f-58f772eeab72", "base64Encoded": "MIILDgYJKoZIhvcNAQcCoIIK..." }, { "certificateUuid": "4f29c8ef-b55d-43c7-a321-f2b1303a29cd", "base64Encoded": "MIILDgYJKoZIhvcNAQcCoIIK..." } ], ``` --- **4.** Для отправки документа с одной из двух подписей передайте в объекте `digestSignatures` тестовые UUID первой **ИЛИ** второй подписи. **Статус в ответе:** `bankStatus: "PARTSIGNED"` **Параметры:** * `certificateUuid`: `d5d4f811-f4d4-4205-a70f-58f772eeab72` (Первая подпись) * `certificateUuid`: `4f29c8ef-b55d-43c7-a321-f2b1303a29cd` (Вторая подпись) **Пример:** ```json "digestSignatures": [ { "certificateUuid": "d5d4f811-f4d4-4205-a70f-58f772eeab72", "base64Encoded": "MIILDgYJKoZIhvcNAQcCoIIK..." } ], ```
operationId: create parameters: - in: header description: Access token организации-клиента, полученный через SSO. Внутри Authorization необходимо передавать тип токена Bearer. name: Authorization schema: type: string required: true example: "f8ad3141-b7e8-4924-92de-3de4fd0a464e-1" requestBody: content: application/json: schema: $ref: '#/components/schemas/FintechPayDocCur' responses: 200: content: application/json: schema: $ref: '#/components/schemas/FintechPayDocCur' description: "Успешный ответ" 202: description: "Операция не завершена полностью" content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 400: description: | "Ошибка в запросе" | **Cause** | **Message** | **Description** | | --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в response в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. | | VALIDATION_FAULT | Ошибка валидации | Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 401: description: | "Не авторизован" | **Cause** | **Message** | **Description** | | ------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | UNAUTHORIZED | accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 403: description: | "Операция не может быть выполнена: доступ к ресурсу запрещён" | **Cause** | **Message** | **Description** | | ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ACTION_ACCESS_EXCEPTION | Операция не может быть выполнена: доступ к ресурсу запрещен | Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `PAY_DOC_RU`. Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 404: description: "Данные не найдены" content: application/json: schema: $ref: "#/components/schemas/FintechWorkflowFault" 429: description: | "Превышен лимит запросов" | **Cause** | **Message** | **Description** | | ----------------- | -------------------------------------------------- | ---------------------| | TOO_MANY_REQUESTS | Превышен лимит запросов. Повторите операцию позже. | Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 500: description: | "Внутренняя ошибка сервера" | **Cause** | **Message** | **Description** | | ----------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 503: description: | "Сервис временно недоступен" | **Cause** | **Message** | **Description** | | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' /v1/pay-doc-cur/{externalId}/state: get: tags: - PaymentDocCur summary: Получение статуса валютного платежного поручения servers: - url: https://fintech-test.sberbank.ru:9443/fintech/api description: Песочница - url: https://fintech.sberbank.ru:9443/fintech/api description: Промышленный контур description: | Возвращает статус ранее созданного валютного платежного поручения. Должен содержать токен доступа (access_token) пользователя в параметре **Authorization** заголовка и идентификатор документа (**externalId**), указанный при его создании. Для доступа к этому методу в параметре `scope` ссылки авторизации пользователя должен быть указан сервис `PAY_DOC_CUR`.
Статусы Значения поля `bankStatus`: | bankStatus | Описание | | ---------------------------------------------------- | ----------------------------------- | | **Промежуточные статусы/Продолжать опрашивать** | | | `ACCEPTED` | Принят | | `ACCEPTED_BY_ABS` | Принят АБС | | `ACCEPTED_BY_CFE` | Принят ВК | | `ACCEPTED_RZK` | Акцептован СБК | | `CARD2` | Картотека №2 | | `CORRESPONDENT_APPROVE_WAITING` | Ожидает подтверждения контрагента | | `CREATED` | Создан | | `CHECKERROR` | Ошибка контроля | | `CREATED_BANK` | Создан Банком | | `CHECKERROR_BANK` | Ошибка контроля, Банк | | `DELAYED` | Приостановлен | | `DELIVERED` | Доставлен | | `EXPORTED` | Выгружен | | `FRAUDSMS` | Требуется подтверждение СМС-паролем | | `FRAUDREVIEW` | На проверке у специалиста банка | | `FRAUDSENT` | Отправлен во ФРОД | | `FRAUDALLOW` | Одобрен ФРОД | | `FRAUDDENY` | Отвергнут ФРОД | | `IMPORTED` | Импортирован | | `IMPORTED_BANK` | Импортирован Банком | | `NEED_REVIEW` | Необходимы исправления | | `PROCESSING` | В обработке | | `PUBLISHED_BY_BANK` | Издан Банком | | `PARTSIGNED` | Частично подписан | | `PROCESSING_RZK` | Обрабатывается СБК | | `PROCESSED` | Обработан | | `READY_TO_SEND` | Ждет отправки | | `RETURNED` | Возвращен | | `RATE_CONFIRMATION` | На подтверждении курса | | `SIGNED` | Подписан | | `SENDING` | Отправляется | | `SENDED` | Отправлен | | `SENDING_TO_RZK` | Отправляется в СБК | | `SIGNED_BANK` | Подписан Банком | | `SENT_TO_ADMIN` | Передан администратору | | `TEMPLATE` | Шаблон документа | | `TRIED` | Проверен | | `TO_PROCESSING_RZK` | К отправке в СБК | | `TO_SIGN_IN_RZK` | Подписывается в СБК | | `TRIED_BY_CFE` | Проверяется ВК | | `USER_RESERVED` | Зарезервированы логины | | `VALIDEDS` | ЭП/АСП верна | | `PROCESSING_RECALL` | Запрошен отзыв | | **Окончательные статусы/Прекратить опрос** | | | `CLOSED` | Закрыт | | `DELETED` | Удален | | `EXPORTED_TO_1C` | Выгружен в реестр | | `INVALIDEDS` | ЭП/АСП не верна | | `PROCESSERROR` | Отказан | | `REQUISITEERROR` | Ошибка реквизитов | | `REFUSEDBYBANK` | Отвергнут Банком | | `REFUSEDBYABS` | Отказан АБС | | `RECALL` | Отозван | | `RECALL_BY_BANK` | Отозван Банком | | `REFUSED_BY_CFE` | Отказан ВК | | `UNABLE_TO_DECRYPT` | Ошибка шифрования | | `UNABLE_TO_RECEIVE` | Ошибка при приеме | | **Окончательные(Успешные) статусы/Прекратить опрос** | | | `IMPLEMENTED` | Исполнен |
Рекомендации по тестированию в песочнице При отправке запроса на получение статуса валютного поручения, ответ зависит от переданного параметра `externalId`. Для симуляции различных сценариев используйте следующие тестовые идентификаторы: | Передаваемое значение `externalId` | Возвращаемое значение `bankStatus` | | :----------------------------------- | :---------------------------------- | | `a7d93c1b-f0eb-49e6-a2c3-1739bc509f82` | `CHECKERROR` | | `2b5a12dc-d567-4b89-bece-587c38551bca` | `REQUISITEERROR` | | `8e34b6fa-78c5-4a32-b719-429433657f26` | `INVALIDEDS` | | Любое другое значение | `IMPLEMENTED` |
operationId: getState parameters: - in: path name: externalId schema: type: string format: uuid required: true example: "3fa85f64-5717-4562-b3fc-2c963f66afa6" description: "Уникальный идентификатор документа, присвоенный партнёром" responses: 200: description: "Успешное выполнение запроса" content: application/json: schema: $ref: '#/components/schemas/FintechDocState' 400: description: | "Ошибка в запросе" | **Cause** | **Message** | **Description** | | --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в response в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. | | VALIDATION_FAULT | Ошибка валидации | Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 401: description: | "Не авторизован" | **Cause** | **Message** | **Description** | | ------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | UNAUTHORIZED | accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 403: description: | "Операция не может быть выполнена: доступ к ресурсу запрещён" | **Cause** | **Message** | **Description** | ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ACTION_ACCESS_EXCEPTION | Операция не может быть выполнена: доступ к ресурсу запрещен | Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `PAY_DOC_RU`. Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 404: description: "Данные не найдены" content: application/json: schema: $ref: "#/components/schemas/FintechWorkflowFault" 429: description: | "Превышен лимит запросов" | **Cause** | **Message** | **Description** | | ----------------- | -------------------------------------------------- | ---------------------| | TOO_MANY_REQUESTS | Превышен лимит запросов. Повторите операцию позже. | Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 500: description: | "Внутренняя ошибка сервера" | **Cause** | **Message** | **Description** | | ----------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 503: description: | "Сервис временно недоступен" | **Cause** | **Message** | **Description** | | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' /v1/pay-doc-cur/{externalId}: get: tags: - PaymentDocCur summary: Получение документа валютное платежное поручение servers: - url: https://fintech-test.sberbank.ru:9443/fintech/api description: Песочница - url: https://fintech.sberbank.ru:9443/fintech/api description: Промышленный контур description: | Возвращает полные данные ранее созданного валютного платёжного поручения. Должен содержать токен доступа (access_token) пользователя в параметре **Authorization** заголовка и идентификатор документа (**externalId**), указанный при его создании. Для доступа к этому методу в параметре `scope` ссылки авторизации пользователя должен быть указан сервис `PAY_DOC_CUR`.
Рекомендации по тестированию в песочнице При отправке запроса на получение валютного поручения, ответ будет статичным при любом `externalId`.
operationId: getDocument parameters: - in: path name: externalId schema: type: string format: uuid required: true example: "3fa85f64-5717-4562-b3fc-2c963f66afa6" description: "Уникальный идентификатор документа, присвоенный партнёром" responses: 200: description: "Успешное выполнение запроса" content: application/json: schema: $ref: '#/components/schemas/FintechPayDocCur' 400: description: | "Ошибка в запросе" | **Cause** | **Message** | **Description** | | --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в response в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. | | VALIDATION_FAULT | Ошибка валидации | Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 401: description: | "Не авторизован" | **Cause** | **Message** | **Description** | | ------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | UNAUTHORIZED | accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 403: description: | "Операция не может быть выполнена: доступ к ресурсу запрещён" | **Cause** | **Message** | **Description** | | ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ACTION_ACCESS_EXCEPTION | Операция не может быть выполнена: доступ к ресурсу запрещен | Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `PAY_DOC_RU`. Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 404: description: "Данные не найдены" content: application/json: schema: $ref: "#/components/schemas/FintechWorkflowFault" 429: description: | "Превышен лимит запросов" | **Cause** | **Message** | **Description** | | ----------------- | -------------------------------------------------- | ---------------------| | TOO_MANY_REQUESTS | Превышен лимит запросов. Повторите операцию позже. | Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 500: description: | "Внутренняя ошибка сервера" | **Cause** | **Message** | **Description** | | ----------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' 503: description: | "Сервис временно недоступен" | **Cause** | **Message** | **Description** | | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. | content: application/json: schema: $ref: '#/components/schemas/FintechWorkflowFault' components: schemas: FintechPayDocCur: type: object title: PaymentDocCur description: Валютное платежное поручение required: - beneficiaryBankCountryDigital - beneficiaryBankCountryIso2 - beneficiaryBankName - beneficiaryBankPlace - beneficiaryCountryDigital - beneficiaryCountryIso2 - beneficiaryName - beneficiaryPlace - chargesType - date - externalId - inn - option50a - option57a - orgName - payerAccount - payerAddress - payerBankBic - payerCountryDigital - payerCountryIso2 - payerCountryName - payerName - payerPlace - paymentDetails - paymentDirection - rateAgree - urgent properties: bankStatus: type: string description: Статус документа readOnly: true example: "PROCESSING" bankComment: type: string readOnly: true description: Банковский комментарий к статусу документа example: "Документ успешно отправлен в банк" addInfo: type: string maxLength: 300 description: Примечание example: "Примечание" additionalInfo: type: string maxLength: 220 description: Информация получателю платежа example: "CCTFDR" amountTransfer: $ref: "#/components/schemas/AmountCurrency" authPersonName: type: string maxLength: 60 example: "Петров Петр Иванович" description: ФИО ответственного лица authPersonTelfax: type: string maxLength: 40 description: Телефон ответственного лица example: "79263689379" b77info: type: string maxLength: 109 description: Информация для регулирующих органов example: "BENEFRES" beneficiaryAccount: type: string description: Счет бенефициара maxLength: 34 pattern: "^[0-9]{1,34}$" example: "40802810600000200000" beneficiaryAddress: type: string maxLength: 255 description: | Адрес бенефициара. Максимальное количество символов для платежей в Индию составляет 33 символа. example: "UL.POBEDA,D.80" beneficiaryBankAccount: type: string pattern: "^[0-9]{1,35}$" description: Корреспондентский счёт банка бенефициара example: "40802810600000200000" beneficiaryBankAddress: type: string maxLength: 255 description: Адрес банка бенефициара example: "3, AVENUE HOCHE" beneficiaryBankBranchName: type: string maxLength: 70 description: Наименование филиала банка бенефициара example: "TREASURY DEPARTMENT" beneficiaryBankClearingCode: $ref: "#/components/schemas/ClearingCode" beneficiaryBankCountryDigital: type: string pattern: "^[0-9]{3}$" description: Цифровой код страны банка бенефициара example: "356" beneficiaryBankCountryIso2: type: string pattern: "^[A-Z]{2}$" description: 2х буквенный ISO-код страны банка бенефициара example: "IN" beneficiaryBankName: type: string maxLength: 140 description: Наименование банка бенефициара example: "ALANDSBANKEN ABP (FINLAND),SVENSK FILIAL" beneficiaryBankPlace: type: string maxLength: 255 description: Местонахождение банка бенефициара example: "TREASURY DEPARTMENT" beneficiaryBankSwift: type: string maxLength: 11 description: SWIFT-код банка бенефициара example: "ICBKFIHH" beneficiaryBeiCode: type: string maxLength: 11 description: BEI-код (SWIFT-код) example: "ICBKFIHH" beneficiaryCountryDigital: type: string pattern: "^[0-9]{3}$" description: Цифровой код страны бенефициара example: "643" beneficiaryCountryIso2: type: string pattern: "^[A-Z]{2}$" description: 2х буквенный ISO-код страны бенефициара example: "RU" beneficiaryCountryName: type: string pattern: "^[А-Яа-я ]*$" maxLength: 255 description: Наименование страны бенефициара на русском языке (краткое наименование) example: "РОССИЯ" beneficiaryInn: type: string pattern: "^([0-9]{10}|[0-9]{12}|0)$" description: ИНН бенефициара. 10 либо 12 цифр, либо 0 example: "678015836445" beneficiaryName: type: string maxLength: 140 description: Наименование бенефициара example: "EMIRP" beneficiaryPlace: type: string maxLength: 35 description: Город (месторасположение) бенефициара example: "MOSKVA" chargesType: type: string pattern: "^(BEN|SHA|OUR)$" description: Тип комиссии за перевод BEN, SHA или OUR example: "BEN" codes23e: type: array items: $ref: "#/components/schemas/Code23e" date: type: string format: date description: Дата документа example: "2023-12-31" digestSignatures: type: array items: $ref: "#/components/schemas/FintechSignature" description: Электронные подписи по дайджесту документа externalId: type: string format: uuid description: Идентификатор документа в организации-партнёре (UUID) example: "550e8400-e29b-41d4-a716-446655440000" factRate: type: number readOnly: true description: Фактический курс конверсии example: '1.0001' iMediaBankAddress: type: string maxLength: 255 description: Адрес банка-посредника example: "33 BEETHOVENSTRASSE" iMediaBankCountryDigital: type: string pattern: "^[0-9]{3}$" description: Цифровой код страны банка-посредника example: "576" iMediaBankCountryIso2: type: string pattern: "^[A-Z]{2}$" description: 2х буквенный ISO-код страны банка-посредника example: "CH" iMediaBankName: type: string maxLength: 140 description: Наименование банка-посредника example: "ABN AMRO BANK (SCHWEIZ)" iMediaBankPlace: type: string maxLength: 35 description: Местоположение банка-посредника example: "ZURICH" iMediaBankSwift: type: string maxLength: 11 description: SWIFT-код банка-посредника example: "ABNACHZZ80A" iMediaClearingCode: $ref: "#/components/schemas/ClearingCode" iMediaFilialBankName: type: string maxLength: 140 description: Наименование филиала банка-посредника example: "FILIAL ONE OF ABN AMRO BANK (SCHWEIZ)" inn: type: string pattern: "^([0-9]{10}|[0-9]{12}|0)$" description: ИНН клиента example: "123456236440" linkedDocs: type: array items: $ref: "#/components/schemas/FintechLinkedDoc" number: type: string pattern: "^[0-9]{1,7}$" description: Номер документа example: "1234567" option50a: type: string pattern: "^[KF]$" description: Опция "K" , "F" для поля 50а example: "F" option56a: type: string pattern: "^[AD]$" description: Опция "A", "D" для поля 56а example: "A" option57a: type: string pattern: "^[AD]$" description: Опция "A", "D" для поля 57а example: "A" option59a: type: string pattern: "^[AF]$" description: Опция "А", "F" для поля 59а или «без опции» example: "A" orgName: type: string maxLength: 160 description: Наименование организации клиента example: "ООО \"Наименование организации\"" payerAccount: type: string pattern: "^[0-9]{20}$" description: Счёт перевододателя example: "12341234123412341234" payerAddress: type: string maxLength: 35 example: "UL.DOBROLIUBOVA,D.18,OF.III" description: | Адрес перевододателя. Максимальное количество символов для платежей в Индию составляет 33 символа. payerBankBic: type: string pattern: "^[0-9]{9}$" description: БИК банка перевододателя example: "044525225" payerBankPlace: type: string maxLength: 35 description: Местонахождение банка перевододателя example: "MOSCOW" payerCountryDigital: type: string pattern: "^[0-9]{3}$" description: Цифровой код страны перевододателя example: "643" payerCountryIso2: type: string pattern: "^[A-Z]{2}$" description: 2х буквенный ISO-код страны перевододателя example: "RU" payerCountryName: type: string maxLength: 80 description: Наименование страны перевододателя на русском языке (краткое наименование) example: "РОССИЯ" payerName: type: string maxLength: 140 description: Международное наименование перевододателя example: "LLC COMPANY" payerPlace: type: string maxLength: 35 description: Город (местонахождение) перевододателя example: "MOSCOW" paymentDetails: type: string maxLength: 137 description: | Назначение платежа. Чтобы передать "Код назначения перевода", необходимо заполнить данное поле в формате: "(ХХХХХ) Текст назначения платежа", где (ХХХХХ)- код назначения перевода. example: "(P1019) CONTRACT 12321" paymentDirection: type: string maxLength: 10 description: 'Направление платежа (Платеж внутри или вне СБРФ): 1-внутри, 0-вне' example: "0" rateAgree: type: boolean description: С курсом проведения конверсионной операции согласны example: true urgent: type: boolean description: Срочность. Значение необходимо отправлять, если по счету списания есть возможность отправлять неотложные платежи. example: false valueDate: type: string readOnly: true format: date description: Дата валютирования/возврата example: "2025-12-31" amountDebitTotal: type: number minimum: 0.01 exclusiveMinimum: false readOnly: true description: Фактическая сумма списанной валюты example: '1.01' ClearingCode: type: object description: Клиринговый код банка бенефициара properties: clearingCode: type: string maxLength: 11 description: Клиринговый код банка-посредника example: "BANKCODE123" countryCode: type: string pattern: "^[A-Z]{2}$" description: Обозначение национального клирингового кода банка-посредника example: "IN" shortName: type: string maxLength: 140 description: Сокращенное наименование национального клирингового кода банка-посредника example: "Indian Financial System Code" symbol: type: string pattern: "^[A-Z]{2}$" description: Обозначение национального клирингового кода банка-посредника example: "IFSC" AmountCurrency: type: object required: - amount - currencyCode - currencyName properties: amount: type: number nullable: false minimum: 0.01 x-extra-annotation: '@ru.sberbank.pprb.sbbol.corpsbbapirko.common.validation.AmountValid' example: '1.01' description: Сумма currencyCode: type: string pattern: "^[A-Z\\d]\\d{2}$" description: Цифровой код валюты example: "840" currencyName: type: string pattern: "^[A-Z]{3}$" description: Буквенный ISO-код валюты example: "USD" FintechLinkedDoc: description: Связанные документы type: object required: - docExtId - type properties: docExtId: type: string #maxLength: 36 #pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ format: uuid nullable: false description: Идентификатор документа в организации-партнёре (UUID) example: "31663ef5-7975-4016-b0f3-f1d70a4e9c22" type: type: string nullable: false minLength: 1 maxLength: 50 description: Тип связанного документа example: "CurrencyOperationDetails" Code23e: type: object required: - code description: 23E Код инструкции properties: code: type: string maxLength: 4 description: Код инструкции example: "SDVA" description: type: string maxLength: 255 example: "Средства должны быть зачислены бенефициару той же датой валютирования" info: type: string maxLength: 30 description: Дополнительная информация example: "DOPOLNITEL INFO 8747483893" FintechSignature: description: Электронная подпись title: Signature type: object required: - certificateUuid - base64Encoded properties: certificateUuid: type: string format: uuid description: Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID) example: "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6" base64Encoded: type: string nullable: false minLength: 1 description: Значение электронной подписи, закодированное в Base64 example: "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==" FintechDocState: description: Статус документа type: object title: DocState allOf: - $ref: '#/components/schemas/FintechDocStateShort' - type: object properties: channelInfo: type: string title: Дополнительная информация description: Комментарий, специфичный для документа, полученного по данному каналу FintechWorkflowFault: description: Описание ошибки ресурса (ошибка в запросе или его жизненном цикле) type: object title: WorkflowFault properties: cause: type: string example: "WORKFLOW_FAULT" description: Причина или основание ошибки referenceId: type: string description: Уникальный идентификатор ошибки (UUID) message: type: string description: Сообщение checks: type: array description: Список проверок, приведших к ошибке items: $ref: '#/components/schemas/FintechCheck' internalErrorCode: description: Внутренний код ошибки nullable: true type: string FintechDocStateShort: description: Сокращенный статус документа type: object title: DocStateShort properties: bankStatus: type: string description: Статус документа example: "PROCESSING" bankComment: type: string maxLength: 255 description: Банковский комментарий к статусу документа example: "Документ в обработке" FintechCheck: description: Результат проверки type: object title: Check properties: level: type: string description: Уровень результата example: ERROR message: type: string description: Сообщение fields: type: array items: type: string description: Названия полей (при наличии связи с моделью)