main.py

"""
Клиент API справочника SWIFT/BIC Atlorium — карточка организации по SWIFT-коду,
поиск по названию и валидация формата BIC по стандарту ISO-9362.

Запуск (работает сразу, без регистрации — на демо-ключе):
    pip install -r requirements.txt
    python main.py
    python main.py DEUTDEFF DE

Боевой ключ: получить на https://atlorium.com и положить в переменную окружения
ATLORIUM_API_KEY. Код при этом не меняется.
"""

import os
import sys
from dataclasses import dataclass, field

import requests

# Публичный демо-ключ. С ним API отвечает правдоподобными МОКАМИ (не реальными
# данными) — чтобы можно было встроить и протестировать интеграцию до оплаты.
# Ответы детерминированы: один и тот же запрос всегда даёт один и тот же результат,
# поэтому на них можно писать стабильные тесты.
SANDBOX_KEY = "ak_sandbox_demo_mockdata_v1"

API_KEY = os.environ.get("ATLORIUM_API_KEY", SANDBOX_KEY)
BASE_URL = os.environ.get("ATLORIUM_BASE_URL", "https://atlorium.com")

TIMEOUT = 30


class AtloriumError(RuntimeError):
    """Ошибка API. Код HTTP разложен в человекочитаемую причину."""

    REASONS = {
        400: "Неверный формат BIC (ожидается 8 или 11 символов по ISO-9362)",
        401: "API-ключ отсутствует, просрочен или недействителен",
        402: "Недостаточно кредитов на балансе — пополните на https://atlorium.com",
        404: "BIC не найден в справочнике SWIFT",
        429: "Превышен лимит запросов — повторите позже",
        503: "Справочник временно недоступен (за сбой на своей стороне мы не списываем деньги)",
    }

    def __init__(self, status: int, body: str):
        reason = self.REASONS.get(status, "Неизвестная ошибка")
        super().__init__(f"HTTP {status}: {reason}. Ответ сервера: {body[:200]}")
        self.status = status


def _get(path: str, params: dict | None = None) -> requests.Response:
    response = requests.get(
        f"{BASE_URL}{path}",
        params=params,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Accept": "application/json",
        },
        timeout=TIMEOUT,
    )
    if not response.ok:
        raise AtloriumError(response.status_code, response.text)
    return response


def get_bank(bic: str) -> dict:
    """Карточка организации по точному SWIFT/BIC (8 или 11 символов).

    8-значный код обозначает головной офис и внутри справочника дополняется до 11
    суффиксом «XXX». Если такого BIC нет — API отвечает 404.
    """
    return _get(f"/api/swift/{bic}").json()


def search_banks(query: str, limit: int = 20) -> dict:
    """Полнотекстовый поиск организаций по наименованию. Например, «Deutsche Bank»."""
    return _get("/api/swift/search", {"query": query, "limit": limit}).json()


def validate_bic(bic: str) -> dict:
    """Проверка формата BIC по ISO-9362 и разбор кода на составные части.

    Проверяется ТОЛЬКО формат, а не существование кода: DEUTDEFF и XXXXDEFF оба
    формально валидны. Чтобы узнать, существует ли организация, нужен get_bank().
    """
    return _get(f"/api/swift/validate/{bic}").json()


def get_stats() -> dict:
    """Служебная информация сервиса: готовность отвечать на запросы."""
    return _get("/api/swift/stats").json()


# ── Применение данных: проверка реквизитов перед международным переводом ──────
# Карточка сама по себе — просто JSON. Ценность появляется, когда из неё делают
# вывод. Ниже — набор проверок, которые делают перед отправкой SWIFT-перевода:
# сначала разбираем формат BIC, потом сверяем его с реальной карточкой организации.


@dataclass
class TransferCheck:
    validation: dict
    bank: dict | None = None
    risks: list[str] = field(default_factory=list)
    notes: list[str] = field(default_factory=list)

    @property
    def is_risky(self) -> bool:
        return bool(self.risks)


def check_before_transfer(bic: str, expected_country: str | None = None) -> TransferCheck:
    """Проверить BIC получателя перед международным переводом.

    expected_country — ожидаемый код страны получателя (ISO-3166 alpha-2, например
    «DE»). Несовпадение страны в BIC с реальной страной получателя — классическая
    ошибка при копировании реквизитов из письма или счёта.
    """
    validation = validate_bic(bic)
    check = TransferCheck(validation=validation)

    # Шаг 1. Формат. Структура BIC по ISO-9362:
    #   AAAA BB CC (DDD) — 4 буквы код банка, 2 буквы код страны,
    #   2 символа код локации, опционально 3 символа код филиала.
    #   XXX или отсутствие кода филиала = головной офис.
    if not validation.get("isValidFormat"):
        check.risks.append(f"Формат BIC нарушен: {validation.get('message')}")
        return check

    bic_country = validation.get("countryCode")

    # Ожидаемая страна получателя не совпала со страной, зашитой в сам BIC.
    if expected_country and bic_country and expected_country.upper() != bic_country.upper():
        check.risks.append(
            f"Страна в BIC ({bic_country}) не совпадает с ожидаемой страной "
            f"получателя ({expected_country.upper()})"
        )

    if validation.get("isPrimaryOffice"):
        check.notes.append(f"Головной офис (код филиала: {validation.get('branchCode') or 'не указан'})")
    else:
        check.notes.append(
            f"Не головной офис, а филиал (код: {validation.get('branchCode')}) — "
            f"убедитесь, что получатель обслуживается именно в нём"
        )

    # Шаг 2. Существует ли организация с таким BIC. Валидный формат ничего не
    # гарантирует: код может быть выдуманным или отозванным.
    try:
        check.bank = get_bank(bic)
    except AtloriumError as error:
        if error.status == 404:
            check.risks.append("BIC не найден в справочнике SWIFT — реквизиты, скорее всего, ошибочны")
            return check
        raise

    bank = check.bank

    # Прекратившая существование организация — деньги уйдут в никуда.
    status = (bank.get("entityStatus") or "").upper()
    if status and status != "ACTIVE":
        check.risks.append(f"Организация неактивна: статус {status}")

    if bank.get("entityExpirationDate"):
        reason = bank.get("entityExpirationReason") or "причина не указана"
        check.risks.append(
            f"Организация прекратила существование {bank['entityExpirationDate'][:10]} ({reason})"
        )
    if bank.get("successorName"):
        check.notes.append(f"Правопреемник: {bank['successorName']} (LEI {bank.get('successorLei')})")

    # Страна организации в справочнике должна совпадать со страной в BIC.
    bank_country = bank.get("country")
    if bank_country and bic_country and bank_country.upper() != bic_country.upper():
        check.risks.append(
            f"Страна организации в справочнике ({bank_country}) не совпадает "
            f"со страной в BIC ({bic_country}) — перепроверьте реквизиты"
        )

    registration = (bank.get("registrationStatus") or "").upper()
    if registration and registration != "ISSUED":
        check.notes.append(f"Регистрация LEI: {registration}")

    all_bics = bank.get("allBics") or []
    if len(all_bics) > 1:
        check.notes.append(f"Другие BIC этой организации: {', '.join(all_bics)}")

    return check


def main() -> int:
    if API_KEY == SANDBOX_KEY:
        print("Демо-ключ: ответы сгенерированы (моки), не реальные данные.\n")

    bic = sys.argv[1] if len(sys.argv) > 1 else "DEUTDEFF"
    expected_country = sys.argv[2] if len(sys.argv) > 2 else None

    try:
        check = check_before_transfer(bic, expected_country)
    except AtloriumError as error:
        print(f"Ошибка: {error}", file=sys.stderr)
        return 1

    validation = check.validation
    if not validation.get("isValidFormat"):
        print(f"BIC {bic}: {validation.get('message')}")
        print("\nВЕРДИКТ: перевод отправлять нельзя.")
        for risk in check.risks:
            print(f"  [!] {risk}")
        return 0

    print(f"Разбор BIC {validation['normalizedBic']} по ISO-9362: формат корректен.")
    print(f"  Код банка:   {validation.get('bankCode')}")
    print(f"  Страна:      {validation.get('countryCode')}")
    print(f"  Локация:     {validation.get('locationCode')}")
    print(f"  Филиал:      {validation.get('branchCode') or '—'}")

    bank = check.bank
    if bank:
        print()
        print(bank["name"])
        print(f"  BIC {bank.get('bic')} · LEI {bank.get('lei')}")
        print(f"  Страна: {bank.get('country')} · {bank.get('city')}")
        print(f"  Адрес: {bank.get('address')}")
        print(f"  Статус: {bank.get('entityStatus')} · регистрация LEI: {bank.get('registrationStatus')}")

    print()
    if check.is_risky:
        print("ВЕРДИКТ: реквизиты сомнительные, перевод отправлять рискованно.")
        for risk in check.risks:
            print(f"  [!] {risk}")
    else:
        print("ВЕРДИКТ: реквизиты выглядят корректно.")

    for note in check.notes:
        print(f"  [i] {note}")

    if bank and bank.get("lastUpdate"):
        print(f"\nЗапись справочника обновлена {bank['lastUpdate'][:10]}.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())