cashio-client

Python client for the Cashio Client API (transactions and purchase payments).

Install in other projects with pip install cashio-client (after publishing) or from a local path / git URL.

کلاینت پایتون برای API کلاینت Cashio (تراکنش‌ها و پرداخت‌های خرید). قابل استفاده در پروژه‌های دیگر و قابل انتشار روی PyPI.

Install

pip install cashio-client

From this repo (editable):

pip install -e .

Quick start

from cashio_client import CashioClient

client = CashioClient("http://127.0.0.1:8000", token="YOUR_TOKEN")

result = client.transactions.create(
    amount=1500000,
    type="income",
    description="from rahkarmelk",
    date="1405-06-22",
)
print(result.ok, result.id)

Token comes from Cashio Settings → Client API Config. There is no session login.

If that config has a default fund (and category), you can omit fund / category.

Authentication

The token is sent with one method (default: Bearer header):

from cashio_client import AuthMethod, CashioClient, CashioSettings

settings = CashioSettings(
    "http://127.0.0.1:8000",
    token="YOUR_TOKEN",
    auth_method=AuthMethod.X_API_TOKEN,
)
client = CashioClient(settings)

base_url is the Cashio host (http://127.0.0.1:8000). A trailing /a/api is stripped if present. Requests go to {base_url}/a/api/....

Create a transaction

POST /a/api/transaction/create

result = client.transactions.create(
    amount=250000,
    transaction_type="expense",
    fund=15,
    category=3,
    description="rent",
    payment_type="full_payment",
)

Aliases from the API are accepted: type for transaction_type, fund_id for fund, category_id for category, holder_id for holder.

With files (multipart)

result = client.transactions.create(
    amount=1500000,
    type="income",
    attached_file=["/path/to/receipt.pdf", "/path/to/photo.jpg"],
)

attached_file may be a path, a file object, a (filename, fileobj) tuple, or a list of those.

Fields

Constants: TransactionType.INCOME, TransactionType.EXPENSE, PaymentType.FULL_PAYMENT, …

Purchase payments

Two kinds: direct (already paid, invoice documents required, created as completed) and indirect (accountant pays later, documents optional, created as unseen).

from cashio_client import PurchaseKind, PurchasePaymentStatus

# direct: documents required
result = client.purchases.create_direct(
    amount=1500000,
    documents=["/path/to/invoice.jpg"],
    description="stationery",
    payment_date="1405-06-22",   # optional Jalali date, defaults to today
    request_id="INV-1",          # optional, unique per client
    lines=[
        {"description": "A4 paper", "quantity": 2, "unit": "box", "unit_price": 750000},
        {"description": "pen", "quantity": 10},
    ],
)
print(result.id, result.status)  # 11 completed

# indirect: documents optional
result = client.purchases.create_indirect(amount=300000, description="taxi", request_id="INV-2")

# read
payment = client.purchases.get(result.id)               # by id
payment = client.purchases.get(request_id="INV-2")      # by your own reference
payments = client.purchases.list(status=PurchasePaymentStatus.IN_REVIEW, kind=PurchaseKind.INDIRECT)
payment.status, payment.amount, payment.lines, payment.documents, payment.transaction_id

# lines, documents, history
client.purchases.lines(payment.id)
client.purchases.add_lines(payment.id, {"description": "stapler", "quantity": 1})        # one
client.purchases.add_lines(payment.id, [{"description": "a", "quantity": 1}, ...])      # many
client.purchases.documents(payment.id)
client.purchases.add_documents(payment.id, ["/path/to/receipt.pdf"])
client.purchases.statuses(payment.id)

• Statuses: unseen, seen, in_review, completed (PurchasePaymentStatus).
• Line units: piece (default), kilogram, gram, liter, meter, box, pack, set, other (PurchaseLineUnit).
• Lines and documents of a completed payment cannot be changed (CashioAPIError).
• Money values are returned as Decimal; dates and timestamps stay strings as sent by the API.
• Files accept the same inputs as attached_file above.

Errors

from cashio_client import (
    CashioAuthError,
    CashioNotFoundError,
    CashioValidationError,
    CashioAPIError,
)

try:
    client.transactions.create(amount=10, type="income")
except CashioAuthError as exc:
    print(exc.status_code, exc.payload)   # 401
except CashioValidationError as exc:
    print(exc.errors)                     # {"fund": ["This field is required."]}
except CashioNotFoundError as exc:
    print(exc.status_code)                # 404 (e.g. unknown purchase payment); subclass of CashioAPIError
except CashioAPIError as exc:
    print(exc.status_code, exc.payload)   # 400 detail / 405 / other

Publish to PyPI

pip install -e ".[dev]"
python -m build
twine upload dist/*

Use TestPyPI first: twine upload --repository testpypi dist/*.

License

MIT