# API Documentation

This directory contains comprehensive API documentation for the Multi-Tenant SaaS Platform for Malaysian SMEs.

## Table of Contents

- [Core API](./core/README.md) - Authentication, tenants, users, subscriptions
- [Retail Module API](./retail/README.md) - Products, sales, inventory, customer management
- [Healthcare Module API](./healthcare/README.md) - Patients, appointments, medical records
- [Education Module API](./education/README.md) - Students, classes, enrollment
- [Logistics Module API](./logistics/README.md) - Shipments, vehicles, tracking
- [Beauty Module API](./beauty/README.md) - Clients, services, appointments

## API Standards

### Base URL
```
https://api.yourplatform.com/v1
```

### Authentication
All API endpoints require authentication using Bearer tokens:
```
Authorization: Bearer <your-access-token>
```

### Response Format
All responses follow this standard format:

```json
{
  "success": true,
  "data": {},
  "message": "Success message",
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456789"
}
```

### Error Handling
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Detailed error message",
    "details": {}
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456789"
}
```

### HTTP Status Codes
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `429` - Rate Limited
- `500` - Internal Server Error

### Multi-Tenant Headers
All requests must include the tenant identifier:
```
X-Tenant-ID: <tenant-id>
```

### Rate Limiting
- Standard endpoints: 100 requests per minute
- Auth endpoints: 10 requests per minute
- File upload endpoints: 20 requests per minute

## Malaysian Market Features

### SST (Sales and Service Tax)
All pricing-related endpoints include SST calculation and display:
```json
{
  "subtotal": 100.00,
  "sst_rate": 0.06,
  "sst_amount": 6.00,
  "total": 106.00
}
```

### Malaysian Phone Validation
Phone numbers are validated according to Malaysian formats:
- `+60123456789` or `0123456789`
- Mobile numbers: `01[2-46-9]`

### Business Registration
All tenant endpoints validate Malaysian business registration numbers.

### Malaysian Timezone
All timestamps are in `Asia/Kuala_Lumpur` timezone.

## Getting Started

1. [Obtain API credentials](./core/authentication.md)
2. [Create your first tenant](./core/tenants.md)
3. [Set up your modules](./core/modules.md)
4. [Explore module-specific APIs](./retail/README.md)

## SDKs

We provide official SDKs for:
- [Python SDK](../sdks/python/README.md)
- [JavaScript SDK](../sdks/javascript/README.md)
- [PHP SDK](../sdks/php/README.md)

## Support

For API support:
- Email: api-support@yourplatform.com
- Documentation: https://docs.yourplatform.com
- Status Page: https://status.yourplatform.com