NpdClient¶

NpdClient — основной класс для взаимодействия с API "Мой Налог" (lknpd.nalog.ru).

Класс предоставляет асинхронный интерфейс для:

🔐 Авторизации и управления сессией
🧾 Создания и управления чеками
💰 Работы со счетами на оплату
📊 Получения статистики и истории операций

Быстрый старт¶

from nalogovich import NpdClient

async with NpdClient(inn="ваш_инн", password="ваш_пароль") as client:
    # Авторизация
    await client.auth()

    # Создание чека
    income = await client.create_check(
        name="Консультация",
        amount=5000.00
    )
    print(f"Чек создан: {income.receipt_id}")

Основные группы методов¶

🔐 Авторизация¶

auth() — авторизация через ЛК ФЛ
re_auth() — обновление токена

🧾 Работа с чеками¶

create_check() — создание чека (регистрация дохода)
cancel_check() — аннулирование чека
get_checks() — получение списка чеков
create_check_from_bill() — создание чека из оплаченного счёта

💰 Работа со счетами¶

create_bill() — создание счёта на оплату
get_bills() — получение списка счетов
approve_bill() — подтверждение оплаты счёта
cancel_bill() — аннулирование счёта
update_bill_payment_info() — обновление платёжной информации счёта

📊 Дополнительно¶

get_payment_types() — список реквизитов для оплаты

Справочник методов¶

Functions¶

auth `async` ¶

auth()

Авторизация через ЛК ФЛ (lkfl).

Raises:

AuthenticationError –

При неверных учетных данных или других ошибках авторизации
ApiError –

При других ошибках API

re_auth `async` ¶

re_auth()

Повторная авторизация через refresh token.

Raises:

AuthenticationError –

При невалидном refresh token
ApiError –

При других ошибках API

get_checks `async` ¶

get_checks(
    from_date: datetime | None = replace(day=1),
    to_date: datetime | None = now(),
    offset: int | None = 0,
    limit: int | None = 30,
    sort_by: SortBy | None = operation_time_desc,
    receipt_type: ReceiptType | None = None,
    buyer_type: BuyerType | None = None,
) -> OperationResponse

Метод для получения чеков в истории за определенный период API Endpoint: https://lknpd.nalog.ru/api/v1/incomes

Parameters:

from_date (datetime | None, default: replace(day=1) ) –

Дата с которой будет браться информация о чеках
to_date (datetime | None, default: now() ) –

Дата по которой будет браться информация о чеках
offset (int | None, default: 0 ) –

Смещение для пагинации
limit (int | None, default: 30 ) –

Количество записей на страницу
sort_by (SortBy | None, default: operation_time_desc ) –

Сортировка записей по определенному параметру
receipt_type (ReceiptType | None, default: None ) –

Сортировка чеков по их статусу (по стандарту - все чеки)
buyer_type (BuyerType | None, default: None ) –

Сортировка чеков по типу клиента (по стандарту - все чеки)

Returns:

OperationResponse –

OperationResponse - модель с информацией о чеках

create_check `async` ¶

create_check(
    name: str | None = None,
    amount: float | None = None,
    services: list[ServiceCheck] | None = None,
    is_business: bool = False,
    is_foreign_organization: bool = False,
    inn_of_organization: str | None = None,
    name_of_organization: str | None = None,
    date_of_sale: datetime | None = None,
    payment_type: PaymentType = CASH,
    ignore_max_total_income_restriction: bool = False,
) -> Income

Регистрация дохода. Поддерживает одну или несколько позиций.

Parameters:

name (str | None, default: None ) –

Название (если одна позиция)
amount (float | None, default: None ) –

Сумма (если одна позиция)
services (list[ServiceCheck] | None, default: None ) –

Список объектов ServiceCheck (если позиций несколько)
is_business (bool, default: False ) –

Является ли организация бизнесом
is_foreign_organization (bool, default: False ) –

Является ли организация иностранной
inn_of_organization (str | None, default: None ) –

ИНН организации
name_of_organization (str | None, default: None ) –

Название организации
date_of_sale (datetime | None, default: None ) –

Дата и время продажи
payment_type (PaymentType, default: CASH ) –

Тип оплаты
ignore_max_total_income_restriction (bool, default: False ) –

Игнорировать ограничение по максимальному годовому доходу

Returns:

Income –

Income - модель с информацией о зарегистрированном доходе

cancel_check `async` ¶

cancel_check(
    receipt_uuid: str, comment: CommentReturn | str = wrong_receipt
) -> IncomeInfo

Метод для аннулирования чека. API Endpoint: https://lknpd.nalog.ru/api/v1/cancel

Parameters:

receipt_uuid (str) –

Уникальный идентификатор чека (например, "200bzznrt0").
comment (CommentReturn | str, default: wrong_receipt ) –

Причина аннулирования.

create_bill `async` ¶

create_bill(
    name: str | None = None,
    amount: float | None = None,
    services: list[ServiceCheck] | None = None,
    client_name: str | None = None,
    client_phone: str | None = None,
    client_email: str | None = None,
    client_inn: str | None = None,
    client_type: InvoiceClientType = FROM_INDIVIDUAL,
    payment_type: InvoicePaymentType = PHONE,
    phone: str | None = None,
    bank_name: str | None = None,
    bank_bik: str | None = None,
    corr_account: str | None = None,
    current_account: str | None = None,
) -> Invoice

Создание счёта на оплату.

API Endpoint: https://lknpd.nalog.ru/api/v1/invoice

Parameters:

name (str | None, default: None ) –

Название услуги (если одна позиция)
amount (float | None, default: None ) –

Сумма услуги (если одна позиция)
services (list[ServiceCheck] | None, default: None ) –

Список объектов ServiceCheck (если позиций несколько)
client_name (str | None, default: None ) –

ФИО/Название клиента
client_phone (str | None, default: None ) –

Телефон клиента
client_email (str | None, default: None ) –

Email клиента
client_inn (str | None, default: None ) –

ИНН клиента (обязательно для юр. лиц и ИП)
client_type (InvoiceClientType, default: FROM_INDIVIDUAL ) –

Тип клиента (FROM_INDIVIDUAL, FROM_LEGAL_ENTITY, FROM_FOREIGN_AGENCY)
payment_type (InvoicePaymentType, default: PHONE ) –

Тип оплаты (PHONE - СБП по номеру телефона, ACCOUNT - на банковский счет)
phone (str | None, default: None ) –

Номер телефона для получения оплаты (обязательно для PHONE)
bank_name (str | None, default: None ) –

Название банка
bank_bik (str | None, default: None ) –

БИК банка (обязательно для ACCOUNT)
corr_account (str | None, default: None ) –

Корреспондентский счет банка (обязательно для ACCOUNT)
current_account (str | None, default: None ) –

Расчетный счет (обязательно для ACCOUNT)

Returns:

Invoice –

Invoice - модель с информацией о созданном счёте

cancel_bill `async` ¶

cancel_bill(invoice_id: int) -> Invoice

Аннулирование счёта. API Endpoint: https://lknpd.nalog.ru/api/v1/invoice/{invoice_id}/cancel

Parameters:

invoice_id (int) –

ID счёта для аннулирования

Returns:

Invoice –

Invoice - модель с информацией об аннулированном счёте

get_bills `async` ¶

get_bills(
    offset: int = 0,
    limit: int = 10,
    status: InvoiceStatus = ALL,
    search: str | None = None,
    date_from: datetime | None = None,
    date_to: datetime | None = None,
    sort_by: str = "createdAt",
    sort_desc: bool = True,
) -> InvoiceResponse

Получение списка счетов. API Endpoint: https://lknpd.nalog.ru/api/v1/invoice/table

Parameters:

offset (int, default: 0 ) –

Смещение для пагинации
limit (int, default: 10 ) –

Лимит записей
status (InvoiceStatus, default: ALL ) –

Статус счетов
search (str | None, default: None ) –

Поиск по ИНН или ФИО клиента
date_from (datetime | None, default: None ) –

Дата начала периода
date_to (datetime | None, default: None ) –

Дата окончания периода
sort_by (str, default: 'createdAt' ) –

Поле для сортировки (createdAt)
sort_desc (bool, default: True ) –

Сортировка по убыванию

Returns:

InvoiceResponse –

InvoiceResponse - список счетов с пагинацией

get_payment_types `async` ¶

get_payment_types(payment_type: InvoicePaymentType) -> list[PaymentTypeInfo]

Получение реквизитов пользователя для получения оплаты. API Endpoint: https://lknpd.nalog.ru/api/v1/payment-type/table?type={type}

Parameters:

payment_type (InvoicePaymentType) –

Тип реквизитов (PHONE - СБП, ACCOUNT - банковский счет)

Returns:

list[PaymentTypeInfo] –

Список реквизитов PaymentTypeInfo

update_bill_payment_info `async` ¶

update_bill_payment_info(
    invoice_id: int,
    payment_type: InvoicePaymentType,
    phone: str | None = None,
    bank_name: str | None = None,
    bank_bik: str | None = None,
    corr_account: str | None = None,
    current_account: str | None = None,
) -> Invoice

Изменение способа оплаты счёта. API Endpoint: https://lknpd.nalog.ru/api/v1/invoice/update-payment-info

Parameters:

invoice_id (int) –

ID счёта
payment_type (InvoicePaymentType) –

Тип оплаты (PHONE - СБП, ACCOUNT - на банковский счет)
phone (str | None, default: None ) –

Номер телефона для получения оплаты (для СБП)
bank_name (str | None, default: None ) –

Название банка
bank_bik (str | None, default: None ) –

БИК банка (для оплаты на счет)
corr_account (str | None, default: None ) –

Корреспондентский счет банка (для оплаты на счет)
current_account (str | None, default: None ) –

Расчетный счет (для оплаты на счет)

Returns:

Invoice –

Invoice - модель с обновлённой информацией о счёте

approve_bill `async` ¶

approve_bill(invoice_id: int) -> Invoice

Пометить счёт как оплаченный. API Endpoint: https://lknpd.nalog.ru/api/v1/invoice/{invoice_id}/approve

Parameters:

invoice_id (int) –

ID счёта

Returns:

Invoice –

Invoice - модель с информацией об оплаченном счёте

create_check_from_bill `async` ¶

create_check_from_bill(
    invoice_id: int, operation_time: datetime | None = None
) -> Invoice

Создать чек на основе оплаченного счёта. API Endpoint: https://lknpd.nalog.ru/api/v1/invoice/{invoice_id}/approve

Parameters:

invoice_id (int) –

ID счёта
operation_time (datetime | None, default: None ) –

Дата и время получения средств (если не указано - текущее время)

Returns:

Invoice –

Invoice - модель с информацией о счёте с чеком

NpdClient¶

Быстрый старт¶

Основные группы методов¶

🔐 Авторизация¶

🧾 Работа с чеками¶

💰 Работа со счетами¶

📊 Дополнительно¶

Справочник методов¶

Functions¶

auth async ¶

re_auth async ¶

get_checks async ¶

create_check async ¶

cancel_check async ¶

create_bill async ¶

cancel_bill async ¶

get_bills async ¶

get_payment_types async ¶

update_bill_payment_info async ¶

approve_bill async ¶

create_check_from_bill async ¶

auth `async` ¶

re_auth `async` ¶

get_checks `async` ¶

create_check `async` ¶

cancel_check `async` ¶

create_bill `async` ¶

cancel_bill `async` ¶

get_bills `async` ¶

get_payment_types `async` ¶

update_bill_payment_info `async` ¶

approve_bill `async` ¶

create_check_from_bill `async` ¶