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

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

Запросы осуществляются посредством протокола https, на адресhttps://api.modulbank.ru/v1/. Для авторизации HTTP-запросы должны содержать следующий заголовок:Authorization: Beare<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
}

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

ПолеЗначениеОписание
clientIdsandboxappИдентификатор приложения
clientSecretsandboxappsecretСекретное слово приложения
tokensandboxtokenТокен авторизации

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

  • Приложение должно производить все сетевые взаимодействия по протоколу HTTPS
  • Приложение должно проверять корректность SSL-сертификата сервера. Если SSL-сертификат не прошел проверку, необходимо немедленно прекратить сессию, чтобы не допустить утечку данных авторизации
  • Приложение не должно хранить токен авторизации в открытом виде (cookie и т. д.)
  • Приложение должно корректно информировать пользователей о недоступности сервиса Модульбанка (в случае проведения сервисных работ на стороне сервера API возвращает ответ с HTTP статусом 503 на все виды запросов)

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

Метод в 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[]Массив компаний пользователя

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

ПараметрТипОписание
companyIdstringСистемный идентификатор компании
companyNamestringНазвание компании
bankAccountsobject[]Массив счетов компании
registrationCompletedboolПризнак окончания регистрации компании
InnstringИНН
KppstringКПП
OgrnstringОГРН

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

ПараметрТипОписание
idstringСистемный идентификатор счета
accountNamestringНаименование счета
balancenumberБаланс на счете
bankBicstringБИК Банка
bankInnstringИНН Банка
bankKppstringКПП Банка
bankCorrespondentAccountstringКорр. счет
bankNamestringНаименование банка
beginDatestringДата открытия счета
categorystringКатегория счета. Возможные значения: CheckingAccount (расчетный счет), DepositAccount (депозитный счет), CardAccount (карточный счет), DepositRateAccount (счет для процентов по депозиту), ReservationAccounting (счет учета резервов)
currencystringКод валюты. Возможные значения — RUR, USD, EUR, CNY
numberstringНомер счета
statusstringСостояния счета. Возможные значения — New (открытый), Deleted (удаленный), Closed (закрытый), Freezed (замороженный), ToClosed (в процессе закрытия), ToOpen (в процессе открытия)

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

[
	{
		"companyId":"70ca00f6-1f10-4964-aca6-a5ec032efe37",
		"companyName":"ООО \"Ромашка\"",
		"Inn":"2204000595",
		"Kpp":"771543001",
		"Ogrn":"1022200525841",
		"registrationCompleted":true,
		"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' Если параметр не задан, выводятся все операции.
tilldateНеобязательный. Вывести операции до момента времени (операции, дата проведения которых равна from, или старше). Формат 'yyyy-MM-dd'. Если параметр не задан, выводятся все операции.
skipnumberНеобязательный. Пропустить n строк в выборке. Если параметр не задан, skip = 0
recordsnumberНеобязательный. Кол-во возвращаемых записей. От 0 до 50. Если параметр не задан, records = 10
sbpOperIdstringНеобязательный. ID операций C2B платежа по СБП
sbpOperIdForRefundstringНеобязательный. ID операции возврата С2B платежa
rcvQrcIdstringНеобязательный. Детали операции по ID QR-кода СБП
sbpRetailPointIdstringНеобязательный. Фильтрация по идентификатору торговой точки СБП
operationsstringНеобязательный. Идентификатор транзакции или нескольких транзакций. Если передается несколько id, они разделяются запятыми, например: ["fa419a14-7715-4713-8bde-ae7c02858cc2", "3e49ee6a-f942-4fa5-bcb4-ae7b03a8729a"]

Возвращает

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

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

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

ПараметрТипОписание
idstringСистемный идентификатор транзакции
companyIdstringСистемный идентификатор компании
statusstringТекущий статус транзакции. Возможные значения: SendToBank (Исходящая, ожидающая исполнения), Executed (Исходящий исполненный), RejectByBank (Исходящая, отказано банком в исполнении), Canceled (Исходящая, отправленная в банк и отменённая пользователем), Received (Входящая исполненная)
categorystringНаправление платежа. Возможные значения: Debet (входящая), Credit (исходящая)
contragentNamestringПолное наименование контрагента
contragentInnstringИНН контрагента
contragentKppstringКПП контрагента
contragentBankAccountNumberstringСчёт контрагента
contragentBankNamestringНаименование банка контрагента
contragentBankBicstringБИК банка контрагента
currencystringКод валюты. Возможные значения: RUR, EUR, USD, CNY
amountnumberСумма платежа без учета банковской комиссии
bankAccountNumberstringНомер банковского счета
paymentPurposestringНазначение платежа
executedstringДата проведения платежа
createdstringДата создания транзакции
docNumberstringНомер документа
absIdstringИдентификатор документа в АБС
ibsoIdstringИдентификатор проводки в АБС
kbkstringДля бюджетных и налоговых платежей. Код бюджетной классификации (104)
oktmostringДля бюджетных и налоговых платежей. Общероссийский классификатор территорий муниципальных образований (105)
paymentBasisstringДля бюджетных и налоговых платежей. Основание платежа (106)
taxCodestringДля бюджетных и налоговых платежей. Налоговый период (в случае налогового или бюджетного платежа)
taxDocNumstringДля бюджетных и налоговых платежей. Номер документа (108)
taxDocDatestringДля бюджетных и налоговых платежей. Дата документа (109)
payerStatusstringДля бюджетных и налоговых платежей. Статус плательщика (101)
uinstringДля бюджетных и налоговых платежей. Уникальный идентификатор начисления (22)
cardIdstringИдентификатор карты, к которой привязан платёж

Пример ответа сервера (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,
		"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":"",
		"absId":"34323454545455",
		"ibsoId":"1332345565654",
		"cardId":"4bdd2fc0-584d-41d8-9241-3f074480fe52"
	}
]

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

Метод в API

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

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

Системный идентификатор счета, по которому запрашиваются баланс. Этот параметр передается как часть 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,
				"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":"",
				"absId":"34323454545455",
				"ibsoId":"1332345565654",
				"cardId":"4bdd2fc0-584d-41d8-9241-3f074480fe52"
		},
		"SHA1Hash": "b2ee4a9197f4a90e893caa4f62eeba0b579321f8"
	}
Важно! Все уведомления отправляются исключительно по протоколу HTTPS

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

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

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

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

ПараметрТипОписание
idstringСистемный идентификатор транзакции
companyIdstringСистемный идентификатор компании
statusstringТекущий статус транзакции. Возможные значения: SendToBank (Исходящая, ожидающая исполнения), Executed (Исходящий исполненный), RejectByBank (Исходящая, отказано банком в исполнении), Canceled (Исходящая, отправленная в банк и отменённая пользователем), Received (Входящая исполненная)
categorystringНаправление платежа. Возможные значения: Debet (входящая), Credit (исходящая)
contragentNamestringПолное наименование контрагента
contragentInnstringИНН контрагента
contragentKppstringКПП контрагента
contragentBankAccountNumberstringСчёт контрагента
contragentBankNamestringНаименование банка контрагента
contragentBankBicstringБИК банка контрагента
currencystringКод валюты. Возможные значения: RUR, EUR, USD, CNY
amountnumberСумма платежа без учета банковской комиссии
bankAccountNumberstringНомер банковского счета
paymentPurposestringНазначение платежа
executedstringДата проведения платежа
createdstringДата создания транзакции
docNumberstringНомер документа
absIdstringИдентификатор документа в АБС
ibsoIdstringИдентификатор проводки в АБС
kbkstringДля бюджетных и налоговых платежей. Код бюджетной классификации (104)
oktmostringДля бюджетных и налоговых платежей. Общероссийский классификатор территорий муниципальных образований (105)
paymentBasisstringДля бюджетных и налоговых платежей. Основание платежа (106)
taxCodestringДля бюджетных и налоговых платежей. Налоговый период (в случае налогового или бюджетного платежа)
taxDocNumstringДля бюджетных и налоговых платежей. Номер документа (108)
taxDocDatestringДля бюджетных и налоговых платежей. Дата документа (109)
payerStatusstringДля бюджетных и налоговых платежей. Статус плательщика (101)
uinstringДля бюджетных и налоговых платежей. Уникальный идентификатор начисления (22)
cardIdstringИдентификатор карты, к которой привязан платёж
sbpOperIdstringID операций C2B платежа по СБП
sbpOperIdForRefundstringID операции возврата С2B платежa
rcvQrcIdstringID QR-кода СБП

При получении от приложения ответа с кодом 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

Не хватило возможностей?

Напишите нам

Отвечаем в течение одного рабочего дня.