Получение документа справки о подтверждающих документах

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

Компаниям

Холдингам

`/fintech/api/v1/confirmatory-documents-inquiries/{externalId}

Запрос позволяет получить полные данные ранее созданного документа «Справка о подтверждающих документах» (далее СПД).

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

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

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

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

Request

/fintech/api/v1/confirmatory-documents-inquiries/{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/confirmatory-documents-inquiries/6a54593d-464b-4c8e-a7e2-742a05e5c241 HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*

Responses

200 (OK)

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

Наименование	Тип	Обязательность	Описание
ConfirmatoryDocumentsInquiry {
acceptDate	string	optional	Дата представления в банк,
authPersonName	string	optional	ФИО ответственного лица,
authPersonTelfax	string	optional	Телефон ответственного лица,
bankComment	string	optional	Банковский комментарий к статусу документа,
bankStatus	string	optional	Статус документа,
bfAttachments	array[BfAttachment]	optional	Прикрепленные большие файлы,
customerBankBIC	string	optional	БИК банка резидента,
customerINN	string	required	ИНН резидента,
customerName	string	required	Наименование резидента,
customerOKPO	string	required	ОКПО резидента,
date	string	required	Дата составления документа,
dealDate	string	required	Дата справки
digestSignatures	array[Signature]	optional	Электронные подписи по дайджесту документа,
docs	array[ConfirmatoryDocumentsInquiryDoc]	optional	Документы, включенные в справку,
executorEmployeeName	string	optional	Должность ответственного лица,
executorName	string	optional	Подпись ответственного лица,
externalId	string	required	Идентификатор документа, который вы присваиваете самостоятельно,
failReasons	Array[FailReason]	optional	Причины отказа,
number	string	optional	Номер документа,
psNumber	string	optional	Уникальный номер контракта (кредитного договора)
returnReason1	boolean	optional	Флаг причины возврата 16.1.1,
returnReason1Comment	string	optional	Комментарий причины возврата 16.1.1,
returnReason2	boolean	optional	Флаг причины возврата 16.1.3,
returnReason2Comment	string	optional	Комментарий причины возврата 16.1.3,
returnReason3	boolean	optional	Флаг причины возврата 16.1.4,
returnReason3Comment	string	optional	Комментарий причины возврата 16.1.4,
returnReason4	boolean	optional	Флаг причины возврата 16.1.5,
returnReason4Comment	string	optional	Комментарий причины возврата 16.1.5,
valueDate	string	optional	Дата принятия/возврата
}
BfAttachment {
fileId	string	optional	Уникальный идентификатор файла,
fileName	string	optional	Имя файла
}
Signature {
base64Encoded	string	required	Значение электронной подписи (ЭП), закодированное в Base64,
certificateuuid	string	required	Уникальный идентификатор сертификата ключа проверки электронной подписи
}
ConfirmatoryDocumentsInquiryDoc {
addInfo	string	optional	Дополнительная информация,
confDocDate	string	optional	Дата подтверждающего документа,
confDocNumber	string	optional	Номер подтверждающего документа,
contractSum	AmountCurrency	optional	Сумма и валюта контракта,
contractSumDel	number	optional	Сумма, соответствующая признаку поставки 2 или 3, в валюте цены контракта (кредитного договора),
correctionDate	string	optional	Дата корректировки,
correctionNumber	integer	optional	Номер корректировки,
countryCode	string	optional	Код страны грузополучателя (грузоотправителя)
countryName	string	optional	Наименование страны грузополучателя (грузоотправителя),
docCode	string	required	Код вида документа,
docName	string	required	Наименование вида документа,
docSum	AmountCurrency	required	Сумма и валюта документа,
docSumDel	number	optional	Сумма, соответствующая признаку поставки 2 или 3, в валюте документа,
expectedLife	string	optional	Ожидаемый срок,
hasConfDocNumber	boolean	required	Признак присутствия номера подтверждающего документа,
ordinalNumber	integer	required	Порядковый номер строки в справке,
supplyFeature	string	optional	Признак поставки
}
FailReason {
docField	string	optional	Поле документа,
reasonComment	string	optional	Правило заполнения/замечания,
reasonId	string	optional	Код причины отказа,
returnComment	string	optional	Комментарий
}
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",
   "authPersonName":"Иванов Иван Иванович",
   "authPersonTelfax":"4955005550",
   "bankComment":"string",
   "bankStatus":"string",
   "bfAttachments":[
      {
         "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
         "fileName":"SB_7718830000_40702810038290010000_T18.txt"
      }
   ],
   "customerBankBIC":"044525225",
   "customerINN":"7707083893",
   "customerName":"Общество с ограниченной ответственностью \"Клиент\"",
   "customerOKPO":"222221001",
   "date":"2018-12-31",
   "dealDate":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "docs":[
      {
         "addInfo":"Дополнительная информация",
         "confDocDate":"2018-12-31",
         "confDocNumber":"123",
         "contractSum":{
            "amount":1.01,
            "currencyCode":"840",
            "currencyName":"USD"
         },
         "contractSumDel":1.01,
         "correctionDate":"2018-12-31",
         "correctionNumber":1,
         "countryCode":"643",
         "countryName":"РОССИЯ",
         "docCode":"03_3",
         "docName":"03_3 О передаче резидентом на территории Российской Федерации товаров и оказании услуг нерезиденту по контрактам, указанным в подпункте 5.1.2 пункта 5.1 настоящей Инструкции",
         "docSum":{
            "amount":1.01,
            "currencyCode":"840",
            "currencyName":"USD"
         },
         "docSumDel":1.01,
         "expectedLife":"2018-12-31",
         "hasConfDocNumber":false,
         "ordinalNumber":1,
         "supplyFeature":"1"
      }
   ],
   "executorEmployeeName":"Ответственный исполнитель банка",
   "executorName":"Иванов Иван Иванович",
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "failReasons":[
      {
         "docField":"Номер контракта",
         "reasonComment":"Указан неверно",
         "reasonId":"PS_REST_REJ_PART_2-9",
         "returnComment":"Отказ проверки"
      }
   ],
   "number":"1",
   "psNumber":"120123A0/1234/GU23/1/2",
   "returnReason1":false,
   "returnReason1Comment":"Ошибка",
   "returnReason2":false,
   "returnReason2Comment":"Ошибка",
   "returnReason3":false,
   "returnReason3Comment":"Ошибка",
   "returnReason4":false,
   "returnReason4Comment":"Ошибка",
   "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, не указана операция CONFIRMATORY_DOCUMENTS_INQUIRY. Необходимо добавить одному или несколько операций в 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": "Внутренняя ошибка сервера"
}