Сервис инкассации

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

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

Ресурс /v1/encash/encash-contracts позволяет получить список договоров инкассации. Информация необходима для формирования заявки на добавление объекта инкассации к одному из полученных договоров.

Шаги:

  1. Получить AccessToken.
  2. Отправить запрос.

Авторизация

Для получения список договоров необходимо отправить GET-запрос (/v1/encash/encash-contracts), в котором необходимо передать авторизационный токен к данным собственной организации (Access Token) и внешний идентификатор платежного поручения. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис ENCASH_DOCUMENTS.

Модель запроса

Параметры заголовка
Authorization (String) Access token полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
page (Integer) Номер запрашиваемой страницы (начиная с 1)

Пример запроса

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/encash/encash-contracts?page=1'

Модель ответа

EncashmentContracts
_links (Array[Link], optional) Ссылки на связанные ресурсы
encashmentContracts (Array[EncashmentContract], optional) Документы "Договор инкассации"
Link
href (string) Абсолютный или относительный адрес
rel (string) Отношение ссылки к текущей сущности (next, prev)
EncashmentContract
createDate (string, optional) Дата заключения договора
endDate (string, optional) Дата окончания действия договора
feeChargeTypes (string, optional) Способ взимания комиссии
number (string, optional) Номер договора
objects (Array[EncashmentContractObject], optional) Объекты инкассации
servicesInfo (Array[EncashmentServicesInfo], optional) Информация об услугах по договору инкассации
startDate (string, optional) Дата начала действия договора
EncashmentContractObject
address (string, optional) Адрес объекта инкассации
encashContractAccounts (Array[EncashmentContractAcc], optional) Счета списания
encashDebitAccounts (Array[EncashmentContractAcc], optional) Счета зачисления наличности
name (string, optional) Наименование объекта инкассации
objectStatus (string, optional) Статус объекта инкассации
EncashmentServicesInfo
serviceName (string, optional) Наименование услуги
serviceType (integer, optional) Тип услуги
EncashmentContractAcc
bankCode (string, optional) БИК
bankName (string, optional) Наименование банка
number (string, optional) Номер счета

Пример ответа

{
   "_links":[
      {
         "href":"?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
         "rel":"next"
      }
   ],
   "encashmentContracts":[
      {
         "createDate":"2018-12-31",
         "endDate":"2018-12-31",
         "feeChargeTypes":"FACT_SCHET_GRP,IPT_SEND",
         "number":"38/943/04",
         "objects":[
            {
               "address":"г.Москва, ул.Тамбовская, д.5",
               "encashContractAccounts":[
                  {
                     "bankCode":"044525225",
                     "bankName":"ПАО СБеРБАНК",
                     "number":"40802810600000200000"
                  }
               ],
               "encashDebitAccounts":[
                  {
                     "bankCode":"044525225",
                     "bankName":"ПАО СБеРБАНК",
                     "number":"40802810600000200000"
                  }
               ],
               "name":"АО \"Тандер\" Многоцветница 773460",
               "objectStatus":"ARHIV"
            }
         ],
         "servicesInfo":[
            {
               "serviceName":"ENCASH",
               "serviceType":0
            }
         ],
         "startDate":"2018-12-31"
      }
   ]
}

Создание заявки на добавление объектов

Ресурс /v1/encash/encash-add-requests позволяет создавать заявку на добавление объектов инкассации, что позволяет передать в Банк информацию о новых объектах инкассации.

Шаги:

  1. Получить AccessToken.
  2. Сформировать ЭП.
  3. Отправить запрос.
  4. Получить статус.

Авторизация

Для создания заявки необходимо отправить POST-запрос (/v1/encash/encash-add-requests), в котором необходимо передать авторизационный токен к данным собственной организации (Access Token) и внешний идентификатор платежного поручения. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис ENCASH_DOCUMENTS.

Модель запроса

Параметры заголовка
Authorization (String) Access token собственной организации, полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
EncashAddRequest
bankComment (string, optional, read only) Банковский комментарий к статусу документа
bankStatus (string, optional, read only) Статус документа
contactName (string) ФИО контактного лица
contactRemarks (string, optional) Комментарий
date (string) Дата составления документа
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа
email (string) Адрес электронной почты
encashObjects (Array[EncashAddRequestObject], optional) Объекты инкассации
externalId (string) Идентификатор документа в организации-партнере
number (string, optional) Номер документа
phoneNumber (string) Контактный телефон
Signature
base64Encoded (string) Значение электронной подписи, закодированное в Base64
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
EncashAddRequestObject
contractModifyDate (string) Желаемая дата внесения изменений в договор инкассации
objectAddress (string) Адрес объекта
objectContactName (string) Контактное лицо на объекте
objectContactPhone (string) Контактный номер телефона на объекте
objectName (string) Наименование объекта
objectRegion (string) Регион объекта
services (Array[EncashAddRequestService]) Подключаемые услуги
workSchedule (Array[EncashAddRequestSchedule]) Объекты инкассации
EncashAddRequestService
encashContractDate (string) Дата создания договора инкассации
encashContractNum (string) Номер договора инкассации
serviceType (integer) Тип услуги
visitInfo (EncashAddRequestVisitInfo, optional) Информация о заездах
EncashAddRequestSchedule
day (string) День недели графика работы = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] stringEnum:"Mon", "Tue","Wed","Thu","Fri", "Sat", "Sun",
timeFrom (integer) Время работы с
timeTo (integer) Время работы по
EncashAddRequestVisitInfo
cashAmount (number) Сумма сдаваемой наличности за заезд
cashCoins (number) Сумма монет в объеме сдаваемой наличности
countInMonth (integer) Количество заездов в месяц
isByRequest (boolean) Тип обслуживания
schedule (Array[EncashAddRequestSchedule]) График заездов

Пример запроса

{
   "bankComment":"string",
   "bankStatus":"string",
   "contactName":"Иванов Иван Иванович",
   "contactRemarks":"Новый комментарий",
   "date":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "email":"address@email.ru",
   "encashObjects":[
      {
         "contractModifyDate":"2018-12-31",
         "objectAddress":"г. Москва, Кутузовский проспект, д 32",
         "objectContactName":"Иванов Иван Иванович",
         "objectContactPhone":"89269999999",
         "objectName":"АО \"Киберлинк\" технологии 555100",
         "objectRegion":"Москва",
         "services":[
            {
               "encashContractDate":"2018-12-31",
               "encashContractNum":"76-И",
               "serviceType":3,
               "visitInfo":{
                  "cashAmount":15000,
                  "cashCoins":25000,
                  "countInMonth":10,
                  "isByRequest":true,
                  "schedule":[
                     {
                        "day":"Fri",
                        "timeFrom":9,
                        "timeTo":18
                     }
                  ]
               }
            }
         ],
         "workSchedule":[
            {
               "day":"Fri",
               "timeFrom":9,
               "timeTo":18
            }
         ]
      }
   ],
   "externalId":"55daccdf-de87-3879-976c-8b8415c8caf9",
   "number":"1",
   "phnoneNumber":"4955005550"
}

Передача электронной подписи

Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature:

Наименование Описание Пример
certificateUuid (String) Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto) 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
base64Encoded (String) Значение ЭП документа HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==

Для платежных поручений, создаваемым по собственным счетам можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:

  • если ЭП переданы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу;
  • если ЭП не были переданы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

Документ может быть подписан следующими наборами подписей:

  • одна (единственная) подпись,
  • первая и вторая подписи.

При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.

Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля пользователя при заведении в Банке.

Формат дайджеста

Наименование Описание Пример
date Дата составления документа 2019-11-20
externalId Идентификатор документа в организации-партнере (UUID) 7beb4b73-ba9d-49e9-9b6d-d9a169ad2638
email Адрес электронной почты контактного лица по заявке test-encash@example.ru
contactName ФИО контактного лица по заявке Иванков Иван Алексеевич
contactRemarks Комментарий к Заявке Комментарий
phoneNumber Контактный телефон 8495111111
TABLES:
Table=EncashmentObjects Информация об объектах инкассации
# Разделитель данных об услугах инкассации
objectAddress Адрес объекта инкассации Россия, Москва, Коптевская улица
objectContactName Контактное лицо на объекте инкассации Иванов Алексей Алексеевич
objectContactPhone Контактный номер телефона на объекте инкассации 89269999999
objectName Наименование объекта инкассации АО “Кибер”
objectRegion Регион объекта инкассации Москва
# Разделитель данных об услугах инкассации
Table=EncashmentObjectServices Информация об услугах инкассации объектов
# Разделитель данных об услугах инкассации
encashContractDate Дата создания договора инкассации 2019-09-15
encashContractNum Номер договора инкассации 76-И
contractModifyDate Желаемая дата внесения изменений в договор инкассации 2020-01-01
serviceType Тип услуги 0
isByRequest Тип обслуживания true
cashAmount Сумма перевозимой наличности за 1 заезд 15000.00
cashCoins Сумма монет в объеме сдаваемой наличности 2500.00
countInMonth Количество заездов в месяц 16

Пример дайджеста

date=2019-11-20
externalId=7beb4b73-ba9d-49e9-9b6d-d9a169ad2638
email=test-encash@example.ru
contactName=Иванков Иван Алексеевич
contactRemarks=Комментарий
phoneNumber=8495111111
TABLES
Table=EncashmentObjects
#
objectAddress=Россия, Москва, Коптевская улица
objectContactName=Иванов Алексей Алексеевич
objectContactPhone=89269999999 
objectName=АО “Кибер”
objectRegion=Москва
#
Table=EncashmentObjectServices
#
encashContractDate=2019-09-15
encashContractNum=76-И
contractModifyDate=2020-01-01
serviceType=0
isByRequest=true
cashAmount=15000.00
cashCoins=2500.00
countInMonth=16
#

Получение информации о КИЦ

Ресурс /v1/encash/encashment-object-centers позволяет получить информацию о доступных кассово-инкассаторских центрах (КИЦ).

Шаги:

  1. Получить AccessToken.
  2. Отправить запрос.

Авторизация

Для получения информацию о доступных кассово-инкассаторских центров необходимо отправить GET-запрос (/v1/encash/encashment-object-centers), в котором нужно передать авторизационный токен к данным собственной организации (Access Token) и номер запрашиваемой страницы (Page=1). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис ENCASH_DOCUMENTS.

Модель запроса

Параметры заголовка
Authorization (String) Access token полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
page (Integer) Номер запрашиваемой страницы (начиная с 1)

Пример запроса

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/encash/encashment-object-centers?page=1'

Модель ответа

_links (Массив объектов JSON (array))
href (string (100)) Абсолютный или относительный адрес
rel (string (4)) Отношение ссылки к текущей сущности (next, prev)
encashmentObjectCenters (Объект JSON массив)
eocAddress (String (2000)) Адрес КИЦ
eocName (String(256)) Наименование
eocId (String(12)) Идентификатор КИЦа

Пример ответа

{
   "_links":[
      {
         "href":"?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
         "rel":"next"
      }
   ],
   "encashmentObjectCenters":[
      {
         "eocAddress":"217146, г. Москва, ул. Красногвардейская, д.5",
         "eocName":"ОО №9013/0199 КИЦ Воронежский",
         "eocId":"667254"
      }
   ]
}

Получение статуса заявки

Ресурс /v1/encash/encash-add-requests/{externalId}/state позволяет получить статус заявки на добавление объекта инкассации.

Шаги:

  1. Получить AccessToken.
  2. Отправить запрос.

Авторизация

Для получения статуса необходимо отправить GET-запрос (/v1/encash/encash-add-requests/{externalId}/state), в котором передать авторизационный токен к данным собственной организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис ENCASH_DOCUMENTS.

Модель запроса

Параметры заголовка
Authorization (String) Access token полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId (String) Идентификатор документа, присвоенный клиентом

Пример запроса

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'

https://edupirfintech.sberbank.ru:9443/fintech/api/v1/encash/encash-add-requests/ffffffff-fffa-458e-ad92-fff9497303ba/state'

Модель ответа

DocState
bankComment (string, optional, read only) Банковский комментарий к статусу документа
bankStatus (string, optional) Статус документа
channelInfo (string, optional, read only) Комментарий, специфичный для документа,полученного по данному каналу

Пример ответа

{
    "bankStatus": "CREATED",
    "bankComment": null,
    "channelInfo": null,
}

Возможные статусы документа

Статус Состояние Комментарий к статусу
CREATED (Создан) Промежуточный/Продолжать опрос
DELETED (Удален) Конечный/Прекратить опрос
SIGNED (Подписан) Промежуточный/Продолжать опрос
PROCESSING (В обработке) Промежуточный/Продолжать опрос Заявка успешно подписана и отправлена.
Промежуточный/Продолжать опрос Обследование объектов. Банк изучает безопасность объектов.
Промежуточный/Продолжать опрос Подготовка коммерческого предложения. Банк готовит коммерческое предложение.
Промежуточный/Продолжать опрос При наличии согласованного коммерческого предложения, означает что Коммерческое предложение успешно согласовано и отправлено в Банк.
CHECKERROR (Ошибка контроля) Конечный / Прекратить опрос
INVALIDEDS (ЭП/АС не верна) Конечный / Прекратить опрос
OFFER_RECEIVED (Получено коммерческое предложение) Промежуточный/Требуется отправить запрос на получение коммерческого предложения
REFUSED_BY_CRM (Отказан Банком) Конечный / Прекратить опрос Отказано в заключении договора инкассации.
Конечный / Прекратить опрос Договор не соответствует ранее согласованным условиям.
Конечный / Прекратить опрос Безопасность объектов вызывает нарекания.
Конечный / Прекратить опрос Данные устарели.
Конечный / Прекратить опрос Истек срок подписания договора.
RECALL (Отозван) Конечный / Прекратить опрос Заявка отменена. Не заинтересовал продукт.
Конечный / Прекратить опрос Заявка отменена. Не устроила цена.
Конечный / Прекратить опрос Заявка отменена. Не подошел график обслуживания.
Конечный / Прекратить опрос Заявка отменена.
NEW_OFFER_ACCEPTED_BY_CLIENT (Согласовано коммерческое предложение) Промежуточный/Продолжать опрос
NEW_OFFER_REFUSED_BY_CLIENT (Коммерческое предложение отклонено) Промежуточный/Продолжать опрос Коммерческое предложение отклонено. Банк подготовит новое коммерческое предложение на других условиях.
ON_PROCESSING_CONTRACT (Подготовка договора) Промежуточный/Продолжать опрос Банк готовит договор на оказание услуги.
Промежуточный/Продолжать опрос Банк подготовил договор. Для подписания документа, перейдите в электронный документооборот E-invoicing
IMPLEMENTED (Исполнен) Успешный конечный/Прекратить опрос Заявка успешно исполнена

Получение актуального предложения

Ресурс /v1/encash/encashment-offers позволяет получить актуальное коммерческое предложение, связанное с заявкой на добавление объекта.

Шаги:

  1. Получить AccessToken.
  2. Отправить запрос.

Авторизация

Для получения актуального коммерческого предложения необходимо отправить GET-запрос (/v1/encash/encashment-offers), в котором необходимо передать авторизационный токен к данным собственной организации/организации клиента (Access Token) и Идентификатор заявки. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис ENCASH_DOCUMENTS.

Модель запроса

Параметры заголовка
Authorization (String) Access token собственной организации/организации клиента, полученный через SSO . Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
requestId (String) Идентификатор заявки на добавление объекта в договор инкассации в системе организации-партнера (UUID)

Пример запроса

curl -X GET --header 'Accept: application/json' --header

'Authorization: c76fb018-27c9-43f7-a751-62646eda7e1a-1 '

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1

/encash/encashment-offers/550e8400-e29b-41d4-a716-446655440000%C2%A0'

Модель ответа

EncashmentOffer
bankComment (string, optional) Банковский комментарий к статусу документа
bankStatus (string, optional) Статус документа
contractModifyDate (string, optional) Желаемая дата внесения изменений в договор инкассации
date (string, optional) Дата составления документа
encashObjects (Array[EncashmentOfferObject], optional) Объекты инкассации
encashOfferId (string, optional) Идентификатор документа, присвоенный партнером (UUID)
number (string, optional) Номер документа
offerAddAttributes (EncashmentOfferAddAttributes, optional) Дополнительные атрибуты коммерческого предложения
EncashmentOfferObject
examResult (string, optional) Результат обследования объекта
objectAddress (string, optional) Адрес объекта
objectName (string, optional) Наименование объекта
services (Array[EncashmentOfferServiceContract], optional) Подключаемые услуги
EncashmentOfferAddAttributes
acceptanceResult (string) Результат ознакомления (Accept - согласие, Decline - отказ) = ['Accept','Decline']stringEnum:"Accept", "Decline",
birthDate (string, optional) Дата рождения
digestSignatures (Array[Signature], optional) Электронные подписи
firstName (string, optional) Имя подписанта
identNum (string, optional) Номер документа
identSeries (string, optional) Серия документа
identType (string, optional) Тип документа, удостоверяющего личность
lastName (string, optional) Фамилия подписанта
middleName (string, optional) Отчество подписанта
post (string, optional) Должность клиента
remarks (string, optional) Комментарий клиента
warrantDate (string, optional) Дата доверенности
warrantNum (string, optional) Номер доверенности
EncashmentOfferServiceContract
contractModifyDate (string, optional) Желаемая дата внесения изменений в договор инкассации
encashContractDate (string, optional) Дата создания договора инкассации
encashContractNum (string,optional) Номер договора инкассации
serviceType (integer, optional) Тип услуги
tariffs (Array[EncashmentOfferServiceTariff], optional) Тарифы/платы по услуге
visitInfo (EncashmentOfferServiceVisitInfo, optional) Информация о заездах
Signature
base64Encoded (string) Значение электронной подписи, закодированное в Base64
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
EncashmentOfferServiceTariff
isNds (boolean, optional) Признак расчета с НДС
tariffKind (string, optional) Вид комиссии
tariffMax (number, optional) Максимум
tariffMin (number, optional) Минимум
tariffRate (number, optional) % от суммы денежной наличности
tariffSum (number, optional) Сумма
EncashmentOfferServiceVisitInfo
cashAmount (integer, optional) Сумма сдаваемой наличности за заезд
cashCoins (integer, optional) Сумма монет в объеме сдаваемой наличности
countInMonth (integer, optional) Количество заездов в месяц
isByRequest (boolean, optional) Тип обслуживания
schedule (Array[EncashmentOfferServiceVisitSchedule], optional) График заездов
EncashmentOfferServiceVisitSchedule
day (string, optional) День заезда
timeFrom (string, optional) Время заезда с
timeTo (string, optional) Время заезда по

Пример ответа

{
   "bankComment":"Новый",
   "bankStatus":"RECEIVED",
   "contractModifyDate":"2018-12-31",
   "date":"2018-12-31",
   "encashObjects":[
      {
         "examResult":"Enrolled",
         "objectAddress":"г. Москва, Кутузовский проспект, д 32",
         "objectName":"АО \"Киберлинк\" технологии 555100",
         "services":[
            {
               "contractModifyDate":"2018-12-31",
               "encashContractDate":"2018-12-31",
               "encashContractNum":"76-П",
               "serviceType":3,
               "tariffs":[
                  {
                     "isNds":false,
                     "tariffKind":"RevisitExchange",
                     "tariffMax":1.01,
                     "tariffMin":1.01,
                     "tariffRate":1.01,
                     "tariffSum":1.01
                  }
               ],
               "visitInfo":{
                  "cashAmount":2323220,
                  "cashCoins":2323,
                  "countInMonth":30,
                  "isByRequest":false,
                  "schedule":[
                     {
                        "day":"Mon",
                        "timeFrom":"10:00",
                        "timeTo":"19:00"
                     }
                  ]
               }
            }
         ]
      }
   ],
   "encashOfferId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "number":"96",
   "offerAddAttributes":{
      "acceptanceResult":"Accept",
      "birthDate":"2018-12-31",
      "digestSignatures":[
         {
            "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6ieOMt71TBS7w==",
            "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
         }
      ],
      "firstName":"Иван",
      "identNum":"111111",
      "identSeries":"0000",
      "identType":"07",
      "lastName":"Иванов",
      "middleName":"Иванович",
      "post":"Бухгалтер",
      "remarks":"Красивый комментарий",
      "warrantDate":"2018-12-31",
      "warrantNum":"1111"
   }
}

Согласование коммерческого предложения

Ресурс /v1/encash/encashment-offers/{externalId}/acceptance позволяет согласовать коммерческое предложение с передачей дополнительных данных для заключения договора на услуги инкассации или отклонить с передачей причины отказа (изменение статуса коммерческого предложения).

Шаги:

  1. Получить AccessToken.
  2. Сформировать ЭП.
  3. Отправить запрос.

Авторизация

Для согласования коммерческого предложения необходимо отправить POST-запрос (/v1/encash/encashment-offers/{externalId}/acceptance), в котором необходимо передать авторизационный токен к данным собственной организации (Access Token) и внешний идентификатор платежного поручения. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис ENCASH_DOCUMENTS.

Модель запроса

Параметры заголовка
Authorization (String) Access token организации-клиента/собственной организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId (String) Идентификатор документа, присвоенный клиентом
Параметры тела запроса
EncashmentOfferAddAttributes {
birthDate (string, optional) Дата рождения ,
digestSignatures (Array[Signature], optional) Электронные подписи ,
firstName (string, optional) Имя подписанта ,
identNum (string, optional) Номер документа ,
identSeries (string, optional) Серия документа ,
lastName (string, optional) Фамилия подписанта ,
middleName (string, optional) Отчество подписанта ,
offerStatus (string) Результат ознакомления (ACCEPT - согласие, DECLINE - отказ) =['ACCEPT', 'DECLINE']stringEnum:"ACCEPT", "DECLINE",
post (string, optional) Должность клиента ,
remarks (string, optional) Комментарий клиента ,
typeDoc (string, optional) Тип документа, удостоверяющего личность = ['07', '08', '21', '24', '26', '27'] stringEnum:"07", "08", "21", "24", "26", "27",
warrantDate (string, optional) Дата доверенности ,
warrantNum (string, optional) Номер доверенности
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

Пример запроса

{
   "birthDate":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "firstName":"Иван",
   "identNum":"111111",
   "identSeries":"0000",
   "lastName":"Иванов",
   "middleName":"Иванович",
   "offerStatus":"ACCEPT",
   "post":"Бухгалтер",
   "remarks":"Красивый комментарий",
   "typeDoc":"07",
   "warrantDate":"2018-12-31",
   "warrantNum":"1111"
}

Модель ответа

Соответствует модели ответа /v1/encash/encashment-offers

Передача электронной подписи

Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature:

Наименование Описание Пример
base64Encoded (String) Значение ЭП документа HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==
certificateUuid (String) Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto) 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

Для платежных поручений, создаваемым по собственным счетам можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:

  • если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу;
  • если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

Документ может быть подписан следующими наборами подписей:

  • одна (единственная) подпись,
  • первая и вторая подписи.

При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.

Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля пользователя при заведении в Банке.

Формат дайджеста

Наименование Описание Пример
offerStatus Результат согласования Accept
date Дата Коммерческого предложения, полученная от Банка в рамках GET-запроса на получение КП 2019-09-27
number Номер Коммерческого предложения, полученный от Банка в рамках GET-запроса на получение КП 94
birthDate Дата рождения подписанта для подготовки договора 2000-10-20
encashOfferId Идентификатор документа Коммерческое предложение, полученный от Банка в рамках REST-запроса GET на получение КП 550e8400-e29b-41d4-a716-446655440000
firstName Имя подписанта для подготовки договора Иван
identNum Номер документа, удостоверяющего личность, подписанта для подготовки договора 567889
identType Тип документа, удостоверяющего личность, подписанта для подготовки договора 07
lastName Фамилия подписанта для подготовки договора Иванков
middleName Отчество подписанта для подготовки договора Алексеевич
post Должность подписанта для подготовки договора Бухгалтер
remarks Комментарий/ Причина отказа Комментарий
series Серия документа, удостоверяющего личность, подписанта для подготовки договора 4444
warrantdate Дата доверенности 2018-12-31
warrantNum Номер доверенности АБВ1234567
TABLES:
Table=EncashmentOfferObjects Информация об объектах инкассации
# Разделитель данных об услугах инкассации
objectName Наименование объекта инкассации из коммерческого предложения, полученный от Банка в рамках GET-запроса на получение КП Объект
# Разделитель данных об услугах инкассации
Table=encashmentOfferServices Информация о об услугах для объектов инкассации
# Разделитель данных об услугах для объектов инкассации
serviceType Тип услуги 2
isByRequest Тип обслуживания true
# Разделитель данных об услугах инкассации
Table=EncashmentOfferTariffs Информация об услугах инкассации объектов
# Разделитель данных об услугах инкассации
isNds Признак расчета с НДС true
tariffKind Вид комиссии RevisitDelivery
tariffMax Максимум 2313.00
tariffMin Минимум 2.00
tariffRate Процент от суммы денежной наличности 67
tariffSum Сумма 133.00
# Разделитель данных об услугах инкассации

Пример дайджеста

offerStatus=Accept
date=2019-09-27
number=94
birthDate=2000-10-20
encashOfferId=550e8400-e29b-41d4-a716-446655440000
firstName=Иван
identNum=567889
identType=07
lastName=Иванков
middleName=Алексеевич
post=Бухгалтер
remarks=Комментарий
series=4444
warrantdate=2018-12-31
warrantNum=АБВ1234567
TABLES
Table=EncashmentOfferObjects
#
objectName=Объект
#
Table=encashmentOfferServices
#
serviceType=2
isByRequest=true
#
Table=EncashmentOfferTariffs
#
isNds=true
tariffKind=RevisitDelivery
tariffMax=2313.00
tariffMin=2.00
tariffRate=67
tariffSum=133.00
#

Дополнительная информация

Подписание запроса транспортной подписью

Content-Type может содержать одно из двух значений:

1. application/json – запрос без подписи.

2. application/jose – запрос, подписанный транспортной подписью.

если Content-Type имеет значение application/jose, то запрос должен содержать данные (реквизитный состав платежного документа) в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из:

  • Заголовка (Header),
  • JSON-документа с реквизитным составом платежного поручения (Payload),
  • Подписи запроса (Signature),

Формирование компактной сериализации JWS.

JWS формируется из трех составляющих:

Base64Url(Header) || ’.’ || Base64Url(Payload) || ’.’ || Base64Url(Signature)

Signature - это подпись данных приватной частью ключевой пары пользователя (используется приватный ключ парный сертификату пользователя с UUID, указанному в Заголовке (Header) в параметре kid). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg, в данном случае gost34.10-2012, и вычисляется от исходных данных: Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

Следует отметить, что при кодировании JWS используется преобразование Base64Url, отличающееся от Base64 преобразования.
Условно это преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

здесь функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x, функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование BASE64URL, отличается от BASE64 преобразования:

BASE64URL BASE64
- (minus) +
_ (underline) /
  • В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

Коды возврата

Код возврата Описание кода возврата Причина возникновения
200 CREATED Создан (GET-запрос)
201 CREATED Создан (PUT-запрос)
400 DESERIALIZATION_FAULT
Неверный формат запроса Неверный формат запроса
WORKFLOW_FAULT
Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
Документ с такими реквизитами уже существует Документ с такими реквизитами уже существует. Проверка по номер документа в течении года.
Не указан идентификатор сертификата подписи Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
Некорректный формат параметра kid заголовка JWS Некорректный формат параметра kid заголовка JWS(ожидается UUID)
VALIDATION_FAULT
Ошибка валидации Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
SIGN_CHECK_EXCEPTION
Подлинность подписи не установлена/Сертификат не обнаружен или не является активным Ошибка возникает, если не удалось установить подлинность подписи
401 UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан некорректный или просроченный access_token.
403 ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещен У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404 NOT_FOUND
Документ с указанным ID не найден Невозможно найти документ с указанным внешним идентификатором
415 JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503 UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступен Проводятся технические работы

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней