# Kissal Group - API Documentation

**Base URL:** `http://localhost:8000/api`

**Authentication:** Bearer Token (Sanctum)

---

## Auth

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/auth/register` | Register new user |
| POST | `/auth/login` | Login with phone + password |
| POST | `/auth/otp/send` | Send OTP code to phone |
| POST | `/auth/otp/verify` | Verify OTP code |
| POST | `/auth/password/reset-request` | Request password reset |
| POST | `/auth/password/reset` | Reset password with OTP |
| GET | `/profile` | Get current user profile |
| PUT | `/profile` | Update profile |
| POST | `/fcm-token` | Update FCM token |
| GET | `/notifications` | Get notifications |
| PUT | `/notifications/{id}/read` | Mark notification as read |
| POST | `/support` | Create support ticket |
| GET | `/support` | List my support tickets |

### Register
```json
POST /api/auth/register
{
  "name": "Moussa Diallo",
  "phone": "+221771111111",
  "password": "secret123",
  "role": "driver"
}
```

### Login
```json
POST /api/auth/login
{
  "phone": "+221771111111",
  "password": "secret123"
}
```

### Send OTP
```json
POST /api/auth/otp/send
{
  "phone": "+221771111111"
}
```

---

## Public Routes

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/cities` | List active cities |
| GET | `/tariffs?origin=&dest=` | Get tariff between 2 cities |

---

## Passenger Routes

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/passenger/routes/search` | Search available routes |
| GET | `/passenger/routes/{route}` | Get route detail |
| POST | `/passenger/reservations` | Create reservation |
| GET | `/passenger/reservations` | List my reservations |
| PUT | `/passenger/reservations/{id}/cancel` | Cancel reservation |
| POST | `/passenger/reservations/{id}/pay` | Pay reservation |
| GET | `/passenger/trips/upcoming` | Upcoming trips |
| GET | `/passenger/trips/completed` | Completed trips |
| GET | `/passenger/trips/cancelled` | Cancelled trips |
| POST | `/passenger/reviews` | Leave a review |

### Search Routes
```
GET /api/passenger/routes/search?origin=1&destination=2&date=2026-07-23&mode=covoiturage&seats=2
```

### Create Reservation
```json
POST /api/passenger/reservations
{
  "route_id": 1,
  "mode": "covoiturage",
  "seats": 2,
  "pickup_stop_id": null,
  "dropoff_stop_id": null
}
```

### Pay Reservation
```json
POST /api/passenger/reservations/1/pay
{
  "payment_method": "wave"
}
```

---

## Driver Routes

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/driver/dashboard` | Dashboard with stats |
| PUT | `/driver/status` | Toggle online/offline |
| POST | `/driver/routes` | Create a route |
| GET | `/driver/routes` | List my routes |
| GET | `/driver/routes/{route}` | Route detail |
| PUT | `/driver/routes/{route}/status` | Update route status |
| GET | `/driver/reservations` | My reservations |
| PUT | `/driver/reservations/{id}/confirm` | Confirm reservation |
| PUT | `/driver/reservations/{id}/cancel` | Cancel reservation |
| GET | `/driver/earnings` | List earnings |
| GET | `/driver/earnings/summary` | Earnings summary |
| GET | `/driver/next-departure` | Next departure |
| GET | `/driver/reviews` | My reviews |

### Create Route
```json
POST /api/driver/routes
{
  "tariff_id": 1,
  "vehicle_id": 1,
  "departure_time": "2026-07-23 08:00:00",
  "available_seats": 4,
  "stops": [
    {
      "name": "Gare routière Dakar",
      "latitude": 14.6928,
      "longitude": -17.4467,
      "order": 1,
      "price_from_origin": 0
    }
  ]
}
```

### Update Route Status
```json
PUT /api/driver/routes/1/status
{
  "status": "in_progress"
}
```

---

## Partner Routes

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/partner/dashboard` | Fleet dashboard |
| GET | `/partner/drivers` | List fleet drivers |
| POST | `/partner/drivers` | Add driver to fleet |
| PUT | `/partner/drivers/{id}/status` | Activate/suspend driver |
| GET | `/partner/vehicles` | List fleet vehicles |
| POST | `/partner/vehicles` | Add vehicle |
| PUT | `/partner/vehicles/{id}` | Update vehicle |
| DELETE | `/partner/vehicles/{id}` | Delete vehicle |
| POST | `/partner/vehicles/{id}/assign/{driver}` | Assign vehicle to driver |
| GET | `/partner/trips` | Fleet trips |
| GET | `/partner/earnings` | Fleet earnings |
| GET | `/partner/reservations` | Fleet reservations |

### Add Vehicle
```json
POST /api/partner/vehicles
{
  "brand": "Hyundai",
  "model": "Tucson",
  "year": 2024,
  "plate_number": "DK-087-M",
  "color": "Blanc",
  "seats": 7,
  "fuel_type": "Diesel"
}
```

---

## Admin Routes

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/admin/dashboard` | Admin dashboard |
| **Cities** | | |
| GET | `/admin/cities` | List cities |
| POST | `/admin/cities` | Create city |
| PUT | `/admin/cities/{id}` | Update city |
| DELETE | `/admin/cities/{id}` | Delete city |
| **Tariffs** | | |
| GET | `/admin/tariffs` | List tariffs |
| POST | `/admin/tariffs` | Create tariff |
| PUT | `/admin/tariffs/{id}` | Update tariff |
| DELETE | `/admin/tariffs/{id}` | Delete tariff |
| PATCH | `/admin/tariffs/{id}/toggle` | Enable/disable tariff |
| **Users** | | |
| GET | `/admin/users` | List users |
| GET | `/admin/users/{id}` | User detail |
| PATCH | `/admin/users/{id}/toggle` | Enable/disable user |
| **Drivers** | | |
| GET | `/admin/drivers` | List drivers |
| PATCH | `/admin/drivers/{id}/verify` | Verify driver |
| **Partners** | | |
| GET | `/admin/partners` | List partners |
| PATCH | `/admin/partners/{id}/verify` | Verify partner |
| **Reservations & Routes** | | |
| GET | `/admin/reservations` | List all reservations |
| GET | `/admin/routes` | List all routes |
| **Revenues** | | |
| GET | `/admin/revenues` | Revenue list |
| GET | `/admin/revenues/summary` | Revenue summary |
| **Support** | | |
| GET | `/admin/support` | List support tickets |
| PUT | `/admin/support/{id}/reply` | Reply to ticket |
| **Notifications** | | |
| POST | `/admin/notifications/send` | Send notification |

### Create Tariff
```json
POST /api/admin/tariffs
{
  "origin_city_id": 1,
  "destination_city_id": 2,
  "solo_price": 3000,
  "covoiturage_price_per_seat": 1500,
  "distance_km": 70,
  "duration_minutes": 90
}
```

### Toggle Tariff
```
PATCH /api/admin/tariffs/1/toggle
```

### Send Notification
```json
POST /api/admin/notifications/send
{
  "role": "driver",
  "title": "Maintenance prévue",
  "body": "L'application sera en maintenance demain de 2h à 4h."
}
```

---

## Payment Webhooks

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/webhooks/wave` | Wave payment callback |
| POST | `/webhooks/orange-money` | Orange Money callback |
| POST | `/webhooks/wizall` | Wizall Money callback |
| POST | `/webhooks/mixx-yas` | Mixx by Yas callback |

---

## Payment Methods

| ID | Name |
|----|------|
| `cash` | Cash (direct to driver) |
| `wave` | Wave |
| `orange_money` | Orange Money |
| `wizall_money` | Wizall Money |
| `mixx_yas` | Mixx by Yas |

---

## Roles

| Role | Access |
|------|--------|
| `passenger` | Passenger app (mobile) |
| `driver` | Driver app (mobile) |
| `partner` | Fleet management (web) |
| `admin` | Full platform admin (web) |

---

## Test Accounts (Development)

| Role | Phone | Password |
|------|-------|----------|
| Admin | +221770000000 | password |
| Driver | +221771111111 | password |
| Passenger | +221772222222 | password |

---

## Tariff Logic

```
Admin defines: Dakar → Mbour
  Solo price = 3,000 FCFA (entire vehicle)
  Covoiturage price = 1,500 FCFA (per seat)

Passenger books 2 seats in Covoiturage → 1,500 × 2 = 3,000 FCFA
Passenger books Solo → 3,000 FCFA (vehicle is private)
```