### Install Geliver Python SDK

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Install the Geliver Python SDK using pip. This is the first step to integrate with the Geliver API.

```bash
pip install geliver
```

--------------------------------

### Create Shipment and Accept Offer

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Create a shipment by providing the sender address ID and recipient address details. This example also shows how to download pre-generated labels if available immediately after creation.

```python
shipment = client.create_shipment({
    "senderAddressID": sender["id"],
    "recipientAddress": {
        "name": "John Doe", "email": "john@example.com", "phone": "+905051234568",
        "address1": "Atatürk Mahallesi", "countryCode": "TR", "cityName": "Istanbul", "cityCode": "34",
        "districtName": "Esenyurt", "zip": "34020",
    },
    "length": "10.0", "width": "10.0", "height": "10.0", "distanceUnit": "cm",
    "weight": "1.0", "massUnit": "kg",
    "order": {
        "orderNumber": "WEB-12345",
        # sourceIdentifier alanına mağazanızın tam adresini yazın (ör. https://magazam.com).
        "sourceIdentifier": "https://magazam.com",
        "totalAmount": "150",
        "totalAmountCurrency": "TRY",
    },
})

# Etiketler bazı akışlarda create sonrasında hazır olabilir; varsa hemen indirin
pre_label = getattr(shipment, 'labelURL', None)
if pre_label:
    # Avoid extra GET by using direct URL
    with open('label_pre.pdf', 'wb') as f:
        f.write(client.download_label_by_url(shipment.labelURL))
pre_html_url = getattr(shipment, 'responsiveLabelURL', None) or getattr(shipment, 'responsiveLabelUrl', None)
if pre_html_url:
    with open('label_pre.html', 'w', encoding='utf-8') as f:
        f.write(client.download_responsive_label_by_url(shipment.responsiveLabelURL))
```

--------------------------------

### Implement Webhook Listener with FastAPI

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Sets up a POST endpoint to receive and validate Geliver webhooks. Verification is currently disabled in this example.

```python
from fastapi import FastAPI, Request
from geliver import verify_webhook
from geliver.models import WebhookUpdateTrackingRequest

app = FastAPI()

@app.post("/webhooks/geliver")
async def handle_webhook(req: Request):
    body = await req.body()

    # Webhook doğrulama (şu an devre dışı, gelecekte aktif olacak)
    is_valid = verify_webhook(
        body,
        req.headers,
        enable_verification=False,
        secret="YOUR_WEBHOOK_SECRET"  # gelecekte kullanılacak
    )

    if not is_valid:
        return {"status": "invalid"}

    # Webhook verisini parse et
    event = WebhookUpdateTrackingRequest.model_validate_json(body.decode("utf-8"))

    if event.event == "TRACK_UPDATED":
        shipment = event.data
        print(f"Gönderi güncellendi: {shipment.id}")
        print(f"Takip numarası: {shipment.trackingNumber}")
        print(f"Takip URL: {shipment.trackingUrl}")

        ts = getattr(shipment, 'trackingStatus', None)
        if ts:
            print(f"Durum: {ts.trackingStatusCode}")
            print(f"Alt durum: {ts.trackingSubStatusCode}")

    return {"status": "ok"}

# Çalıştır: uvicorn webhook_server:app --host 0.0.0.0 --port 8000
```

--------------------------------

### Accept Offer and Get Shipment Details

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Accepts the cheapest offer for a shipment and prints the barcode, label URL, and tracking URL. Use webhooks for real-time tracking updates.

```python
offers = getattr(shipment, "offers", None)
if not offers or not offers.get("cheapest"):
    raise RuntimeError("Teklifler hazır değil; GET /shipments çağrısı ile tekrar kontrol edin.")

cheapest = offers["cheapest"]
tx = client.accept_offer(cheapest["id"])  # purchase label
print('Barcode:', getattr(tx.shipment, 'barcode', None))
print('Label URL:', getattr(tx.shipment, 'labelURL', None))
print('Tracking URL:', getattr(tx.shipment, 'trackingUrl', None))
```

--------------------------------

### Quick Start: Create Sender Address and Shipment

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Initialize the Geliver client with your API token and create a sender address. Then, create a test shipment with recipient details and order information. Use `create_shipment` for live environments.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

sender = client.create_sender_address({
    "name": "ACME Inc.", "email": "ops@acme.test", "phone": "+905051234567",
    "address1": "Hasan Mahallesi", "countryCode": "TR", "cityName": "Istanbul", "cityCode": "34",
    "districtName": "Esenyurt", "zip": "34020",
})

shipment = client.create_shipment_test({
    "senderAddressID": sender["id"],
    "recipientAddress": {"name": "John Doe", "email": "john@example.com", "phone": "+905051234568", "address1": "Atatürk Mahallesi", "countryCode": "TR", "cityName": "Istanbul", "cityCode": "34", "districtName": "Kadıköy", "zip": "34000"},
    # Request dimensions/weight must be strings
    "length": "10.0", "width": "10.0", "height": "10.0", "distanceUnit": "cm", "weight": "1.0", "massUnit": "kg",
    "order": {
        "orderNumber": "WEB-12345",
        # sourceIdentifier alanına mağazanızın tam adresini yazın (ör. https://magazam.com).
        "sourceIdentifier": "https://magazam.com",
        "totalAmount": "150",
        "totalAmountCurrency": "TRY",
    },
})
```

--------------------------------

### GET /cities and /districts

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Retrieves lists of cities and districts for address validation.

```APIDOC
## GET /cities

### Description
Lists all cities for a given country code.

### Query Parameters
- **countryCode** (string) - Required - The ISO country code (e.g., TR)

## GET /districts

### Description
Lists all districts for a specific city.

### Query Parameters
- **countryCode** (string) - Required - The ISO country code
- **cityCode** (string) - Required - The city code
```

--------------------------------

### GET /shipments

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Retrieves a list of shipments using an iterator for automatic pagination.

```APIDOC
## GET /shipments

### Description
Retrieves a list of shipments with automatic pagination support.

### Method
GET

### Endpoint
/shipments

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of shipments to return per page.
```

--------------------------------

### GET /shipments/{id}

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Retrieves details of a specific shipment by its ID.

```APIDOC
## GET /shipments/{id}

### Description
Fetches detailed information for a specific shipment using its unique identifier.

### Method
GET

### Endpoint
/shipments/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the shipment.
```

--------------------------------

### Initialize Price List Query

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Initializes the client for querying shipping prices.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))
```

--------------------------------

### Create and List Webhooks

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Demonstrates how to create a new webhook subscription and then list all existing webhooks for the account.

```python
client.create_webhook(url="https://yourapp.test/webhooks/geliver")
webhooks = client.list_webhooks()
```

--------------------------------

### Initialize Geliver Client

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Instantiate the GeliverClient with your API token. Options for base URL, timeout, retries, and user agent are available for advanced configuration.

```python
from geliver import GeliverClient, ClientOptions

# Temel başlatma
client = GeliverClient(ClientOptions(token="YOUR_API_TOKEN"))

# Tüm seçeneklerle başlatma
client = GeliverClient(ClientOptions(
    token="YOUR_API_TOKEN",
    base_url="https://api.geliver.io/api/v1",  # varsayılan
    timeout=30.0,       # saniye cinsinden istek zaman aşımı
    max_retries=2,      # başarısız istekler için yeniden deneme sayısı
    user_agent="MyApp/1.0"  # özel user-agent
))
```

--------------------------------

### Retrieve Price List

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Fetches shipping price estimates based on package dimensions and weight.

```python
prices = client.list_prices(
    paramType="STANDARD",
    length="30",
    width="20",
    height="15",
    weight="2.5",
    distanceUnit="cm",
    massUnit="kg"
)

print(f"Fiyat sonuçları: {prices}")
```

--------------------------------

### Manage Provider Accounts

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Create, list, and delete provider accounts via the client.

```python
# Create provider account
acc = client.create_provider_account({
    'username': 'user', 'password': 'pass', 'name': 'My Account', 'providerCode': 'SURAT',
    'version': 1, 'isActive': True, 'isPublic': False, 'sharable': False, 'isDynamicPrice': False,
})
# List accounts
accounts = client.list_provider_accounts()
# Delete account
client.delete_provider_account(acc['id'], is_delete_account_connection=True)
```

--------------------------------

### Create Test Shipment

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Use the `create_shipment_test` method to create shipments in the test environment. Test shipments do not incur actual shipping charges.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Test gönderisi oluştur
test_shipment = client.create_shipment_test({
    "senderAddressID": "addr_sender123",
    "recipientAddress": {
        "name": "Test Alıcı",
        "phone": "+905001234567",
        "address1": "Test Mahallesi",
        "countryCode": "TR",
        "cityName": "Istanbul",
        "cityCode": "34",
        "districtName": "Beşiktaş"
    },
    "length": "10.0",
    "width": "10.0",
    "height": "10.0",
    "distanceUnit": "cm",
    "weight": "1.0",
    "massUnit": "kg"
})

print(f"Test Gönderi ID: {test_shipment.id}")
print(f"Test modu: {getattr(test_shipment, 'test', False)}")
# Çıktı: Test Gönderi ID: shp_test_xyz
# Çıktı: Test modu: True
```

--------------------------------

### Create Return Shipment

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Initiate a return process for an existing shipment.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# İade gönderisi oluştur
return_shipment = client.create_return_shipment("shp_original123", {
    "willAccept": True,  # True: otomatik teklif kabul, False: manuel kabul
    "providerServiceCode": "SURAT_STANDART",  # opsiyonel, varsayılan orijinal sağlayıcı
    "count": 1
})

print(f"İade gönderi ID: {return_shipment.id}")
print(f"İade durumu: {return_shipment.isReturn}")
print(f"Etiket URL: {getattr(return_shipment, 'labelURL', None)}")
```

--------------------------------

### Create Shipment and Label in One Step

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Performs shipment creation and label purchase in a single API call, enabling the fastest shipping integration flow. Use the 'test' parameter for sandbox testing.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Tek adımda gönderi + etiket
transaction = client.create_transaction({
    "senderAddressID": "addr_sender123",
    "recipientAddress": {
        "name": "Fatma Öztürk",
        "phone": "+905551234567",
        "address1": "Nilüfer Mahallesi",
        "countryCode": "TR",
        "cityName": "Bursa",
        "cityCode": "16",
        "districtName": "Nilüfer"
    },
    "length": "25.0",
    "width": "20.0",
    "height": "15.0",
    "distanceUnit": "cm",
    "weight": "2.0",
    "massUnit": "kg",
    "test": True,  # Test modu
    "order": {
        "orderNumber": "HIZLI-001",
        "totalAmount": "199.90",
        "totalAmountCurrency": "TRY"
    }
})

print(f"İşlem ID: {transaction.id}")
print(f"Gönderi ID: {transaction.shipment.id if transaction.shipment else None}")
print(f"Barkod: {getattr(transaction.shipment, 'barcode', None)}")
```

--------------------------------

### Manage Webhooks

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Create, list, test, and delete webhooks to receive real-time shipment status updates.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Webhook oluştur
webhook = client.create_webhook(
    url="https://myapp.com/webhooks/geliver",
    type="TRACK_UPDATED"  # opsiyonel
)
print(f"Webhook ID: {webhook['id']}")
print(f"Webhook URL: {webhook['url']}")

# Webhook listele
webhooks = client.list_webhooks()
for wh in webhooks.data:
    print(f"ID: {wh.id} | URL: {wh.url}")

# Webhook test et
result = client.test_webhook(
    type="TRACK_UPDATED",
    url="https://myapp.com/webhooks/geliver"
)
print(f"Test sonucu: {result}")

# Webhook sil
client.delete_webhook("webhook_id_123")
```

--------------------------------

### Manage Shipments with Python SDK

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Basic operations for updating, canceling, and cloning shipments.

```python
client.update_package(fetched.id, {
    "length": "12.0",
    "width": "12.0",
    "height": "10.0",
    "distanceUnit": "cm",
    "weight": "1.2",
    "massUnit": "kg",
})
```

```python
client.cancel_shipment(fetched.id)
```

```python
cloned = client.clone_shipment(fetched.id)
print("Cloned shipment:", getattr(cloned, "id", None))
```

--------------------------------

### Create Return Shipment

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Creates a return shipment for an existing shipment. The `willAccept` parameter can automatically accept the offer if set to `True`.

```python
returned = client.create_return_shipment(shipment.id, {
    'willAccept': True,
    'providerServiceCode': 'SURAT_STANDART',
})
```

--------------------------------

### Manage Parcel Templates

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Create, list, and delete parcel templates to standardize shipping dimensions.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Şablon oluştur
template = client.create_parcel_template({
    "name": "Küçük Kutu",
    "length": "15",
    "width": "10",
    "height": "8",
    "distanceUnit": "cm",
    "weight": "0.5",
    "massUnit": "kg"
})
print(f"Şablon ID: {template['id']}")

# Şablonları listele
templates = client.list_parcel_templates()
for tpl in templates.data:
    print(f"{tpl.id}: {tpl.length}x{tpl.width}x{tpl.height} {tpl.distanceUnit}")

# Şablonu kullanarak gönderi oluştur
shipment = client.create_shipment({
    "senderAddressID": "addr_sender123",
    "recipientAddressID": "addr_recipient456",
    "parcelTemplateID": template['id']
})

# Şablon sil
client.delete_parcel_template(template['id'])
```

--------------------------------

### Retrieve City and District Lists

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Fetches geographic data for Turkey using the Geliver client.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Türkiye şehirlerini listele
cities = client.list_cities("TR")
for city in cities.data:
    print(f"{city.cityCode}: {city.name}")
# Çıktı:
# 34: Istanbul
# 06: Ankara
# 35: Izmir
# ...

# Belirli bir şehrin ilçelerini listele (örn: Istanbul)
districts = client.list_districts("TR", "34")
for district in districts.data:
    print(f"{district.districtID}: {district.name}")
# Çıktı:
# 1: Adalar
# 2: Arnavutköy
# 3: Ataşehir
# ...
```

--------------------------------

### Manage Provider Accounts

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Register and manage third-party shipping provider credentials.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Sağlayıcı hesabı oluştur (kendi kargo anlaşmanız)
account = client.create_provider_account({
    "username": "cargo_user",
    "password": "cargo_pass",
    "name": "ACME Kargo Hesabı",
    "providerCode": "MNG",
    "version": 1,
    "isActive": True,
    "isPublic": False,
    "sharable": False,
    "isDynamicPrice": False
})
print(f"Hesap ID: {account['id']}")

# Sağlayıcı hesaplarını listele
accounts = client.list_provider_accounts()
for acc in accounts.data:
    print(f"{acc.id}: {acc.name} ({acc.providerCode}) - Aktif: {acc.isActive}")

# Sağlayıcı hesabı sil
client.delete_provider_account(
    account['id'],
    is_delete_account_connection=True
)
```

--------------------------------

### Webhook Handler with FastAPI

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Sets up a FastAPI endpoint to receive and verify Geliver webhooks. It processes tracking updates and logs shipment information.

```python
from fastapi import FastAPI, Request
from geliver import verify_webhook, WebhookUpdateTrackingRequest

app = FastAPI()

@app.post("/webhooks/geliver")
async def webhook(req: Request):
    body = await req.body()
    ok = verify_webhook(body, req.headers, enable_verification=False)
    if not ok:
        return {"status": "invalid"}
    evt = WebhookUpdateTrackingRequest.model_validate_json(body.decode("utf-8"))
    if evt.event == "TRACK_UPDATED":
        shipment = evt.data
        print("Tracking update:", shipment.trackingUrl, shipment.trackingNumber)
    return {"status": "ok"}
```

--------------------------------

### Retrieve Location Data

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Fetch city and district information for shipping addresses.

```python
cities = client.list_cities('TR')
districts = client.list_districts('TR', '34')
```

--------------------------------

### Iterate Shipments

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Use the iterator to automatically handle pagination when fetching multiple shipments.

```python
for shipment in client.iter_shipments(ListParams(limit=50)):
    print(f"Gönderi: {shipment.id} - {shipment.statusCode}")
```

--------------------------------

### Accept Offer and Buy Label

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Accepts the cheapest offer for a shipment to purchase a label. The transaction object contains barcode, label URL, and tracking information. Requires a valid sender address ID and recipient details.

```python
from geliver import GeliverClient, ClientOptions
from geliver.client import GeliverError

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Gönderi oluştur ve teklifleri al
shipment = client.create_shipment({
    "senderAddressID": "addr_sender123",
    "recipientAddress": {
        "name": "Ayşe Kaya",
        "phone": "+905441234567",
        "address1": "Alsancak Mahallesi",
        "countryCode": "TR",
        "cityName": "Izmir",
        "cityCode": "35",
        "districtName": "Konak"
    },
    "length": "20.0",
    "width": "15.0",
    "height": "10.0",
    "distanceUnit": "cm",
    "weight": "1.5",
    "massUnit": "kg"
})

# Teklifleri kontrol et
offers = getattr(shipment, 'offers', None)
if offers and offers.get('cheapest'):
    cheapest_offer = offers['cheapest']
    print(f"En ucuz teklif: {cheapest_offer['amount']} {cheapest_offer.get('currency', 'TRY')}")
    print(f"Kargo firması: {cheapest_offer.get('providerCode')}")

    try:
        # Teklifi kabul et (etiket satın al)
        transaction = client.accept_offer(cheapest_offer['id'])

        print(f"İşlem ID: {transaction.id}")
        print(f"Ödeme durumu: {transaction.isPayed}")
        print(f"Barkod: {getattr(transaction.shipment, 'barcode', None)}")
        print(f"Takip numarası: {getattr(transaction.shipment, 'trackingNumber', None)}")
        print(f"Etiket URL: {getattr(transaction.shipment, 'labelURL', None)}")
        print(f"Takip URL: {getattr(transaction.shipment, 'trackingUrl', None)}")
    except GeliverError as e:
        print(f"Hata kodu: {e.code}")
        print(f"Hata mesajı: {e.message}")
else:
    print("Teklifler henüz hazır değil")
```

--------------------------------

### Manage Parcel Templates

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Create, list, and delete reusable parcel templates.

```python
tpl = client.create_parcel_template({'name':'Small Box','distanceUnit':'cm','massUnit':'kg','height':'4','length':'4','weight':'1','width':'4'})
tpls = client.list_parcel_templates()
client.delete_parcel_template(tpl['id'])
```

--------------------------------

### Create Cash on Delivery (COD) Shipment

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Creates a shipment with Cash on Delivery (COD) functionality using the `providerServiceCode` and `productPaymentOnDelivery` fields. Ensure the `order` object includes the total amount and currency for COD.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Kapıda ödemeli gönderi
transaction = client.create_transaction({
    "senderAddressID": "addr_sender123",
    "recipientAddress": {
        "name": "Mustafa Aydın",
        "phone": "+905331234567",
        "address1": "Merkez Mahallesi",
        "countryCode": "TR",
        "cityName": "Istanbul",
        "cityCode": "34",
        "districtName": "Pendik"
    },
    "length": "30.0",
    "width": "25.0",
    "height": "20.0",
    "distanceUnit": "cm",
    "weight": "3.0",
    "massUnit": "kg",
    "providerServiceCode": "PTT_KAPIDA_ODEME",
    "productPaymentOnDelivery": True,
    "order": {
        "orderNumber": "COD-2024-001",
        "totalAmount": "549.90",
        "totalAmountCurrency": "TRY"
    }
})

print(f"Kapıda ödemeli gönderi oluşturuldu: {transaction.id}")
```

--------------------------------

### List Shipments with Pagination

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Fetches a paginated list of shipments, displaying their IDs and status codes. Useful for retrieving multiple shipments at once.

```python
# Listeleme (sayfalandırma)
resp = client.list_shipments({"page": 1, "limit": 20})
for shipment in resp.data or []:
    print(shipment.id, getattr(shipment, "statusCode", None))
```

--------------------------------

### POST /webhooks

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Creates a new webhook for receiving shipment updates.

```APIDOC
## POST /webhooks

### Description
Registers a new webhook URL to receive real-time shipment status updates.

### Method
POST

### Endpoint
/webhooks

### Parameters
#### Request Body
- **url** (string) - Required - The callback URL.
- **type** (string) - Optional - The type of event to subscribe to (e.g., TRACK_UPDATED).
```

--------------------------------

### Create Sender Address

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Create a sender address for your shipments. This is typically done once and the sender address ID can be reused for multiple shipments.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

sender = client.create_sender_address({
    "name": "ACME Inc.",
    "email": "ops@acme.test",
    "phone": "+905051234567",
    "address1": "Hasan Mahallesi",
    "countryCode": "TR",
    "cityName": "Istanbul",
    "cityCode": "34",
    "districtName": "Esenyurt",

    "zip": "34020",
})
```

--------------------------------

### Download Labels

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Download shipping labels in PDF or HTML format based on the provider's file type.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Gönderi bilgilerini al
shipment = client.get_shipment("shp_abc123")

# LabelFileType kontrolü
label_file_type = getattr(shipment, 'labelFileType', None)

if label_file_type == 'PROVIDER_PDF':
    # Sadece PDF etiket kullanılmalı
    pdf_content = client.download_label_for_shipment("shp_abc123")
    with open('kargo_etiketi.pdf', 'wb') as f:
        f.write(pdf_content)
    print("PDF etiket indirildi")

elif label_file_type == 'PDF':
    # HTML (responsive) etiket kullanılabilir
    html_content = client.download_responsive_label_for_shipment("shp_abc123")
    with open('kargo_etiketi.html', 'w', encoding='utf-8') as f:
        f.write(html_content)
    print("HTML etiket indirildi")

# URL ile doğrudan indirme
label_url = getattr(shipment, 'labelURL', None)
if label_url:
    pdf_bytes = client.download_label_by_url(label_url)
    with open('etiket_direct.pdf', 'wb') as f:
        f.write(pdf_bytes)

responsive_url = getattr(shipment, 'responsiveLabelURL', None)
if responsive_url:
    html_text = client.download_responsive_label_by_url(responsive_url)
    with open('etiket_direct.html', 'w', encoding='utf-8') as f:
        f.write(html_text)
```

--------------------------------

### Query Organization Balance

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Checks the current account balance for a specific organization.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Bakiye sorgula
balance = client.get_balance("org_123456")
print(f"Mevcut bakiye: {balance}")
```

--------------------------------

### POST /shipments/{id}/return

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Creates a return shipment for an existing shipment.

```APIDOC
## POST /shipments/{id}/return

### Description
Initiates a return process for an existing shipment.

### Method
POST

### Endpoint
/shipments/{id}/return

### Parameters
#### Path Parameters
- **id** (string) - Required - The original shipment ID.

#### Request Body
- **willAccept** (boolean) - Required - Whether to automatically accept the return offer.
- **providerServiceCode** (string) - Optional - The provider service code.
- **count** (integer) - Required - Number of items to return.
```

--------------------------------

### Use Enums for Shipment Configuration

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Utilize SDK enums for type-safe shipment creation and response validation.

```python
from geliver.models import ShipmentDistanceUnit, ShipmentMassUnit, ShipmentLabelFileType

shipment = client.create_shipment({
    "senderAddressID": sender["id"],
    "recipientAddressID": recipient["id"],
    "distanceUnit": ShipmentDistanceUnit.cm.value,
    "massUnit": ShipmentMassUnit.kg.value,
})
# Yanıtta label dosya türünü enum ile güvenli kontrol edebilirsiniz
if getattr(shipment, 'labelFileType', None) == ShipmentLabelFileType.PDF.value:
    print("PDF etiket hazır")
```

--------------------------------

### Create Shipment with Recipient Address ID

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Creates a shipment using a pre-existing recipient address ID. Ensure sender and recipient addresses are set up before use.

```python
from geliver import CreateShipmentWithRecipientID
created_direct = client.create_shipment(CreateShipmentWithRecipientID(
    senderAddressID=sender["id"],
    recipientAddressID=recipient["id"],
    providerServiceCode="MNG_STANDART",
    length="10.0", width="10.0", height="10.0", distanceUnit="cm",
    weight="1.0", massUnit="kg",
))
```

--------------------------------

### POST /shipment

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Creates a new shipment with an inline recipient address.

```APIDOC
## POST /shipment

### Description
Creates a shipment record. Recipient address can be provided inline without pre-registration.

### Request Body
- **senderAddressID** (string) - Required - ID of the sender address
- **recipientAddress** (object) - Required - Recipient details
- **length** (string) - Required - Package length
- **width** (string) - Required - Package width
- **height** (string) - Required - Package height
- **distanceUnit** (string) - Required - Unit of measurement (e.g., cm)
- **weight** (string) - Required - Package weight
- **massUnit** (string) - Required - Unit of mass (e.g., kg)
- **order** (object) - Optional - Order details including number and amount

### Response
#### Success Response (200)
- **id** (string) - Shipment ID
- **statusCode** (string) - Current status of the shipment
```

--------------------------------

### Create Recipient Address

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Create a recipient address for a shipment. The 'phone' field is mandatory, while 'zip' is optional.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

recipient = client.create_recipient_address({
    "name": "Ahmet Yılmaz",
    "email": "ahmet@email.com",
    "phone": "+905339876543",
    "address1": "Bağdat Caddesi No:120 D:5",
    "countryCode": "TR",
    "cityName": "Istanbul",
    "cityCode": "34",
    "districtName": "Kadıköy"
})

print(f"Alıcı ID: {recipient['id']}")
# Çıktı: Alıcı ID: addr_xyz789abc
```

--------------------------------

### List and Paginate Shipments

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Lists and filters all shipments using `list_shipments` and `iter_shipments` methods. The `ListParams` object allows specifying page number, limit, status filter, and date range for precise retrieval.

```python
from geliver import GeliverClient, ClientOptions
from geliver.types import ListParams

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Sayfalı listeleme
response = client.list_shipments(ListParams(
    page=1,
    limit=20,
    statusFilter="DELIVERED",
    startDate="2024-01-01",
    endDate="2024-12-31"
))

print(f"Toplam kayıt: {response.totalRows}")
print(f"Toplam sayfa: {response.totalPages}")

for shipment in response.data:
    ts = getattr(shipment, 'trackingStatus', None) or {}
    print(f"ID: {shipment.id} | Durum: {ts.get('trackingStatusCode', 'N/A')}")
```

--------------------------------

### Manage Shipments

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Retrieve, update package dimensions, cancel, or clone a shipment using its ID.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Gönderi getir
shipment = client.get_shipment("shp_abc123")
print(f"Gönderi durumu: {shipment.statusCode}")

ts = getattr(shipment, 'trackingStatus', None)
if ts:
    print(f"Takip durumu: {ts.get('trackingStatusCode')}")
    print(f"Alt durum: {ts.get('trackingSubStatusCode')}")

# Paket boyutlarını güncelle
updated = client.update_package("shp_abc123", {
    "length": "35.0",
    "width": "25.0",
    "height": "20.0",
    "distanceUnit": "cm",
    "weight": "3.5",
    "massUnit": "kg"
})
print(f"Güncellenen ağırlık: {updated.weight} {updated.massUnit}")

# Gönderiyi iptal et
cancelled = client.cancel_shipment("shp_abc123")
print(f"İptal durumu: {cancelled.statusCode}")

# Gönderiyi klonla (aynı parametrelerle yeni gönderi)
cloned = client.clone_shipment("shp_abc123")
print(f"Klonlanan gönderi ID: {cloned.id}")
```

--------------------------------

### Handle API Errors

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Demonstrates catching validation errors and GeliverError exceptions to access detailed error metadata.

```python
from geliver import GeliverClient, ClientOptions
from geliver.client import GeliverError

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

try:
    shipment = client.create_shipment({
        "senderAddressID": "invalid_id",
        "recipientAddress": {
            "name": "Test",
            # phone eksik - hata verecek
            "address1": "Test adres",
            "countryCode": "TR",
            "cityName": "Istanbul",
            "cityCode": "34",
            "districtName": "Kadıköy"
        },
        "length": "10.0",
        "width": "10.0",
        "height": "10.0",
        "distanceUnit": "cm",
        "weight": "1.0",
        "massUnit": "kg"
    })
except ValueError as e:
    # Validasyon hatası (örn: phone eksik)
    print(f"Validasyon hatası: {e}")
except GeliverError as e:
    # API hatası
    print(f"Hata kodu: {e.code}")
    print(f"Hata mesajı: {str(e)}")
    print(f"Ek bilgi: {e.additional_message}")
    print(f"HTTP durumu: {e.status}")
    print(f"Yanıt gövdesi: {e.response_body}")
```

--------------------------------

### PUT /shipments/{id}/package

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Updates the package dimensions and weight for a specific shipment.

```APIDOC
## PUT /shipments/{id}/package

### Description
Updates the physical dimensions and weight of the package associated with a shipment.

### Method
PUT

### Endpoint
/shipments/{id}/package

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the shipment.

#### Request Body
- **length** (string) - Required - Package length.
- **width** (string) - Required - Package width.
- **height** (string) - Required - Package height.
- **distanceUnit** (string) - Required - Unit for dimensions (e.g., cm).
- **weight** (string) - Required - Package weight.
- **massUnit** (string) - Required - Unit for weight (e.g., kg).
```

--------------------------------

### Manage Shipping Addresses

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Operations for listing, retrieving, and deleting sender or recipient addresses.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Tüm gönderici adreslerini listele
sender_addresses = client.list_addresses(is_recipient_address=False, limit=50, page=1)
for addr in sender_addresses.data:
    print(f"Gönderici: {addr.name} - {addr.cityName}/{addr.districtName}")

# Tüm alıcı adreslerini listele
recipient_addresses = client.list_addresses(is_recipient_address=True)
for addr in recipient_addresses.data:
    print(f"Alıcı: {addr.name} - {addr.cityName}/{addr.districtName}")

# Belirli adresi getir
address = client.get_address("addr_abc123")
print(f"Adres: {address.address1}, {address.districtName}/{address.cityName}")

# Adres sil
client.delete_address("addr_abc123")
```

--------------------------------

### POST /shipments/{id}/clone

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Clones an existing shipment to create a new one with identical parameters.

```APIDOC
## POST /shipments/{id}/clone

### Description
Creates a new shipment by cloning the parameters of an existing shipment.

### Method
POST

### Endpoint
/shipments/{id}/clone

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the shipment to clone.
```

--------------------------------

### Use Enums for Type Safety

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Utilizes SDK enums for units and file types to ensure consistent API requests and responses.

```python
from geliver import GeliverClient, ClientOptions
from geliver.models import ShipmentDistanceUnit, ShipmentMassUnit, ShipmentLabelFileType

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

# Enum değerleriyle gönderi oluştur
shipment = client.create_shipment({
    "senderAddressID": "addr_sender123",
    "recipientAddressID": "addr_recipient456",
    "length": "20.0",
    "width": "15.0",
    "height": "10.0",
    "distanceUnit": ShipmentDistanceUnit.cm.value,  # "cm"
    "weight": "1.5",
    "massUnit": ShipmentMassUnit.kg.value  # "kg"
})

# Etiket dosya türünü kontrol et
if getattr(shipment, 'labelFileType', None) == ShipmentLabelFileType.PDF.value:
    print("PDF etiket hazır")
elif getattr(shipment, 'labelFileType', None) == ShipmentLabelFileType.PROVIDER_PDF.value:
    print("Sağlayıcı PDF etiketi hazır")
```

--------------------------------

### Advance Shipment Status in Test Environments

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Advances the tracking status of a shipment by repeatedly calling get_shipment. This is useful for testing and is not recommended for production; use webhooks instead.

```python
"""Test gönderilerinde her GET /shipments çağrısı kargo durumunu bir adım ilerletir."""
for _ in range(5):
    import time; time.sleep(1)
    client.get_shipment(shipment.id)
final = client.get_shipment(shipment.id)
ts = getattr(final, 'trackingStatus', None)
print('Final status:', ts.get('trackingStatusCode') if ts else None, ts.get('trackingSubStatusCode') if ts else None)
```

--------------------------------

### Fetch Shipment by ID

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Retrieves a specific shipment using its unique ID and prints its tracking status. Requires a valid shipment ID.

```python
# Getir
fetched = client.get_shipment("SHIPMENT_ID")
ts = getattr(fetched, "trackingStatus", {}) or {}
print("Tracking:", ts.get("trackingStatusCode"), ts.get("trackingSubStatusCode"))
```

--------------------------------

### Create Recipient Address

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Creates a new recipient address entry. This can be used to simplify future shipment creations.

```python
recipient = client.create_recipient_address({
    "name": "John Doe", "email": "john@example.com",
    "address1": "Atatürk Mahallesi", "countryCode": "TR", "cityName": "Istanbul", "cityCode": "34",
    "districtName": "Kadıköy", "zip": "34000",
})
```

--------------------------------

### Parcel Template Management

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Manage reusable parcel dimension templates for shipment creation.

```APIDOC
## POST /parcel-templates

### Description
Creates a new parcel dimension template.

## GET /parcel-templates

### Description
Lists all saved parcel templates.

## DELETE /parcel-templates/{id}

### Description
Deletes a parcel template by ID.
```

--------------------------------

### POST /recipient-address

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Creates a new recipient address for shipping operations. Phone is mandatory.

```APIDOC
## POST /recipient-address

### Description
Creates a new recipient address to define the destination point of a shipment.

### Request Body
- **name** (string) - Required - Name of the recipient
- **email** (string) - Required - Email address
- **phone** (string) - Required - Phone number
- **address1** (string) - Required - Street address
- **countryCode** (string) - Required - Country code
- **cityName** (string) - Required - City name
- **cityCode** (string) - Required - City code
- **districtName** (string) - Required - District name

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the created recipient address
```

--------------------------------

### Handle Geliver API Errors

Source: https://github.com/geliverapp/geliver-python/blob/main/README.md

Catch and inspect GeliverError exceptions for API-related failures.

```python
from geliver.client import GeliverError

try:
    client.create_shipment({...})
except GeliverError as e:
    print('code:', e.code)
    print('message:', str(e))
    print('additional:', e.additional_message)
    print('status:', e.status)
```

--------------------------------

### Create Shipment with Inline Recipient Address

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Create a shipment, providing the recipient's address directly within the request instead of using a pre-registered address ID. Ensure dimension and weight values are sent as strings.

```python
from geliver import GeliverClient, ClientOptions

client = GeliverClient(ClientOptions(token="YOUR_TOKEN"))

shipment = client.create_shipment({
    "senderAddressID": "addr_sender123",
    "recipientAddress": {
        "name": "Mehmet Demir",
        "email": "mehmet@email.com",
        "phone": "+905551112233",
        "address1": "Kızılay Mahallesi, Atatürk Bulvarı No:50",
        "countryCode": "TR",
        "cityName": "Ankara",
        "cityCode": "06",
        "districtName": "Çankaya",
        "zip": "06420"
    },
    "length": "30.0",
    "width": "20.0",
    "height": "15.0",
    "distanceUnit": "cm",
    "weight": "2.5",
    "massUnit": "kg",
    "order": {
        "orderNumber": "SIP-2024-00123",
        "sourceIdentifier": "https://magazam.com.tr",
        "totalAmount": "299.90",
        "totalAmountCurrency": "TRY"
    }
})

print(f"Gönderi ID: {shipment.id}")
print(f"Durum: {shipment.statusCode}")
# Çıktı: Gönderi ID: shp_abc123
# Çıktı: Durum: CREATED
```

--------------------------------

### POST /webhooks/geliver

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Endpoint to receive and process shipment tracking updates via webhooks.

```APIDOC
## POST /webhooks/geliver

### Description
Receives shipment tracking updates from Geliver. The endpoint validates the request and processes the tracking status.

### Method
POST

### Endpoint
/webhooks/geliver

### Request Body
- **event** (string) - The type of event (e.g., TRACK_UPDATED)
- **data** (object) - The shipment tracking details including ID, trackingNumber, and trackingStatus.
```

--------------------------------

### POST /sender-address

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Creates a new sender address for shipping operations. Phone and zip code are mandatory.

```APIDOC
## POST /sender-address

### Description
Creates a new sender address to define the origin point of a shipment.

### Request Body
- **name** (string) - Required - Name of the sender
- **email** (string) - Required - Email address
- **phone** (string) - Required - Phone number
- **address1** (string) - Required - Street address
- **countryCode** (string) - Required - Country code (e.g., TR)
- **cityName** (string) - Required - City name
- **cityCode** (string) - Required - City code
- **districtName** (string) - Required - District name
- **zip** (string) - Required - Zip code

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the created sender address
```

--------------------------------

### Provider Account Management

Source: https://context7.com/geliverapp/geliver-python/llms.txt

Manage logistics provider credentials and account settings.

```APIDOC
## POST /provider-accounts

### Description
Registers a new logistics provider account (e.g., MNG, Sürat).

## GET /provider-accounts

### Description
Lists all configured provider accounts.

## DELETE /provider-accounts/{id}

### Description
Deletes a provider account connection.
```