README

🔥 PHARMACY ENHANCED: Medicine Catalogue with Variants!

PHP SDK for integrating external applications (Hospital, Lab, Imaging, Insurance, Supplier Portal, etc.) with SmartMart360.

New in v2.5.0:

• 📦 PROPER AUTOLOADING: Classes separated into individual files for correct PSR-4 autoloading
• 🎯 DOCUMENT_TYPES Fully Independent: Can be imported separately from SmartMartClient
• 🔧 Enhanced Test Script: Comprehensive autoloading verification
• 📚 Improved Documentation: Clear separation of classes and usage examples

New in v2.4.0:

• 🎯 DOCUMENT TYPES NOW DEFAULT: createTransaction() uses document types by default
• 📋 Complete DOCUMENT_TYPES enum: All standard business document types included
• 🔄 Legacy TRANSACTION_TYPES: Still supported for backward compatibility

New in v2.3.0:

• Document type support for transaction creation
• Enhanced transaction creation flexibility

New in v2.7.0:

• 🏥 PHARMACY FIRST: Variants included by default for medicine catalogue
• 💊 Medicine Display Names: Variants show as "500mg Tablets (10's)" format
• 👨‍⚕️ Doctor-Friendly: Search medicines, see all variants with stock
• 🛒 Prescription Ready: Each variant includes item_variant_id for ordering
• 📱 Web Interface Optimized: Clean grouping under medicine names

New in v2.6.0:

• 🔍 Item Variants in Catalogue: include_variants=true returns item_variant_id with each item
• 📊 Per-Variant Stock Details: include_stock_details=true shows stock per variant/location
• 🎯 Enhanced getItems() Method: New parameters for variant and stock detail control
• 🛠️ getItemsWithVariants(): Convenience method for getting items with variants
• 📋 Complete Variant Information: SKU, MRP, UOM, and stock levels per variant

New in v2.5.0:

• 📦 PROPER AUTOLOADING: Classes separated into individual files for correct PSR-4 autoloading
• 🎯 DOCUMENT_TYPES Fully Independent: Can be imported separately from SmartMartClient
• 🔧 Enhanced Test Script: Comprehensive autoloading verification

New in v2.4.0:

• 🎯 DOCUMENT TYPES NOW DEFAULT: createTransaction() uses document types by default
• 📋 Complete DOCUMENT_TYPES enum: All standard business document types included
• 🔄 Legacy TRANSACTION_TYPES: Still supported for backward compatibility

New in v2.3.0:

• Document type support for transaction creation
• Enhanced transaction creation flexibility

New in v2.2.0:

• Categories API for hierarchical product organization

📦 Installation & Autoloading

Option 1: Install from Packagist (Recommended)

composer require codesbytvt/smartmart360-sdk

Option 2: Local Development Repository

If the SDK isn't published yet, add this to your composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "/path/to/smartmart360-sdk",
            "options": {
                "symlink": false
            }
        }
    ],
    "require": {
        "codesbytvt/smartmart360-sdk": "2.1.0"
    }
}

Autoloading Verification

After installation, verify autoloading works:

// This should work without require/include statements
use SmartMart\External\SmartMartClient;
use SmartMart\External\TRANSACTION_TYPES;
use SmartMart\External\PARTY_TYPES;

// Create client
$client = new SmartMartClient($url, $apiKey, $clientId, $appName);

🔧 Troubleshooting Autoloading Issues

If you get Class not found errors, try these solutions:

1. Regenerate Autoloader

# Clear composer cache
composer clear-cache

# Remove and reinstall vendor directory
rm -rf vendor/
composer install

# Or just regenerate autoload files
composer dump-autoload

2. Check Installation

# Verify package is installed
composer show codesbytvt/smartmart360-sdk

# Check autoload files exist
ls -la vendor/composer/

3. Test Autoloading Manually

Create a test file:

<?php
require_once 'vendor/autoload.php';

// Test class loading
try {
    $reflection = new ReflectionClass('SmartMart\External\SmartMartClient');
    echo "✅ SmartMartClient class found\n";
} catch (Exception $e) {
    echo "❌ SmartMartClient class not found: " . $e->getMessage() . "\n";
}

// Test constants
if (class_exists('SmartMart\External\TRANSACTION_TYPES')) {
    echo "✅ TRANSACTION_TYPES class found\n";
} else {
    echo "❌ TRANSACTION_TYPES class not found\n";
}

4. Check PHP Include Path

// Add this to your script if autoloading fails
set_include_path(get_include_path() . PATH_SEPARATOR . 'vendor/');
require_once 'vendor/autoload.php';

5. Composer.json Configuration

Ensure your composer.json has:

{
    "autoload": {
        "psr-4": {
            "Your\\App\\": "app/"
        }
    }
}

6. Web Server Configuration

For Apache/Nginx, ensure vendor/ is accessible and the autoloader is loaded in your bootstrap file.

7. PHP Version Compatibility

Ensure you're using PHP 8.1+ as required by the SDK:

php --version

8. Run Autoloader Test

Use the included test script to diagnose issues:

# Copy the test script to your project
cp vendor/codesbytvt/smartmart360-sdk/test-autoload.php .

# Run the test
php test-autoload.php

This script will check:

• ✅ Vendor autoload file exists
• ✅ Autoloader loads correctly
• ✅ SDK package is installed
• ✅ Classes are autoloaded properly
• ✅ Constants are accessible
• ✅ PHP version compatibility

Requirements

• PHP 8.1+
• ext-json

Installation

composer require codesbytvt/smartmart360-sdk

Autoloaded namespaces:

use SmartMart\External\SmartMartClient;
use SmartMart\External\DOCUMENT_TYPES;  // Primary - Document Types
use SmartMart\External\PARTY_TYPES;     // Party Types
use SmartMart\External\TRANSACTION_TYPES; // Legacy Transaction Types

All classes are in separate files for proper autoloading:

• SmartMartClient.php - Main API client
• DocumentTypes.php - Document type constants
• PartyTypes.php - Party type constants

Quick start

$client = new SmartMartClient(
    'https://api.smartmart360.com', // Base URL
    'your_api_key_here',            // API Key
    1,                              // Your client/branch ID
    'HOSPITAL'                      // Application name
);

if ($client->healthCheck()) {
    echo "Connected\n";
}

🔥 New Unified Items API

Get Items with Stock Filtering

The new getItems() method provides flexible inventory views:

// Complete catalogue (default)
$allItems = $client->getItems(['search' => 'paracetamol']);

// Only items in stock
$availableItems = $client->getItems(['search' => 'paracetamol'], 'in_stock');

// Items needing restock (below reorder level)
$lowStockItems = $client->getItems([], 'low_stock', 5);

// Out of stock items (procurement list)
$outOfStockItems = $client->getItems([], 'out_of_stock');

// With variant details (includes item_variant_id!)
$itemsWithVariants = $client->getItems(['search' => 'paracetamol'], 'all', 10, true);

// Full variant details with stock breakdown
$fullDetails = $client->getItems(['search' => 'paracetamol'], 'all', 10, true, true);

// Convenience method for variants
$variants = $client->getItemsWithVariants(['search' => 'paracetamol']);

// Pharmacy workflow - get medicines for prescriptions
$medicines = $client->getMedicineCatalogue(['search' => 'paracetamol']);

Stock Filter Options

Filter	Description	Response Includes Stock Data
'all'	Complete catalogue	❌ No
'in_stock'	Items with stock > 0	✅ Yes
'out_of_stock'	Items with stock ≤ 0	✅ Yes
'low_stock'	Items needing restock	✅ Yes

Response Format

[
    'status' => 1,
    'data' => [
        'records' => [
            [
                'id' => 123,
                'name' => 'Paracetamol 500mg',
                'code' => 'PARA500',
                'categoryName' => 'Medicine',
                'brandName' => 'Generic',
                // Stock data (only when stock_filter ≠ 'all')
                'current_stock' => 25.5,
                'stock_value' => 637.50
            ]
        ],
        'totalRecords' => 150,
        'page' => 1,
        'pageLength' => 50
    ]
]

Legacy Methods (Still Supported)

// These still work but use the new unified API internally
$catalog = $client->getItemCatalog(['search' => 'medicine']);
$stockReport = $client->getStockReport(['search' => 'paracetamol']);
$lowStock = $client->getLegacyLowStockItems();

📂 Categories API

Get Item Categories

Get the complete list of item categories for catalog management:

// Get all categories
$categories = $client->getCategories();

// Get subcategories of a parent category
$subCategories = $client->getCategories(['parent_id' => 5]);

// Search categories
$categories = $client->getCategories(['search' => 'medicine']);

// Paginated results
$categories = $client->getCategories(['page' => 1, 'pageLength' => 50]);

Response Structure:

[
    'status' => 1,
    'data' => [
        'records' => [
            [
                'id' => 1,
                'name' => 'Medicines',
                'code' => 'MED',
                'parentName' => null,  // Top-level category
                'created_at' => '2025-01-15 10:30:00'
            ],
            [
                'id' => 5,
                'name' => 'Pain Relief',
                'code' => 'PAIN',
                'parentName' => 'Medicines',  // Subcategory
                'created_at' => '2025-01-15 11:00:00'
            ]
        ],
        'totalRecords' => 25,
        'page' => 1,
        'pageLength' => 50
    ]
]

Use Cases:

• Build category dropdowns in your application
• Filter items by category
• Create hierarchical category navigation
• Sync category structure with your system

Request & response shape

• Headers are auto-added: X-API-Key, X-Client-ID, X-Application-Source.
• All methods return the same envelope:

// success
['status' => 1, 'data' => [...], 'error' => [], 'infoDtls' => []];
// error
['status' => 0, 'data' => [], 'error' => 'message' or ['field' => 'error'], 'http_code' => 400];

Data contracts

• OpenAPI spec: openapi.yaml
• JSON examples: docs/examples/*.json
  • create-transaction-request.json
  • create-transaction-response.json
  • party-sync-request.json
  • payment-request.json
  • invoice-response.json
  • party-statement-response.json

🏥 Pharmacy Prescription Workflow

Medicine Catalogue & Prescription Creation

// 1. Doctor searches for medicine
$medicines = $client->getMedicineCatalogue(['search' => 'paracetamol']);

// Returns: Paracetamol with all variants (500mg tabs, 250mg tabs, syrup, etc.)
foreach ($medicines['data']['records'] as $medicine) {
    echo "Medicine: {$medicine['name']}\n";
    foreach ($medicine['variants'] as $variant) {
        echo "  - {$variant['display_name']} ({$variant['stock']} in stock)\n";
        echo "    Variant ID: {$variant['id']} (use for prescription)\n";
    }
}

// 2. Doctor selects variant and creates prescription
$prescription = $client->createTransaction(
    DOCUMENT_TYPES::SALES_INVOICE,
    'RX-12345',
    $patientId,
    [
        [
            'item_variant_id' => $selectedVariantId,  // From catalogue
            'quantity' => 10,
            'rate' => $variant['mrp']
        ]
    ]
);

Example Response Structure

{
  "status": 1,
  "data": {
    "records": [
      {
        "id": 123,
        "name": "Paracetamol",
        "categoryName": "Analgesics",
        "variants": [
          {
            "id": 456,
            "display_name": "500mg Tablets",    // Auto-generated from SKU parsing
            "sku": "PARA500-TAB",
            "mrp": 25.00,
            "stock": 150,
            "in_stock": true
          },
          {
            "id": 457,
            "display_name": "250mg Tablets",    // Auto-generated from SKU parsing
            "sku": "PARA250-TAB",
            "mrp": 15.00,
            "stock": 200,
            "in_stock": true
          },
          {
            "id": 458,
            "display_name": "120mg/5ml Syrup",   // Auto-generated from SKU parsing
            "sku": "PARA120-SYP",
            "mrp": 45.00,
            "stock": 25,
            "in_stock": true
          }
        ]
      }
    ]
  }
}

Display Name Generation:

• Parses SKU patterns like PARA500-TAB → 500mg Tablets
• Supports common pharmacy forms: Tablets, Capsules, Syrup, Injection, Cream, etc.
• Extracts strength information (500mg, 120mg/5ml, etc.)
• Falls back to SKU or barcode if parsing fails

Request & response shape

Using Document Type (RECOMMENDED - Primary Approach):

$txn = $client->createTransaction(
    DOCUMENT_TYPES::SALES_INVOICE,   // Document type (primary approach)
    'RX-12345',                      // your reference
    'hosp_pat_12345',                // external party id
    [
        [
            'item_variant_id' => 123, // OR 'item_id' => 456 (auto-converts to default variant)
            'quantity' => 2,
            'uom_id' => 1,             // Optional: auto-filled from variant
            'rate' => 25.00
        ]
    ],
    [
        'party_type_id' => 9,        // PATIENT type
        'notes' => 'Urgent prescription'
    ]
    // useTransactionType defaults to false (document type mode)
);

Using Transaction Type (Legacy - Only if needed):

$txn = $client->createTransaction(
    TRANSACTION_TYPES::SALES,        // Transaction type ID (legacy approach)
    'RX-12345',                      // your reference
    'hosp_pat_12345',                // external party id
    [
        [
            'item_variant_id' => 123, // OR 'item_id' => 456 (auto-converts to default variant)
            'quantity' => 2,
            'uom_id' => 1,             // Optional: auto-filled from variant
            'rate' => 25.00
        ]
    ],
    [
        'party_type_id' => 9,        // PATIENT type
        'notes' => 'Urgent prescription'
    ],
    true                            // useTransactionType = true
);

Sample success response:

[
  'status' => 1,
  'data' => [
    'transaction_id' => 9876,
    'external_reference_id' => 'RX-12345',
    'status' => 'created'
  ]
]

Common operations

Catalog & items

// Browse items with stock filtering
$client->getItems(['search' => 'paracetamol', 'page' => 1]);
$client->searchItems('paracetamol 500mg');
$client->getItem(123);
$client->checkStock(123, $locationId);

// Get items for specific document type (RECOMMENDED)
$items = $client->getItemsForTransaction(DOCUMENT_TYPES::SALES_INVOICE, $locationId);

// Get items for legacy transaction type (Only if needed)
$items = $client->getItemsForTransaction(25, $locationId, true); 

Parties (customers, suppliers, patients, doctors, etc.)

$client->createOrSyncParty('hosp_pat_12345', PARTY_TYPES::PATIENT, [
    'name' => 'John Doe',
    'phone' => '+919876543210'
], 'MRN-789');

$client->searchPartyByReference('MRN-789', PARTY_TYPES::PATIENT);
$client->getPartyDues($partyLinkId);
$client->getPartyStatement($partyLinkId, '2025-01-01', '2025-01-31');

Transactions

$client->createTransaction(...);                  // create order
$client->getTransaction($transactionId);          // fetch by id
$client->getTransactionByReference('RX-12345');   // fetch by your ref
$client->getTransactionStatus($transactionId);    // status
$client->listTransactions(['from_date' => '2025-01-01', 'to_date' => '2025-01-31']);
$client->cancelTransaction($transactionId, 'reason here');
$client->updateTransactionStatus($transactionId, 5, 'In transit'); // example status id

Billing & payments

$client->getInvoice($transactionId);
$client->getInvoicePDF($transactionId);
$client->recordPayment($transactionId, 1500.00, [
    'payment_mode' => 'Insurance Claim',
    'reference_no' => 'CLAIM-12345',
]);
$client->getPaymentHistory($partyLinkId, '2025-01-01', '2025-01-31');
$client->getOutstandingBills($partyLinkId);

Reports

// Get transaction summary for a date range
$client->getTransactionSummary('2025-01-01', '2025-01-31');

// Filter summary by document type (RECOMMENDED)
$client->getTransactionSummary('2025-01-01', '2025-01-31', ['document_type_id' => DOCUMENT_TYPES::SALES_INVOICE]);

// Filter summary by legacy transaction type
$client->getTransactionSummary('2025-01-01', '2025-01-31', ['transaction_type_id' => 25]);

$client->getStockReport(['location_id' => 1]);
$client->getLowStockItems();

Reference values

Party types

PARTY_TYPES::CUSTOMER  // 1
PARTY_TYPES::SUPPLIER  // 2
PARTY_TYPES::EMPLOYEE  // 3
PARTY_TYPES::PATIENT   // 9
PARTY_TYPES::DOCTOR    // 10
PARTY_TYPES::LAB       // 11
PARTY_TYPES::INSURANCE // 12

Transaction types

TRANSACTION_TYPES::PURCHASE_ORDER   // 2
TRANSACTION_TYPES::PURCHASE         // 3
TRANSACTION_TYPES::SALES_ORDER      // 24
TRANSACTION_TYPES::SALES            // 25
TRANSACTION_TYPES::PURCHASE_RETURN  // 13
TRANSACTION_TYPES::SALES_RETURN     // 14
TRANSACTION_TYPES::STOCK_OPENING    // 12
TRANSACTION_TYPES::STOCK_ADJUSTMENT // 10

Testing

composer install
./vendor/bin/phpunit

Best practices

• Always check status === 1 before using data.
• Add retries for transient failures.
• Cache catalog/stock when possible.
• Use reference codes (MRN, vendor code, prescription id) consistently.
• Run healthCheck() before critical flows to validate connectivity.