Metadata-Version: 2.4
Name: ofdclient
Version: 0.1.0
Summary: Python client for the Kazakhstan fiscal data operator middleware (Программный Фискализатор / FiscalizationService, SOAP + ЭЦП)
Project-URL: Homepage, https://github.com/DamirBakty/ofdclient
Project-URL: Repository, https://github.com/DamirBakty/ofdclient
Project-URL: Issues, https://github.com/DamirBakty/ofdclient/issues
Project-URL: Changelog, https://github.com/DamirBakty/ofdclient/blob/main/CHANGELOG.md
Author-email: Damir Baktygaliyev <damir050602@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Damir Baktygaliyev
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cash-register,fiscal,fiscalization,kazakhstan,kkm,ncanode,ofd,ккм,офд
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests>=2.31
Requires-Dist: xmltodict>=0.13
Requires-Dist: zeep>=4.2
Description-Content-Type: text/markdown

# ofdclient

[![CI](https://github.com/DamirBakty/ofdclient/actions/workflows/ci.yml/badge.svg)](https://github.com/DamirBakty/ofdclient/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/ofdclient)](https://pypi.org/project/ofdclient/)
[![Python](https://img.shields.io/pypi/pyversions/ofdclient)](https://pypi.org/project/ofdclient/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Python client for the Kazakhstan fiscal data operator (OFD) middleware —
«Программный Фискализатор» / FiscalizationService 3.0.1 (SOAP + XML digital
signature with NCA RK certificates).

**Русская версия документации: [README.ru.md](README.ru.md)** — она основная и
самая полная.

## Features

- Full API coverage: sales, refunds, expenses, service cash in/out, KKM state,
  shift closing with Z-report, X-report, Z-report copies, document copies.
- Framework-agnostic: no Django/Celery inside, plain typed dataclasses.
- Pluggable XML signers: [NCANode](https://ncanode.kz), any compatible REST
  signing service, or your own implementation.
- ~150 documented OFD error codes mapped to a typed exception hierarchy.
- Idempotency via `ClientSystemGUID`, optional auto-recovery from the
  "shift auto-closed" error (code 220).
- Fully typed (PEP 561), tested without a real OFD connection.

## Installation

```bash
pip install ofdclient
```

## Quickstart

```python
from decimal import Decimal

from ofdclient import (
    Customer, Item, NCANodeSigner, OFDClient, Payment, Receipt, Tax,
)

signer = NCANodeSigner(
    "http://localhost:14579",
    key="<base64-encoded p12>",
    password="password",
)

client = OFDClient(
    wsdl_url="https://fiscal.example.kz/FiscalizationService?wsdl",
    kkm_code="123456",
    cashier="cashier-1",
    signer=signer,
    auto_close_shift=True,
)

receipt = Receipt(
    items=[
        Item(name="Coffee", price=Decimal("1500"), quantity=2, taxes=[Tax.vat(16)]),
    ],
    payments=[Payment.card(Decimal("3000"))],
    customer=Customer(email="buyer@example.kz"),
)

bill = client.sell(receipt)
print(bill.fiscal_sign)      # FiscalisationSystemGUID
print(bill.bill_content)     # printable receipt text
print(bill.qr_code)          # QR code bytes for verification
```

Refunds reference the original receipt:

```python
from ofdclient import OriginalDocument

original = OriginalDocument(
    fiscal_sign=bill.fiscal_sign,
    date_time=bill.registration_datetime,
    amount=bill.amount,
    kkm_code="123456",
)
client.refund(refund_receipt, original)
```

Shift lifecycle and reports:

```python
client.state()           # KKM status
client.x_report()        # intermediate report
client.close_shift()     # close session, returns Z-report
client.z_report_copy(7)  # Z-report copy for session #7
```

See [examples/](examples/) for a complete script and a Django + Celery
integration example, and [docs/errors.md](docs/errors.md) for the error-code
reference.

## License

[MIT](LICENSE)
