RS.ge Python SDK

Python SDK for the Georgian Revenue Service (სსიპ შემოსავლების სამსახური) electronic services.

• WayBill Service (ელექტრონული ზედნადები) — SOAP/XML API for electronic commodity waybills
• Customs Declarations (საბაჟო დეკლარაციები) — REST/JSON API for customs declaration data
• Invoice / Declaration (საგადასახადო დოკუმენტი) — REST/JSON API for tax invoices and declarations

Installation

pip install rsge-python

Or install from source:

git clone https://github.com/kuduxaaa/rsge-python.git
cd rsge-python
pip install -e .

For development (includes pytest, ruff, mypy):

pip install -e ".[dev]"

Requirements: Python 3.10+

Quick Start

WayBill Service

from rsge import WayBillClient, WayBillType, VATType

with WayBillClient('your_service_user', 'your_service_password') as client:
    # Verify credentials
    un_id, s_user_id = client.check_service_user()
    print(f'Taxpayer ID: {un_id}, User ID: {s_user_id}')

    # Create a waybill
    waybill = client.create_waybill(
        waybill_type  = WayBillType.TRANSPORTATION,
        buyer_tin     = '12345678901',
        start_address = 'Tbilisi, Rustaveli Ave 1',
        end_address   = 'Batumi, Chavchavadze St 5',
        driver_tin    = '01234567890',
        car_number    = 'AB-123-CD',
    )

    # Add goods
    waybill.add_goods(
        name     = 'Office Supplies',
        unit_id  = 1,
        quantity = 10,
        price    = 25.50,
        bar_code = '5901234123457',
        vat_type = VATType.REGULAR,
    )

    # Save, activate, close
    result = client.save_waybill(waybill)
    if result.is_success:
        wb_number = client.activate_waybill(result.waybill_id)
        print(f'Waybill number: {wb_number}')
        client.close_waybill(result.waybill_id)

Customs Declarations

from rsge import CustomsClient

with CustomsClient() as client:
    auth = client.authenticate('username', 'password')

    declarations = client.get_declarations(
        date_from = '2024-01-01',
        date_to   = '2024-01-31',
    )

    for decl in declarations:
        print(f'{decl.declaration_number}: {decl.description} = {decl.customs_value}')

Invoice / Declaration Service

from rsge import InvoiceClient, Invoice, InvoiceCategory, InvoiceType

with InvoiceClient() as client:
    # Authenticate (supports 2FA)
    auth = client.authenticate('your_username', 'your_password')

    if auth.needs_pin:
        pin = input('Enter PIN: ')
        auth = client.authenticate_pin(auth.pin_token, pin)

    # Create and save an invoice
    inv = Invoice(
        inv_category   = InvoiceCategory.GOODS_SERVICE,
        inv_type       = InvoiceType.WITH_TRANSPORT,
        operation_date = '10-04-2025 10:00:00',
        tin_seller     = '206322102',
        tin_buyer      = '12345678910',
    )

    inv.add_goods('Office Supplies', quantity=10, unit_price=25.50)
    inv.add_goods('Printer Paper',   quantity=5,  unit_price=15.00)

    txn_id = client.save_invoice(inv)
    result = client.get_transaction_result(txn_id)
    print(f'Saved invoice ID: {result.invoice_id}')

    # List, activate, and manage invoices
    invoices = client.list_invoices(TYPE=1, MAXIMUM_ROWS=20)
    client.activate_invoices([result.invoice_id])

    # Look up organization info
    org = client.get_org_info('206322102')
    print(f'{org.name} — VAT payer: {org.is_vat_payer}')

Documentation

API Overview

WayBillClient

CustomsClient

InvoiceClient

WayBill Types & Statuses

Error Handling

from rsge import RSGeError, RSGeAuthenticationError, RSGeAPIError, RSGeConnectionError

try:
    result = client.save_waybill(waybill)
except RSGeAuthenticationError:
    print('Invalid credentials')
except RSGeConnectionError:
    print('Cannot reach RS.ge servers')
except RSGeAPIError as exc:
    print(f'API error {exc.code}: {exc.message}')
except RSGeError as exc:
    print(f'SDK error: {exc.message}')

Project Structure

rsge/
├── __init__.py              # Public API exports
├── core/
│   ├── exceptions.py        # Exception hierarchy
│   ├── transport.py         # SOAP HTTP transport
│   └── xml_utils.py         # XML builder/parser helpers
├── waybill/
│   ├── client.py            # WayBillClient
│   ├── enums.py             # WayBillType, Status, etc.
│   └── models.py            # WayBill, GoodsItem, etc.
├── customs/
│   ├── client.py            # CustomsClient
│   └── models.py            # CustomsDeclaration, etc.
└── invoice/
    ├── client.py            # InvoiceClient (eAPI REST)
    ├── enums.py             # InvoiceCategory, InvoiceType, etc.
    └── models.py            # Invoice, InvoiceGoods, etc.

Contributing

git clone https://github.com/kuduxaaa/rsge-python.git
cd rsge-python
pip install -e ".[dev]"
pytest
ruff check .
mypy rsge

License

MIT