README

Introduction

Welcome to the Basalam PHP SDK - a comprehensive client library for interacting with Basalam API services. This SDK provides a clean, developer-friendly interface for all Basalam services. Whether you're building a server-to-server integration or a user-facing application, this SDK provides the tools you need.

Supported PHP Versions: PHP 8.0+, PHP 8.1+, PHP 8.2+, PHP 8.3+

Key Features:

• Type Safety: Built with strict typing 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
• Installation
• Quick Start
• Authentication
• Services
  • Core Service
  • Chat Service
  • Order Service
  • Order Processing Service
  • Wallet Service
  • Search Service
  • Upload Service
  • Webhook Service
  • Shipping Service
  • Story Service
  • Apps Service
• License

Installation

📖 Full Introduction Documentation

Install the SDK using composer:

composer require basalam/php-sdk

Quick Start

1. Import the SDK

use Basalam\BasalamClient;
use Basalam\Auth\PersonalToken;

2. Set up Authentication

// Personal Token (Token-based authentication)
$auth = new PersonalToken(
    token: "your-access-token",
    refreshToken: "your-refresh-token"
);

3. Create the Client

$client = new BasalamClient(auth: $auth);

4. Your First API Calls

function main()
{
    // Setup
    $auth = new PersonalToken(
        token: "your-access-token",
        refreshToken: "your-refresh-token"
    );
    $client = new BasalamClient(auth: $auth);

    // Get products
    $products = $client->getProducts();
    echo "Found " . count($products) . " products\n";

    // Print first few products
    foreach (array_slice($products, 0, 3) as $product) {
        echo "Product: {$product->getName()} - Price: {$product->getPrice()}\n";
    }

    return $products;
}

// Run the function
$result = main();

Authentication

📖 Full Authentication Documentation

The SDK supports three main authentication methods:

Personal Token (For Existing Tokens)

Use this method when you already have valid access and refresh tokens:

use Basalam\BasalamClient;
use Basalam\Auth\PersonalToken;

$auth = new PersonalToken(
    token: "your_existing_access_token",
    refreshToken: "your_existing_refresh_token"
);

$client = new BasalamClient(auth: $auth);

Authorization Code Flow (For User Authentication)

Use this method when you need to authenticate on behalf of a user:

use Basalam\BasalamClient;
use Basalam\Auth\AuthorizationCode;
use Basalam\Auth\Scope;

// Create auth object
$auth = new AuthorizationCode(
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    redirectUri: "https://your-app.com/callback",
    scopes: [Scope::CUSTOMER_WALLET_READ, Scope::CUSTOMER_ORDER_READ]
);

// Get authorization URL
$authUrl = $auth->getAuthorizationUrl(state: "optional_state_parameter");
echo "Visit: {$authUrl}\n";

// Exchange code for tokens (after user authorization)
$tokenInfo = $auth->getToken(code: "authorization_code_from_callback");

// Create authenticated client
$client = new BasalamClient(auth: $auth);

Client Credentials (For Server-to-Server)

Use this method for server-to-server applications:

use Basalam\BasalamClient;
use Basalam\Auth\ClientCredentials;
use Basalam\Auth\Scope;

$auth = new ClientCredentials(
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    scopes: [Scope::CUSTOMER_WALLET_READ, Scope::VENDOR_PRODUCT_WRITE]
);

$client = new BasalamClient(auth: $auth);

Services

The SDK provides access to all Basalam services through a unified client interface.

Core Service

📖 Full Core Service Documentation

Manage vendors, products, 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), product price-history and reminders, update user verification and information, handle bank account operations, and manage categories and attributes.

Deprecation: the shipping-methods helpers on this service (getShippingMethods(), getDefaultShippingMethods(), getWorkingShippingMethods(), updateShippingMethods()) are deprecated — the underlying endpoints were removed from the API. Use the new Shipping Service ($client->shipping) instead.

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:

Example:

use Basalam\Core\Models\CreateVendorSchema;

// Create a new vendor
$vendor = $client->createVendor(
    userId: 123,
    request: new CreateVendorSchema([
        'title' => "My Store",
        'identifier' => "store123",
        'category_type' => 1,
        'city' => 1,
        'summary' => "A great store for all your needs"
    ])
);

// Get vendor details
$vendorDetails = $client->getVendor(vendorId: $vendor->getId());

Chat Service

📖 Full Chat Service Documentation

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:

Example:

use Basalam\Chat\Models\MessageRequest;

// Create a message
$message = $client->createMessage(
    request: new MessageRequest([
        'chat_id' => 123,
        'content' => "Hello, how can I help you?",
        'message_type' => "text"
    ]),
    userAgent: "MyApp/1.0",
    xClientInfo: "web"
);

// Get messages from a chat
$messages = $client->getMessages(
    chatId: 123,
    limit: 20,
    order: "DESC"
);

Order Service

📖 Full Order Service Documentation

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:

Example:

use Basalam\Order\Models\CreatePaymentRequestModel;

// Get active baskets
$baskets = $client->getBaskets(refresh: true);

// Create payment for invoice
$payment = $client->createInvoicePayment(
    invoiceId: 123,
    request: new CreatePaymentRequestModel([
        'payment_method' => "credit_card",
        'amount' => 10000
    ])
);

Order Processing Service

📖 Full Order Processing Service Documentation

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:

Example:

use Basalam\OrderProcessing\Models\OrderFilter;

// Get orders with filters
$orders = $client->getCustomerOrders(
    filters: new OrderFilter([
        'coupon_code' => "SAVE10",
        'cursor' => "next_cursor_123",
        'customer_ids' => "123,456,789",
        'customer_name' => "John Doe"
    ])
);

// Get specific order details
$order = $client->getCustomerOrder(orderId: 123);

Wallet Service

📖 Full Wallet Service Documentation

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 | |-------------------------|-----------------------------|--------------------------------------------------------------------- --| | getBalance() | Get user's balance | userId, filters, xOperatorId | | getTransactions() | Get transaction history | userId, page, perPage, xOperatorId | | createExpense() | Create an expense | userId, request, xOperatorId | | getExpense() | Get expense details | userId, expenseId, xOperatorId | | deleteExpense() | Delete/rollback expense | userId, expenseId, rollbackReasonId, xOperatorId | | getExpenseByRef() | Get expense by reference | userId, reasonId, referenceId, xOperatorId | | deleteExpenseByRef() | Delete expense by reference | userId, reasonId, referenceId, rollbackReasonId, xOperatorId |

Example:

use Basalam\Wallet\Models\SpendCreditRequest;

// Get user balance
$balance = $client->getBalance(userId: 123);

// Create an expense
$expense = $client->createExpense(
    userId: 123,
    request: new 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

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:

Example:

use Basalam\Search\Models\ProductSearchModel;

// Search for products
$results = $client->searchProducts(
    request: new 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

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:

Example:

use Basalam\Upload\Models\UserUploadFileTypeEnum;

// Upload a file
$result = $client->uploadFile(
    file: "image.jpg",
    fileType: UserUploadFileTypeEnum::PRODUCT_PHOTO,
    customUniqueName: "my-product-image",
    expireMinutes: 1440  // 24 hours
);

echo "File uploaded: {$result->getUrl()}\n";

Webhook Service

📖 Full Webhook Service Documentation

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:

Example:

use Basalam\Webhook\Models\CreateWebhookRequest;

// Create a new webhook
$webhook = $client->createWebhook(
    request: new 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 = $client->getWebhookEvents();

Shipping Service

📖 Full Shipping Service Documentation

Manage the new logistics stack with the Shipping Service: shipping profiles, zones, carriers, carrier-rates, own-rates, profile-products, and free-shipping rules.

Note: This replaces the old shipping-methods endpoints that lived on the Core Service. Those Core methods (getShippingMethods(), getDefaultShippingMethods(), getWorkingShippingMethods(), updateShippingMethods()) are now deprecated — use $client->shipping instead.

Key Features:

• Create, read, update and delete shipping profiles and zones
• Manage carriers, carrier-rates and vendor own-rates
• Configure free-shipping rules per profile product
• Query delivery estimates and locations

// List a vendor's shipping profiles
$profiles = $client->shipping->readVendorProfiles(page: 1, perPage: 20, vendorId: 123);

// Create a profile
use Basalam\Shipping\Models\CreateProfileRequest;
$profile = $client->shipping->createProfile(new CreateProfileRequest('My Profile', 123));

// Read available carriers
$carriers = $client->shipping->readCarriers();

Story Service

📖 Full Story Service Documentation

Create and explore stories, reels, and feeds with the Story Service.

Key Features:

• Create stories and reels
• List your own / a user's reels and stories
• Story discovery and hashtag feeds
• Like reels

// Get your stories
$stories = $client->story->myStories(count: 10);

// Story discovery feed
$discovery = $client->story->discovery();

// Hashtag feed
$feed = $client->story->hashtagFeed(hashtag: 'basalam');

Apps Service

📖 Full Apps Service Documentation

Handle Appstore payments and subscriptions with the Apps Service: payment methods, transactions, verification, pre-transactions, plans, and plan subscriptions.

Key Features:

• List payment methods and transactions
• Inquiry and verify transactions
• Create pre-transactions
• List plans and plan subscriptions

// List available plans
$plans = $client->apps->listPlans();

// List transactions
$transactions = $client->apps->listTransactions(page: 1, perPage: 20);

// Verify a transaction
$result = $client->apps->verifyTransaction(hashId: "abc123");

License

This project is licensed under the MIT License - see the LICENSE file for details.