Metadata-Version: 2.4
Name: ru-requisites
Version: 0.2.0
Summary: Проверка российских реквизитов и разбор справочника БИК ED807
Author: Leonid Kushkin
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/lennyk1279/ru-requisites
Project-URL: Repository, https://gitlab.com/lennyk1279/ru-requisites
Project-URL: Issues, https://gitlab.com/lennyk1279/ru-requisites/-/issues
Project-URL: Changelog, https://gitlab.com/lennyk1279/ru-requisites/-/blob/main/CHANGELOG.md
Keywords: russia,banking,inn,kpp,bic,ed807,requisites
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.ru
Requires-Dist: defusedxml<0.8,>=0.7.1
Provides-Extra: dev
Requires-Dist: black>=25.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: mypy>=1.15.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: twine>=6.0.0; extra == "dev"
Dynamic: license-file

# ru-requisites

Библиотека проверяет российские платёжные реквизиты по формату и контрольным алгоритмам и разбирает локально переданный официальный справочник БИК Банка России в формате ED807.

Она отвечает на вопросы: верны ли контрольные цифры ИНН и счёта, похож ли БИК на девятизначный номер, какой корреспондентский счёт можно подставить из уже полученного ED807. Это не проверка того, что счёт открыт или обслуживается банком. Принадлежность расчётного счёта конкретной организации из данных ED807 тоже не следует: библиотека такую проверку не обещает.

## Что библиотека намеренно не делает

- не скачивает ED807 из интернета и не знает URL, расписание обновления или правила повторных попыток;
- не хранит и не обновляет собственную базу справочника;
- не определяет схему базы данных приложения и не создаёт миграции;
- не проверяет, что счёт открыт именно этой организации;
- не знает про HTTP API, формы, права доступа и тексты интерфейса.

Тексты для пользователя пишет приложение. Библиотека возвращает код вроде `checksum_mismatch`.

## Источник справочника БИК

Библиотека разбирает официальный справочник банковских идентификационных кодов Банка России в формате ED807. Она не скачивает файл сама: приложение получает ZIP-архив, обрабатывает сетевые ошибки и передаёт содержимое в `parse_ed807_zip()` как `bytes`.

Официальные страницы Банка России (справочная информация для документации, не часть публичного API библиотеки):

- [Справочник БИК Банка России](https://www.cbr.ru/PSystem/system_p/);
- [точка получения актуального архива ED807](https://www.cbr.ru/s/newbik).

```python
from ru_requisites import parse_ed807_zip

# ed807_zip_bytes загружает и передаёт вызывающее приложение.
snapshot = parse_ed807_zip(ed807_zip_bytes)
```

Unit-тесты используют только локально созданные данные и fixture-файлы JSON-снимка; сеть не требуется.

## Установка

Нужен Python 3.11 или новее. Единственная зависимость — `defusedxml`.

```bash
python -m pip install ru-requisites
```

### Из исходников (разработка)

```bash
python -m pip install .
# или editable:
python -m pip install -e ".[dev]"
```

Собрать wheel локально:

```bash
python -m pip install build
python -m build
```

## Быстрый старт

```python
from ru_requisites import (
    AccountKind,
    OrganizationKind,
    validate_account,
    validate_inn,
    validate_kpp,
)

legal = validate_inn("7707083893", OrganizationKind.LEGAL_ENTITY)
assert legal.ok

ip = validate_inn("780437137422", OrganizationKind.INDIVIDUAL_ENTREPRENEUR)
assert ip.ok

assert validate_kpp("770701001").ok

bic = "044525974"
settlement = validate_account(
    "40802810000004494903",
    bic=bic,
    kind=AccountKind.SETTLEMENT,
)
assert settlement.ok

correspondent = validate_account(
    "30101810145250000974",
    bic=bic,
    kind=AccountKind.CORRESPONDENT,
)
assert correspondent.ok
```

Пробелы во вводе валидатор не вырезает. Отдельно можно снять только оформление — пробелы и дефисы — функцией `normalize_digits`. Буквы и прочий мусор она не выкидывает молча, а поднимает `ValueError`. Это не проверка реквизита:

```python
from ru_requisites import normalize_digits

normalize_digits("7707 083893")  # "7707083893"
normalize_digits("7707-083-893")  # "7707083893"
normalize_digits("7707\u00a0083893")  # "7707083893"
# normalize_digits("7707abc083893")  # ValueError
```

Ошибочный ввод — это `CheckResult`, а не исключение:

```python
from ru_requisites import AccountKind, CheckCode, validate_account

bad = validate_account(
    "40802810000004494904",
    bic="044525974",
    kind=AccountKind.SETTLEMENT,
)
assert bad.ok is False
assert bad.code is CheckCode.CHECKSUM_MISMATCH
```

После разбора ZIP можно выбрать корреспондентский счёт по правилам статусов ED807:

```python
from ru_requisites import (
    CorrespondentOutcome,
    parse_ed807_zip,
    resolve_correspondent_account,
)

# ed807_zip_bytes — ZIP, который приложение уже получило локально.
snapshot = parse_ed807_zip(ed807_zip_bytes)
entry = snapshot.get("044525974")
if entry is not None:
    resolution = resolve_correspondent_account(entry)
    if resolution.outcome is CorrespondentOutcome.FOUND:
        print(resolution.account)
```

Разобранный снимок можно сохранить в переносимый JSON и восстановить без повторного разбора ZIP. Это формат обмена, а не замена `parse_ed807_zip` и не обязательное хранилище для lookup:

```python
from ru_requisites import (
    parse_ed807_zip,
    snapshot_from_json,
    snapshot_to_json,
)

snapshot = parse_ed807_zip(ed807_zip_bytes)
payload = snapshot_to_json(snapshot)
# payload можно записать в файл, object storage или передать сервису.
restored = snapshot_from_json(payload)
assert snapshot_to_json(restored) == payload
```

## Публичный API

| Имя | Назначение |
|---|---|
| `validate_inn(value, kind)` | ИНН юрлица (10) или ИП (12) |
| `validate_kpp(value)` | КПП из 9 цифр |
| `validate_bic_format(value)` | БИК из 9 цифр, без справочника |
| `validate_account(value, *, bic, kind)` | Контрольная сумма р/с или к/с |
| `normalize_digits(value)` | Снять пробелы/дефисы; вернуть только `0`–`9` или `ValueError` |
| `parse_ed807_zip(payload)` | ZIP → `DirectorySnapshot` |
| `snapshot_to_json(snapshot) -> bytes` | `DirectorySnapshot` → UTF-8 JSON schema v1 |
| `snapshot_from_json(payload: bytes) -> DirectorySnapshot` | UTF-8 `bytes` → `DirectorySnapshot` (не `str`) |
| `resolve_correspondent_account(entry)` | Выбор CRSA |
| `CheckResult` | `ok`, `code`, `details` |
| `CheckCode` | Коды ошибок ввода |
| `OrganizationKind`, `AccountKind` | Виды ИНН и счёта |
| `CorrespondentOutcome` | `found`, `missing`, `ambiguous`, `inactive` |
| `Ed807ArchiveError`, `Ed807EncodingError`, `Ed807FormatError` | Битый источник ED807 |
| `DirectorySnapshotFormatError`, `DirectorySnapshotVersionError` | Битый или неподдерживаемый JSON-снимок |

Подробности: [docs/validation.md](docs/validation.md), [docs/ed807.md](docs/ed807.md), [docs/snapshot-json.md](docs/snapshot-json.md).

## Коды ошибок ввода

| Код | Значение |
|---|---|
| `invalid_length` | Неверное число символов |
| `non_digit` | Есть символ, не являющийся цифрой |
| `checksum_mismatch` | Контрольная сумма не сошлась |
| `invalid_prefix` | Для к/с номер не начинается с `30101` |
| `unsupported_organization_kind` | Неизвестный вид организации |

Коды не привязаны к именам полей формы. Исключение при обычной опечатке не бросается: смотрите `result.ok`.

Исключения `Ed807*` — только когда сам файл справочника испорчен.

## Как хранить данные

`ru-requisites` не требует базу данных и не поставляет миграции или ORM-модели. Ниже приведены рекомендуемые схемы для приложений, которые используют реляционную БД. Имена таблиц и колонок — пример, а не обязательный контракт библиотеки.

### Какие данные обычно разделяют

| Данные | Назначение | Правило хранения |
|---|---|---|
| Справочник БИК | Внешние данные Банка России: БИК, название банка, статусы и счета | Полный версионированный snapshot; при обновлении заменяется целиком |
| Текущие реквизиты организации | Данные покупателя или продавца, которые можно редактировать | Отдельная запись, связанная с организацией или профилем; не смешивать со строками справочника |

Справочник отвечает на вопрос «что известно о банке с этим БИК». Текущие реквизиты организации — это уже выбор и ввод пользователя (или импорт из другого источника). Проверка ИНН, КПП, БИК и контрольной суммы счетов не подтверждает, что расчётный счёт принадлежит именно этой организации: в ED807 таких сведений нет.

### Рекомендуемая реляционная проекция справочника

У одного БИК в ED807 может быть несколько счетов. Чтобы выбрать корреспондентский счёт, нужны статус участника, статус счёта и тип `CRSA`. Для частого поиска по БИК удобнее держать реляционную проекцию, а не разбирать ZIP или большой JSON при каждом запросе.

```text
bank_directory_snapshots
  id
  business_day
  directory_version
  imported_at
  source_sha256
  is_current

bank_directory_entries
  snapshot_id
  bic
  name
  participant_status
  registration_number

bank_directory_accounts
  entry_id
  account
  account_status
  regulation_account_type
```

Практичные ограничения уникальности:

- для снимка — `(business_day, directory_version)`;
- для записи БИК — `(snapshot_id, bic)`.

Поле `source_sha256` необязательно: его имеет смысл хранить, если приложению нужна проверка, что импортирован именно тот ZIP, который скачали.

### JSON-снимок справочника

С версии `0.2.0` доступны `snapshot_to_json` и `snapshot_from_json`. JSON — переносимый снимок для обмена, offline-доставки и фикстур. Приложение само выбирает файл, object storage или БД. Для частого lookup по БИК в веб-приложении обычно нужна реляционная проекция; JSON её не заменяет и не отменяет `parse_ed807_zip`.

Подробная schema v1 и исключения — в [docs/snapshot-json.md](docs/snapshot-json.md).

### Пример текущих реквизитов организации

Если приложение само хранит банковские реквизиты профиля, типичный набор полей может выглядеть так:

```text
organization_invoice_profile
  organization_id
  organization_kind
  legal_name
  inn
  kpp
  ogrn_or_ogrnip
  legal_address
  postal_address
  bank_name
  bic
  correspondent_account
  settlement_account
  updated_at
```

Библиотека эти таблицы не создаёт: она только проверяет значения, которые приложение уже держит у себя или собирает из формы.

## Совместимость

Версия `0.2.0` следует semver в диапазоне `0.x`. Уже выпущенное значение `CheckCode` не переименовывается. Исправление алгоритма — patch, новая функция — minor. История — в [CHANGELOG.md](CHANGELOG.md).

## Ссылки

- [Справочник БИК Банка России](https://www.cbr.ru/PSystem/system_p/)
- [Актуальный архив ED807](https://www.cbr.ru/s/newbik)
- [Проверка реквизитов](docs/validation.md)
- [Разбор ED807](docs/ed807.md)
- [JSON-снимок справочника](docs/snapshot-json.md)
- [CHANGELOG](CHANGELOG.md)
- [MIT License](LICENSE) · [перевод на русский](LICENSE.ru)

## Лицензия

Проект распространяется по [MIT License](LICENSE).
Для удобства доступен [неофициальный перевод на русский](LICENSE.ru);
при расхождениях приоритет имеет английский текст лицензии.
