# WABA SAAS - Reseller API Documentation

Dokumentasi API lengkap untuk **Reseller** pada sistem WABA SAAS.

---

## Overview

API ini digunakan oleh **Reseller** untuk:
- Mengelola margin dedicated number
- Memonitor transaksi client
- Melihat pendapatan dari margin
- Mengelola client di bawah reseller

**Base URL:**
```
Production:  https://your-domain.com/api
Development: http://localhost:8001/api
```

---

## Authentication

Reseller menggunakan **Bearer Token** yang dikirim via header:

```http
Authorization: Bearer {your_reseller_token}
```

Atau menggunakan **API Key** reseller:

```http
X-Api-Key: {your_reseller_api_key}
```

> ⚠️ **Penting:** Token dapat diperoleh setelah login ke panel reseller.

---

## Response Format

### Success Response
```json
{
  "status": true,
  "message": "Operation successful",
  "data": { ... }
}
```

### Error Response
```json
{
  "status": false,
  "message": "Error description",
  "error_code": "ERROR_CODE"
}
```

### Error Codes (Reseller)
| Code | Description |
|------|-------------|
| `UNAUTHORIZED` | Token tidak valid atau expired |
| `MARGIN_EXISTS` | Margin untuk nomor ini sudah ada |
| `POOL_NOT_FOUND` | WABA Pool tidak ditemukan |
| `CLIENT_NOT_FOUND` | Client tidak ditemukan |
| `VALIDATION_ERROR` | Data input tidak valid |
| `FORBIDDEN` | Tidak memiliki akses ke resource ini |

---

## 1. Number Margin Management

### GET /api/reseller/number-margins

Melihat daftar margin yang sudah di-set untuk nomor dedicated.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Margins retrieved",
  "data": [
    {
      "id": 1,
      "waba_pool_id": 5,
      "phone_number": "628123456789",
      "account_name": "Business Account 1",
      "base_price": 500000,
      "margin_amount": 50000,
      "margin_percent": 0,
      "final_price": 550000,
      "is_active": true,
      "created_at": "2025-12-01T10:00:00Z"
    },
    {
      "id": 2,
      "waba_pool_id": 6,
      "phone_number": "628123456790",
      "account_name": "Business Account 2",
      "base_price": 750000,
      "margin_amount": 0,
      "margin_percent": 10,
      "final_price": 825000,
      "is_active": true,
      "created_at": "2025-12-01T10:00:00Z"
    }
  ]
}
```

---

### GET /api/reseller/number-margins/available

Melihat daftar nomor dedicated yang tersedia untuk dijual ke client.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Available numbers",
  "data": [
    {
      "id": 5,
      "phone_number": "628123456789",
      "account_name": "Business Account 1",
      "base_price": 500000,
      "has_margin": true,
      "margin": {
        "id": 1,
        "margin_amount": 50000,
        "margin_percent": 0,
        "is_active": true
      }
    },
    {
      "id": 7,
      "phone_number": "628123456791",
      "account_name": "Business Account 3",
      "base_price": 600000,
      "has_margin": false,
      "margin": null
    }
  ]
}
```

---

### POST /api/reseller/number-margins

Menambahkan margin untuk nomor dedicated.

**Headers:**
```http
Authorization: Bearer {token}
Content-Type: application/json
```

#### Request Body - Fixed Amount Margin
```json
{
  "waba_pool_id": 5,
  "margin_amount": 50000
}
```

#### Request Body - Percentage Margin
```json
{
  "waba_pool_id": 5,
  "margin_percent": 10
}
```

#### Parameters
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| waba_pool_id | integer | ✅ | ID WABA Pool |
| margin_amount | decimal | ❌ | Margin nominal (Rp) |
| margin_percent | decimal | ❌ | Margin persentase (%) |

> 💡 **Catatan:** Isi salah satu: `margin_amount` ATAU `margin_percent`

#### Response Success
```json
{
  "status": true,
  "message": "Margin berhasil disimpan",
  "data": {
    "id": 3,
    "reseller_id": 1,
    "waba_pool_id": 5,
    "margin_amount": 50000,
    "margin_percent": 0,
    "is_active": true,
    "created_at": "2025-12-10T10:00:00Z"
  }
}
```

#### cURL Example
```bash
curl -X POST "https://domain.com/api/reseller/number-margins" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "waba_pool_id": 5,
    "margin_amount": 50000
  }'
```

#### PHP Example
```php
$response = Http::withToken($resellerToken)
    ->post('https://domain.com/api/reseller/number-margins', [
        'waba_pool_id' => 5,
        'margin_amount' => 50000
    ]);

$result = $response->json();
```

#### JavaScript Example
```javascript
const response = await fetch('https://domain.com/api/reseller/number-margins', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${resellerToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    waba_pool_id: 5,
    margin_amount: 50000
  })
});

const result = await response.json();
```

---

### PUT /api/reseller/number-margins/{id}

Mengubah margin yang sudah ada.

**Headers:**
```http
Authorization: Bearer {token}
Content-Type: application/json
```

#### Request Body
```json
{
  "margin_amount": 75000,
  "is_active": true
}
```

#### Response
```json
{
  "status": true,
  "message": "Margin berhasil diupdate",
  "data": {
    "id": 1,
    "margin_amount": 75000,
    "margin_percent": 0,
    "is_active": true,
    "updated_at": "2025-12-10T10:00:00Z"
  }
}
```

---

### DELETE /api/reseller/number-margins/{id}

Menghapus margin.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Margin berhasil dihapus",
  "data": null
}
```

---

## 2. Dedicated Number Monitoring

### GET /api/reseller/dedicated-numbers

Melihat daftar nomor dedicated yang di-assign ke client di bawah reseller.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Dedicated numbers retrieved",
  "data": [
    {
      "id": 1,
      "client_id": 10,
      "client_name": "PT Client Satu",
      "waba_pool_id": 5,
      "phone_number": "628123456789",
      "label": "Nomor CS Utama",
      "status": "active",
      "price": 550000,
      "assigned_at": "2025-12-01T10:00:00Z"
    },
    {
      "id": 2,
      "client_id": 11,
      "client_name": "CV Client Dua",
      "waba_pool_id": 6,
      "phone_number": "628123456790",
      "label": "Hotline Support",
      "status": "active",
      "price": 825000,
      "assigned_at": "2025-12-05T14:00:00Z"
    }
  ]
}
```

---

### GET /api/reseller/dedicated-numbers/available

Melihat nomor dedicated yang tersedia dengan harga yang sudah termasuk margin.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Available numbers",
  "data": [
    {
      "id": 7,
      "phone_number": "628123456791",
      "account_name": "Business Account 3",
      "base_price": 600000,
      "margin": 60000,
      "total_price": 660000
    }
  ]
}
```

---

## 3. Transaction History

### GET /api/reseller/dedicated-numbers/transactions

Melihat riwayat transaksi assign nomor dedicated.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| page | integer | Halaman (default: 1) |
| per_page | integer | Items per halaman (default: 50) |
| date_from | date | Filter dari tanggal |
| date_to | date | Filter sampai tanggal |
| client_id | integer | Filter berdasarkan client |
| type | string | Filter tipe: assign, unassign, refund |

#### Response
```json
{
  "status": true,
  "message": "Transactions retrieved",
  "data": {
    "transactions": [
      {
        "id": 101,
        "client_id": 10,
        "client_name": "PT Client Satu",
        "waba_pool_id": 5,
        "phone_number": "628123456789",
        "type": "assign",
        "base_price": 500000,
        "margin": 50000,
        "total_amount": 550000,
        "notes": "Dedicated number assignment",
        "created_at": "2025-12-01T10:00:00Z"
      },
      {
        "id": 102,
        "client_id": 11,
        "client_name": "CV Client Dua",
        "waba_pool_id": 6,
        "phone_number": "628123456790",
        "type": "assign",
        "base_price": 750000,
        "margin": 75000,
        "total_amount": 825000,
        "notes": "Dedicated number assignment",
        "created_at": "2025-12-05T14:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 25,
      "last_page": 1
    }
  }
}
```

---

## 4. Revenue Report

### GET /api/reseller/dedicated-numbers/report

Melihat laporan pendapatan margin reseller.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Report retrieved",
  "data": {
    "total_margin_earned": 1250000,
    "formatted_margin": "Rp 1.250.000",
    "total_transactions": 15,
    "active_assignments": 12,
    "period": "all_time"
  }
}
```

---

### GET /api/reseller/dedicated-numbers/report/monthly

Melihat laporan bulanan.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| month | integer | Bulan (1-12) |
| year | integer | Tahun |

#### Response
```json
{
  "status": true,
  "message": "Monthly report",
  "data": {
    "month": 12,
    "year": 2025,
    "total_margin": 500000,
    "formatted_margin": "Rp 500.000",
    "transactions_count": 5,
    "breakdown": [
      {
        "date": "2025-12-01",
        "transactions": 2,
        "margin": 125000
      },
      {
        "date": "2025-12-05",
        "transactions": 3,
        "margin": 375000
      }
    ]
  }
}
```

---

## 5. Client Management

### GET /api/reseller/clients

Melihat daftar client di bawah reseller.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Clients retrieved",
  "data": [
    {
      "id": 10,
      "name": "PT Client Satu",
      "email": "client1@example.com",
      "phone": "628111111111",
      "balance": 1500000,
      "formatted_balance": "Rp 1.500.000",
      "dedicated_numbers_count": 2,
      "messages_this_month": 1500,
      "status": "active",
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": 11,
      "name": "CV Client Dua",
      "email": "client2@example.com",
      "phone": "628222222222",
      "balance": 750000,
      "formatted_balance": "Rp 750.000",
      "dedicated_numbers_count": 1,
      "messages_this_month": 800,
      "status": "active",
      "created_at": "2025-03-20T14:00:00Z"
    }
  ]
}
```

---

### GET /api/reseller/clients/{id}

Melihat detail client tertentu.

**Headers:**
```http
Authorization: Bearer {token}
```

#### Response
```json
{
  "status": true,
  "message": "Client detail",
  "data": {
    "id": 10,
    "name": "PT Client Satu",
    "email": "client1@example.com",
    "phone": "628111111111",
    "address": "Jl. Contoh No. 123",
    "balance": 1500000,
    "formatted_balance": "Rp 1.500.000",
    "status": "active",
    "dedicated_numbers": [
      {
        "id": 1,
        "phone_number": "628123456789",
        "label": "Nomor CS Utama",
        "status": "active"
      }
    ],
    "statistics": {
      "messages_today": 50,
      "messages_this_month": 1500,
      "total_spent_this_month": 525000
    },
    "created_at": "2025-01-15T10:00:00Z"
  }
}
```

---

## Margin Calculation

### Perhitungan Margin

Reseller dapat menentukan margin dalam 2 cara:

#### 1. Fixed Amount (Nominal Tetap)
```
Base Price:     Rp 500.000
Margin Amount:  Rp  50.000
─────────────────────────────
Total Price:    Rp 550.000
```

#### 2. Percentage (Persentase)
```
Base Price:       Rp 500.000
Margin (10%):     Rp  50.000
─────────────────────────────
Total Price:      Rp 550.000
```

### Alur Pendapatan Margin

```
┌─────────┐      Assign Request      ┌──────────┐
│ Client  │ ─────────────────────▶   │  System  │
│         │                          │          │
│ Bayar   │                          │ Potong   │
│ Rp550rb │                          │ Saldo    │
└─────────┘                          └────┬─────┘
                                          │
                    ┌─────────────────────┴─────────────────────┐
                    ▼                                           ▼
              ┌──────────┐                                ┌──────────┐
              │  Admin   │                                │ Reseller │
              │ Terima   │                                │ Terima   │
              │ Rp500rb  │                                │ Rp 50rb  │
              │ (Base)   │                                │ (Margin) │
              └──────────┘                                └──────────┘
```

---

## Notes & Restrictions

1. **Scope**: Reseller hanya bisa melihat client & transaksi di bawahnya
2. **Margin**: Jika tidak di-set, client akan melihat base price langsung
3. **Multiple Margins**: Hanya satu margin aktif per nomor per reseller
4. **Transaction History**: Semua transaksi tercatat otomatis
5. **Revenue Calculation**: Margin dihitung saat client assign nomor

---

## Support

Untuk bantuan teknis, hubungi admin sistem.