Получение данных


Описание протокола

Запросы осуществляются посредством протокола https, на адрес https://api.modulbank.ru/v1/.
Для авторизации HTTP-запросы должны содержать следующий заголовок:Authorization: Bearer <access_token>,
где access_token - токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Параметры запроса передаются в теле сообщения. Допустимо передавать данные как в формате application/json так и в формате x-www-form-urlencoded.

Пример запроса (в формате json):

POST /v1/operation-history/843eeb4e-d50f-4ac7-8efd-a5ec037179a0 HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Authorization: Bearer aWQwMDAwMDAwMC0wMDAwLTAwMDArMDAwMC0wMDAwMDAwMDAwMDA3MTQ5M2FhYy1lZTFjLTQ1ZWMtYTZkNC1kNTk4ZTQzM2

{
    category: 'Debet',
    records: 10
}

Пример того же запроса (в формате x-www-form-urlencoded):

POST /v1/operation-history/843eeb4e-d50f-4ac7-8efd-a5ec037179a0 HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer aWQwMDAwMDAwMC0wMDAwLTAwMDArMDAwMC0wMDAwMDAwMDAwMDA3MTQ5M2FhYy1lZTFjLTQ1ZWMtYTZkNC1kNTk4ZTQzM2

category=Debet&records=10

Режим песочница

Песочница - это созданный для разработки режим работы API, при котором все реальные данные о пользователях, компаниях, счетах и транзакциях подменяются на тестовые. С помощью песочницы вы можете разрабатывать и отлаживать свой код не имея учетной записи и открытого расчетного счета в Модульбанке. Для того чтобы наше API распознало входящий запрос как запрос к песочнице, нужно ясно указать это в запросе одним из двух способов: добавить в HTTP заголовок запроса (http request header) sandbox:on или добавить в URI GET параметр sandbox=on.

Пример запроса списка операций по счету в режиме песочница (параметр sandbox передан в заголовке запроса):

POST /v1/operation-history/843eeb4e-d50f-4ac7-8efd-a5ec037179a0 HTTP/1.1
Host: api.modulbank.ru
sandbox: on
Content-Type: application/json
Authorization: Bearer sandboxtoken

{
    category: 'Debet',
    skip: 50,
    records: 10
}

Тот же самый запрос, но параметр sandbox передан в URI в виде GET параметра:

POST /v1/operation-history/843eeb4e-d50f-4ac7-8efd-a5ec037179a0?sandbox=on HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Authorization: Bearer sandboxtoken

{
    category: 'Debet',
    skip: 50,
    records: 10,
}

Также следует помнить, что в режиме песочницы запрещено использовать реальные данные - идентификаторы приложений, токены авторизации и т.д. Вместо реальных идентификаторов в песочнице разрешается использовать следующие:

Поле Значение Описание
clientId sandboxapp Идентификатор приложения
clientSecret sandboxappsecret Секретное слово приложения
token sandboxtoken Токен авторизации

Требования к разработчикам


Получение информации о компаниях пользователя

Метод в API

https://api.modulbank.ru/v1/account-info

Пример вызова

POST /v1/account-info HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Authorization: Bearer aWQwMDAwMDAwMC0wMDAwLTAwMDArMDAwMC0wMDAwMDAwMDAwMDA3MTQ5M2FhYy1lZTFjLTQ1ZWMtYTZkNC1kNTk4ZTQzM2

Описание

Получение информации о компаниях пользователя (один и тот же клиент Модульбанка может быть сотрудником нескольких компаний) и счетах компаний пользователя.

Требуемые права токена

account-info

Входные параметры

Отсутствуют

Возвращает

В случае успеха возвращает JSON-документ со следующим содержимым:

Параметр Тип Описание
- (response body) object[] Массив компаний пользователя

Каждый элемент массива - это компания, в которой состоит пользователь.
Каждая компания имеет следующий набор полей:

Параметр Тип Описание
companyId string Системный идентификатор компании
companyName string Название компании
bankAccounts object[] Массив счетов компании

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

Параметр Тип Описание
id string Системный идентификатор счета
accountName string Наименование счета
balance number Баланс на счете
bankBic string БИК Банка
bankInn string ИНН Банка
bankKpp string КПП Банка
bankCorrespondentAccount string Корр. счет
bankName string Наименование банка
beginDate string Дата открытия счета
category string Категория счета. Возможные значения: CheckingAccount (расчетный счет), DepositAccount (депозитный счет), CardAccount (карточный счет), DepositRateAccount (счет для процентов по депозиту), ReservationAccounting (счет учета резервов)
currency string Код валюты. Возможные значения - RUR, USD, EUR, CNY
number string Номер счета
status string Состояния счета. Возможные значения - New (открытый), Deleted (удаленный), Closed (закрытый), Freezed (замороженный), ToClosed (в процессе закрытия), ToOpen (в процессе открытия)

Пример ответа сервера (JSON)

[
    {
        "companyId":"70ca00f6-1f10-4964-aca6-a5ec032efe37",
        "companyName":"ООО \"Ромашка\"",
        "bankAccounts":
            [
                {
                    "accountName":"Основной счет",
                    "balance":900000.0,
                    "bankBic":"044583340",
                    "bankInn":"2204000595",
                    "bankKpp":"770443001",
                    "bankCorrespondentAccount":"30101810000000000001",
                    "bankName":"МОСКОВСКИЙ ФИЛИАЛ ОАО КБ\"РЕГИОНАЛЬНЫЙ КРЕДИТ\" Г.МОСКВА",
                    "beginDate":"2015-10-07T00:00:00",
                    "category":"CheckingAccount",
                    "currency":"RUR",
                    "id":"edb10116-5a93-4963-a53b-a5ec037177f0",
                    "number":"40802810070000000001",
                    "status":"New"
                }
            ]
    }
]

Просмотр истории операций

Метод в API

https://api.modulbank.ru/v1/operation-history/<bankAccountId>

Пример вызова

POST /v1/operation-history/9f65fff4-d638-41d8-83eb-a616039d3fe5 HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Authorization: Bearer aWQwMDAwMDAwMC0wMDAwLTAwMDArMDAwMC0wMDAwMDAwMDAwMDA3MTQ5M2FhYy1lZTFjLTQ1ZWMtYTZkNC1kNTk4ZTQzM2

{
    category : 'Debet',
    records: 10,
    from: '2016-04-25'
}

Описание

Просмотр истории операций по счету.

Требуемые права токена

operation-history

Входные параметры

Обязательный параметр только один - системный идентификатор счета, по которому запрашиваются операции. Этот параметр передается как часть URI. Все остальные параметры являются необязательными и передаются в теле запроса. Если не задан ни один необязательный параметр, тело запроса может быть пустым.

Список параметров:

Параметр Как передается Описание
bankAccountId Передается как часть Uri Обязательный. Системный идентификатор счета
category В теле запроса Необязательный. Направление платежа. Возможные значения: Debet - входящий, Credit - исходящий
from В теле запроса Необязательный. Вывести операции от момента времени (операции, дата проведения которых равна from, или младше). Формат 'yyyy-MM-dd' Если параметр не задан, выводятся все операции.
till Необязательный. Вывести операции до момента времени (операции, дата проведения которых равна from, или старше). Формат 'yyyy-MM-dd'. Если параметр не задан, выводятся все операции.
skip Необязательный. Пропустить n строк в выборке. Если параметр не задан, skip = 0
records Необязательный. Кол-во возвращаемых записей. От 0 до 50. Если параметр не задан, records = 10

Возвращает

В случае успеха возвращает JSON-документ со следующим содержимым:

Параметр Тип Описание
- (response body) object[] Массив операций по счету

Каждый элемент массива - это одна операция. Каждая операция имеет следующий набор полей:

Параметр Тип Описание
id string Системный идентификатор транзакции
companyId string Системный идентификатор компании
status string Текущий статус транзакции. Возможные значения: SendToBank (Исходящая, ожидающая исполнения), Executed (Исходящий исполненный), RejectByBank (Исходящая, отказано банком в исполнении), Canceled (Исходящая, отправленная в банк и отменённая пользователем), Received (Входящая исполненная)
category string Направление платежа. Возможные значения: Debet (входящая), Credit (исходящая)
contragentName string Полное наименование контрагента
contragentInn string ИНН контрагента
contragentKpp string КПП контрагента
contragentBankAccountNumber string Счёт контрагента
contragentBankName string Наименование банка контрагента
contragentBankBic string БИК банка контрагента
currency string Код валюты. Возможные значения: RUR, EUR, USD, CNY
amount number Сумма платежа без учета банковской комиссии
amountWithCommission number Сумма платежа с учетом банковской комиссии
bankAccountNumber string Номер банковского счета
paymentPurpose string Назначение платежа
executed string Дата проведения платежа
created string Дата создания транзакции
docNumber string Номер документа
kbk string Для бюджетных и налоговых платежей. Код бюджетной классификации (104)
oktmo string Для бюджетных и налоговых платежей. Общероссийский классификатор территорий муниципальных образований (105)
oktmo string Для бюджетных и налоговых платежей. Общероссийский классификатор территорий муниципальных образований (105)
paymentBasis string Для бюджетных и налоговых платежей. Основание платежа (106)
taxCode string Для бюджетных и налоговых платежей. Налоговый период (в случае налогового или бюджетного платежа)
taxDocNum string Для бюджетных и налоговых платежей. Номер документа (108)
taxDocDate string Для бюджетных и налоговых платежей. Дата документа (109)
payerStatus string Для бюджетных и налоговых платежей. Статус плательщика(101)
uin string Для бюджетных и налоговых платежей. Уникальный идентификатор начисления (22)

Пример ответа сервера (JSON)

[
    {
        "id":"a4b825ca-a6f8-4996-a1db-a5f3028bb68d",
        "companyId":"599ebe36-ed20-49c4-b802-a5ec0329ebce",
        "status":"Received",
        "category":"Debet",
        "contragentName":"Индивидуальный предприниматель Иванов Иван Иванович",
        "contragentInn":"1111111111",
        "contragentKpp":"",
        "contragentBankAccountNumber":"30101810000000000005",
        "contragentBankName":"МОСКОВСКИЙ ФИЛИАЛ ОАО КБ\"РЕГИОНАЛЬНЫЙ КРЕДИТ\"",
        "contragentBankBic":"044583340",
        "currency":"RUR",
        "amount":100000.0,
        "amountWithCommission":100000.0,
        "bankAccountNumber":"30101810000000000001",
        "paymentPurpose":"Оплата по счету №4 от 01.04.2016 г. Без НДС",
        "executed":"2016-04-01T00:00:00",
        "created":"2016-04-01T00:00:00",
        "kbk":"",
        "oktmo":"",
        "paymentBasis":"",
        "taxCode":"",
        "taxDocNum":"",
        "taxDocDate":"",
        "payerStatus":"",
        "uin":""            
    }
]

Получение баланса по счету

https://api.modulbank.ru/v1/account-info/balance/<bankAccountId>

Пример вызова

POST /v1/account-info/balance/9f65fff4-d638-41d8-83eb-a616039d3fe5 HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Authorization: Bearer aWQwMDAwMDAwMC0wMDAwLTAwMDArMDAwMC0wMDAwMDAwMDAwMDA3MTQ5M2FhYy1lZTFjLTQ1ZWMtYTZkNC1kNTk4ZTQzM2

Описание

Получение баланса по счету

Требуемые права токена

account-info

Входные параметры

Cистемный идентификатор счета, по которому запрашиваются баланс. Этот параметр передается как часть URI.

Список параметров:

Параметр Как передается Описание
bankAccountId Передается как часть Uri Обязательный. Системный идентификатор счета

Возвращает

В случае успеха возвращает сумму остатка денежных средств на счете

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

1785723.0

Уведомления о произошедших транзакциях (веб-хуки)

Описание

При появлении новой исполненной транзакции в Модульбанке, вашему приложению будет отправлено уведомление. Уведомление - это http запрос, выполненный на специальный, указанный при регистрации приложения Uri для уведомлений.

Требуемые права токена

operation-history

Пример.

При регистрации качестве Uri для уведомлений был указан адрес https://example.ru/modulbank/ Стороннее приложение авторизовало пользователя, работающего в ИП Иванов Иван Иванович. При появлении новой исполненной транзакции по счету открытому ИП Иванов Иван Иванович, Модульбанк выполнит следующий POST запрос:

POST  /modulbank
Host: example.ru
Content-Type: application/json

{
    "companyInn": "1111111111",
    "companyKpp": "",
    "operation":        
        {
            "id":"a4b825ca-a6f8-4996-a1db-a5f3028bb68d",
            "companyId":"599ebe36-ed20-49c4-b802-a5ec0329ebce",
            "status":"Received",
            "category":"Debet",
            "contragentName":"Индивидуальный предприниматель Иванов Иван Иванович",
            "contragentInn":"1111111111",
            "contragentKpp":"",
            "contragentBankAccountNumber":"30101810000000000005",
            "contragentBankName":"МОСКОВСКИЙ ФИЛИАЛ ОАО КБ\"РЕГИОНАЛЬНЫЙ КРЕДИТ\"",
            "contragentBankBic":"044583340",
            "currency":"RUR",
            "amount":100000.0,
            "amountWithCommission":100000.0,
            "bankAccountNumber":"30101810000000000001",
            "paymentPurpose":"Оплата по счету №4 от 01.04.2016 г. Без НДС",
            "executed":"2016-04-01T00:00:00",
            "created":"2016-04-01T00:00:00",
            "docNumber":"4",
            "kbk":"",
            "oktmo":"",
            "paymentBasis":"",
            "taxCode":"",
            "taxDocNum":"",
            "taxDocDate":"",
            "payerStatus":"",
            "uin":""
    },
    "SHA1Hash": "b2ee4a9197f4a90e893caa4f62eeba0b579321f8"
}

Важно! Все уведомления отправляются исключительно по протоколу HTTPS

В теле запроса передается информация о произошедшей транзакции в виде JSON объекта.

Описание полей объекта:

Параметр Тип Описание
companyInn string ИНН компании (для которой в Модульбанке появилась транзакция)
companyKpp string КПП компании (для которой в Модульбанке появилась транзакция)
operation object Информация по транзакции
SHA1Hash string Подпись сообщения, гарантирующая целостность данных уведомления и то, что уведомления были отправлены сервером Модульбанка. Информация о том как проверить SHA1Hash на стороне приложения описана чуть ниже

Объект operation имеет следующий набор полей:

Параметр Тип Описание
id string Системный идентификатор транзакции
companyId string Системный идентификатор компании
status string Текущий статус транзакции. Возможные значения: SendToBank (Исходящая, ожидающая исполнения), Executed (Исходящий исполненный), RejectByBank (Исходящая, отказано банком в исполнении), Canceled (Исходящая, отправленная в банк и отменённая пользователем), Received (Входящая исполненная)
category string Направление платежа. Возможные значения: Debet (входящая), Credit (исходящая)
contragentName string Полное наименование контрагента
contragentInn string ИНН контрагента
contragentKpp string КПП контрагента
contragentBankAccountNumber string Счёт контрагента
contragentBankName string Наименование банка контрагента
contragentBankBic string БИК банка контрагента
currency string Код валюты. Возможные значения: RUR, EUR, USD, CNY
amount number Сумма платежа без учета банковской комиссии
amountWithCommission number Сумма платежа с учетом банковской комиссии
bankAccountNumber string Номер банковского счета
paymentPurpose string Назначение платежа
executed string Дата проведения платежа
created string Дата создания транзакции
docNumber string Номер документа
kbk string Для бюджетных и налоговых платежей. Код бюджетной классификации (104)
oktmo string Для бюджетных и налоговых платежей. Общероссийский классификатор территорий муниципальных образований (105)
oktmo string Для бюджетных и налоговых платежей. Общероссийский классификатор территорий муниципальных образований (105)
paymentBasis string Для бюджетных и налоговых платежей. Основание платежа (106)
taxCode string Для бюджетных и налоговых платежей. Налоговый период (в случае налогового или бюджетного платежа)
taxDocNum string Для бюджетных и налоговых платежей. Номер документа (108)
taxDocDate string Для бюджетных и налоговых платежей. Дата документа (109)
payerStatus string Для бюджетных и налоговых платежей. Статус плательщика(101)
uin string Для бюджетных и налоговых платежей. Уникальный идентификатор начисления (22)

При получении от приложения ответа с кодом http статуса 200, уведомление считается полученным. В случае отказа Модульбанк предпримет еще две попытки доставить уведомление: через 10 минут и через час.

Алгоритм расчета подписи сообщения в случае если токен был сгенерирован в ЛК Модульбанка

1) Сформировать строку из параметров уведомления в кодировке UTF-8.
Формат строки: <первые 10 символов токена авторизации>&operationId
Пример строки параметров для токена NDIWJFNASDJKFHNASDJFASDJKFHASDJKFHASDJFHASDK: NDIWJFNASD&a4b825ca-a6f8-4996-a1db-a5f3028bb68d
2) Вычислить значение хэш-функции SHA-1 от полученной строки.
3) Отформатировать полученный результат в HEX-кодированном виде.
Пример рассчитанного значения параметра sha1_hash для примера: 27063efdefd944907e08cfa242170f4d1a260c36

Алгоритм расчета подписи сообщения в случае если токен был получен по протоколу OAuth

1) Сформировать строку из параметров уведомления в кодировке UTF-8 (где clientSecret — это секретное слово приложения).
Формат строки: clientSecret&operationId
Пример строки параметров: JSADFJASFJASLKJWERMNGIODVBKLMNEWSTOHEJLWRTFNEHNSDJLFHNWEO&a4b825ca-a6f8-4996-a1db-a5f3028bb68d
2) Вычислить значение хэш-функции SHA-1 от полученной строки.
3) Отформатировать полученный результат в HEX-кодированном виде.
Пример рассчитанного значения параметра sha1_hash для примера: f232c33785c13009614a7ddb69f12133300a33c8