# Basalam Python SDK
## Introduction
Welcome to the Basalam Python SDK - a comprehensive client library for interacting with Basalam API services. This SDK
provides a clean, developer-friendly interface for all Basalam services with full async support. Whether you're building
a server-to-server integration or a user-facing application, this SDK provides the tools you need.
**Supported Python Versions:** Python 3.9+, Python 3.10+, Python 3.11+, Python 3.12+
**Key Features:**
- **Full Async/Sync Support**: All operations support both synchronous and asynchronous patterns
- **Type Safety**: Built with Pydantic for robust type checking and validation
- **Multiple Authentication Methods**: Support for client credentials, authorization code flow, and personal tokens
- **Comprehensive Service Coverage**: Access to all Basalam services including wallet, orders, chat, and more
- **Error Handling**: Detailed error classes for different types of failures
- **Developer Friendly**: Clean API design with comprehensive documentation
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Authentication](#authentication)
- [Services](#services)
- [Core Service](#core-service)
- [Chat Service](#chat-service)
- [Order Service](#order-service)
- [Order Processing Service](#order-processing-service)
- [Wallet Service](#wallet-service)
- [Search Service](#search-service)
- [Upload Service](#upload-service)
- [Webhook Service](#webhook-service)
- [Async/Sync Usage](#asyncsync-usage)
- [License](#license)
## Installation
**📖 [Full Introduction Documentation](docs/en/intro.md)**
Install the SDK using pip:
```bash
pip install basalam-sdk
```
## Quick Start
### 1. Import the SDK
```python
from basalam_sdk import BasalamClient, PersonalToken
```
### 2. Set up Authentication
```python
# Personal Token (Token-based authentication)
auth = PersonalToken(
token="your-access-token",
refresh_token="your-refresh-token"
)
```
### 3. Create the Client
```python
client = BasalamClient(auth=auth)
```
### 4. Your First API Calls
```python
import asyncio
async def main():
# Setup
auth = PersonalToken(
token="your-access-token",
refresh_token="your-refresh-token"
)
client = BasalamClient(auth=auth)
# Get products
products = await client.get_products()
print(f"Found {len(products)} products")
# Print first few products
for product in products[:3]:
print(f"Product: {product.name} - Price: {product.price}")
return products
# Run the async function
result = asyncio.run(main())
```
## Authentication
**📖 [Full Authentication Documentation](docs/en/auth.md)**
The SDK supports three main authentication methods:
### Personal Token (For Existing Tokens)
Use this method when you already have valid access and refresh tokens:
```python
from basalam_sdk import BasalamClient, PersonalToken
auth = PersonalToken(
token="your_existing_access_token",
refresh_token="your_existing_refresh_token"
)
client = BasalamClient(auth=auth)
```
### Authorization Code Flow (For User Authentication)
Use this method when you need to authenticate on behalf of a user:
```python
from basalam_sdk import BasalamClient, AuthorizationCode, Scope
# Create auth object
auth = AuthorizationCode(
client_id="your-client-id",
client_secret="your-client-secret",
redirect_uri="https://your-app.com/callback",
scopes=[Scope.CUSTOMER_WALLET_READ, Scope.CUSTOMER_ORDER_READ]
)
# Get authorization URL
auth_url = auth.get_authorization_url(state="optional_state_parameter")
print(f"Visit: {auth_url}")
# Exchange code for tokens (after user authorization)
token_info = await auth.get_token(code="authorization_code_from_callback")
# Create authenticated client
client = BasalamClient(auth=auth)
```
### Client Credentials (For Server-to-Server)
Use this method for server-to-server applications:
```python
from basalam_sdk import BasalamClient, ClientCredentials, Scope
auth = ClientCredentials(
client_id="your-client-id",
client_secret="your-client-secret",
scopes=[Scope.CUSTOMER_WALLET_READ, Scope.VENDOR_PRODUCT_WRITE]
)
client = BasalamClient(auth=auth)
```
## Services
The SDK provides access to all Basalam services through a unified client interface. All services support both
synchronous and asynchronous operations.
### Core Service
**📖 [Full Core Service Documentation](docs/en/services/core.md)**
Manage vendors, products, shipping methods, user information, and more with the Core Service. This service provides
comprehensive functionality for handling core business entities and operations: create and manage vendors, handle
product creation and updates (with file upload support), manage shipping methods, update user verification and
information, handle bank account operations, and manage categories and attributes.
**Key Features:**
- Create and manage vendors
- Handle product creation and updates with file upload support
- Manage shipping methods
- Update user verification and information
- Handle bank account operations
- Manage categories and attributes
**Core Methods:**
| Method | Description | Parameters |
|----------------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------|
| `create_vendor()` | Create new vendor | `user_id`, `request: CreateVendorSchema` |
| `update_vendor()` | Update vendor | `vendor_id`, `request: UpdateVendorSchema` |
| `get_vendor()` | Get vendor details | `vendor_id`, `prefer` |
| `get_default_shipping_methods()` | Get default shipping methods | `None` |
| `get_shipping_methods()` | Get shipping methods | `ids`, `vendor_ids`, `include_deleted`, `page`, `per_page` |
| `get_working_shipping_methods()` | Get working shipping methods | `vendor_id` |
| `update_shipping_methods()` | Update shipping methods | `vendor_id`, `request: UpdateShippingMethodSchema` |
| `get_vendor_products()` | Get vendor products | `vendor_id`, `query_params: GetVendorProductsSchema` |
| `update_vendor_status()` | Update vendor status | `vendor_id`, `request: UpdateVendorStatusSchema` |
| `create_vendor_mobile_change_request()` | Create vendor mobile change | `vendor_id`, `request: ChangeVendorMobileRequestSchema` |
| `create_vendor_mobile_change_confirmation()` | Confirm vendor mobile change | `vendor_id`, `request: ChangeVendorMobileConfirmSchema` |
| `create_product()` | Create a new product (supports file upload) | `vendor_id`, `request: ProductRequestSchema`, `photo_files`, `video_file` |
| `update_bulk_products()` | Update multiple products | `vendor_id`, `request: BatchUpdateProductsRequest` |
| `update_product()` | Update a single product (supports file upload) | `product_id`, `request: ProductRequestSchema`, `photo_files`, `video_file` |
| `get_product()` | Get product details | `product_id`, `prefer` |
| `get_products()` | Get products list | `query_params: GetProductsQuerySchema`, `prefer` |
| `create_products_bulk_action_request()` | Create bulk product updates | `vendor_id`, `request: BulkProductsUpdateRequestSchema` |
| `update_product_variation()` | Update product variation | `product_id`, `variation_id`, `request: UpdateProductVariationSchema` |
| `get_products_bulk_action_requests()` | Get bulk update status | `vendor_id`, `page`, `per_page` |
| `get_products_bulk_action_requests_count()` | Get bulk updates count | `vendor_id` |
| `get_products_unsuccessful_bulk_action_requests()` | Get failed updates | `request_id`, `page`, `per_page` |
| `get_product_shelves()` | Get product shelves | `product_id` |
| `create_discount()` | Create discount for products | `vendor_id`, `request: CreateDiscountRequestSchema` |
| `delete_discount()` | Delete discount for products | `vendor_id`, `request: DeleteDiscountRequestSchema` |
| `get_current_user()` | Get current user info | `None` |
| `create_user_mobile_confirmation_request()` | Create mobile confirmation request | `user_id` |
| `verify_user_mobile_confirmation_request()` | Confirm user mobile | `user_id`, `request: ConfirmCurrentUserMobileConfirmSchema` |
| `create_user_mobile_change_request()` | Create mobile change request | `user_id`, `request: ChangeUserMobileRequestSchema` |
| `verify_user_mobile_change_request()` | Confirm mobile change | `user_id`, `request: ChangeUserMobileConfirmSchema` |
| `get_user_bank_accounts()` | Get user bank accounts | `user_id`, `prefer` |
| `create_user_bank_account()` | Create user bank account | `user_id`, `request: UserCardsSchema`, `prefer` |
| `verify_user_bank_account_otp()` | Verify bank account OTP | `user_id`, `request: UserCardsOtpSchema` |
| `verify_user_bank_account()` | Verify bank accounts | `user_id`, `request: UserVerifyBankInformationSchema` |
| `delete_user_bank_account()` | Delete bank account | `user_id`, `bank_account_id` |
| `update_user_bank_account()` | Update bank account | `bank_account_id`, `request: UpdateUserBankInformationSchema` |
| `update_user_verification()` | Update user verification | `user_id`, `request: UserVerificationSchema` |
| `get_category_attributes()` | Get category attributes | `category_id`, `product_id`, `vendor_id`, `exclude_multi_selects` |
| `get_categories()` | Get all categories | `None` |
| `get_category()` | Get specific category | `category_id` |
**Example:**
```python
from basalam_sdk.core.models import CreateVendorSchema
# Create a new vendor
vendor = await client.create_vendor(
user_id=123,
request=CreateVendorSchema(
title="My Store",
identifier="store123",
category_type=1,
city=1,
summary="A great store for all your needs"
)
)
# Get vendor details
vendor_details = await client.get_vendor(vendor_id=vendor.id)
```
### Chat Service
**📖 [Full Chat Service Documentation](docs/en/services/chat.md)**
Handle messaging and chat functionalities with the Chat Service. This service provides comprehensive tools for managing
conversations, messages, and chat interactions.
**Key Features:**
- Create and manage chat conversations
- Send and retrieve messages
- Handle different message types
- Manage chat participants
- Track chat history and updates
**Methods:**
| Method | Description | Parameters |
|--------------------|-------------------|------------------------------------------------------------------------------------------------------|
| `create_message()` | Create a message | `request`, `user_agent`, `x_client_info`, `admin_token` |
| `create_chat()` | Create a chat | `request`, `x_creation_tags`, `x_user_session`, `x_client_info` |
| `get_messages()` | Get chat messages | `chat_id`, `msg_id`, `limit`, `chat_type`, `order`, `op`, `temp_id` |
| `get_chats()` | Get chats list | `limit`, `order_by`, `updated_from`, `updated_before`, `modified_from`, `modified_before`, `filters` |
**Example:**
```python
from basalam_sdk.chat.models import MessageRequest
# Create a message
message = await client.create_message(
request=MessageRequest(
chat_id=123,
content="Hello, how can I help you?",
message_type="text"
),
user_agent="MyApp/1.0",
x_client_info="web"
)
# Get messages from a chat
messages = await client.get_messages(
chat_id=123,
limit=20,
order="DESC"
)
```
### Order Service
**📖 [Full Order Service Documentation](docs/en/services/order.md)**
Manage baskets, payments, and invoices with the Order Service. This service provides comprehensive functionality for
handling order-related operations and payment processing.
**Key Features:**
- Manage shopping baskets
- Process payments and invoices
- Handle payment callbacks
- Track order status and product variations
- Manage payable and unpaid invoices
**Methods:**
| Method | Description | Parameters |
|----------------------------------|------------------------------|----------------------------------------------------|
| `get_baskets()` | Get active baskets | `refresh` |
| `get_product_variation_status()` | Get product variation status | `product_id` |
| `create_invoice_payment()` | Create payment for invoice | `invoice_id`, `request` |
| `get_payable_invoices()` | Get payable invoices | `page`, `per_page` |
| `get_unpaid_invoices()` | Get unpaid invoices | `invoice_id`, `status`, `page`, `per_page`, `sort` |
| `get_payment_callback()` | Get payment callback | `payment_id`, `request` |
| `create_payment_callback()` | Create payment callback | `payment_id`, `request` |
**Example:**
```python
from basalam_sdk.order.models import CreatePaymentRequestModel
# Get active baskets
baskets = await client.get_baskets(refresh=True)
# Create payment for invoice
payment = await client.create_invoice_payment(
invoice_id=123,
request=CreatePaymentRequestModel(
payment_method="credit_card",
amount=10000
)
)
```
### Order Processing Service
**📖 [Full Order Processing Service Documentation](docs/en/services/order-processing.md)**
Manage customer orders, vendor parcels, and the entire order lifecycle with the Order Processing Service. This service
provides comprehensive functionality to get and manage customer orders, track order items and details, handle vendor
parcels and shipping, generate order statistics, and monitor order status and updates.
**Key Features:**
- Get and manage customer orders
- Track order items and details
- Handle vendor parcels and shipping
- Generate order statistics
- Monitor order status and updates
**Methods:**
| Method | Description | Parameters |
|-------------------------------|----------------------|--------------------------------------------------------------------------------------------|
| `get_customer_orders()` | Get orders | `filters` (OrderFilter) |
| `get_customer_order()` | Get specific order | `order_id` |
| `get_customer_order_items()` | Get order items | `filters` (ItemFilter) |
| `get_customer_order_item()` | Get specific item | `item_id` |
| `get_vendor_orders_parcels()` | Get orders parcels | `filters` (OrderParcelFilter) |
| `get_order_parcel()` | Get specific parcel | `parcel_id` |
| `get_orders_stats()` | Get order statistics | `resource_count`, `vendor_id`, `product_id`, `customer_id`, `coupon_code`, `cache_control` |
**Example:**
```python
from basalam_sdk.order_processing.models import OrderFilter
# Get orders with filters
orders = await client.get_customer_orders(
filters=OrderFilter(
coupon_code="SAVE10",
cursor="next_cursor_123",
customer_ids="123,456,789",
customer_name="John Doe"
)
)
# Get specific order details
order = await client.get_customer_order(order_id=123)
```
### Wallet Service
**📖 [Full Wallet Service Documentation](docs/en/services/wallet.md)**
Manage user balances, expenses, and refunds with the Wallet Service. This service provides comprehensive functionality
for handling user financial operations.
**Key Features:**
- Get user balance and transaction history
- Create and manage expenses
- Process refunds
- Handle credit-specific operations
**Methods:**
| Method | Description | Parameters |
|--------------------------------|-------------------------------------|-------------------------------------------------------------------------------|
| `get_balance()` | Get user's balance | `user_id`, `filters`, `x_operator_id` |
| `get_transactions()` | Get transaction history | `user_id`, `page`, `per_page`, `x_operator_id` |
| `create_expense()` | Create an expense | `user_id`, `request`, `x_operator_id` |
| `create_expense_from_credit()` | Create expense from specific credit | `user_id`, `credit_id`, `request`, `x_operator_id` |
| `get_expense()` | Get expense details | `user_id`, `expense_id`, `x_operator_id` |
| `delete_expense()` | Delete/rollback expense | `user_id`, `expense_id`, `rollback_reason_id`, `x_operator_id` |
| `get_expense_by_ref()` | Get expense by reference | `user_id`, `reason_id`, `reference_id`, `x_operator_id` |
| `delete_expense_by_ref()` | Delete expense by reference | `user_id`, `reason_id`, `reference_id`, `rollback_reason_id`, `x_operator_id` |
| `create_refund()` | Process a refund | `request`, `x_operator_id` |
| `can_rollback_refund()` | Check if refund can be rolled back | `refund_reason`, `refund_reference_id`, `x_operator_id` |
| `rollback_refund()` | Rollback a refund | `request`, `x_operator_id` |
**Example:**
```python
from basalam_sdk.wallet.models import SpendCreditRequest
# Get user balance
balance = await client.get_balance(user_id=123)
# Create an expense
expense = await client.create_expense(
user_id=123,
request=SpendCreditRequest(
reason_id=1,
reference_id=456,
amount=10000,
description="Payment for order #456",
types=[1, 2],
settleable=True
)
)
```
### Search Service
**📖 [Full Search Service Documentation](docs/en/services/search.md)**
Search for products and entities with the Search Service. This service provides powerful search capabilities.
**Key Features:**
- Search for products with advanced filters
- Apply price ranges and category filters
- Sort results by various criteria
- Paginate through search results
- Get detailed product information
**Methods:**
| Method | Description | Parameters |
|---------------------|---------------------|------------|
| `search_products()` | Search for products | `request` |
**Example:**
```python
from basalam_sdk.search.models import ProductSearchModel
# Search for products
results = await client.search_products(
request=ProductSearchModel(
query="laptop",
category_id=123,
min_price=100000,
max_price=500000,
sort_by="price",
sort_order="asc",
page=1,
per_page=20
)
)
```
### Upload Service
**📖 [Full Upload Service Documentation](docs/en/services/upload.md)**
Upload and manage files with the Upload Service. This service provides secure file upload capabilities.
**Key Features:**
- Upload files securely
- Support various file types (images, documents, videos)
- Set custom file names and expiration times
- Get file URLs for access
- Manage file lifecycle
**Methods:**
| Method | Description | Parameters |
|-----------------|---------------|-------------------------------------------------------------|
| `upload_file()` | Upload a file | `file`, `file_type`, `custom_unique_name`, `expire_minutes` |
**Example:**
```python
from basalam_sdk.upload.models import UserUploadFileTypeEnum
# Upload a file
with open("image.jpg", "rb") as file:
result = await client.upload_file(
file=file,
file_type=UserUploadFileTypeEnum.PRODUCT_PHOTO,
custom_unique_name="my-product-image",
expire_minutes=1440 # 24 hours
)
print(f"File uploaded: {result.url}")
```
### Webhook Service
**📖 [Full Webhook Service Documentation](docs/en/services/webhook.md)**
Manage webhook subscriptions and events with the Webhook Service. This service allows you to receive real-time
notifications about events happening in your Basalam account.
**Key Features:**
- Create and manage webhook subscriptions
- Handle different types of events
- Monitor webhook logs and delivery status
- Register and unregister clients to webhooks
**Methods:**
| Method | Description | Parameters |
|-----------------------------|----------------------------|----------------------------------|
| `get_webhook_services()` | Get webhook services | None |
| `create_webhook_service()` | Create webhook service | `request` |
| `get_webhooks()` | Get webhooks list | `service_id`, `event_ids` |
| `create_webhook()` | Create new webhook | `request` |
| `update_webhook()` | Update webhook | `webhook_id`, `request` |
| `delete_webhook()` | Delete webhook | `webhook_id` |
| `get_webhook_events()` | Get available events | None |
| `get_webhook_customers()` | Get webhook customers | `page`, `per_page`, `webhook_id` |
| `get_webhook_logs()` | Get webhook logs | `webhook_id` |
| `register_webhook()` | Register client to webhook | `request` |
| `unregister_webhook()` | Unregister client | `request` |
| `get_registered_webhooks()` | Get registered webhooks | `page`, `per_page`, `service_id` |
**Example:**
```python
from basalam_sdk.webhook.models import CreateWebhookRequest
# Create a new webhook
webhook = await client.create_webhook(
request=CreateWebhookRequest(
service_id=1,
event_ids=["order.created", "payment.completed"],
request_method="POST",
url="https://your-app.com/webhook",
is_active=True
)
)
# Get webhook events
events = await client.get_webhook_events()
```
## Async/Sync Usage
All SDK methods support both synchronous and asynchronous patterns:
### Asynchronous (Recommended)
```python
async def async_example():
auth = PersonalToken(token="your-token", refresh_token="your-refresh-token")
client = BasalamClient(auth=auth)
# Async calls
balance = await client.get_balance(user_id=123)
webhooks = await client.get_webhooks()
return balance, webhooks
# Run async function
result = asyncio.run(async_example())
```
### Synchronous
```python
def sync_example():
auth = PersonalToken(token="your-token", refresh_token="your-refresh-token")
client = BasalamClient(auth=auth)
# Sync calls (note the _sync suffix)
balance = client.get_balance_sync(user_id=123)
webhooks = client.get_webhooks_sync()
return balance, webhooks
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "basalam-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "api, async, basalam, client, e-commerce, sdk",
"author": null,
"author_email": "Basalam Development Team <developers@basalam.com>",
"download_url": "https://files.pythonhosted.org/packages/49/b9/4ac3db342d7563b658f635d7967c2a170ed41b193aa30d3b37297b479899/basalam_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# Basalam Python SDK\n\n## Introduction\n\nWelcome to the Basalam Python SDK - a comprehensive client library for interacting with Basalam API services. This SDK\nprovides a clean, developer-friendly interface for all Basalam services with full async support. Whether you're building\na server-to-server integration or a user-facing application, this SDK provides the tools you need.\n\n**Supported Python Versions:** Python 3.9+, Python 3.10+, Python 3.11+, Python 3.12+\n\n**Key Features:**\n\n- **Full Async/Sync Support**: All operations support both synchronous and asynchronous patterns\n- **Type Safety**: Built with Pydantic for robust type checking and validation\n- **Multiple Authentication Methods**: Support for client credentials, authorization code flow, and personal tokens\n- **Comprehensive Service Coverage**: Access to all Basalam services including wallet, orders, chat, and more\n- **Error Handling**: Detailed error classes for different types of failures\n- **Developer Friendly**: Clean API design with comprehensive documentation\n\n\n\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Authentication](#authentication)\n- [Services](#services)\n - [Core Service](#core-service)\n - [Chat Service](#chat-service)\n - [Order Service](#order-service)\n - [Order Processing Service](#order-processing-service)\n - [Wallet Service](#wallet-service)\n - [Search Service](#search-service)\n - [Upload Service](#upload-service)\n - [Webhook Service](#webhook-service)\n- [Async/Sync Usage](#asyncsync-usage)\n- [License](#license)\n\n## Installation\n\n**\ud83d\udcd6 [Full Introduction Documentation](docs/en/intro.md)**\n\nInstall the SDK using pip:\n\n```bash\npip install basalam-sdk\n```\n\n## Quick Start\n\n### 1. Import the SDK\n\n```python\nfrom basalam_sdk import BasalamClient, PersonalToken\n```\n\n### 2. Set up Authentication\n\n```python\n# Personal Token (Token-based authentication)\nauth = PersonalToken(\n token=\"your-access-token\",\n refresh_token=\"your-refresh-token\"\n)\n```\n\n### 3. Create the Client\n\n```python\nclient = BasalamClient(auth=auth)\n```\n\n### 4. Your First API Calls\n\n```python\nimport asyncio\n\n\nasync def main():\n # Setup\n auth = PersonalToken(\n token=\"your-access-token\",\n refresh_token=\"your-refresh-token\"\n )\n client = BasalamClient(auth=auth)\n\n # Get products\n products = await client.get_products()\n print(f\"Found {len(products)} products\")\n\n # Print first few products\n for product in products[:3]:\n print(f\"Product: {product.name} - Price: {product.price}\")\n\n return products\n\n\n# Run the async function\nresult = asyncio.run(main())\n```\n\n## Authentication\n\n**\ud83d\udcd6 [Full Authentication Documentation](docs/en/auth.md)**\n\nThe SDK supports three main authentication methods:\n\n### Personal Token (For Existing Tokens)\n\nUse this method when you already have valid access and refresh tokens:\n\n```python\nfrom basalam_sdk import BasalamClient, PersonalToken\n\nauth = PersonalToken(\n token=\"your_existing_access_token\",\n refresh_token=\"your_existing_refresh_token\"\n)\n\nclient = BasalamClient(auth=auth)\n```\n\n### Authorization Code Flow (For User Authentication)\n\nUse this method when you need to authenticate on behalf of a user:\n\n```python\nfrom basalam_sdk import BasalamClient, AuthorizationCode, Scope\n\n# Create auth object\nauth = AuthorizationCode(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n redirect_uri=\"https://your-app.com/callback\",\n scopes=[Scope.CUSTOMER_WALLET_READ, Scope.CUSTOMER_ORDER_READ]\n)\n\n# Get authorization URL\nauth_url = auth.get_authorization_url(state=\"optional_state_parameter\")\nprint(f\"Visit: {auth_url}\")\n\n# Exchange code for tokens (after user authorization)\ntoken_info = await auth.get_token(code=\"authorization_code_from_callback\")\n\n# Create authenticated client\nclient = BasalamClient(auth=auth)\n```\n\n### Client Credentials (For Server-to-Server)\n\nUse this method for server-to-server applications:\n\n```python\nfrom basalam_sdk import BasalamClient, ClientCredentials, Scope\n\nauth = ClientCredentials(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n scopes=[Scope.CUSTOMER_WALLET_READ, Scope.VENDOR_PRODUCT_WRITE]\n)\n\nclient = BasalamClient(auth=auth)\n```\n\n## Services\n\nThe SDK provides access to all Basalam services through a unified client interface. All services support both\nsynchronous and asynchronous operations.\n\n### Core Service\n\n**\ud83d\udcd6 [Full Core Service Documentation](docs/en/services/core.md)**\n\nManage vendors, products, shipping methods, user information, and more with the Core Service. This service provides\ncomprehensive functionality for handling core business entities and operations: create and manage vendors, handle\nproduct creation and updates (with file upload support), manage shipping methods, update user verification and\ninformation, handle bank account operations, and manage categories and attributes.\n\n**Key Features:**\n\n- Create and manage vendors\n- Handle product creation and updates with file upload support\n- Manage shipping methods\n- Update user verification and information\n- Handle bank account operations\n- Manage categories and attributes\n\n**Core Methods:**\n\n| Method | Description | Parameters |\n|----------------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------|\n| `create_vendor()` | Create new vendor | `user_id`, `request: CreateVendorSchema` |\n| `update_vendor()` | Update vendor | `vendor_id`, `request: UpdateVendorSchema` |\n| `get_vendor()` | Get vendor details | `vendor_id`, `prefer` |\n| `get_default_shipping_methods()` | Get default shipping methods | `None` |\n| `get_shipping_methods()` | Get shipping methods | `ids`, `vendor_ids`, `include_deleted`, `page`, `per_page` |\n| `get_working_shipping_methods()` | Get working shipping methods | `vendor_id` |\n| `update_shipping_methods()` | Update shipping methods | `vendor_id`, `request: UpdateShippingMethodSchema` |\n| `get_vendor_products()` | Get vendor products | `vendor_id`, `query_params: GetVendorProductsSchema` |\n| `update_vendor_status()` | Update vendor status | `vendor_id`, `request: UpdateVendorStatusSchema` |\n| `create_vendor_mobile_change_request()` | Create vendor mobile change | `vendor_id`, `request: ChangeVendorMobileRequestSchema` |\n| `create_vendor_mobile_change_confirmation()` | Confirm vendor mobile change | `vendor_id`, `request: ChangeVendorMobileConfirmSchema` |\n| `create_product()` | Create a new product (supports file upload) | `vendor_id`, `request: ProductRequestSchema`, `photo_files`, `video_file` |\n| `update_bulk_products()` | Update multiple products | `vendor_id`, `request: BatchUpdateProductsRequest` |\n| `update_product()` | Update a single product (supports file upload) | `product_id`, `request: ProductRequestSchema`, `photo_files`, `video_file` |\n| `get_product()` | Get product details | `product_id`, `prefer` |\n| `get_products()` | Get products list | `query_params: GetProductsQuerySchema`, `prefer` |\n| `create_products_bulk_action_request()` | Create bulk product updates | `vendor_id`, `request: BulkProductsUpdateRequestSchema` |\n| `update_product_variation()` | Update product variation | `product_id`, `variation_id`, `request: UpdateProductVariationSchema` |\n| `get_products_bulk_action_requests()` | Get bulk update status | `vendor_id`, `page`, `per_page` |\n| `get_products_bulk_action_requests_count()` | Get bulk updates count | `vendor_id` |\n| `get_products_unsuccessful_bulk_action_requests()` | Get failed updates | `request_id`, `page`, `per_page` |\n| `get_product_shelves()` | Get product shelves | `product_id` |\n| `create_discount()` | Create discount for products | `vendor_id`, `request: CreateDiscountRequestSchema` |\n| `delete_discount()` | Delete discount for products | `vendor_id`, `request: DeleteDiscountRequestSchema` |\n| `get_current_user()` | Get current user info | `None` |\n| `create_user_mobile_confirmation_request()` | Create mobile confirmation request | `user_id` |\n| `verify_user_mobile_confirmation_request()` | Confirm user mobile | `user_id`, `request: ConfirmCurrentUserMobileConfirmSchema` |\n| `create_user_mobile_change_request()` | Create mobile change request | `user_id`, `request: ChangeUserMobileRequestSchema` |\n| `verify_user_mobile_change_request()` | Confirm mobile change | `user_id`, `request: ChangeUserMobileConfirmSchema` |\n| `get_user_bank_accounts()` | Get user bank accounts | `user_id`, `prefer` |\n| `create_user_bank_account()` | Create user bank account | `user_id`, `request: UserCardsSchema`, `prefer` |\n| `verify_user_bank_account_otp()` | Verify bank account OTP | `user_id`, `request: UserCardsOtpSchema` |\n| `verify_user_bank_account()` | Verify bank accounts | `user_id`, `request: UserVerifyBankInformationSchema` |\n| `delete_user_bank_account()` | Delete bank account | `user_id`, `bank_account_id` |\n| `update_user_bank_account()` | Update bank account | `bank_account_id`, `request: UpdateUserBankInformationSchema` |\n| `update_user_verification()` | Update user verification | `user_id`, `request: UserVerificationSchema` |\n| `get_category_attributes()` | Get category attributes | `category_id`, `product_id`, `vendor_id`, `exclude_multi_selects` |\n| `get_categories()` | Get all categories | `None` |\n| `get_category()` | Get specific category | `category_id` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.core.models import CreateVendorSchema\n\n# Create a new vendor\nvendor = await client.create_vendor(\n user_id=123,\n request=CreateVendorSchema(\n title=\"My Store\",\n identifier=\"store123\",\n category_type=1,\n city=1,\n summary=\"A great store for all your needs\"\n )\n)\n\n# Get vendor details\nvendor_details = await client.get_vendor(vendor_id=vendor.id)\n```\n\n### Chat Service\n\n**\ud83d\udcd6 [Full Chat Service Documentation](docs/en/services/chat.md)**\n\nHandle messaging and chat functionalities with the Chat Service. This service provides comprehensive tools for managing\nconversations, messages, and chat interactions.\n\n**Key Features:**\n\n- Create and manage chat conversations\n- Send and retrieve messages\n- Handle different message types\n- Manage chat participants\n- Track chat history and updates\n\n**Methods:**\n\n| Method | Description | Parameters |\n|--------------------|-------------------|------------------------------------------------------------------------------------------------------|\n| `create_message()` | Create a message | `request`, `user_agent`, `x_client_info`, `admin_token` |\n| `create_chat()` | Create a chat | `request`, `x_creation_tags`, `x_user_session`, `x_client_info` |\n| `get_messages()` | Get chat messages | `chat_id`, `msg_id`, `limit`, `chat_type`, `order`, `op`, `temp_id` |\n| `get_chats()` | Get chats list | `limit`, `order_by`, `updated_from`, `updated_before`, `modified_from`, `modified_before`, `filters` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.chat.models import MessageRequest\n\n# Create a message\nmessage = await client.create_message(\n request=MessageRequest(\n chat_id=123,\n content=\"Hello, how can I help you?\",\n message_type=\"text\"\n ),\n user_agent=\"MyApp/1.0\",\n x_client_info=\"web\"\n)\n\n# Get messages from a chat\nmessages = await client.get_messages(\n chat_id=123,\n limit=20,\n order=\"DESC\"\n)\n```\n\n### Order Service\n\n**\ud83d\udcd6 [Full Order Service Documentation](docs/en/services/order.md)**\n\nManage baskets, payments, and invoices with the Order Service. This service provides comprehensive functionality for\nhandling order-related operations and payment processing.\n\n**Key Features:**\n\n- Manage shopping baskets\n- Process payments and invoices\n- Handle payment callbacks\n- Track order status and product variations\n- Manage payable and unpaid invoices\n\n**Methods:**\n\n| Method | Description | Parameters |\n|----------------------------------|------------------------------|----------------------------------------------------|\n| `get_baskets()` | Get active baskets | `refresh` |\n| `get_product_variation_status()` | Get product variation status | `product_id` |\n| `create_invoice_payment()` | Create payment for invoice | `invoice_id`, `request` |\n| `get_payable_invoices()` | Get payable invoices | `page`, `per_page` |\n| `get_unpaid_invoices()` | Get unpaid invoices | `invoice_id`, `status`, `page`, `per_page`, `sort` |\n| `get_payment_callback()` | Get payment callback | `payment_id`, `request` |\n| `create_payment_callback()` | Create payment callback | `payment_id`, `request` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.order.models import CreatePaymentRequestModel\n\n# Get active baskets\nbaskets = await client.get_baskets(refresh=True)\n\n# Create payment for invoice\npayment = await client.create_invoice_payment(\n invoice_id=123,\n request=CreatePaymentRequestModel(\n payment_method=\"credit_card\",\n amount=10000\n )\n)\n```\n\n### Order Processing Service\n\n**\ud83d\udcd6 [Full Order Processing Service Documentation](docs/en/services/order-processing.md)**\n\nManage customer orders, vendor parcels, and the entire order lifecycle with the Order Processing Service. This service\nprovides comprehensive functionality to get and manage customer orders, track order items and details, handle vendor\nparcels and shipping, generate order statistics, and monitor order status and updates.\n\n**Key Features:**\n\n- Get and manage customer orders\n- Track order items and details\n- Handle vendor parcels and shipping\n- Generate order statistics\n- Monitor order status and updates\n\n**Methods:**\n\n| Method | Description | Parameters |\n|-------------------------------|----------------------|--------------------------------------------------------------------------------------------|\n| `get_customer_orders()` | Get orders | `filters` (OrderFilter) |\n| `get_customer_order()` | Get specific order | `order_id` |\n| `get_customer_order_items()` | Get order items | `filters` (ItemFilter) |\n| `get_customer_order_item()` | Get specific item | `item_id` |\n| `get_vendor_orders_parcels()` | Get orders parcels | `filters` (OrderParcelFilter) |\n| `get_order_parcel()` | Get specific parcel | `parcel_id` |\n| `get_orders_stats()` | Get order statistics | `resource_count`, `vendor_id`, `product_id`, `customer_id`, `coupon_code`, `cache_control` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.order_processing.models import OrderFilter\n\n# Get orders with filters\norders = await client.get_customer_orders(\n filters=OrderFilter(\n coupon_code=\"SAVE10\",\n cursor=\"next_cursor_123\",\n customer_ids=\"123,456,789\",\n customer_name=\"John Doe\"\n )\n)\n\n# Get specific order details\norder = await client.get_customer_order(order_id=123)\n```\n\n### Wallet Service\n\n**\ud83d\udcd6 [Full Wallet Service Documentation](docs/en/services/wallet.md)**\n\nManage user balances, expenses, and refunds with the Wallet Service. This service provides comprehensive functionality\nfor handling user financial operations.\n\n**Key Features:**\n\n- Get user balance and transaction history\n- Create and manage expenses\n- Process refunds\n- Handle credit-specific operations\n\n**Methods:**\n\n| Method | Description | Parameters |\n|--------------------------------|-------------------------------------|-------------------------------------------------------------------------------|\n| `get_balance()` | Get user's balance | `user_id`, `filters`, `x_operator_id` |\n| `get_transactions()` | Get transaction history | `user_id`, `page`, `per_page`, `x_operator_id` |\n| `create_expense()` | Create an expense | `user_id`, `request`, `x_operator_id` |\n| `create_expense_from_credit()` | Create expense from specific credit | `user_id`, `credit_id`, `request`, `x_operator_id` |\n| `get_expense()` | Get expense details | `user_id`, `expense_id`, `x_operator_id` |\n| `delete_expense()` | Delete/rollback expense | `user_id`, `expense_id`, `rollback_reason_id`, `x_operator_id` |\n| `get_expense_by_ref()` | Get expense by reference | `user_id`, `reason_id`, `reference_id`, `x_operator_id` |\n| `delete_expense_by_ref()` | Delete expense by reference | `user_id`, `reason_id`, `reference_id`, `rollback_reason_id`, `x_operator_id` |\n| `create_refund()` | Process a refund | `request`, `x_operator_id` |\n| `can_rollback_refund()` | Check if refund can be rolled back | `refund_reason`, `refund_reference_id`, `x_operator_id` |\n| `rollback_refund()` | Rollback a refund | `request`, `x_operator_id` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.wallet.models import SpendCreditRequest\n\n# Get user balance\nbalance = await client.get_balance(user_id=123)\n\n# Create an expense\nexpense = await client.create_expense(\n user_id=123,\n request=SpendCreditRequest(\n reason_id=1,\n reference_id=456,\n amount=10000,\n description=\"Payment for order #456\",\n types=[1, 2],\n settleable=True\n )\n)\n```\n\n### Search Service\n\n**\ud83d\udcd6 [Full Search Service Documentation](docs/en/services/search.md)**\n\nSearch for products and entities with the Search Service. This service provides powerful search capabilities.\n\n**Key Features:**\n\n- Search for products with advanced filters\n- Apply price ranges and category filters\n- Sort results by various criteria\n- Paginate through search results\n- Get detailed product information\n\n**Methods:**\n\n| Method | Description | Parameters |\n|---------------------|---------------------|------------|\n| `search_products()` | Search for products | `request` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.search.models import ProductSearchModel\n\n# Search for products\nresults = await client.search_products(\n request=ProductSearchModel(\n query=\"laptop\",\n category_id=123,\n min_price=100000,\n max_price=500000,\n sort_by=\"price\",\n sort_order=\"asc\",\n page=1,\n per_page=20\n )\n)\n```\n\n### Upload Service\n\n**\ud83d\udcd6 [Full Upload Service Documentation](docs/en/services/upload.md)**\n\nUpload and manage files with the Upload Service. This service provides secure file upload capabilities.\n\n**Key Features:**\n\n- Upload files securely\n- Support various file types (images, documents, videos)\n- Set custom file names and expiration times\n- Get file URLs for access\n- Manage file lifecycle\n\n**Methods:**\n\n| Method | Description | Parameters |\n|-----------------|---------------|-------------------------------------------------------------|\n| `upload_file()` | Upload a file | `file`, `file_type`, `custom_unique_name`, `expire_minutes` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.upload.models import UserUploadFileTypeEnum\n\n# Upload a file\nwith open(\"image.jpg\", \"rb\") as file:\n result = await client.upload_file(\n file=file,\n file_type=UserUploadFileTypeEnum.PRODUCT_PHOTO,\n custom_unique_name=\"my-product-image\",\n expire_minutes=1440 # 24 hours\n )\n\n print(f\"File uploaded: {result.url}\")\n```\n\n### Webhook Service\n\n**\ud83d\udcd6 [Full Webhook Service Documentation](docs/en/services/webhook.md)**\n\nManage webhook subscriptions and events with the Webhook Service. This service allows you to receive real-time\nnotifications about events happening in your Basalam account.\n\n**Key Features:**\n\n- Create and manage webhook subscriptions\n- Handle different types of events\n- Monitor webhook logs and delivery status\n- Register and unregister clients to webhooks\n\n**Methods:**\n\n| Method | Description | Parameters |\n|-----------------------------|----------------------------|----------------------------------|\n| `get_webhook_services()` | Get webhook services | None |\n| `create_webhook_service()` | Create webhook service | `request` |\n| `get_webhooks()` | Get webhooks list | `service_id`, `event_ids` |\n| `create_webhook()` | Create new webhook | `request` |\n| `update_webhook()` | Update webhook | `webhook_id`, `request` |\n| `delete_webhook()` | Delete webhook | `webhook_id` |\n| `get_webhook_events()` | Get available events | None |\n| `get_webhook_customers()` | Get webhook customers | `page`, `per_page`, `webhook_id` |\n| `get_webhook_logs()` | Get webhook logs | `webhook_id` |\n| `register_webhook()` | Register client to webhook | `request` |\n| `unregister_webhook()` | Unregister client | `request` |\n| `get_registered_webhooks()` | Get registered webhooks | `page`, `per_page`, `service_id` |\n\n**Example:**\n\n```python\nfrom basalam_sdk.webhook.models import CreateWebhookRequest\n\n# Create a new webhook\nwebhook = await client.create_webhook(\n request=CreateWebhookRequest(\n service_id=1,\n event_ids=[\"order.created\", \"payment.completed\"],\n request_method=\"POST\",\n url=\"https://your-app.com/webhook\",\n is_active=True\n )\n)\n\n# Get webhook events\nevents = await client.get_webhook_events()\n```\n\n## Async/Sync Usage\n\nAll SDK methods support both synchronous and asynchronous patterns:\n\n### Asynchronous (Recommended)\n\n```python\nasync def async_example():\n auth = PersonalToken(token=\"your-token\", refresh_token=\"your-refresh-token\")\n client = BasalamClient(auth=auth)\n\n # Async calls\n balance = await client.get_balance(user_id=123)\n webhooks = await client.get_webhooks()\n\n return balance, webhooks\n\n\n# Run async function\nresult = asyncio.run(async_example())\n```\n\n### Synchronous\n\n```python\ndef sync_example():\n auth = PersonalToken(token=\"your-token\", refresh_token=\"your-refresh-token\")\n client = BasalamClient(auth=auth)\n\n # Sync calls (note the _sync suffix)\n balance = client.get_balance_sync(user_id=123)\n webhooks = client.get_webhooks_sync()\n\n return balance, webhooks\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python client library for interacting with Basalam API services",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/basalam/python-sdk",
"Issues": "https://github.com/basalam/python-sdk/issues",
"Repository": "https://github.com/basalam/python-sdk.git"
},
"split_keywords": [
"api",
" async",
" basalam",
" client",
" e-commerce",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b23734e81fb9219627d00b625520478adf77018ee0a56ddca495543bdf2ea53c",
"md5": "292d79bc7d90bbd218ccc4818e4f52ce",
"sha256": "b97255fcfaeca1dc222d39be2be47e2f9a9cf33c93e1ab9b80860a4d0c4ca17f"
},
"downloads": -1,
"filename": "basalam_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "292d79bc7d90bbd218ccc4818e4f52ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 57512,
"upload_time": "2025-08-05T09:24:07",
"upload_time_iso_8601": "2025-08-05T09:24:07.767418Z",
"url": "https://files.pythonhosted.org/packages/b2/37/34e81fb9219627d00b625520478adf77018ee0a56ddca495543bdf2ea53c/basalam_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "49b94ac3db342d7563b658f635d7967c2a170ed41b193aa30d3b37297b479899",
"md5": "156e7850c8edc4f3e94675a2ac3d7848",
"sha256": "e5b3796855c999c79456d974bd76709d36d18e5a71f4294372f7b28c8ac38465"
},
"downloads": -1,
"filename": "basalam_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "156e7850c8edc4f3e94675a2ac3d7848",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 212673,
"upload_time": "2025-08-05T09:24:16",
"upload_time_iso_8601": "2025-08-05T09:24:16.637614Z",
"url": "https://files.pythonhosted.org/packages/49/b9/4ac3db342d7563b658f635d7967c2a170ed41b193aa30d3b37297b479899/basalam_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 09:24:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "basalam",
"github_project": "python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": [
[
">=",
"0.28.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.11.4"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.13.2"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.9.0"
]
]
},
{
"name": "Authlib",
"specs": [
[
">=",
"1.5.2"
]
]
},
{
"name": "ruff",
"specs": [
[
">=",
"0.11.10"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.23.5"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.1.0"
]
]
}
],
"lcname": "basalam-sdk"
}
JSON
