Metadata-Version: 2.4
Name: tochka_py
Version: 0.0.3
Summary: Tochka API wrapper for Python built on top of httpx and pydantic
Author-email: "Fiodar Y." <hi@fiodar.dev>
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.20.1
Requires-Dist: pydantic>=2.0
Requires-Dist: pyjwt[crypto]>=2.0.1
Description-Content-Type: text/markdown

# tochka_py
[Tochka API docs](https://developers.tochka.com/docs/tochka-api/) - [Sandbox docs](https://developers.tochka.com/docs/tochka-api/pesochnica)

Python-клиент для Tochka API на базе `httpx` и `pydantic`.

Сейчас библиотека покрывает:

- `tochka_py.invoice` - полный lifecycle работы со счетами:
  `create`, `get_file`, `send_to_email`, `get_payment_status`, `delete`
- `tochka_py.webhook` - управление webhook-подписками и верификация входящих webhook JWT:
  `create`, `edit`, `get`, `send_test`, `delete`, `WebhookVerifier`

Поддерживаются синхронные и асинхронные вызовы, единый transport и типизированные модели запросов и ответов.

Также доступен CLI `tochka-py` для управления webhook-подписками.

## Установка

```bash
pip install tochka_py
```

Требуется Python `>=3.10`.

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

```python
from tochka_py import TochkaClient
from tochka_py.invoice.types import (
    ContentInvoice,
    CounterpartType,
    InvoiceCreateRequest,
    InvoiceCreateRequestData,
    InvoiceModel,
    NdsKind,
    PositionModel,
    SecondSideModel,
    UnitCode,
)

request = InvoiceCreateRequestData(
    data=InvoiceCreateRequest(
        account_id="12345123451234512345/044525104",
        customer_code="1234567ab",
        second_side=SecondSideModel(
            tax_code="7707083893",
            type=CounterpartType.COMPANY,
            second_side_name='ООО "Покупатель"',
        ),
        content=ContentInvoice(
            invoice=InvoiceModel(
                number="42",
                total_amount=1000.0,
                positions=[
                    PositionModel(
                        position_name="Консультационные услуги",
                        unit_code=UnitCode.PIECE,
                        nds_kind=NdsKind.WITHOUT_NDS,
                        price=1000.0,
                        quantity=1,
                        total_amount=1000.0,
                    )
                ],
            )
        ),
    )
)

with TochkaClient(token="your_token") as client:
    response = client.invoice.create_sync(request)

print(response.data.document_id)
```

Получение PDF, статуса оплаты, отправка на email и удаление:

```python
from tochka_py.invoice.types import SendDocumentToEmailRequest

document_id = response.data.document_id
customer_code = request.customer_code

with TochkaClient(token="your_token") as client:
    payment_status = client.invoice.get_payment_status_sync(customer_code, document_id)
    pdf_file = client.invoice.get_file_sync(customer_code, document_id)
    email_result = client.invoice.send_to_email_sync(
        customer_code,
        document_id,
        SendDocumentToEmailRequest(email="test@example.com"),
    )
    delete_result = client.invoice.delete_sync(customer_code, document_id)

print(payment_status.data.payment_status)
print(pdf_file.filename, pdf_file.content_type, len(pdf_file.content))
print(email_result.data.result, delete_result.data.result)
```

### Webhooks

Управление webhook-подпиской:

```python
from tochka_py import TochkaClient
from tochka_py.webhook.types import WebhookSubscription, WebhookType

with TochkaClient(token="your_token") as client:
    response = client.webhooks.create_sync(
        client_id="your_app_client_id",
        request=WebhookSubscription(
            webhooks_list=[
                WebhookType.INCOMING_PAYMENT,
                WebhookType.OUTGOING_PAYMENT,
            ],
            url="https://app.example.com/tochka/webhook",
        ),
    )

print(response.data.webhooks_list, response.data.url)
```

Верификация и парсинг входящего webhook JWT:

```python
from tochka_py.webhook.verifier import WebhookVerifier

raw_webhook_jwt = request_body.decode()

with WebhookVerifier() as verifier:
    payload = verifier.decode_sync(raw_webhook_jwt)

print(payload.webhook_type, payload.customer_code)
```

### CLI

Повесить webhook одной командой:

```bash
export TOCHKA_API_TOKEN=your_token
tochka-py webhook set \
  --client-id your_app_client_id \
  --url https://app.example.com/tochka/webhook \
  --event incomingPayment \
  --event outgoingPayment
```

Посмотреть текущую подписку:

```bash
tochka-py webhook get --client-id your_app_client_id
```

Отправить тестовый webhook:

```bash
tochka-py webhook test --client-id your_app_client_id --event incomingPayment
```

Удалить подписку:

```bash
tochka-py webhook delete --client-id your_app_client_id
```

CLI использует:

- `TOCHKA_API_TOKEN` для токена
- `TOCHKA_BASE_URL` для переопределения base URL

Для sandbox можно использовать:

- base URL: `https://enter.tochka.com/sandbox/v2`
- токен: `sandbox.jwt.token`

## Структура API

```python
from tochka_py import TochkaClient
```

`TochkaClient`:

- `invoice.create_sync(...)`
- `invoice.create(...)`
- `invoice.get_file_sync(...)`
- `invoice.get_file(...)`
- `invoice.send_to_email_sync(...)`
- `invoice.send_to_email(...)`
- `invoice.get_payment_status_sync(...)`
- `invoice.get_payment_status(...)`
- `invoice.delete_sync(...)`
- `invoice.delete(...)`
- `webhooks.create_sync(...)`
- `webhooks.create(...)`
- `webhooks.edit_sync(...)`
- `webhooks.edit(...)`
- `webhooks.get_sync(...)`
- `webhooks.get(...)`
- `webhooks.send_test_sync(...)`
- `webhooks.send_test(...)`
- `webhooks.delete_sync(...)`
- `webhooks.delete(...)`
- `webhooks.set_sync(...)`
- `webhooks.set(...)`

## Обработка ошибок

Библиотека поднимает исключения из `tochka_py.core.errors`, например:

- `AuthenticationError`
- `RequestValidationError`
- `NotFoundError`
- `ServerError`

У исключений доступны поля `product`, `http_status`, `code`, `request_id` и `raw`.

## Интеграционные тесты для sandbox

По умолчанию интеграционные тесты отключены.

Запуск unit-тестов:

```bash
uv run pytest tests
```

Запуск integration:

```bash
uv run pytest tests -m integration
```
