SIHA API Documentation

Welcome to the SIHA (Smart Inventory & Handling Automation) API documentation. This guide provides comprehensive documentation for all available API endpoints to help you integrate with our platform.

Table of Contents

• Getting Started
  • Registration
  • Authentication
  • Base URL
  • Headers
• API Endpoints
  • Authentication
  • User Management
  • Inventory
  • Orders & Deliveries
  • Payments
  • Operations
  • Settings
• Error Handling
• Rate Limiting
• Webhooks
• Support

Getting Started

Registration

Before using the API, you need to register as a vendor:

1. Visit the vendor registration page
2. Fill in your business details
3. Verify your email address
4. Log in to your vendor dashboard
5. Navigate to API Settings in your SIHA dashboard to generate your API key

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer your_api_key_here

Base URL

All API endpoints are relative to the base URL:

https://api.siha.africa/v1

Headers

Include the following headers in all requests:

Content-Type: application/json
Accept: application/json
Authorization: Bearer your_api_key_here

API Endpoints

Authentication

Vendor Login

POST /auth/vendor/login

Request Body:

{
    "email": "vendor@example.com",
    "password": "your_secure_password"
}

Response:

{
    "user": {
        "id": "user_123",
        "name": "Vendor Name",
        "email": "vendor@example.com",
        "role": "vendor",
        "permissions": ["inventory:read", "inventory:write", "orders:manage"]
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Mobile App Login

POST /auth/app/login

Request Body:

{
    "email": "user@example.com",
    "password": "your_secure_password"
}

Response:

{
    "user": {
        "id": "user_456",
        "name": "App User",
        "email": "user@example.com",
        "role": "customer"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Password Reset Request

POST /auth/recover

Request Body:

{
    "email": "user@example.com"
}

Response:

{
    "message": "Password reset link has been sent to your email",
    "status": "success"
}

Reset Password

POST /auth/reset

Request Body:

{
    "token": "reset_token_from_email",
    "email": "user@example.com",
    "password": "new_secure_password",
    "password_confirmation": "new_secure_password"
}

Response:

{
    "message": "Password has been reset successfully",
    "status": "success"
}

User Management

User Roles and Permissions

SIHA supports multiple user roles with different permission levels:

Get User Profile

GET /users/{id}

Headers:

• Authorization: Bearer your_api_key_here

Response:

{
    "id": "user_123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+254712345678",
    "avatar": "https://api.siha.africa/storage/avatars/123.jpg",
    "role": "vendor",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "last_login": "2025-07-28T08:45:12Z",
    "permissions": [
        "inventory:read",
        "inventory:write",
        "orders:create",
        "orders:view"
    ]
}

Update User Profile

PUT /users/{id}

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body:

{
    "name": "John Updated",
    "phone": "+254712345679",
    "current_password": "current_secure_password",
    "new_password": "new_secure_password"
}

Response:

{
    "message": "Profile updated successfully",
    "user": {
        "id": "user_123",
        "name": "John Updated",
        "email": "john@example.com",
        "phone": "+254712345679",
        "avatar": "https://api.siha.africa/storage/avatars/123.jpg"
    }
}

Upload Profile Picture

POST /users/account/update/avatar/{id}

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: multipart/form-data

Form Data:

• avatar: (File) Image file (JPG, PNG, max 5MB)

Response:

{
    "message": "Profile picture updated successfully",
    "avatar_url": "https://api.siha.africa/storage/avatars/123_updated.jpg"
}

Get User Notifications

GET /users/notifications

Headers:

• Authorization: Bearer your_api_key_here

Query Parameters:

• unread_only (boolean): Return only unread notifications
• limit (number): Number of notifications to return (default: 10)
• page (number): Page number for pagination

Response:

{
    "data": [
        {
            "id": "notif_123",
            "type": "order_status",
            "title": "Order Shipped",
            "message": "Your order #ORD-12345 has been shipped.",
            "read": false,
            "data": {
                "order_id": "order_123",
                "status": "shipped"
            },
            "created_at": "2025-07-28T10:30:00Z"
        }
    ],
    "meta": {
        "total": 15,
        "unread_count": 3,
        "current_page": 1,
        "last_page": 2
    }
}

Inventory Management

Product Management

List All Products

GET /inventory/products

Headers:

• Authorization: Bearer your_api_key_here

Query Parameters:

• category (string, optional): Filter by category ID
• search (string, optional): Search term for product name, SKU, or description
• status (string, optional): Filter by status (active/inactive)
• min_price (number, optional): Minimum price filter
• max_price (number, optional): Maximum price filter
• in_stock (boolean, optional): Only show in-stock items
• sort_by (string, optional): Field to sort by (name, price, created_at, etc.)
• order (string, optional): Sort order (asc/desc)
• page (number, optional): Page number (default: 1)
• limit (number, optional): Items per page (default: 20, max: 100)

Response:

{
    "data": [
        {
            "id": "prod_123",
            "name": "Premium Wireless Headphones",
            "sku": "AUD-1001",
            "price": 199.99,
            "sale_price": 179.99,
            "stock_quantity": 50,
            "category_name": "Audio",
            "status": "active"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 5,
        "total_items": 87,
        "per_page": 20
    }
}

Get Product Details

GET /inventory/products/{id}

Headers:

• Authorization: Bearer your_api_key_here

Response:

{
    "id": "prod_123",
    "name": "Premium Wireless Headphones",
    "sku": "AUD-1001",
    "description": "High-quality wireless headphones with noise cancellation",
    "price": 199.99,
    "sale_price": 179.99,
    "stock_quantity": 50,
    "category_id": "cat_audio_123",
    "category_name": "Audio",
    "images": [
        "https://api.siha.africa/storage/products/headphones_1.jpg"
    ],
    "status": "active"
}

Create New Product

POST /inventory/products

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body:

{
    "name": "New Premium Headphones",
    "sku": "AUD-1002",
    "description": "Latest model with improved battery life",
    "price": 229.99,
    "cost_price": 150.00,
    "sale_price": 209.99,
    "stock_quantity": 100,
    "category_id": "cat_audio_123",
    "barcode": "123456789036",
    "weight": 0.3,
    "status": "active"
}

Response:

{
    "message": "Product created successfully",
    "product_id": "prod_124"
}

Update Product

PUT /inventory/products/{id}

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body: (Partial updates supported)

{
    "price": 239.99,
    "sale_price": 219.99,
    "stock_quantity": 85,
    "status": "active"
}

Response:

{
    "message": "Product updated successfully",
    "product_id": "prod_124"
}

Delete Product

DELETE /inventory/products/{id}

Headers:

• Authorization: Bearer your_api_key_here

Response:

{
    "message": "Product deleted successfully",
    "product_id": "prod_124"
}

Orders & Deliveries

Order Management

Create New Order

POST /deliveries/orders

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body:

{
    "customer_id": "cust_123",
    "customer_name": "John Doe",
    "customer_phone": "+254712345678",
    "customer_email": "john@example.com",
    "shipping_address": {
        "street": "123 Main St",
        "city": "Nairobi",
        "state": "Nairobi",
        "postal_code": "00100",
        "country": "Kenya",
        "notes": "Ring the bell twice"
    },
    "billing_address_same": true,
    "items": [
        {
            "product_id": "prod_123",
            "variant_id": "var_456",
            "quantity": 2,
            "unit_price": 99.99,
            "notes": "Gift wrapping required"
        }
    ],
    "payment_method": "mpesa",
    "shipping_method": "standard",
    "discount_code": "SUMMER10",
    "notes": "Handle with care"
}

Response:

{
    "id": "order_ORD-2025-1234",
    "order_number": "ORD-2025-1234",
    "status": "pending_payment",
    "total_amount": 199.98,
    "subtotal": 199.98,
    "shipping_cost": 10.00,
    "tax_amount": 30.00,
    "discount_amount": 0.00,
    "grand_total": 239.98,
    "currency": "KES",
    "customer_id": "cust_123",
    "shipping_address": {
        "street": "123 Main St",
        "city": "Nairobi",
        "state": "Nairobi",
        "postal_code": "00100",
        "country": "Kenya"
    },
    "items": [
        {
            "id": "item_789",
            "product_id": "prod_123",
            "product_name": "Premium Wireless Headphones",
            "variant_id": "var_456",
            "variant_name": "Black",
            "sku": "AUD-1001-BLK",
            "quantity": 2,
            "unit_price": 99.99,
            "total_price": 199.98,
            "image_url": "https://api.siha.africa/storage/products/headphones_1.jpg"
        }
    ],
    "payment_status": "pending",
    "shipping_status": "pending",
    "created_at": "2025-07-28T14:30:00Z",
    "updated_at": "2025-07-28T14:30:00Z"
}

Get Order Details

GET /deliveries/orders/{order_id}

Headers:

• Authorization: Bearer your_api_key_here

Response:

{
    "id": "order_ORD-2025-1234",
    "order_number": "ORD-2025-1234",
    "status": "processing",
    "total_amount": 239.98,
    "customer_details": {
        "id": "cust_123",
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+254712345678"
    },
    "shipping_address": {
        "street": "123 Main St",
        "city": "Nairobi",
        "state": "Nairobi",
        "postal_code": "00100",
        "country": "Kenya"
    },
    "items": [
        {
            "id": "item_789",
            "product_id": "prod_123",
            "product_name": "Premium Wireless Headphones",
            "variant_id": "var_456",
            "variant_name": "Black",
            "sku": "AUD-1001-BLK",
            "quantity": 2,
            "unit_price": 99.99,
            "total_price": 199.98
        }
    ],
    "payments": [
        {
            "id": "pay_123",
            "amount": 239.98,
            "payment_method": "mpesa",
            "transaction_id": "MPE2345678",
            "status": "completed",
            "paid_at": "2025-07-28T14:35:22Z"
        }
    ],
    "shipping": {
        "method": "standard",
        "tracking_number": "SHIP-123-456-789",
        "carrier": "SIHA Logistics",
        "status": "shipped",
        "estimated_delivery": "2025-08-02T00:00:00Z"
    },
    "timeline": [
        {
            "status": "order_placed",
            "timestamp": "2025-07-28T14:30:00Z",
            "message": "Order placed"
        },
        {
            "status": "payment_received",
            "timestamp": "2025-07-28T14:35:22Z",
            "message": "Payment received via M-Pesa"
        },
        {
            "status": "order_processing",
            "timestamp": "2025-07-28T15:10:05Z",
            "message": "Order is being processed"
        },
        {
            "status": "order_shipped",
            "timestamp": "2025-07-29T09:15:33Z",
            "message": "Order has been shipped"
        }
    ],
    "created_at": "2025-07-28T14:30:00Z",
    "updated_at": "2025-07-29T09:15:33Z"
}

List Orders

GET /deliveries/orders

Headers:

• Authorization: Bearer your_api_key_here

Query Parameters:

• status (string, optional): Filter by order status
• customer_id (string, optional): Filter by customer ID
• start_date (string, optional): Filter by order date (ISO 8601 format)
• end_date (string, optional): Filter by order date (ISO 8601 format)
• sort_by (string, optional): Field to sort by (created_at, total_amount, etc.)
• order (string, optional): Sort order (asc/desc)
• page (number, optional): Page number (default: 1)
• limit (number, optional): Items per page (default: 20, max: 100)

Response:

{
    "data": [
        {
            "id": "order_ORD-2025-1234",
            "order_number": "ORD-2025-1234",
            "status": "processing",
            "total_amount": 239.98,
            "customer_name": "John Doe",
            "item_count": 2,
            "created_at": "2025-07-28T14:30:00Z",
            "payment_status": "paid",
            "shipping_status": "processing"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 5,
        "total_items": 87,
        "per_page": 20,
        "stats": {
            "pending": 12,
            "processing": 8,
            "shipped": 45,
            "delivered": 22,
            "cancelled": 3
        }
    }
}

Update Order Status

PATCH /deliveries/orders/{order_id}/status

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body:

{
    "status": "shipped",
    "tracking_number": "SHIP-123-456-789",
    "carrier": "SIHA Logistics",
    "notes": "Package handed over to logistics partner"
}

Response:

{
    "message": "Order status updated successfully",
    "order_id": "order_ORD-2025-1234",
    "new_status": "shipped",
    "tracking_number": "SHIP-123-456-789"
}

Delivery Management

Create Delivery Assignment

POST /deliveries/dispatchs

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body:

{
    "order_id": "order_ORD-2025-1234",
    "rider_id": "rider_123",
    "pickup_location": "Nairobi Warehouse",
    "pickup_contact": "John Manager (0722123456)",
    "delivery_notes": "Call customer before delivery",
    "estimated_pickup_time": "2025-07-29T10:00:00Z",
    "estimated_delivery_time": "2025-07-29T14:00:00Z"
}

Response:

{
    "message": "Delivery assignment created successfully",
    "delivery_id": "del_789",
    "tracking_url": "https://track.siha.com/deliveries/del_789"
}

Update Delivery Status

PATCH /deliveries/dispatchs/{delivery_id}/status

Headers:

• Authorization: Bearer your_api_key_here
• Content-Type: application/json

Request Body:

{
    "status": "out_for_delivery",
    "location": {
        "latitude": -1.2921,
        "longitude": 36.8219
    },
    "notes": "Package picked up from warehouse"
}

Response:

{
    "message": "Delivery status updated successfully",
    "delivery_id": "del_789",
    "new_status": "out_for_delivery",
    "updated_at": "2025-07-29T10:15:30Z"
}

Payments

Process MPESA Payment

POST /finance/mpesa/process

Request Body:

{
    "order_id": "order_123",
    "phone_number": "254712345678",
    "amount": 199.98
}

Response:

{
    "status": "pending",
    "checkout_request_id": "ws_CO_28072025124512345678",
    "merchant_request_id": "1000-12345678-01"
}

Operations

List Cities

GET /operation/zone/cities

Response:

[
    {
        "id": "city_1",
        "name": "Nairobi",
        "zone": {
            "id": "zone_1",
            "name": "East Africa"
        }
    }
]

Settings

Get Setting by Name

GET /preference/settings/name?name=currency

Response:

{
    "name": "currency",
    "value": "KES",
    "type": "general",
    "description": "Default currency"
}

Error Handling

Error Responses

All error responses follow this format:

{
    "error": {
        "code": "error_code",
        "message": "Human-readable error message",
        "details": {
            "field": "Specific error details"
        }
    }
}

Common Error Codes

Rate Limiting

• Rate Limit: 100 requests per minute per API key
• Response Headers:
  • X-RateLimit-Limit: Request limit
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Time when limit resets (UTC timestamp)

Webhooks

Available Webhook Events

• order.created
• order.updated
• payment.received
• payment.failed

Webhook Payload Example

{
    "event": "order.created",
    "data": {
        "id": "order_123",
        "status": "pending",
        "amount": 199.98
    },
    "created_at": "2025-07-28T12:00:00Z",
    "webhook_id": "wh_123"
}

Support

For any questions or issues, please contact our support team:

• Email: info@siha.africa
• Phone: +254 791222838
• Documentation: https://siha.africa/docs
• Vendor Portal: https://siha.africa/account/vendor/register

Last Updated: July 28, 2025