# Quick Start Guide

This guide walks you through making your first API calls to the B12 SIS backend.

## Prerequisites

- Server running on `http://localhost:8080`
- A user account created in the database
- cURL or an API client like Postman

## Step 1: Login

First, authenticate to get your access token:

=== "cURL"
    ```bash
    curl -X POST http://localhost:8080/api/auth/login \
      -H "Content-Type: application/json" \
      -d '{
        "email": "admin@school.edu",
        "password": "yourpassword"
      }'
    ```

=== "JavaScript"
    ```javascript
    const response = await fetch('http://localhost:8080/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'admin@school.edu',
        password: 'yourpassword'
      })
    });
    const data = await response.json();
    console.log(data.token.access_token);
    ```

**Response:**
```json
{
  "token": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 86400
  },
  "user": {
    "id": "uuid",
    "email": "admin@school.edu",
    "name": "Admin User"
  }
}
```

Save the `access_token` for subsequent requests.

## Step 2: Get Current User Info

Verify your authentication by fetching your user profile:

```bash
curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**
```json
{
  "success": true,
  "message": "user",
  "data": {
    "user": {
      "id": "uuid",
      "email": "admin@school.edu",
      "name": "Admin User",
      "teams": [...]
    },
    "permissions": {
      "Student": ["list", "read", "create", "update", "delete"],
      "Teacher": ["list", "read", "create", "update", "delete"]
    }
  }
}
```

## Step 3: List Students

Fetch a list of students. Note the required headers:

```bash
curl -X POST http://localhost:8080/api/students/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20
  }'
```

**Response:**
```json
{
  "success": true,
  "message": "Records retrieved successfully",
  "data": {
    "list": [
      {
        "id": "student-uuid-1",
        "code": "STD001",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "status": "active",
        "email": "john.doe@school.edu"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150
    }
  }
}
```

## Step 4: Create a Student

Create a new student record:

```bash
curl -X POST http://localhost:8080/api/students \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@school.edu",
    "birthdate": "2010-05-15",
    "gender": "Female",
    "status": "active"
  }'
```

**Response:**
```json
{
  "success": true,
  "message": "Record created successfully",
  "data": {
    "id": "new-student-uuid",
    "code": "STD002",
    "name": "Smith Jane",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@school.edu",
    "status": "active"
  }
}
```

## Step 5: Search with Filters

Use the filter system to search for students:

```bash
curl -X POST http://localhost:8080/api/students/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20,
    "search": "John",
    "filter": {
      "group": "AND",
      "conditions": [
        {"field": "status", "operator": "=", "value": "active"}
      ]
    }
  }'
```

## Step 6: Update a Record

Update an existing student:

```bash
curl -X PUT http://localhost:8080/api/students/STUDENT_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_mobile": "+84123456789",
    "address": "123 Main Street"
  }'
```

## Step 7: Delete a Record

Soft-delete a student (records are never permanently deleted):

```bash
curl -X DELETE http://localhost:8080/api/students/STUDENT_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"
```

## Common Patterns

### Required Headers

Most protected endpoints require these headers:

| Header | Description |
|--------|-------------|
| `Authorization` | `Bearer <access_token>` |
| `X-Team-ID` | UUID of the current team/campus |
| `Content-Type` | `application/json` for POST/PUT requests |
| `X-Academic-Session-ID` | Optional: current academic year |

### List Endpoint Pattern

All list endpoints use POST with a JSON body:

```json
{
  "page": 1,
  "limit": 20,
  "search": "search term",
  "sort_field": "created_at",
  "sort_direction": "desc",
  "filter": { ... }
}
```

### CRUD Endpoints Pattern

Every module follows this pattern:

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/{module}` | Create single record |
| POST | `/api/{module}/bulk` | Create multiple records |
| POST | `/api/{module}/list` | List with pagination |
| GET | `/api/{module}/:id` | Get single record |
| PUT | `/api/{module}/:id` | Update record |
| DELETE | `/api/{module}/:id` | Soft delete record |
| DELETE | `/api/{module}/bulk` | Bulk soft delete |
| POST | `/api/{module}/export` | Export to Excel |
| POST | `/api/{module}/import` | Import from Excel |

### Relationship Endpoints

Managing related records:

```bash
# List related records
POST /api/students/list_relate/STUDENT_ID/courses/Course

# Add relationship
PUT /api/students/list_relate/STUDENT_ID/courses/Course
Body: { "ids": ["course-id-1", "course-id-2"] }

# Remove relationship
DELETE /api/students/list_relate/STUDENT_ID/courses/Course
Body: { "ids": ["course-id-1"] }
```

## Error Handling

### Common Error Responses

**401 Unauthorized:**
```json
{
  "error": "Invalid or expired token"
}
```

**403 Forbidden:**
```json
{
  "error": "Insufficient permissions"
}
```

**400 Bad Request:**
```json
{
  "success": false,
  "message": "Invalid input",
  "errors": "validation error details"
}
```

**404 Not Found:**
```json
{
  "success": false,
  "message": "Record not found"
}
```

## Token Refresh

When your access token expires, use the refresh token to get a new pair:

```bash
curl -X POST http://localhost:8080/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'
```

## Next Steps

- [API Overview](../api/overview.md) - Full API conventions
- [Filter System](../guides/filter-system.md) - Advanced filtering
- [Student Module](../api/modules/students.md) - Complete student API