Получение сведений о валютной операции

Обновлено 29 ноября 2024

Компаниям

Холдингам

/fintech/api/v1/currency-operation-details/{externalId}

Запрос позволяет получить полные данные ранее созданного документа «Справка о валютной операции» (далее СВО).

Для получения полных данных СВО необходимо отправить GET-запрос /fintech/api/v1/currency-operation-details/{externalId} с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатором документа (externalId) в path-параметре.

В параметре scope ссылки авторизации пользователя должен быть указан сервис CURRENCY_OPERATION_DETAILS для получения доступа к этому запросу.

Для обращения к ресурсу необходимо отправлять запрос на:

• Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443
• Промышленный контур https://fintech.sberbank.ru:9443

Request

/fintech/api/v1/currency-operation-details/{externalId}

• Модель
• Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
PATH PARAMETER
externalId	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	required	Идентификатор документа, присвоенный вами при его создании

GET /fintech/api/v1/currency-operation-details/6a54593d-464b-4c8e-a7e2-742a05e5c241 HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*

Responses

200 (OK)

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
CurrencyOperationDetails {
acceptDate	string	optional	Дата представления в банк,
accountNumber	string	optional	Номер счета,
addInfo	string	optional	Дополнительная информация,
authPersonName	string	optional	ФИО ответственного лица,
authPersonTelfax	string	optional	Телефон ответственного лица,
bankComment	string	optional	Банковский комментарий к статусу документа,
bankNonResidentCountryName	string	optional	Наименование страны,
bankNonResidentCountryNumericCode	string	required	Цифровой код страны,
bankStatus	string	required	Статус документа,
bfAttachments	array[BfAttachment]	optional	Прикрепленные большие файлы,
correction	boolean	optional	Признак корректировки,
correctionNumber	integer	optional	Порядковый номер корректировки,
currencyDocDate	string	optional	Дата валютного документа,
currencyDocNumber	string	optional	Номер документа по валютной операций,
currencyDocType	string	optional	Тип валютного документа,
date	string	required	Дата составления документа,
digestSignatures	array[Signature]	optional	Электронные подписи по дайджесту документа,
executorEmployeeName	string	optional	Должность ответственного лица,
executorName	string	optional	Подпись ответственного лица,
externalId	string	required	Идентификатор документа, который вы присваиваете самостоятельно,
failReasons	array[FailReason]	optional	Причины отказа,
isAccountInOtherBank	boolean	required	Признак счета в другом банке,
isNumberAbsent	boolean	required	Признак отсутствия номера валютного документа,
linkedDocs	array[LinkedDoc]	optional	Cвязанные документы,
number	string	optional	Номер документа,
operationDate	string	optional	Дата операции,
operations	array[CurrencyOperationDetailsDoc]	required	Документы валютного контроля,
paymentAmount	AmountCurrency	required	Сумма и валюта платежа,
paymentDirection	string	required	Направление платежа,
senderInn	string	required	ИНН резидента, указываемый в документе,
senderName	string	required	Полное наименование организации, указываемое в документе,
senderOkpo	string	required	ОКПО клиента, указываемый в документе,
valueDate	string	optional	Дата принятия/возврата
}
BfAttachment {
fileId	string	optional	Уникальный идентификатор файла,
fileName	string	optional	Имя файла
}
Signature {
base64Encoded	string	required	Значение электронной подписи (ЭП), закодированное в Base64,
certificateuuid	string	required	Уникальный идентификатор сертификата ключа проверки электронной подписи
}
FailReason {
docField	string	optional	Поле документа,
reasonComment	string	optional	Правило заполнения/замечания,
reasonId	string	optional	Код причины отказа,
returnComment	string	optional	Комментарий
}
LinkedDoc {
docExtId	string	required	Идентификатор документа во внешней системе,
type	string	required	Тип связанного документа
}
CurrencyOperationDetailsDoc {
additionalInfo	string	optional	Примечание,
amount	AmountCurrency	required	Сумма платежа,
contractDate	string	optional	Дата договора,
contractNumber	string	optional	Номер договора,
contractNumberType	string	optional	Тип указание номера договора,
creditAmount	AmountCurrency	optional	Сумма платежа в валюте цены контракта,
dataComposition	string	optional	Состав предоставляемой информации,
expectedDate	string	optional	Ожидаемый срок,
operationCode	string	required	Код вида валютной операции,
operationCodeDescription	string	required	Описание валютной операции,
operationReason	string	required	Основание проведения операции,
passportNumber	string	optional	Уникальный номер контракта (кредитного договора),
paymentConditions	string	optional	Условия расчета,
serialNumber	integer	required	Номер по порядку
}
AmountCurrency {
amount	number	required	Сумма,
currencyCode	string	required	Цифровой код валюты,
currencyName	string	required	Буквенный ISO-код валюты
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "acceptDate": "2018-12-31",
  "accountNumber": "40802840600000200000",
  "addInfo": "Дополнительная информация",
  "authPersonName": "Иванов Иван Иванович",
  "authPersonTelfax": "4955005550",
  "bankComment": "string",
  "bankNonResidentCountryName": "РОССИЯ",
  "bankNonResidentCountryNumericCode": "643",
  "bankStatus": "string",
  "bfAttachments": [
    {
      "fileId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "fileName": "SB_7718830000_40702810038290010000_T18.txt"
    }
  ],
  "correction": false,
  "correctionNumber": 0,
  "currencyDocDate": "2018-12-31",
  "currencyDocNumber": "123",
  "currencyDocType": "PayDocCur",
  "date": "2018-12-31",
  "digestSignatures": [
    {
      "base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
      "certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
    }
  ],
  "executorEmployeeName": "Ответственный исполнитель банка",
  "executorName": "Иванов Иван Иванович",
  "externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
  "failReasons": [
    {
      "docField": "Номер контракта",
      "reasonComment": "Указан неверно",
      "reasonId": "PS_REST_REJ_PART_2-9",
      "returnComment": "Отказ проверки"
    }
  ],
  "isAccountInOtherBank": false,
  "isNumberAbsent": false,
  "linkedDocs": [
    {
      "docExtId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "type": "ExportContractInsure"
    }
  ],
  "number": "1",
  "operationDate": "2018-12-31",
  "operations": [
    {
      "additionalInfo": "Дополнительная информация",
      "amount": {
        "amount": 1.01,
        "currencyCode": "840",
        "currencyName": "USD"
      },
      "contractDate": "2018-12-31",
      "contractNumber": "123",
      "contractNumberType": "0",
      "creditAmount": {
        "amount": 1.01,
        "currencyCode": "840",
        "currencyName": "USD"
      },
      "dataComposition": "1",
      "expectedDate": "2018-12-31",
      "operationCode": "20300",
      "operationCodeDescription": "Оплата нерезидента резиденту по договору аренды движимого или недвижимого имущества",
      "operationReason": "1",
      "passportNumber": "120123A0/1234/GU23/1/2",
      "paymentConditions": "0",
      "serialNumber": 1
    }
  ],
  "paymentAmount": {
    "amount": 1.01,
    "currencyCode": "840",
    "currencyName": "USD"
  },
  "paymentDirection": "1",
  "senderInn": "7707083893",
  "senderName": "Общество с ограниченной ответственностью \"Клиент\"",
  "senderOkpo": "222221001",
  "valueDate": "2018-12-31"
}

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, не указана операция CURRENCY_OPERATION_DETAILS. Необходимо добавить одному или несколько операций в 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": "Внутренняя ошибка сервера"
}