API модули
===========

Обзор всех доступных API модулей в aioyookassa.

Доступ к модулям
----------------

Все API модули доступны через главный клиент:

.. code-block:: python

    from aioyookassa import YooKassa

    client = YooKassa(api_key="your_key", shop_id=12345)

    # Доступные модули
    payments = client.payments          # Платежи
    refunds = client.refunds            # Возвраты
    receipts = client.receipts          # Чеки
    invoices = client.invoices          # Счета
    payment_methods = client.payment_methods  # Способы оплаты

💳 Payments API
---------------

Модуль для работы с платежами.

Основные методы
~~~~~~~~~~~~~~~

.. code-block:: python

    from aioyookassa.types.enum import ConfirmationType, Currency
    from aioyookassa.types.params import CreatePaymentParams, GetPaymentsParams
    
    # Создание платежа
    params = CreatePaymentParams(
        amount=PaymentAmount(value=100.00, currency=Currency.RUB),
        confirmation=Confirmation(type=ConfirmationType.REDIRECT, return_url="https://example.com"),
        description="Тестовый платеж"
    )
    payment = await client.payments.create_payment(params)

    # Получение списка платежей
    params = GetPaymentsParams(
        created_at=datetime(2023, 1, 1),
        status=PaymentStatus.SUCCEEDED,
        limit=10
    )
    payments = await client.payments.get_payments(params)

    # Получение конкретного платежа
    payment = await client.payments.get_payment("payment_id")

    # Подтверждение платежа
    payment = await client.payments.capture_payment("payment_id")

    # Отмена платежа
    payment = await client.payments.cancel_payment("payment_id")

Примеры использования
~~~~~~~~~~~~~~~~~~~~~

Создание платежа с полными параметрами
'''''''''''''''''''''''''''''''''''''''

.. code-block:: python

    from aioyookassa.types.payment import (
        PaymentAmount, Confirmation, PaymentMethod, CardInfo,
        Recipient, Customer, Receipt, PaymentItem
    )
    from aioyookassa.types.enum import (
        ConfirmationType, Currency, PaymentMethodType,
        PaymentSubject, PaymentMode
    )

    async def create_full_payment():
        # Настройка способа оплаты
        card_info = CardInfo(
            first_six="123456",
            last_four="7890",
            expiry_month="12",
            expiry_year="2025",
            card_type="Visa"
        )
        
        payment_method = PaymentMethod(
            type=PaymentMethodType.CARD,
            id="pm_123456",
            saved=False,
            card=card_info
        )
        
        # Настройка подтверждения
        confirmation = Confirmation(
            type=ConfirmationType.REDIRECT,
            return_url="https://example.com/success"
        )
        
        # Настройка получателя
        recipient = Recipient(
            account_id="123456789",
            gateway_id="123456"
        )
        
        # Настройка клиента
        customer = Customer(
            full_name="Иван Иванов",
            email="ivan@example.com",
            phone="+79001234567"
        )
        
        # Настройка чека
        receipt = Receipt(
            customer=customer,
            items=[
                PaymentItem(
                    description="Товар",
                    quantity=1,
                    amount=PaymentAmount(value=100.00, currency=Currency.RUB),
                    vat_code=1,
                    payment_subject=PaymentSubject.COMMODITY,
                    payment_mode=PaymentMode.FULL_PAYMENT
                )
            ],
            tax_system_code=1
        )
        
        # Создание платежа
        from aioyookassa.types.params import CreatePaymentParams
        
        params = CreatePaymentParams(
            amount=PaymentAmount(value=100.00, currency=Currency.RUB),
            description="Оплата заказа #12345",
            payment_method=payment_method,
            confirmation=confirmation,
            recipient=recipient,
            receipt=receipt,
            metadata={"order_id": "12345", "user_id": "67890"}
        )
        payment = await client.payments.create_payment(params)
        
        return payment

💰 Refunds API
--------------

Модуль для работы с возвратами.

Основные методы
~~~~~~~~~~~~~~~

.. code-block:: python

    from aioyookassa.types.enum import Currency
    from aioyookassa.types.params import CreateRefundParams
    
    # Создание возврата
    params = CreateRefundParams(
        payment_id="payment_id",
        amount=PaymentAmount(value=50.00, currency=Currency.RUB),
        description="Частичный возврат"
    )
    refund = await client.refunds.create_refund(params)

    # Получение информации о возврате
    refund = await client.refunds.get_refund("refund_id")

    # Получение списка возвратов
    refunds = await client.refunds.get_refunds(
        payment_id="payment_id",
        limit=10
    )

Примеры использования
~~~~~~~~~~~~~~~~~~~~~

Создание возврата с деталями
'''''''''''''''''''''''''''''

.. code-block:: python

    from aioyookassa.types.refund import RefundMethod, RefundArticle
    from aioyookassa.types.enum import Currency

    async def create_detailed_refund():
        # Настройка способа возврата
        refund_method = RefundMethod(
            type="bank_card",
            account_id="123456789"
        )
        
        # Настройка статей возврата
        articles = [
            RefundArticle(
                description="Возврат товара",
                quantity=1,
                amount=PaymentAmount(value=50.00, currency=Currency.RUB),
                vat_code=1
            )
        ]
        
        # Создание возврата
        from aioyookassa.types.params import CreateRefundParams
        
        params = CreateRefundParams(
            payment_id="payment_id",
            amount=PaymentAmount(value=50.00, currency=Currency.RUB),
            description="Возврат за некачественный товар",
            refund_method=refund_method,
            articles=articles
        )
        refund = await client.refunds.create_refund(params)
        
        return refund

🧾 Receipts API
---------------

Модуль для работы с фискальными чеками.

Основные методы
~~~~~~~~~~~~~~~

.. code-block:: python

    from aioyookassa.types.payment import PaymentItem
    from aioyookassa.types.enum import Currency, PaymentSubject, PaymentMode
    from aioyookassa.types.params import CreateReceiptParams
    
    # Создание чека
    params = CreateReceiptParams(
        payment_id="payment_id",
        items=[
            PaymentItem(
                description="Товар",
                quantity=1,
                amount=PaymentAmount(value=100.00, currency=Currency.RUB),
                vat_code=1,
                payment_subject=PaymentSubject.COMMODITY,
                payment_mode=PaymentMode.FULL_PAYMENT
            )
        ],
        tax_system_code=1
    )
    receipt = await client.receipts.create_receipt(params)

    # Получение информации о чеке
    receipt = await client.receipts.get_receipt("receipt_id")

    # Получение списка чеков
    receipts = await client.receipts.get_receipts(
        payment_id="payment_id",
        limit=10
    )

Примеры использования
~~~~~~~~~~~~~~~~~~~~~

Создание чека с полными данными
'''''''''''''''''''''''''''''''

.. code-block:: python

    from aioyookassa.types.payment import Settlement
    from aioyookassa.types.receipt_registration import (
        ReceiptRegistrationItem, Supplier
    )
    from aioyookassa.types.enum import Currency, PaymentSubject, PaymentMode

    async def create_detailed_receipt():
        # Настройка поставщика
        supplier = Supplier(
            name="ООО 'Пример'",
            inn="1234567890",
            phone="+79001234567"
        )
        
        # Настройка позиций чека
        items = [
            ReceiptRegistrationItem(
                description="Товар 1",
                quantity=2,
                amount=PaymentAmount(value=100.00, currency=Currency.RUB),
                vat_code=1,
                payment_subject=PaymentSubject.COMMODITY,
                payment_mode=PaymentMode.FULL_PAYMENT,
                supplier=supplier
            ),
            ReceiptRegistrationItem(
                description="Товар 2",
                quantity=1,
                amount=PaymentAmount(value=200.00, currency=Currency.RUB),
                vat_code=1,
                payment_subject=PaymentSubject.COMMODITY,
                payment_mode=PaymentMode.FULL_PAYMENT,
                supplier=supplier
            )
        ]
        
        # Настройка расчетов
        settlements = [
            Settlement(
                type="prepayment",
                amount=PaymentAmount(value=400.00, currency=Currency.RUB)
            )
        ]
        
        # Создание чека
        from aioyookassa.types.params import CreateReceiptParams
        
        params = CreateReceiptParams(
            payment_id="payment_id",
            items=items,
            tax_system_code=1,
            settlements=settlements
        )
        receipt = await client.receipts.create_receipt(params)
        
        return receipt

📄 Invoices API
---------------

Модуль для работы со счетами на оплату.

Основные методы
~~~~~~~~~~~~~~~

.. code-block:: python

    from aioyookassa.types.enum import Currency
    from aioyookassa.types.params import CreateInvoiceParams
    
    # Создание счета
    params = CreateInvoiceParams(
        amount=PaymentAmount(value=1000.00, currency=Currency.RUB),
        description="Счет на оплату"
    )
    invoice = await client.invoices.create_invoice(params)

    # Получение информации о счете
    invoice = await client.invoices.get_invoice("invoice_id")

    # Получение списка счетов
    invoices = await client.invoices.get_invoices(limit=10)

Примеры использования
~~~~~~~~~~~~~~~~~~~~~

Создание счета с деталями
'''''''''''''''''''''''''

.. code-block:: python

    from aioyookassa.types.invoice import (
        InvoicePaymentData, InvoiceReceipt, InvoiceCartItem
    )
    from aioyookassa.types.payment import PaymentItem
    from aioyookassa.types.enum import Currency, PaymentSubject, PaymentMode

    async def create_detailed_invoice():
        # Настройка корзины
        cart_items = [
            InvoiceCartItem(
                description="Услуга 1",
                quantity=1,
                amount=PaymentAmount(value=500.00, currency=Currency.RUB),
                vat_code=1
            ),
            InvoiceCartItem(
                description="Услуга 2",
                quantity=2,
                amount=PaymentAmount(value=250.00, currency=Currency.RUB),
                vat_code=1
            )
        ]
        
        # Настройка чека
        receipt = InvoiceReceipt(
            items=[
                PaymentItem(
                    description="Услуга 1",
                    quantity=1,
                    amount=PaymentAmount(value=500.00, currency=Currency.RUB),
                    vat_code=1,
                    payment_subject=PaymentSubject.SERVICE,
                    payment_mode=PaymentMode.FULL_PAYMENT
                ),
                PaymentItem(
                    description="Услуга 2",
                    quantity=2,
                    amount=PaymentAmount(value=250.00, currency=Currency.RUB),
                    vat_code=1,
                    payment_subject=PaymentSubject.SERVICE,
                    payment_mode=PaymentMode.FULL_PAYMENT
                )
            ],
            tax_system_code=1
        )
        
        # Настройка данных платежа
        payment_data = InvoicePaymentData(
            type="bank_card",
            account_id="123456789"
        )
        
        # Создание счета
        from aioyookassa.types.params import CreateInvoiceParams
        
        params = CreateInvoiceParams(
            amount=PaymentAmount(value=1000.00, currency=Currency.RUB),
            description="Счет на оплату услуг",
            cart=cart_items,
            receipt=receipt,
            payment_method=payment_data
        )
        invoice = await client.invoices.create_invoice(params)
        
        return invoice

💳 Payment Methods API
---------------------

Модуль для управления способами оплаты.

Основные методы
~~~~~~~~~~~~~~~

.. code-block:: python

    # Получение списка способов оплаты
    methods = await client.payment_methods.get_payment_methods()

    # Получение конкретного способа оплаты
    method = await client.payment_methods.get_payment_method("method_id")

Примеры использования
~~~~~~~~~~~~~~~~~~~~~

Работа со способами оплаты
'''''''''''''''''''''''''''

.. code-block:: python

    async def work_with_payment_methods():
        # Получение всех доступных способов оплаты
        methods = await client.payment_methods.get_payment_methods()
        
        print("Доступные способы оплаты:")
        for method in methods.items:
            print(f"- {method.type}: {method.description}")
        
        # Получение информации о конкретном способе
        if methods.items:
            method_id = methods.items[0].id
            method = await client.payment_methods.get_payment_method(method_id)
            print(f"Детали способа оплаты: {method.type}")

Комбинированное использование
-----------------------------

Пример комплексной обработки платежа
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from aioyookassa.types.payment import PaymentItem
    from aioyookassa.types.enum import (
        ConfirmationType, Currency, PaymentSubject, PaymentMode
    )
    
    async def process_complete_payment():
        """Полный цикл обработки платежа с чеком и возвратом."""
        
        try:
            # 1. Создание платежа
            from aioyookassa.types.params import CreatePaymentParams
            
            params = CreatePaymentParams(
                amount=PaymentAmount(value=1000.00, currency=Currency.RUB),
                description="Комплексный платеж",
                confirmation=Confirmation(type=ConfirmationType.REDIRECT, return_url="https://example.com")
            )
            payment = await client.payments.create_payment(params)
            
            print(f"✅ Платеж создан: {payment.id}")
            
            # 2. Ожидание оплаты (в реальном приложении через webhook)
            await asyncio.sleep(2)
            
            # 3. Проверка статуса
            payment_info = await client.payments.get_payment(payment.id)
            
            if payment_info.status == PaymentStatus.SUCCEEDED:
                # 4. Создание чека
                from aioyookassa.types.params import CreateReceiptParams
                
                params = CreateReceiptParams(
                    payment_id=payment.id,
                    items=[
                        PaymentItem(
                            description="Товар",
                            quantity=1,
                            amount=PaymentAmount(value=1000.00, currency=Currency.RUB),
                            vat_code=1,
                            payment_subject=PaymentSubject.COMMODITY,
                            payment_mode=PaymentMode.FULL_PAYMENT
                        )
                    ],
                    tax_system_code=1
                )
                receipt = await client.receipts.create_receipt(params)
                
                print(f"✅ Чек создан: {receipt.id}")
                
                # 5. Создание возврата (если нужно)
                if should_refund:
                    from aioyookassa.types.params import CreateRefundParams
                    
                    params = CreateRefundParams(
                        payment_id=payment.id,
                        amount=PaymentAmount(value=500.00, currency=Currency.RUB),
                        description="Частичный возврат"
                    )
                    refund = await client.refunds.create_refund(params)
                    
                    print(f"✅ Возврат создан: {refund.id}")
            
        except Exception as e:
            print(f"❌ Ошибка: {e}")
            raise