fix: handle sandbox errors in examples and fix response None checks

  - Fix  to  in customs
    client and SOAP transport (requests.Response.__bool__ is False for
    non-2xx status codes)
  - Extract API error messages from 400 response bodies in invoice client
  - Add _safe_int/_safe_float helpers for ListInvoices Georgian text fields
  - Add sandbox error handling to all examples (SOAP 500, auth, customs 404)
  - Use sandbox credentials in examples (satesto2/tbilisi)
  - Add create_declaration.py example

Author: Kuduxaaa

examples/basic_invoice.py

@@ -16,7 +16,7 @@
 def main():
     with InvoiceClient() as client:
         # Step 1: Authenticate (handles both 1FA and 2FA)
-        auth = client.authenticate('your_username', 'your_password')
+        auth = client.authenticate('satesto2', '123456')
 
         if auth.needs_pin:
             pin = input(f'Enter PIN sent to {auth.masked_mobile}: ')
@@ -25,14 +25,19 @@ def main():
         print(f'Authenticated (token: {auth.access_token[:20]}...)')
 
         # Step 2: Create an invoice
+        # Note: sandbox only allows test TINs 206322102 and 12345678910
         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_category        = InvoiceCategory.GOODS_SERVICE,
+            inv_type            = InvoiceType.WITH_TRANSPORT,
+            operation_date      = '10-02-2025 10:00:00',
+            tin_seller          = '12345678910',
+            tin_buyer           = '206322102',
             trans_start_address = 'თბილისი, რუსთაველის გამზ. 12',
             trans_end_address   = 'რუსთავი, მშვიდობის ქ. 5',
+            trans_type          = 1,
+            trans_car_no        = 'AB-123-CD',
+            trans_driver_tin    = '206322102',
+            trans_cost_payer    = 2,
         )
 
         # Step 3: Add goods (amount auto-calculated)

examples/basic_waybill.py

@@ -2,6 +2,8 @@
 
 Demonstrates the full lifecycle of an electronic commodity waybill
 using the RS.ge WayBill SOAP service.
+
+Note: Some SOAP endpoints return 500 on the sandbox intermittently.
 """
 
 from rsge import (
@@ -10,12 +12,17 @@
     WayBillClient,
     WayBillType,
 )
+from rsge.core.exceptions import RSGeAuthenticationError, RSGeConnectionError
 
 
 def main():
     with WayBillClient('tbilisi', '123456') as client:
-        un_id, user_id = client.check_service_user()
-        print(f'Authenticated — TIN: {un_id}, User ID: {user_id}')
+        # check_service_user() may return false on sandbox test accounts
+        try:
+            un_id, user_id = client.check_service_user()
+            print(f'Authenticated — TIN: {un_id}, User ID: {user_id}')
+        except RSGeAuthenticationError:
+            print('Note: check_service_user() not available for this sandbox account')
 
         wb = client.create_waybill(
             waybill_type         = WayBillType.TRANSPORTATION,
@@ -50,17 +57,20 @@ def main():
 
         print(f'Goods: {len(wb.goods_list)} items, total: {wb.full_amount} GEL')
 
-        result = client.save_waybill(wb)
-        if result.is_success:
-            print(f'Saved — Waybill ID: {result.waybill_id}')
+        try:
+            result = client.save_waybill(wb)
+            if result.is_success:
+                print(f'Saved — Waybill ID: {result.waybill_id}')
 
-            wb_number = client.activate_waybill(result.waybill_id)
-            print(f'Activated — Number: {wb_number}')
+                wb_number = client.activate_waybill(result.waybill_id)
+                print(f'Activated — Number: {wb_number}')
 
-            client.close_waybill(result.waybill_id)
-            print('Closed — Delivery complete')
-        else:
-            print(f'Save failed: code {result.status}')
+                client.close_waybill(result.waybill_id)
+                print('Closed — Delivery complete')
+            else:
+                print(f'Save failed: code {result.status}')
+        except (RSGeAuthenticationError, RSGeConnectionError) as exc:
+            print(f'Note: Sandbox limitation: {exc}')
 
 
 if __name__ == '__main__':

examples/buyer_confirmation.py

@@ -2,19 +2,26 @@
 
 Demonstrates querying unconfirmed waybills as a buyer
 and confirming or rejecting them.
+
+Note: Some SOAP endpoints return 500 on the sandbox intermittently.
 """
 
 from rsge import WayBillClient
+from rsge.core.exceptions import RSGeConnectionError
 
 
 def main():
     with WayBillClient('satesto2', '123456') as buyer:
-        waybills = buyer.get_buyer_waybills_ex(
-            statuses      = ',2,',
-            is_confirmed  = 0,
-            create_date_s = '2024-01-01',
-            create_date_e = '2024-12-31',
-        )
+        try:
+            waybills = buyer.get_buyer_waybills_ex(
+                statuses      = ',2,',
+                is_confirmed  = 0,
+                create_date_s = '2024-01-01',
+                create_date_e = '2024-12-31',
+            )
+        except RSGeConnectionError as exc:
+            print(f'Note: SOAP service error (sandbox may be unstable): {exc}')
+            return
 
         print(f'Pending confirmation: {len(waybills)}')
 

examples/create_declaration.py

@@ -0,0 +1,55 @@
+"""Monthly declaration for მცირე მეწარმე (small business, 1% tax).
+
+Demonstrates listing invoices eligible for declaration binding,
+checking the sequence number, and creating a monthly declaration.
+
+Note: create_decl() may fail on sandbox because test invoices
+don't meet the attachment conditions required for declarations.
+"""
+
+from rsge import InvoiceClient, InvoiceListType
+from rsge.core.exceptions import RSGeAPIError
+
+
+def main():
+    with InvoiceClient() as client:
+        auth = client.authenticate('satesto2', '123456')
+
+        if auth.needs_pin:
+            pin = input(f'Enter PIN sent to {auth.masked_mobile}: ')
+            auth = client.authenticate_pin(auth.pin_token, pin)
+
+        print(f'Authenticated (token: {auth.access_token[:20]}...)')
+
+        year, month = 2025, 2
+
+        # Step 1: List seller invoices eligible for declaration
+        invoices = client.list_invoices(TYPE=InvoiceListType.SELLER_DECL)
+
+        print(f'\nInvoices eligible for declaration: {len(invoices)}')
+        for inv in invoices:
+            print(f'  #{inv.id} | {inv.inv_number} | {inv.amount_full} GEL')
+
+        if not invoices:
+            print('No invoices to attach — nothing to declare')
+            client.sign_out()
+            return
+
+        # Step 2: Check sequence number
+        seq = client.get_seq_num(year, month)
+        print(f'\nSequence number ({year}/{month:02d}): {seq}')
+
+        # Step 3: Create monthly declaration with all eligible invoices
+        invoice_ids = [inv.id for inv in invoices]
+        try:
+            client.create_decl(invoice_ids, year=year, month=month)
+            print(f'Declaration created — {len(invoice_ids)} invoice(s) attached to {year}/{month:02d}')
+        except RSGeAPIError as exc:
+            print(f'Note: create_decl() not available on sandbox: {exc}')
+
+        client.sign_out()
+        print('Signed out')
+
+
+if __name__ == '__main__':
+    main()

examples/customs_declarations.py

@@ -2,14 +2,22 @@
 
 Demonstrates authenticating with the customs API,
 fetching declarations by date range, and signing out.
+
+Note: The customs API may not be available on the sandbox environment.
 """
 
 from rsge import CustomsClient
+from rsge.core.exceptions import RSGeAPIError
 
 
 def main():
     with CustomsClient() as client:
-        auth = client.authenticate('your_username', 'your_password')
+        try:
+            auth = client.authenticate('satesto2', '123456')
+        except RSGeAPIError as exc:
+            print(f'Note: Customs API auth not available on sandbox: {exc}')
+            return
+
         print(f'Authenticated (token: {auth.access_token[:20]}...)')
 
         declarations = client.get_declarations(

examples/invoice_management.py

@@ -9,7 +9,7 @@
 
 def main():
     with InvoiceClient() as client:
-        client.authenticate('your_username', 'your_password')
+        client.authenticate('satesto2', '123456')
 
         # List seller's own documents
         seller_docs = client.list_invoices(

examples/query_waybills.py

@@ -2,27 +2,38 @@
 
 Demonstrates listing waybills with filters and retrieving
 full waybill details by ID.
+
+Note: Some SOAP endpoints return 500 on the sandbox intermittently.
 """
 
 from rsge import WayBillClient, WayBillType
+from rsge.core.exceptions import RSGeConnectionError
 
 
 def main():
     with WayBillClient('tbilisi', '123456') as client:
-        waybills = client.get_waybills(
-            statuses      = ',1,',
-            create_date_s = '2024-01-01',
-            create_date_e = '2024-01-31',
-        )
+        try:
+            waybills = client.get_waybills(
+                statuses      = ',1,',
+                create_date_s = '2024-01-01',
+                create_date_e = '2024-01-31',
+            )
+        except RSGeConnectionError as exc:
+            print(f'Note: SOAP service error (sandbox may be unstable): {exc}')
+            return
 
         print(f'Seller waybills: {len(waybills)}')
         for wb in waybills[:5]:
             print(f'  #{wb.id} | {wb.waybill_number} | {wb.buyer_name} | {wb.full_amount} GEL')
 
-        buyer_wbs = client.get_buyer_waybills(
-            create_date_s = '2024-01-01',
-            create_date_e = '2024-01-31',
-        )
+        try:
+            buyer_wbs = client.get_buyer_waybills(
+                create_date_s = '2024-01-01',
+                create_date_e = '2024-01-31',
+            )
+        except RSGeConnectionError as exc:
+            print(f'Note: SOAP service error (sandbox may be unstable): {exc}')
+            return
 
         print(f'Buyer waybills: {len(buyer_wbs)}')
 

examples/templates.py

@@ -2,9 +2,12 @@
 
 Demonstrates creating a waybill template, listing templates,
 loading a template, and creating a waybill from it.
+
+Note: Some SOAP endpoints return 500 on the sandbox intermittently.
 """
 
 from rsge import WayBillClient, WayBillType
+from rsge.core.exceptions import RSGeConnectionError
 
 
 def main():
@@ -25,18 +28,21 @@ def main():
             bar_code = 'STD01',
         )
 
-        client.save_waybill_template('ბათუმის მარშრუტი', wb)
-        print('Template saved')
-
-        templates = client.get_waybill_templates()
-        for t in templates:
-            print(f"  Template #{t['id']}: {t['name']}")
-
-        if templates:
-            loaded = client.get_waybill_template(templates[0]['id'])
-            loaded.buyer_name = 'შპს ახალი მყიდველი'
-            result = client.save_waybill(loaded)
-            print(f'Waybill from template: {result.waybill_id}')
+        try:
+            client.save_waybill_template('ბათუმის მარშრუტი', wb)
+            print('Template saved')
+
+            templates = client.get_waybill_templates()
+            for t in templates:
+                print(f"  Template #{t['id']}: {t['name']}")
+
+            if templates:
+                loaded = client.get_waybill_template(templates[0]['id'])
+                loaded.buyer_name = 'შპს ახალი მყიდველი'
+                result = client.save_waybill(loaded)
+                print(f'Waybill from template: {result.waybill_id}')
+        except RSGeConnectionError as exc:
+            print(f'Note: SOAP service error (sandbox may be unstable): {exc}')
 
 
 if __name__ == '__main__':

rsge/core/transport.py

@@ -89,8 +89,9 @@ def call(
                 f'Request to RS.ge timed out after {self._timeout}s'
             ) from exc
         except requests.exceptions.HTTPError as exc:
+            status_code = exc.response.status_code if exc.response is not None else 0
             raise RSGeConnectionError(
-                f'HTTP error from RS.ge: {exc.response.status_code}'
+                f'HTTP error from RS.ge: {status_code}'
             ) from exc
 
         return self._parse_response(response.text, method)

rsge/customs/client.py

@@ -181,7 +181,8 @@ def get_declarations(
             raise RSGeConnectionError(f'Connection failed: {exc}') from exc
 
         except requests.exceptions.HTTPError as exc:
-            raise RSGeAPIError(f'HTTP error: {exc.response.status_code}') from exc
+            status_code = exc.response.status_code if exc.response is not None else 0
+            raise RSGeAPIError(f'HTTP error: {status_code}') from exc
 
         data = response.json()
         status = data.get('STATUS', {})
@@ -220,7 +221,7 @@ def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
             raise RSGeConnectionError(f'Connection failed: {exc}') from exc
 
         except requests.exceptions.HTTPError as exc:
-            status_code = exc.response.status_code if exc.response else 0
+            status_code = exc.response.status_code if exc.response is not None else 0
             raise RSGeAPIError(f'HTTP error: {status_code}') from exc
 
         result: dict[str, Any] = response.json()