Welcome to modulbank’s documentation!¶
modulbank¶
Python client for ModulBank REST API
Getting started¶
Make sure to include this lines in the beginning of your code:
from modulbank.client import ModulbankClient
import modulbank.structs as structs
Set your API Token and choose sandbox mode on
or off
:
client = ModulbankClient(token=MODULBANK_TOKEN, sandbox_mode=True)
Make queries:
print([str(acc) for acc in client.accounts()])
print(client.balance('58c20343-5d3b-422c-b98b-a5ec037df782'))
print([str(op) for op in client.operations('58c20343-5d3b-422c-b98b-a5ec037df782')])
Or send payment order:
p = structs.PaymentOrder(
doc_num='994720', account_num='40802810670010011008', amount=Decimal(100.00), purpose='Для теста',
payer=structs.Contractor(name='Индивидуальный предприниматель Александров Александр Александрович',
inn='770400372208', kpp='',
bank=structs.BankShort(account='40802810670010011008',
name='МОСКОВСКИЙ ФИЛИАЛ АО КБ "МОДУЛЬБАНК"',
bic='044525092', corr_acc='30101810645250000092')),
recipient=structs.Contractor(name='МОСКОВСКИЙ ФИЛИАЛ АО КБ "МОДУЛЬБАНК"',
inn='2204000595', kpp='771543001',
bank=structs.BankShort(account='30102810675250000092',
name='МОСКОВСКИЙ ФИЛИАЛ АО КБ "МОДУЛЬБАНК"',
bic='044525092', corr_acc='30102810675250000092')))
res = client.create_payment_draft(p)
assert len(res.errors) == 0
assert res.total_loaded == 1
Helper class for processing web-hooks¶
Sample usage of class NotifyRequest
:
@app.route('/modulbank', methods=['POST'])
def notify():
client = ModulbankClient(token=MODULBANK_TOKEN)
if not request.is_json:
return make_response(render_template('template.json'), 400)
nr = structs.NotifyRequest(request.json)
# Filter only needed company's operations
if nr.inn != INN or nr.kpp != KPP:
return make_response(render_template('template.json'), 200)
# Check signature in `SHA1Hash` field
if not nr.check_signature(MODULBANK_TOKEN):
return make_response(render_template('template.json'), 403)
#
# Make something with `nr`
#
make_response(render_template('template.json'), 200)
TODO¶
- OAuth 2 authorization.
Links¶
modulbank package¶
Submodules¶
modulbank.client module¶
-
class
modulbank.client.
ModulbankClient
(token: str, sandbox_mode: bool = False, page_size: int = 50)¶ Bases:
object
МодульБанк для Python-разработчиков.
-
accounts
() → list¶ Получение информации о компаниях пользователя
Метод в API: https://api.modulbank.ru/v1/account-info
Returns: Массив компаний, представленных структурой
Company
Return type: list(Company)
Raises: - NotAuthorizedModulbankException – Если не прошли авторизацию.
- UnexpectedResponseStatusModulbankException – Если статус ответа сервера отлиается от ожидаемого.
- UnexpectedResponseBodyModulbankException – Если не удалось обработать полученные данные.
-
balance
(account_id: str) → decimal.Decimal¶ Получение баланса по счёту
Метод в API: https://api.modulbank.ru/v1/account-info/balance/<account_id>
Parameters: account_id (str) – Системный идентификатор счёта
Returns: Сумма остатка денежных средств на счёте
Return type: Decimal
Raises: - NotAuthorizedModulbankException – Если не прошли авторизацию.
- UnexpectedResponseStatusModulbankException – Если статус ответа сервера отлиается от ожидаемого.
- UnexpectedValueModulbankException – Если не удалось конвертировать полученное значение.
-
create_payment_draft
(order: modulbank.structs.PaymentOrder) → modulbank.client.PaymentResponse¶ Создание черновика платёжки.
Все создаваемые через API платежные поручения имеют статус “Черновик”. Подписание поручений возможно только внутри личного кабинета.
Метод в API: https://api.modulbank.ru/v1/operation-upload/1c
Parameters: order (PaymentOrder) – Объект платёжного поручения
Returns: Ответ API МодульБанка, содержащий количество загруженных платёжных поручений и ошибки по незагруженным платёжным поручениям при их наличии
Return type: Raises: - NotAuthorizedModulbankException – Если не прошли авторизацию.
- UnexpectedResponseStatusModulbankException – Если статус ответа сервера отлиается от ожидаемого.
- UnexpectedResponseBodyModulbankException – Если не удалось обработать полученные данные.
-
operations
(account_id: str, search: modulbank.client.SearchOptions = None) → list¶ Просмотр истории операций
Метод в API: https://api.modulbank.ru/v1/operation-history/<account_id>
Parameters: - account_id (str) – Системный идентификатор счёта
- search (SearchOptions) – Опциональные параметры поиска операций
Returns: Массив операций, представленных структурой
Operation
Return type: list(Operation)
Raises: - NotAuthorizedModulbankException – Если не прошли авторизацию.
- UnexpectedResponseStatusModulbankException – Если статус ответа сервера отлиается от ожидаемого.
- UnexpectedResponseBodyModulbankException – Если не удалось обработать полученные данные.
-
token
¶ Токен API
Returns: Токен API Return type: str
-
-
class
modulbank.client.
PaymentResponse
(obj: dict, document: str = None)¶ Bases:
object
Ответ на импорт платёжек в API МодульБанка, содержащий количество загруженных платёжных поручений и ошибки по незагруженным платёжным поручениям при их наличии
-
document
¶ Платёжное поручение в формате 1CClientBankExchange
Returns: Документ, отправленный в API МодульБанка Return type: str
-
errors
¶ Ошибки по незагруженным платежным поручениям
Returns: Ошибки по незагруженным платежным поручениям Return type: list(str)
-
total_loaded
¶ Количество загруженных платежных поручений
Returns: Количество загруженных платежных поручений Return type: int
-
-
class
modulbank.client.
SearchOptions
(category: modulbank.structs.OperationCategory = None, date_from: datetime.date = None, date_till: datetime.date = None, page: int = 0)¶ Bases:
object
Критерии отбора операций при поиске.
-
category
¶ Направление платежа
Возможные значения:
- OperationCategory.Debet - входящий;
- OperationCategory.Credit - исходящий
Returns: Направление платежа Return type: OperationCategory
-
date_from
¶ Вывести операции от момента времени
Returns: Момент времен “от” Return type: datetime.date
-
date_till
¶ Вывести операции до момента времени
Returns: Момент времен “до” Return type: datetime.date
-
page
¶ Номер страницы постраничного вывода
Начиная с 0, размер определяется в конструкторе
ModulbankClient
Returns: Номер страницы Return type: int
-
to_dict
() → dict¶ Возвращает парметры поиска в виде словаря (для последующей запаковки в JSON-объект).
Returns: Словарь критериев поиска. Return type: dict
-
modulbank.client_bank_exchange module¶
-
class
modulbank.client_bank_exchange.
BalancesSection
¶ Bases:
modulbank.client_bank_exchange.BaseSection
Секция Начальных остатков
-
class
modulbank.client_bank_exchange.
BaseSection
¶ Bases:
object
Абстрактный базовый класс для секций документа обмена данными
-
document
¶ Свойство выдает полностью сформированную секцию документа в формате 1С.
Returns: Текст секции Return type: str
-
-
class
modulbank.client_bank_exchange.
ClientBankExchange
¶ Bases:
object
Файл обмена данными 1С
-
document
¶ Свойство выдает полностью сформированный документ обмена данными клиент-банк-клиент в формате 1С.
Returns: Текст документа Return type: str
-
-
class
modulbank.client_bank_exchange.
DocumentSection
¶ Bases:
modulbank.client_bank_exchange.BaseSection
Секция Документ
-
class
modulbank.client_bank_exchange.
FilterSection
¶ Bases:
modulbank.client_bank_exchange.BaseSection
Секция Фильтров
-
class
modulbank.client_bank_exchange.
GeneralSection
¶ Bases:
modulbank.client_bank_exchange.BaseSection
Общая секция
modulbank.exceptions module¶
-
exception
modulbank.exceptions.
ModulbankException
¶ Bases:
Exception
Базовый класс для исключений пакета.
-
exception
modulbank.exceptions.
NotAuthorizedModulbankException
¶ Bases:
modulbank.exceptions.ModulbankException
Возникает если не прошли авторизацию.
-
exception
modulbank.exceptions.
UnexpectedResponseBodyModulbankException
¶ Bases:
modulbank.exceptions.ModulbankException
Возникает если не удалось обработать полученные данные.
-
exception
modulbank.exceptions.
UnexpectedResponseStatusModulbankException
¶ Bases:
modulbank.exceptions.ModulbankException
Возникает если статус ответа сервера отлиается от ожидаемого.
-
exception
modulbank.exceptions.
UnexpectedValueModulbankException
¶ Bases:
modulbank.exceptions.ModulbankException
Возникает если не удалось конвертировать полученное значение.
modulbank.structs module¶
-
class
modulbank.structs.
AccountCategory
¶ Bases:
enum.Enum
An enumeration.
-
CardAccount
= 3¶
-
CheckingAccount
= 1¶
-
DepositAccount
= 2¶
-
DepositRateAccount
= 4¶
-
ReservationAccounting
= 5¶
-
-
class
modulbank.structs.
AccountStatus
¶ Bases:
enum.Enum
An enumeration.
-
Closed
= 3¶
-
Deleted
= 2¶
-
Freezed
= 4¶
-
New
= 1¶
-
ToClosed
= 5¶
-
ToOpen
= 6¶
-
-
class
modulbank.structs.
Bank
(obj: dict)¶ Bases:
object
Реквизиты банка (из платежных реквизитов организации).
-
bic
¶ БИК Банка
Returns: БИК Банка Return type: str
-
corr_account
¶ Номер корреспондетского счёта
Returns: Корр. счёт Return type: str
-
inn
¶ ИНН Банка
Returns: ИНН Банка Return type: str
-
kpp
¶ КПП Банка
Returns: КПП Банка Return type: str
-
name
¶ Наименование банка
Returns: Наименование банка Return type: str
-
-
class
modulbank.structs.
BankAccount
(obj: dict)¶ Bases:
object
Счёт компании-пользователя МодульБанка.
-
account_id
¶ Системный идентификатор счёта
Returns: Системный идентификатор счёта Return type: str
-
balance
¶ Баланс на счёте
Returns: Баланс на счёте (в валюте счёта) Return type: Decimal
-
begin_date
¶ Дата открытия счёта
Returns: Дата открытия счёта Return type: datetime.date
-
category
¶ Категория счёта
Возможные значения:
- CheckingAccount (расчетный счёт),
- DepositAccount (депозитный счёт),
- CardAccount (карточный счёт),
- DepositRateAccount (счёт для процентов по депозиту),
- ReservationAccounting (счёт учета резервов)
Returns: Категория счёта Return type: AccountCategory
-
name
¶ Наименование счёта
Returns: Наименование счёта Return type: str
-
number
¶ Номер счёта
Returns: Номер счёта Return type: str
-
status
¶ Состояния счёта
Возможные значения:
- New (открытый)
- Deleted (удалённый)
- Closed (закрытый)
- Freezed (замороженный)
- ToClosed (в процессе закрытия)
- ToOpen (в процессе открытия)
Returns: Состояние счёта Return type: AccountStatus
-
-
class
modulbank.structs.
BankShort
(account: str = None, name: str = None, bic: str = None, corr_acc: str = None)¶ Bases:
object
Короткие банковские реквизиты.
Номер счета, Название банка, БИК и корр. счёт.
-
account
¶ Номер счета
Returns: Номер счета Return type: str
-
bic
¶ БИК
Returns: БИК Return type: str
-
corr_acc
¶ Корреспондентский счёт
Returns: Корреспондентский счёт Return type: str
-
name
¶ Название банка
Returns: Название банка Return type: str
-
-
class
modulbank.structs.
BudgetaryAndTax
(obj: dict)¶ Bases:
object
Параметры бюджетных и налоговых платежей в операции.
-
kbk
¶ Код бюджетной классификации (104)
Returns: Код бюджетной классификации Return type: str
-
oktmo
¶ Общероссийский классификатор территорий муниципальных образований (105)
Returns: Общероссийский классификатор территорий муниципальных образований Return type: str
-
payer_status
¶ Статус плательщика (101)
Returns: Статус плательщика Return type: str
-
payment_basis
¶ Основание платежа (106)
Returns: Основание платежа Return type: str
-
tax_code
¶ Налоговый период
Returns: Налоговый период Return type: str
-
tax_doc_date
¶ Дата документа (109)
Returns: Дата документа Return type: str
-
tax_doc_num
¶ Номер документа (108)
Returns: Номер документа Return type: str
-
uin
¶ Уникальный идентификатор начисления (22)
Returns: Уникальный идентификатор начисления Return type: str
-
-
class
modulbank.structs.
Company
(obj: dict)¶ Bases:
object
Компания, в которой состоит пользователь МодульБанка.
-
bank_accounts
¶ Массив счетов компании
Returns: Массив счетов компании Return type: list(BankAccount)
-
company_id
¶ Системный идентификатор компании
Returns: Системный идентификатор компании Return type: str
-
name
¶ Название компании
Returns: Название компании Return type: str
-
-
class
modulbank.structs.
Contractor
(obj: dict = None, name: str = None, inn: str = None, kpp: str = None, bank: modulbank.structs.BankShort = None)¶ Bases:
object
Контрагент в операции.
-
bank
¶ Банковские реквизиты контрагента (Номер счета, Название банка и БИК)
Returns: Банковские реквизиты контрагента Return type: BankShort
-
inn
¶ ИНН контрагента
Returns: ИНН контрагента Return type: str
-
kpp
¶ КПП контрагента
Returns: КПП контрагента Return type: str
-
name
¶ Полное наименование контрагента
Returns: Полное наименование контрагента Return type: str
-
-
class
modulbank.structs.
Currency
¶ Bases:
enum.Enum
An enumeration.
-
CNY
= 4¶
-
EUR
= 3¶
-
RUR
= 1¶
-
USD
= 2¶
-
-
class
modulbank.structs.
NotifyRequest
(obj: dict = None)¶ Bases:
object
Уведомление о произошедшей транзакции.
-
check_signature
(token) → bool¶ Проверка SHA1-подписи.
Parameters: token (str) – Токен из ЛК МодульБанка Returns: Успешность проверки цифровой подписи Return type: bool
-
inn
¶ ИНН компании (для которой в Модульбанке появилась транзакция)
Returns: ИНН компании Return type: str
-
kpp
¶ КПП компании (для которой в Модульбанке появилась транзакция)
Returns: КПП компании Return type: str
-
signature
¶ Подпись сообщения, гарантирующая целостность данных уведомления и то, что уведомления были отправлены сервером Модульбанка. Проверяется с помощью
check_signature()
Returns: Подпись сообщения Return type: str
-
-
class
modulbank.structs.
Operation
(obj: dict)¶ Bases:
object
Операция по счёту
-
account_number
¶ Номер банковского счета
Returns: Номер банковского счета Return type: str
-
amount
¶ Сумма платежа без учета банковской комиссии
Returns: Сумма платежа без учета банковской комиссии Return type: Decimal
-
amount_with_commission
¶ Сумма платежа с учетом банковской комиссии
Returns: Сумма платежа с учетом банковской комиссии Return type: Decimal
-
budgetary_and_tax
¶ Параметры бюджетных и налоговых платежей в операции
Returns: Параметры бюджетных и налоговых платежей в операции Return type: BudgetaryAndTax
-
category
¶ Направление платежа.
Возможные значения:
- Debet (входящая),
- Credit (исходящая)
Returns: Направление платежа Return type: OperationCategory
-
company_id
¶ Системный идентификатор компании
Returns: Системный идентификатор компании Return type: str
-
contractor
¶ Контрагент
Returns: Контрагент Return type: Contractor
-
created
¶ Дата создания транзакции
Returns: Дата создания транзакции Return type: datetime.datetime
-
currency
¶ Код валюты.
Возможные значения:
- RUR,
- EUR,
- USD,
- CNY
Returns: Код валюты Return type: Currency
-
doc_number
¶ Номер документа
Returns: Номер документа Return type: str
-
executed
¶ Дата проведения платежа
Returns: Дата проведения платежа Return type: datetime.datetime
-
operation_id
¶ Системный идентификатор транзакции
Returns: Системный идентификатор транзакции Return type: str
-
purpose
¶ Назначение платежа
Returns: Назначение платежа Return type: str
-
status
¶ Текущий статус транзакции.
Возможные значения:
- SendToBank (Исходящая, ожидающая исполнения),
- Executed (Исходящий исполненный),
- RejectByBank (Исходящая, отказано банком в исполнении),
- Canceled (Исходящая, отправленная в банк и отменённая пользователем),
- Received (Входящая исполненная)
Returns: Текущий статус транзакции Return type: OperationStatus
-
-
class
modulbank.structs.
OperationStatus
¶ Bases:
enum.Enum
An enumeration.
-
Canceled
= 4¶
-
Executed
= 2¶
-
Received
= 5¶
-
RejectByBank
= 3¶
-
SendToBank
= 1¶
-
-
class
modulbank.structs.
PaymentOrder
(doc_num: str, account_num: str, amount: decimal.Decimal, purpose: str, payer: modulbank.structs.Contractor, recipient: modulbank.structs.Contractor, payment_type: str = '01', priority: str = '5', date: datetime.date = None)¶ Bases:
object
Платёжное поручение
-
account_num
¶ Номер банковского счета
Returns: Номер банковского счета Return type: str
-
amount
¶ Сумма платежа
Returns: Сумма платежа Return type: Decimal
-
date
¶ Дата подготовки платежа
Returns: Дата подготовки платежа Return type: datetime.date
-
doc_num
¶ Номер документа
Returns: Номер документа Return type: str
-
payer
¶ Плательщик
Returns: Плательщик Return type: Contractor
-
payment_type
¶ Вид оплаты. По умолчанию ‘01’.
Returns: Вид оплаты Return type: str
-
priority
¶ Очередность. По умолчанию ‘5’.
Returns: Очередность Return type: str
-
purpose
¶ Назначение платежа
Returns: Назначение платежа Return type: str
-
recipient
¶ Получатель
Returns: Получатель Return type: Contractor
-