alrahma_sunday_school/API_DOCUMENTATION.md

# Al Rahma Sunday School API Documentation

## Overview

This API provides RESTful endpoints for mobile app integration with the Al Rahma Sunday School backend. All endpoints follow RESTful conventions and return JSON responses.

**Base URL**: `https://your-domain.com/api/v1`

**API Version**: v1

## Table of Contents

1. [Authentication](#authentication)
2. [Response Format](#response-format)
3. [Error Handling](#error-handling)
4. [Pagination](#pagination)
5. [Endpoints](#endpoints)
   - [Authentication](#authentication-endpoints)
   - [User & Profile](#user--profile)
   - [Messaging](#messaging)
   - [Students](#students)
   - [Parents](#parents)
   - [Classes](#classes)
   - [Attendance](#attendance)
   - [Scores & Grades](#scores--grades)
   - [Payments & Invoices](#payments--invoices)
   - [Notifications](#notifications)
   - [Events & Calendar](#events--calendar)
   - [Dashboard](#dashboard)
   - [Homework & Assignments](#homework--assignments)
   - [Quizzes & Exams](#quizzes--exams)
   - [And more...](#additional-endpoints)
6. [Public Endpoints](#public-endpoints)
7. [Environment Variables](#environment-variables)

## Authentication

All protected endpoints require JWT (JSON Web Token) authentication via the `Authorization` header:

```
Authorization: Bearer <your-jwt-token>
```

### Token Lifecycle

- Tokens are valid for 24 hours by default
- Tokens contain user information (ID, name, roles)
- Invalid or expired tokens return `401 Unauthorized`

### Getting a Token

**POST** `/api/v1/login`

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**Success Response (200):**
```json
{
  "status": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "name": "John Doe",
    "roles": {
      "parent": true,
      "teacher": false,
      "admin": false
    }
  }
}
```

**Error Response (401):**
```json
{
  "status": false,
  "message": "Invalid credentials"
}
```

## Response Format

### Success Response

All successful responses follow this format:

```json
{
  "status": true,
  "message": "Success message",
  "data": {
    // Response data here
  }
}
```

### Error Response

All error responses follow this format:

```json
{
  "status": false,
  "message": "Error description",
  "errors": {
    // Optional: Validation errors
  }
}
```

## Error Handling

### HTTP Status Codes

- `200` - Success
- `201` - Created (resource successfully created)
- `400` - Bad Request (invalid request data)
- `401` - Unauthorized (missing or invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found (resource doesn't exist)
- `422` - Validation Error (request validation failed)
- `500` - Server Error (internal server error)

### Validation Errors

When validation fails (422), the response includes detailed field errors:

```json
{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "email": "The email field is required.",
    "password": "The password must be at least 8 characters."
  }
}
```

## Pagination

List endpoints support pagination via query parameters:

- `page` (optional): Page number (default: 1)
- `per_page` (optional): Items per page (default: 20, max: 100)

**Paginated Response:**
```json
{
  "status": true,
  "message": "Success",
  "data": {
    "data": [...],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}
```

## Endpoints

### Authentication Endpoints

#### Login
**POST** `/api/v1/login`

**Request:**
```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**Response:**
```json
{
  "status": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "name": "John Doe",
    "roles": {
      "parent": true
    }
  }
}
```

#### Register
**POST** `/api/v1/register`

**Request:**
```json
{
  "email": "newuser@example.com",
  "password": "password123",
  "firstname": "Jane",
  "lastname": "Doe"
}
```

### User & Profile

#### Get Current User Profile
**GET** `/api/v1/profile`

**Headers:** `Authorization: Bearer <token>`

**Response:**
```json
{
  "status": true,
  "message": "Profile retrieved successfully",
  "data": {
    "id": 1,
    "firstname": "John",
    "lastname": "Doe",
    "email": "user@example.com",
    "cellphone": "1234567890",
    "roles": ["parent", "teacher"]
  }
}
```

#### Update Profile
**PUT** `/api/v1/profile`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "firstname": "John",
  "lastname": "Updated",
  "email": "newemail@example.com",
  "cellphone": "1234567890"
}
```

**Allowed Fields:**
- `firstname`
- `lastname`
- `email`
- `cellphone`
- `address_street`
- `apt`
- `city`
- `state`
- `zip`
- `gender`

### Messaging

The messaging API provides a complete chat system for users to communicate with each other.

#### Get Conversations
**GET** `/api/v1/messaging/conversations`

**Headers:** `Authorization: Bearer <token>`

**Description:** Returns all conversations (chat threads) for the current user, sorted by last message time.

**Response:**
```json
{
  "status": true,
  "message": "Conversations retrieved successfully",
  "data": [
    {
      "user_id": 2,
      "user_name": "Jane Smith",
      "user_initials": "JS",
      "last_message": "Hello, how are you?",
      "last_message_time": "2025-01-15 10:30:00",
      "unread_count": 3
    }
  ]
}
```

#### Get Conversation Messages
**GET** `/api/v1/messaging/conversation/{userId}`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `page` (optional): Page number (default: 1)
- `per_page` (optional): Items per page (default: 50, max: 100)

**Description:** Retrieves all messages in a conversation between the current user and the specified user. Messages are automatically marked as read when retrieved.

**Response:**
```json
{
  "status": true,
  "message": "Messages retrieved successfully",
  "data": {
    "messages": [
      {
        "id": 1,
        "sender_id": 1,
        "recipient_id": 2,
        "message": "Hello!",
        "sent_datetime": "2025-01-15 10:00:00",
        "read_status": 1,
        "read_datetime": "2025-01-15 10:05:00",
        "attachment": null,
        "is_sender": true
      }
    ],
    "other_user": {
      "id": 2,
      "name": "Jane Smith",
      "initials": "JS"
    },
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 25,
      "total_pages": 1
    }
  }
}
```

#### Send Message
**POST** `/api/v1/messaging/send`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "recipient_id": 2,
  "message": "Hello, how are you?",
  "attachment": null
}
```

**Validation Rules:**
- `recipient_id` (required): Must be a valid user ID (integer)
- `message` (required): Message text, max 5000 characters
- `attachment` (optional): File attachment path

**Response:**
```json
{
  "status": true,
  "message": "Message sent successfully",
  "data": {
    "id": 123,
    "sender_id": 1,
    "recipient_id": 2,
    "message": "Hello, how are you?",
    "sent_datetime": "2025-01-15 10:30:00",
    "read_status": 0,
    "attachment": null,
    "is_sender": true
  }
}
```

**Error Responses:**
- `400`: Cannot send message to yourself
- `404`: Recipient not found
- `422`: Validation failed

#### Mark Messages as Read
**POST** `/api/v1/messaging/mark-read`

**Headers:** `Authorization: Bearer <token>`

**Request Body (Option 1 - Mark specific messages):**
```json
{
  "message_ids": [1, 2, 3]
}
```

**Request Body (Option 2 - Mark all from user):**
```json
{
  "user_id": 2
}
```

**Response:**
```json
{
  "status": true,
  "message": "Messages marked as read",
  "data": {
    "updated_count": 5
  }
}
```

#### Get Unread Count
**GET** `/api/v1/messaging/unread-count`

**Headers:** `Authorization: Bearer <token>`

**Response:**
```json
{
  "status": true,
  "message": "Unread count retrieved successfully",
  "data": {
    "unread_count": 5
  }
}
```

#### Search Users
**GET** `/api/v1/messaging/search-users`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `q` (required): Search query (minimum 2 characters)
- `limit` (optional): Maximum results (default: 10, max: 20)

**Description:** Searches for users by name or email to start a conversation.

**Response:**
```json
{
  "status": true,
  "message": "Users retrieved successfully",
  "data": [
    {
      "id": 2,
      "name": "Jane Smith",
      "initials": "JS",
      "email": "jane@example.com"
    }
  ]
}
```

#### Delete Message
**DELETE** `/api/v1/messaging/message/{id}`

**Headers:** `Authorization: Bearer <token>`

**Description:** Soft deletes a message (marks as deleted). Only the sender or recipient can delete a message.

**Response:**
```json
{
  "status": true,
  "message": "Message deleted successfully"
}
```

**Error Responses:**
- `403`: Unauthorized to delete this message
- `404`: Message not found

#### Delete Conversation
**DELETE** `/api/v1/messaging/conversation/{userId}`

**Headers:** `Authorization: Bearer <token>`

**Description:** Soft deletes all messages in a conversation with the specified user.

**Response:**
```json
{
  "status": true,
  "message": "Conversation deleted successfully",
  "data": {
    "deleted_count": 25
  }
}
```

### Students

#### List Students
**GET** `/api/v1/students`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `page` (optional): Page number
- `per_page` (optional): Items per page
- `parent_id` (optional): Filter by parent ID
- `class_id` (optional): Filter by class ID

**Response:**
```json
{
  "status": true,
  "message": "Students retrieved successfully",
  "data": {
    "data": [
      {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "school_id": "STU001",
        "current_class": {
          "id": 1,
          "class_name": "Grade 1 - Section A"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}
```

#### Get Student Details
**GET** `/api/v1/students/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Create Student
**POST** `/api/v1/students`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "firstname": "Jane",
  "lastname": "Doe",
  "school_id": "STU002",
  "parent_id": 1,
  "class_id": 1
}
```

#### Update Student
**PUT** `/api/v1/students/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Delete Student
**DELETE** `/api/v1/students/{id}`

**Headers:** `Authorization: Bearer <token>`

### Parents

#### List Parents
**GET** `/api/v1/parents`

**Headers:** `Authorization: Bearer <token>`

#### Get Parent Details
**GET** `/api/v1/parents/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Get Parent's Students
**GET** `/api/v1/parents/{id}/students`

**Headers:** `Authorization: Bearer <token>`

**Response:**
```json
{
  "status": true,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "firstname": "John",
      "lastname": "Doe",
      "school_id": "STU001"
    }
  ]
}
```

### Classes

#### List Classes
**GET** `/api/v1/classes`

**Headers:** `Authorization: Bearer <token>`

#### Get Class Details
**GET** `/api/v1/classes/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Get Class Students
**GET** `/api/v1/classes/{id}/students`

**Headers:** `Authorization: Bearer <token>`

### Attendance

#### List Attendance Records
**GET** `/api/v1/attendance`

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:**
- `student_id` (optional): Filter by student
- `date` (optional): Filter by date (YYYY-MM-DD)

#### Get Student Attendance
**GET** `/api/v1/attendance/student/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Create Attendance Record
**POST** `/api/v1/attendance`

**Headers:** `Authorization: Bearer <token>`

**Request Body:**
```json
{
  "student_id": 1,
  "date": "2025-01-15",
  "status": "present",
  "notes": "Optional notes"
}
```

#### Update Attendance
**PUT** `/api/v1/attendance/{id}`

**Headers:** `Authorization: Bearer <token>`

### Scores & Grades

#### List Scores
**GET** `/api/v1/scores`

**Headers:** `Authorization: Bearer <token>`

#### Get Student Scores
**GET** `/api/v1/scores/student/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Create Score
**POST** `/api/v1/scores`

**Headers:** `Authorization: Bearer <token>`

#### Update Score
**PUT** `/api/v1/scores/{id}`

**Headers:** `Authorization: Bearer <token>`

### Payments & Invoices

#### List Payments
**GET** `/api/v1/payments`

**Headers:** `Authorization: Bearer <token>`

#### Get Payment Details
**GET** `/api/v1/payments/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Get Parent Payments
**GET** `/api/v1/payments/parent/{id}`

**Headers:** `Authorization: Bearer <token>`

#### List Invoices
**GET** `/api/v1/invoices`

**Headers:** `Authorization: Bearer <token>`

#### Get Invoice Details
**GET** `/api/v1/invoices/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Get Parent Invoices
**GET** `/api/v1/invoices/parent/{id}`

**Headers:** `Authorization: Bearer <token>`

### Notifications

#### List Notifications
**GET** `/api/v1/notifications`

**Headers:** `Authorization: Bearer <token>`

#### Get Notification
**GET** `/api/v1/notifications/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Mark as Read
**POST** `/api/v1/notifications/{id}/read`

**Headers:** `Authorization: Bearer <token>`

### Events & Calendar

#### List Events
**GET** `/api/v1/events`

**Headers:** `Authorization: Bearer <token>`

#### Get Event Details
**GET** `/api/v1/events/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Calendar Endpoints
**GET** `/api/v1/calendar`

**GET** `/api/v1/calendar/{id}`

**POST** `/api/v1/calendar`

**PUT** `/api/v1/calendar/{id}`

**DELETE** `/api/v1/calendar/{id}`

### Dashboard

#### Get Dashboard Data
**GET** `/api/v1/dashboard`

**Headers:** `Authorization: Bearer <token>`

#### Get Dashboard Stats
**GET** `/api/v1/dashboard/stats`

**Headers:** `Authorization: Bearer <token>`

### Homework & Assignments

#### List Homework
**GET** `/api/v1/homework`

**Headers:** `Authorization: Bearer <token>`

#### Get Student Homework
**GET** `/api/v1/homework/student/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Create Homework
**POST** `/api/v1/homework`

**Headers:** `Authorization: Bearer <token>`

#### Update Homework
**PUT** `/api/v1/homework/{id}`

**Headers:** `Authorization: Bearer <token>`

#### List Assignments
**GET** `/api/v1/assignments`

**Headers:** `Authorization: Bearer <token>`

#### Get Assignment
**GET** `/api/v1/assignments/{id}`

**Headers:** `Authorization: Bearer <token>`

### Quizzes & Exams

#### List Quizzes
**GET** `/api/v1/quizzes`

**Headers:** `Authorization: Bearer <token>`

#### Get Quiz Details
**GET** `/api/v1/quizzes/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Get Student Quizzes
**GET** `/api/v1/quizzes/student/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Create Quiz
**POST** `/api/v1/quizzes`

**Headers:** `Authorization: Bearer <token>`

#### Update Quiz
**PUT** `/api/v1/quizzes/{id}`

**Headers:** `Authorization: Bearer <token>`

#### Projects
**GET** `/api/v1/projects`
**GET** `/api/v1/projects/{id}`
**GET** `/api/v1/projects/student/{id}`
**POST** `/api/v1/projects`
**PUT** `/api/v1/projects/{id}`

#### Midterm Exams
**GET** `/api/v1/midterms/student/{id}`
**POST** `/api/v1/midterms`
**PUT** `/api/v1/midterms/{id}`

#### Final Exams
**GET** `/api/v1/finals/student/{id}`
**POST** `/api/v1/finals`
**PUT** `/api/v1/finals/{id}`

#### Participation
**GET** `/api/v1/participations/student/{id}`
**POST** `/api/v1/participations`
**PUT** `/api/v1/participations/{id}`

### Additional Endpoints

#### Teachers
- `GET /api/v1/teachers` - List teachers
- `GET /api/v1/teachers/{id}` - Get teacher details
- `GET /api/v1/teachers/{id}/classes` - Get teacher's classes

#### Expenses
- `GET /api/v1/expenses` - List expenses
- `GET /api/v1/expenses/{id}` - Get expense details
- `POST /api/v1/expenses` - Create expense
- `PUT /api/v1/expenses/{id}` - Update expense

#### Reimbursements
- `GET /api/v1/reimbursements` - List reimbursements
- `GET /api/v1/reimbursements/{id}` - Get reimbursement details
- `POST /api/v1/reimbursements` - Create reimbursement
- `PUT /api/v1/reimbursements/{id}` - Update reimbursement

#### Refunds
- `GET /api/v1/refunds` - List refunds
- `GET /api/v1/refunds/{id}` - Get refund details
- `POST /api/v1/refunds` - Create refund
- `PUT /api/v1/refunds/{id}` - Update refund

#### Discounts
- `GET /api/v1/discounts` - List discounts
- `GET /api/v1/discounts/code/{code}` - Get discount by code
- `POST /api/v1/discounts/apply` - Apply discount

#### Payment Transactions
- `GET /api/v1/payment-transactions` - List transactions
- `GET /api/v1/payment-transactions/{id}` - Get transaction details
- `GET /api/v1/payment-transactions/payment/{id}` - Get transactions by payment
- `POST /api/v1/payment-transactions` - Create transaction

#### Emergency Contacts
- `GET /api/v1/emergency-contacts` - List contacts
- `GET /api/v1/emergency-contacts/{id}` - Get contact details
- `GET /api/v1/emergency-contacts/parent/{id}` - Get contacts by parent
- `POST /api/v1/emergency-contacts` - Create contact
- `PUT /api/v1/emergency-contacts/{id}` - Update contact
- `DELETE /api/v1/emergency-contacts/{id}` - Delete contact

#### Families
- `GET /api/v1/families` - List families
- `GET /api/v1/families/{id}` - Get family details
- `GET /api/v1/families/student/{id}` - Get families by student
- `GET /api/v1/families/{id}/guardians` - Get family guardians

#### Staff
- `GET /api/v1/staff` - List staff
- `GET /api/v1/staff/{id}` - Get staff details
- `POST /api/v1/staff` - Create staff
- `PUT /api/v1/staff/{id}` - Update staff
- `DELETE /api/v1/staff/{id}` - Delete staff

#### Financial
- `GET /api/v1/financial/report` - Get financial report
- `GET /api/v1/financial/unpaid-parents` - Get unpaid parents list

#### Configuration
- `GET /api/v1/configurations` - List configurations
- `GET /api/v1/configurations/{id}` - Get configuration details
- `GET /api/v1/configurations/key/{key}` - Get configuration by key
- `POST /api/v1/configurations` - Create configuration
- `PUT /api/v1/configurations/{id}` - Update configuration
- `DELETE /api/v1/configurations/{id}` - Delete configuration

#### Contact
- `POST /api/v1/contact` - Submit contact form

#### Extra Charges
- `GET /api/v1/extra-charges` - List extra charges
- `GET /api/v1/extra-charges/{id}` - Get charge details
- `POST /api/v1/extra-charges` - Create charge
- `PUT /api/v1/extra-charges/{id}` - Update charge
- `POST /api/v1/extra-charges/{id}/void` - Void charge
- `GET /api/v1/extra-charges/parents` - Get parent options

#### Flags
- `GET /api/v1/flags` - List flags
- `GET /api/v1/flags/{id}` - Get flag details
- `POST /api/v1/flags` - Create flag
- `PUT /api/v1/flags/{id}/state` - Update flag state
- `POST /api/v1/flags/{id}/close` - Close flag
- `POST /api/v1/flags/{id}/cancel` - Cancel flag
- `GET /api/v1/flags/students/by-grade/{grade}` - Get students by grade

#### IP Bans
- `GET /api/v1/ip-bans` - List IP bans
- `GET /api/v1/ip-bans/{id}` - Get ban details
- `POST /api/v1/ip-bans/unban` - Unban IP
- `POST /api/v1/ip-bans/ban` - Ban IP

#### Support
- `POST /api/v1/support` - Submit support request
- `GET /api/v1/support/requests` - List support requests
- `GET /api/v1/support/requests/{id}` - Get support request details

#### Attendance Tracking
- `POST /api/v1/attendance-tracking/record` - Record attendance
- `GET /api/v1/attendance-tracking/violations` - Get violations
- `GET /api/v1/attendance-tracking/student/{id}` - Get student tracking

#### Communication
- `GET /api/v1/communication/students/{id}/families` - Get families by student
- `GET /api/v1/communication/families/{id}/guardians` - Get guardians by family
- `POST /api/v1/communication/preview` - Preview communication
- `POST /api/v1/communication/send` - Send communication

#### Class Preparation
- `GET /api/v1/class-preparation` - List class preparations
- `GET /api/v1/class-preparation/{id}` - Get preparation details
- `POST /api/v1/class-preparation/{id}/mark-printed` - Mark as printed

#### PayPal Transactions
- `GET /api/v1/paypal-transactions` - List transactions
- `GET /api/v1/paypal-transactions/{id}` - Get transaction details
- `GET /api/v1/paypal-transactions/transaction/{transactionId}` - Get by transaction ID

#### Stats
- `GET /api/v1/stats` - Get statistics

#### Suppliers
- `GET /api/v1/suppliers` - List suppliers
- `GET /api/v1/suppliers/{id}` - Get supplier details
- `POST /api/v1/suppliers` - Create supplier
- `PUT /api/v1/suppliers/{id}` - Update supplier
- `DELETE /api/v1/suppliers/{id}` - Delete supplier

#### Payment Notifications
- `GET /api/v1/payment-notifications` - List notifications
- `POST /api/v1/payment-notifications/send` - Send notification

#### RFID
- `POST /api/v1/rfid/process` - Process RFID scan
- `GET /api/v1/rfid/logs` - Get RFID logs

#### Nav Builder
- `GET /api/v1/nav-builder` - List navigation items
- `GET /api/v1/nav-builder/{id}` - Get navigation item
- `POST /api/v1/nav-builder` - Create navigation item
- `PUT /api/v1/nav-builder/{id}` - Update navigation item
- `DELETE /api/v1/nav-builder/{id}` - Delete navigation item
- `POST /api/v1/nav-builder/reorder` - Reorder navigation items

#### Inventory
- `GET /api/v1/inventory` - List inventory items
- `GET /api/v1/inventory/{id}` - Get inventory item
- `POST /api/v1/inventory` - Create inventory item
- `PUT /api/v1/inventory/{id}` - Update inventory item
- `DELETE /api/v1/inventory/{id}` - Delete inventory item
- `GET /api/v1/inventory/movements` - Get inventory movements

#### Preferences
- `GET /api/v1/preferences` - Get preferences
- `PUT /api/v1/preferences` - Update preferences

#### Late Slip Logs
- `GET /api/v1/late-slip-logs` - List late slip logs
- `GET /api/v1/late-slip-logs/{id}` - Get late slip log

#### Supply Categories
- `GET /api/v1/supply-categories` - List categories
- `GET /api/v1/supply-categories/{id}` - Get category
- `POST /api/v1/supply-categories` - Create category
- `PUT /api/v1/supply-categories/{id}` - Update category
- `DELETE /api/v1/supply-categories/{id}` - Delete category

#### Homework Tracking
- `GET /api/v1/homework-tracking` - Get homework tracking

#### Parent Attendance Reports
- `GET /api/v1/parent-attendance-reports` - List reports
- `POST /api/v1/parent-attendance-reports` - Submit report
- `PUT /api/v1/parent-attendance-reports/{id}` - Update report

#### Printables Reports
- `GET /api/v1/printables/report-card/meta` - Get report card metadata
- `GET /api/v1/printables/badges/status` - Get badge status
- `POST /api/v1/printables/badges/log` - Log badge print

#### Broadcast Email
- `POST /api/v1/broadcast-email/send` - Send broadcast email
- `GET /api/v1/broadcast-email/parents` - Get parent options

#### Role Permissions
- `GET /api/v1/roles` - List roles
- `GET /api/v1/roles/{id}` - Get role details
- `GET /api/v1/roles/{id}/permissions` - Get role permissions
- `GET /api/v1/permissions` - List permissions
- `POST /api/v1/users/{id}/roles` - Assign role to user
- `GET /api/v1/users/role-assignment` - Get user role assignments

#### WhatsApp
- `GET /api/v1/whatsapp/links` - List WhatsApp links
- `POST /api/v1/whatsapp/links` - Save WhatsApp link
- `PUT /api/v1/whatsapp/membership` - Update membership

#### Purchase Orders
- `GET /api/v1/purchase-orders` - List purchase orders
- `GET /api/v1/purchase-orders/{id}` - Get purchase order
- `POST /api/v1/purchase-orders` - Create purchase order
- `PUT /api/v1/purchase-orders/{id}` - Update purchase order

#### Grading
- `GET /api/v1/grading/{type}/{studentId}/{classId}` - Get grading data
- `PUT /api/v1/grading` - Update grades

#### Score Comments
- `POST /api/v1/score-comments` - Save comment
- `GET /api/v1/score-comments/student/{id}` - Get comments by student
- `PUT /api/v1/score-comments/{id}` - Update comment

#### Authorized Users
- `GET /api/v1/authorized-users` - List authorized users
- `GET /api/v1/authorized-users/{id}` - Get authorized user
- `POST /api/v1/authorized-users` - Create authorized user
- `DELETE /api/v1/authorized-users/{id}` - Delete authorized user

#### Email Extractor
- `GET /api/v1/email-extractor/emails` - Extract emails
- `POST /api/v1/email-extractor/compare` - Compare emails

#### Slip Printer
- `POST /api/v1/slip-printer/print` - Print slip
- `POST /api/v1/slip-printer/preview` - Preview slip

#### Score Predictor
- `GET /api/v1/score-predictor/report` - Get score prediction report

#### Family Admin
- `GET /api/v1/family-admin` - List families (admin)
- `GET /api/v1/family-admin/search` - Search families

#### School Calendar
- `GET /api/v1/school-calendar` - Get school calendar
- `GET /api/v1/school-calendar/view/{view}` - Get calendar view

#### Email
- `POST /api/v1/email/send` - Send email

#### Session Management
- `GET /api/v1/session/timeout-config` - Get timeout configuration
- `GET /api/v1/session/check` - Check session timeout
- `POST /api/v1/session/ping` - Ping session activity

#### Role Switcher
- `GET /api/v1/role-switcher/roles` - Get available roles
- `POST /api/v1/role-switcher/switch` - Switch role

#### Files
- `GET /api/v1/files` - List files
- `GET /api/v1/files/receipt/{filename}` - Get receipt file
- `GET /api/v1/files/reimbursement/{filename}` - Get reimbursement file

#### Page
- `POST /api/v1/page/contact` - Submit contact form
- `GET /api/v1/page/privacy-policy` - Get privacy policy
- `GET /api/v1/page/terms-of-service` - Get terms of service
- `GET /api/v1/page/help-center` - Get help center

#### SMS
- `POST /api/v1/sms/send` - Send SMS
- `GET /api/v1/sms/carriers` - Get available carriers

#### Dashboard Redirect
- `GET /api/v1/dashboard/route` - Get dashboard route

#### Landing Page
- `GET /api/v1/landing-page/data` - Get landing page data

#### Frontend
- `GET /api/v1/frontend/user` - Get frontend user
- `GET /api/v1/frontend/pages` - Get frontend pages

#### UI
- `GET /api/v1/ui/style` - Get UI style
- `POST /api/v1/ui/style` - Update UI style

#### Info Icon
- `GET /api/v1/info-icon/profile` - Get profile icon info

#### Administrator
- `GET /api/v1/administrator/dashboard` - Get admin dashboard
- `GET /api/v1/administrator/search` - Admin search
- `GET /api/v1/administrator/enrollment-withdrawal` - Get enrollment/withdrawal data

#### Settings
- `GET /api/v1/settings/preferences` - Get preferences
- `PUT /api/v1/settings/preferences` - Update preferences
- `GET /api/v1/settings/system` - Get system settings

## Public Endpoints

These endpoints do not require authentication.

### Time

#### Get Current Time
**GET** `/api/v1/time/now`

**Headers:**
- `X-Timezone` (optional): User timezone (e.g., "America/New_York")

**Response:**
```json
{
  "user_timezone": "America/New_York",
  "server_timezone": "UTC",
  "local_time": "2025-01-15 10:30:00",
  "utc_time": "2025-01-15 15:30:00"
}
```

#### Convert Time
**POST** `/api/v1/time/convert`

**Headers:**
- `X-Timezone` (optional): User timezone

**Request Body:**
```json
{
  "time": "2025-01-15 10:30:00",
  "direction": "toUTC"
}
```

**Response:**
```json
{
  "user_timezone": "America/New_York",
  "server_timezone": "UTC",
  "original_time": "2025-01-15 10:30:00",
  "converted_time": "2025-01-15 15:30:00"
}
```

**Valid Directions:**
- `toUTC` - Convert from user timezone to UTC
- `fromUTC` - Convert from UTC to user timezone

### Health Check
**GET** `/api/v1/health`

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z"
}
```

## Rate Limiting

Currently, there is no rate limiting implemented. However, it's recommended to:
- Implement reasonable request intervals in your client
- Cache responses when appropriate
- Use pagination for large data sets

## CORS

The API supports CORS for cross-origin requests from mobile apps and web clients. All origins are allowed by default. For production, consider restricting to specific domains.

## Environment Variables

Required environment variables:

- `JWT_SECRET`: Secret key for JWT token signing (change from default in production!)
- `API_BASE_URL`: Base URL for outbound API calls (optional)
- `API_TIMEOUT`: Timeout for API requests in seconds (default: 10)

## Best Practices

### For Mobile App Development

1. **Token Storage**: Store the JWT token securely (e.g., Keychain on iOS, Keystore on Android)
2. **Token Refresh**: Implement token refresh logic before expiration
3. **Error Handling**: Handle 401 responses by redirecting to login
4. **Request Headers**: Always include the `Authorization` header for protected requests
5. **Timezone Support**: Use the `X-Timezone` header for timezone-aware requests
6. **Pagination**: Use pagination for large data sets to improve performance
7. **Caching**: Cache responses when appropriate to reduce API calls
8. **Offline Support**: Implement offline storage for critical data

### Request/Response Guidelines

1. **Content-Type**: Always use `Content-Type: application/json` for POST/PUT requests
2. **Accept**: Use `Accept: application/json` header
3. **Timestamps**: All timestamps are in UTC unless specified
4. **Date Format**: Use ISO 8601 format (YYYY-MM-DD HH:mm:ss)
5. **Validation**: Validate data on the client side before sending requests

## Support

For API support or questions:
- Check the help center: `/api/v1/page/help-center`
- Submit a support request: `POST /api/v1/support`

## Changelog

### Version 1.0.0
- Initial API release
- Authentication with JWT
- Messaging system
- Student, parent, and class management
- Attendance tracking
- Payment and invoice management
- And more...

## License

This API is proprietary software for Al Rahma Sunday School.