Методы для B2B платформы ВТБ24

Oauth2 авторизация и методы по получению данных пользователей банка.

Авторизация

Авторизация проходит по протоколу OAuth2.0

Сайт протокола: https://oauth.net/2/

Короткое описание протокола: https://aaronparecki.com/oauth-2-simplified

Приложение клиента имеет CLIENT_ID, CLIENT_SECRET, а также в рамках безопасности фикисруется CLIENT_HOST с которого принимаются запросы.

Шаг 1.

Приложение открывает (через redirect или в новом окне/вкладке) форму логина по ссылке:

https://<хост сервиса>/auth?response_type=code&scope=all&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=RANDOM_STATE

где

параметры response_type=code, scope=all требуются по протоколу и в данном случае являются фиксированными
значение CLIENT_ID фиксировано для каждого клиента и выдается отдельно
REDIRECT_URI - адрес на который произойдет редирект после прохождения аутентификации пользователем, должен иметь хост CLIENT_HOST
state=RANDOM_STATE будет добавлено к аргументам при редиректе на REDIRECT_URI, используется для сопоставления редиректов с отправленными запросами на стороне клиента

после успешного прохождения аутентификации приложение перенаправляет пользователя на адрес

REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STATE

При неуспешной аутентификации происходит перенаправление на адрес

REDIRECT_URI?error_code=ERROR_CODE&error=ERROR_DESCRIPTION

Возможные значения ERROR_CODE описаны ниже в разделе "Ошибки сервиса". ERROR_DESCRIPTION содержит описание ошибки.

Шаг 2.

После получения AUTH_CODE с первого шага, клиент на своем сервере, где хранится CLIENT_SECRET, осуществляет POST запрос на получение access_token пользователя:

```
POST https://<хост сервиса>/token HTTP/1.1
Host: <CLIENT_HOST>

```

С параметрами:

```
grant_type=authorization_code
code=AUTH_CODE
redirect_uri=REDIRECT_URI
client_id=CLIENT_ID
client_secret=CLIENT_SECRET
```

где

grant_type=authorization_code требуется по протоколу и в данном случае является фиксированным
AUTH_CODE берется с 1го шага
REDIRECT_URI совпадает с REDIRECT_URI для 1го шага (требование безопасности протокола OAuth2)
CLIENT_ID, CLIENT_SECRET фиксировано для каждого клиента и выдается отдельно

В ответе приходит json вида

{
    "access_token": <str, токен доступа>,
    "expires_in": <float, количество секунд до истечения срока действия токена>
}

В случае ошибки возвращается json вида

{
    "error_code": <int, код ошибки>,
    "error": <str, описание ошибки>
}

Возможные значения "error_code" описаны ниже в разделе "Ошибки сервиса"

Методы

Список счетов

Для получения списка счетов требуется отправить GET запрос на /accounts с указанием токена доступа:

```
GET /accounts HTTP/1.1
Host: <CLIENT_HOST>
Authorization: Bearer <access_token>

```

Ответ содержит список счетов в формате json вида

[
    {
        "Acc": "40702810510000000150",
        "BIC": "044525716",
        "ClientID": "2",
        "INN": "7727693801",
        "KPP": "123456789,123456789",
        "Name_Bank": "ВТБ 24 (ПАО) Центральный Филиал",
        "Name_org": "ООО  \"УралЭкспортЛес\""
    },
    ...
]

В случае ошибки возвращается json вида

{
    "error_code": <int, код ошибки>,
    "error": <str, описание ошибки>
}

Возможные значения "error_code" описаны ниже в разделе "Ошибки сервиса"

Выписка

Для получения выписки требуется отправить GET запрос на /statement с указанием токена доступа и параметров:

```
GET /statement?customer=CUSTOMER_ID&account=ACCOUNT_NUMBER&statement_type=STATEMENT_TYPE&date_from=DATE_FROM&date_to=DATE_TO
Host: <CLIENT_HOST>
Authorization: Bearer <access_token>

```

где

CUSTOMER_ID - id компании (ClientID в списке счетов)
ACCOUNT_NUMBER - номер счета
STATEMENT_TYPE - тип выписки (2 - онлайн, 0 - остальные)
DATE_FROM - дата начала периода выписки
DATE_TO - дата конца периода выписки

Онлайн выписка даёт актуальный остаток на текущий день, плюс операции за сегодня.

В случае формирования выписки дольше 30 секунд происходит Timeout. Небольшая выписка формируется меньше секунды.

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

/statement?customer=2012972&account=40702978402001004260&statement_type=2&date_from=2017-06-06T00:00:00&date_to=2017-06-07T00:00:00

Ответ содержит выписку в формате xml. Пример выписки:

```
<?xml version="1.0" encoding="utf-8"?>
<Statement xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="687161d1-f72d-4687-96aa-d9a2bb45d3a1" formatVersion="1.99" creationDate="2017-07-03T17:31:09.6904598+03:00" userAgent="1C service" xmlns="http://bank.1c.ru/XMLSchema">
  <Sender bic="044525716" name="ВТБ 24 (ПАО) Центральный Филиал" />
  <Recipient id="2012972" name="ООО &quot;Элит&quot;" inn="7707084093" />
  <Data>
    <StatementType>2</StatementType>
    <DateFrom>2017-06-06T00:00:00</DateFrom>
    <DateTo>2017-06-07T00:00:00</DateTo>
    <Account>40702978402001004260</Account>
    <Bank>
      <BIC>044525716</BIC>
      <Name>ВТБ 24 (ПАО) Центральный Филиал</Name>
      <City>Г. МОСКВА</City>
      <CorrespAcc>30101810100000000716</CorrespAcc>
    </Bank>
    <OpeningBalance>340726.81</OpeningBalance>
    <TotalDebits>407056.43</TotalDebits>
    <TotalCredits>589651.01</TotalCredits>
    <ClosingBalance>522322.39</ClosingBalance>
    <OperationInfo>
      <PayDoc id="0" docKind="10">
        <PayDocRu>
          <DocNo>398</DocNo>
          <DocDate>2017-07-03</DocDate>
          <Sum>20000.00</Sum>
          <Payer>
            <Name>ООО "Элит"</Name>
            <INN>7707084093</INN>
            <Account>40702978402001004260</Account>
            <Bank>
              <BIC>044525716</BIC>
              <Name>ВТБ 24 (ПАО) Центральный Филиал</Name>
              <CorrespAcc>30101810100000000716</CorrespAcc>
            </Bank>
          </Payer>
          <Payee>
            <Name>Счет: 40702810260100004416 БИК: 040702615</Name>
            <INN />
            <Account>40702810260100004416</Account>
            <Bank>
              <BIC>040702615</BIC>
            </Bank>
          </Payee>
          <Priority>5</Priority>
          <Purpose>Оплата за сендвич по счету №33 от 30.10.2015г.Сумма 20000-00В т.ч. НДС  (18%) 3050-85</Purpose>
        </PayDocRu>
      </PayDoc>
      <DC>1</DC>
      <Date>2017-07-03</Date>
    </OperationInfo>
    <OperationInfo>
      <PayDoc id="0" docKind="10">
        <PayDocRu>
          <DocNo>284</DocNo>
          <DocDate>2017-07-03</DocDate>
          <Sum>2658.18</Sum>
          <Payer>
            <Name>Счет: 40702810515000000059 БИК: 040702719</Name>
            <INN />
            <Account>40702810515000000059</Account>
            <Bank>
              <BIC>040702719</BIC>
            </Bank>
          </Payer>
          <Payee>
            <Name>ООО "Элит"</Name>
            <INN>7707084093</INN>
            <Account>40702978402001004260</Account>
            <Bank>
              <BIC>044525716</BIC>
              <Name>ВТБ 24 (ПАО) Центральный Филиал</Name>
              <CorrespAcc>30101810100000000716</CorrespAcc>
            </Bank>
          </Payee>
          <Priority>5</Priority>
          <Purpose>оплата по заказу клиента № УТ-976 счет № УТ-976 от 10.03.16, за профиль, в т.ч. НДС 18% 405,49</Purpose>
        </PayDocRu>
      </PayDoc>
      <DC>2</DC>
      <Date>2017-07-03</Date>
    </OperationInfo>
    <Stamp>
      <BIC>044525716</BIC>
      <Name>ВТБ 24 (ПАО) Центральный Филиал</Name>
      <City>Г. МОСКВА</City>
      <CorrespAcc>30101810100000000716</CorrespAcc>
      <Branch />
    </Stamp>
  </Data>
  <ExtIDStatementRequest>687161d1-f72d-4687-96aa-d9a2bb45d3a1</ExtIDStatementRequest>
</Statement>
```

В случае ошибки возвращается json вида

{
    "error_code": <int, код ошибки>,
    "error": <str, описание ошибки>
}

Возможные значения "error_code" описаны ниже в разделе "Ошибки сервиса"

Отправка платежного поручения

Для создания платежного поручения требуется отправить POST запрос на /payment с указанием токена доступа и параметров:

```
document_number - номер документа
sum - сумма платежа
purpose - назначение платежа

payer_name - наименование отправителя
payer_inn - ИНН отправителя
payer_kpp - КПП отправителя
payer_account - номер счета отправителя
payer_bank_bic - БИК банка отправителя
payer_bank_name - наименование банка отправителя
payer_bank_city - город банка отправителя
payer_bank_correspondent_account - корреспондентский счет банка отправителя

payee_name - наименование получателя
payee_inn - ИНН получателя
payee_kpp - КПП получателя
payee_account - номер счета получателя
payee_bank_bic - БИК банка получателя
payee_bank_name - наименование банка получателя
payee_bank_city - город банка получателя
payee_bank_correspondent_account - корреспондентский счет банка получателя

document_date - (опционально, по умолчанию текущая дата) дата документа в формате YYYY-MM-DD
payment_kind - (опционально, по умолчанию "Почтой") вид документа, один из "Почтой", "Срочно", "Почтой", "Телеграфом", "Электронно"
transition_kind - (опционально, по умолчанию "01") вид операции согласно установленного ЦБР перечня условных обозначений (шифров) документов
priority - (опционально, по умолчанию "5") очередность платежа от 1 до 5
```

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

```
curl -X POST \
http://82.202.199.51/payment \
-H 'authorization: Bearer eed38fa4064d483996de31ef838a773fe3c68010a7a04994a7c6af5044cb6a72' \
-H 'host: 127.0.0.1:5000' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F document_number=5 \
-F sum=100.00 \
-F 'purpose=ТЕСТИРОВАНИЕ B2B платформы 2017 в т.ч. НДС' \
-F 'payer_name=ООО &quot;Элит&quot;' \
-F payer_inn=7707084093 \
-F payer_kpp=0 \
-F payer_account=40702978102000004260 \
-F payer_bank_bic=044525716 \
-F 'payer_bank_name=ВТБ 24 (ПАО)' \
-F 'payer_bank_city=Г. МОСКВА' \
-F payer_bank_correspondent_account=30101810100000000716 \
-F 'payee_name=ООО ВВВ' \
-F payee_inn=1234567894 \
-F payee_kpp=111111111 \
-F payee_account=40702810900000000000 \
-F payee_bank_bic=044525225 \
-F 'payee_bank_name=ПАО СБЕРБАНК' \
-F 'payee_bank_city=Г. МОСКВА' \
-F payee_bank_correspondent_account=30101810400000000225
```

Ответ содержит json вида

{
    "Code": "01",
    "Name": null,
    "MoreInfo": "Принят"
}

Если на этапе обработки данных в банке произошла ошибка, такой json содержит соответствующую информацию. Например:

{
    "Code": "03",
    "Name": "Отклонен банком",
    "MoreInfo": "Счет Плательщика: Счет плательщика не принадлежит клиенту. ErrDocDuplicate"
}

В случае выявления ошибки на стороне сервиса возвращается json вида

{
    "error_code": <int, код ошибки>,
    "error": <str, описание ошибки>
}

Возможные значения "error_code" описаны ниже в разделе "Ошибки сервиса"

Ошибки сервиса

error_code 400 - переданы неверные параметры запроса
error_code 401 - пользователь не авторизован
error_code 403 - нарушение доступа (может возникать, например, если не передан или передан неправильный заголовок Host)
error_code 408 - таймаут
error_code 500 - внутренняя ошибка сервиса, может быть вызвана недоступностью шлюза