Получение статуса отправленного документа

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

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

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

Для получения статуса СВО необходимо отправить GET-запрос /fintech/api/v1/currency-operation-details/{externalId}/state с токеном доступа (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}/state

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

Наименование	Тип	Формат	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)

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

Наименование	Тип	Обязательность	Описание
DocState {
bankComment	string	optional	Банковский комментарий к статусу документа,
bankStatus	string	optional	Статус документа,
channelInfo	string	optional	Комментарий, специфичный для документа, полученного по данному каналу
}

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

{
  "bankComment": "Документ в обработке",
  "bankStatus": "PROCESSING",
  "channelInfo": "string"
}

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, не указана операция `PAY_DOC_CUR`. Необходимо добавить одному или несколько операций в 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	Сообщение,
}

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": "Внутренняя ошибка сервера"
}

Статусы СВО

bankStatus (string)

Код состояние документа	Наименование статуса	Назначение кода состояния
Промежуточные статусы/Продолжать опрашивать
`CHECK_ERROR`	Ошибка контроля	Сведения о валютной операции сохранены, но есть ошибки контроля
`CREATED`	Создан	Сведения о валютной операции созданы клиентом для отправки в банк (не подписаны).
`IMPORTED`	Импортирован	Сведения о валютной операции импортированы из систем клиента для отправки в банк (не подписаны).
`CREATED_CS`	Создан банком	Сведения о валютной операции созданы банком в рамках оказания консалтинговой услуги (не подписаны)
`SIGNED`	Подписан	Сведения о валютной операции подписаны, готовы к отправке в банк
`DELIVERED` `EXPORTED` `EXPORT_ERROR` `ACCEPTED_BY_ABS`	В обработке	Клиент отправил сведения о валютной операции на проверку в банк.
Окончательные статусы/Прекратить опрос
`REFUSED_BY_ABS`	Ошибка	Сведения о валютной операции не приняты банком, валютный контроль пройден
`REFUSED_BY_CFE`	Отказ ВК	Сведения о валютной операции отказаны после проверки валютным контролем
`INVALID_SIGN`	Подпись неверна	Возникла ошибка при подписании сведений о валютной операции
Окончательные(Успешные) статусы/Прекратить опрос
`ACCEPTED_BY_CFE`	Принят ВК	Сведения о валютной операции приняты банком, валютный контроль пройден
`RECALL`	Отозван	Сведения и валютной операции отозваны клиентом до обработки документа банком

Получение статуса отправленного документа

Статусы СВО﻿

Статусы СВО