{"success":true,"version":"2.1","status":"FROZEN","documentation":"# Fibermedia Provisioning System - Complete API Specification & Reference Manual (v2.1 Frozen)\n\nDokumen ini merupakan panduan spesifikasi dan referensi resmi API untuk **Fibermedia Provisioning System** (v2.1 API Freeze). Ditujukan untuk pengembang Frontend (Web Admin, Mobile Sales, Mobile Teknisi), QA Tester, dan Tim Integrasi.\n\n---\n\n## \ud83d\udccc Ringkasan Arsitektur & Otorisasi\n\n* **Base URL**: `http:\/\/localhost:8000\/api`\n* **Format Request & Response**: `application\/json` (kecuali upload file menggunakan `multipart\/form-data`)\n* **Autentikasi**: Laravel Sanctum Bearer Token (`Authorization: Bearer <token>`)\n* **Role-Based Access Control (RBAC)**: Enforced via Spatie Permission (`Superadmin`, `Admin`, `Sales`, `Teknisi`)\n\n---\n\n## \ud83d\udee0\ufe0f 1. Autentikasi & Pengelolaan Akun (Auth & User Profile)\n\n### 1.1 Login User\n* **Endpoint**: `POST \/login`\n* **Rate Limit**: 100 request\/menit\n* **Public Route**\n* **Request Body**:\n  ```json\n  {\n    \"email\": \"admin@example.com\",\n    \"password\": \"password\"\n  }\n  ```\n* **Response (200 OK)**:\n  ```json\n  {\n    \"success\": true,\n    \"message\": \"Login successful\",\n    \"data\": {\n      \"access_token\": \"1|sanctum_token_string...\",\n      \"token_type\": \"Bearer\",\n      \"user\": {\n        \"id\": 1,\n        \"name\": \"Super Admin\",\n        \"email\": \"admin@example.com\",\n        \"roles\": [\"Admin\"]\n      }\n    }\n  }\n  ```\n\n### 1.2 Minta Link Lupa Password (Forgot Password)\n* **Endpoint**: `POST \/forgot-password`\n* **Rate Limit**: 100 request\/menit\n* **Public Route**\n* **Request Body**: `{\"email\": \"user@fibermedia.test\"}`\n* **Response (200 OK)**: `{\"success\": true, \"data\": null, \"message\": \"We have emailed your password reset link!\"}`\n\n### 1.3 Reset Password Baru (Reset Password)\n* **Endpoint**: `POST \/reset-password`\n* **Public Route**\n* **Request Body**:\n  ```json\n  {\n    \"token\": \"reset_token_string\",\n    \"email\": \"user@fibermedia.test\",\n    \"password\": \"PasswordBaru123\",\n    \"password_confirmation\": \"PasswordBaru123\"\n  }\n  ```\n* **Response (200 OK)**: `{\"success\": true, \"data\": null, \"message\": \"Your password has been reset!\"}`\n\n### 1.4 Get Profile User Saat Ini\n* **Endpoint**: `GET \/user`\n* **Header**: `Authorization: Bearer <token>`\n* **Response (200 OK)**:\n  ```json\n  {\n    \"id\": 1,\n    \"name\": \"Admin System\",\n    \"email\": \"admin@example.com\",\n    \"status\": \"active\",\n    \"roles\": [\"Admin\"]\n  }\n  ```\n\n### 1.5 Logout User\n* **Endpoint**: `POST \/logout`\n* **Header**: `Authorization: Bearer <token>`\n* **Response (200 OK)**: `{\"success\": true, \"data\": null, \"message\": \"Successfully logged out\"}`\n\n### 1.6 Update Profile & Password Mandiri\n* **Endpoint Profile**: `PUT \/user\/profile` (`{\"name\": \"...\", \"phone\": \"...\"}`)\n* **Endpoint Password**: `PUT \/user\/password` (`{\"current_password\": \"...\", \"new_password\": \"...\", \"new_password_confirmation\": \"...\"}`)\n\n---\n\n## \ud83d\udd14 2. Pusat Notifikasi (Notifications)\n\n* **Get All Notifications**: `GET \/notifications`\n* **Mark All As Read**: `PATCH \/notifications\/read-all`\n* **Mark Single As Read**: `PATCH \/notifications\/{id}\/read`\n\n---\n\n## \ud83d\udce6 3. Katalog Paket & Kode Promo (Catalog & Promos)\n\n### 3.1 Get Katalog Paket Internet Active\n* **Endpoint**: `GET \/packages`\n* **Access**: Public \/ Authenticated\n* **Response (200 OK)**:\n  ```json\n  {\n    \"success\": true,\n    \"data\": [\n      {\n        \"id\": 1,\n        \"name\": \"FMP Basic 20 Mbps\",\n        \"speed_mbps\": 20,\n        \"price\": 150000,\n        \"installation_fee\": 100000,\n        \"is_active\": true\n      }\n    ]\n  }\n  ```\n\n### 3.2 Validasi Kode Promo (Sales \/ Public)\n* **Endpoint**: `POST \/promos\/validate`\n* **Request Body**: `{\"code\": \"PROMO2026\", \"package_id\": 1}`\n* **Response (200 OK)**:\n  ```json\n  {\n    \"success\": true,\n    \"data\": {\n      \"code\": \"PROMO2026\",\n      \"discount_type\": \"fixed\",\n      \"discount_value\": 50000,\n      \"calculated_discount\": 50000\n    }\n  }\n  ```\n\n---\n\n## \ud83d\udcbc 4. Modul Sales (Sales Submissions)\n**Access Control**: `role: Sales | Admin | Superadmin`\n\n### 4.1 Get List Submissions Sales\n* **Endpoint**: `GET \/sales\/submissions`\n* **Query Params**: `status`, `search`, `page`, `per_page`\n* **Response**: Paginated Collection\n\n### 4.2 Buat Pendaftaran Pelanggan Baru (Store Submission)\n* **Endpoint**: `POST \/sales\/submissions`\n* **Request Body**:\n  ```json\n  {\n    \"customer_name\": \"Budi Santoso\",\n    \"nik\": \"3171234567890001\",\n    \"phone\": \"081299998888\",\n    \"email\": \"budi@example.com\",\n    \"address\": \"Jl. Merdeka No. 45\",\n    \"district\": \"Gambir\",\n    \"city\": \"Jakarta Pusat\",\n    \"province\": \"DKI Jakarta\",\n    \"postal_code\": \"10110\",\n    \"lat\": -6.175392,\n    \"lng\": 106.827153,\n    \"package_id\": 1,\n    \"promo_code\": \"PROMO2026\"\n  }\n  ```\n* **Response (201 Created)**: Data Submission baru dengan status `pending`.\n\n### 4.3 Upload Berkas Dokumen Pelanggan (KTP \/ KK \/ Surat Kuasa)\n* **Endpoint**: `POST \/sales\/submissions\/{submission_id}\/upload-document`\n* **Content-Type**: `multipart\/form-data`\n* **Form Data**:\n  - `document_type`: `ktp` | `kk` | `surat_kuasa` | `foto_rumah`\n  - `file`: Berkas PDF \/ JPG \/ PNG (Max 5MB)\n* **Response (200 OK)**: Metadata berkas terunggah.\n\n---\n\n## \ud83d\udc6e 5. Modul Admin: Validasi Berkas & Document Review\n**Access Control**: `role: Admin | Superadmin`\n\n### 5.1 List Submissions untuk Validasi\n* **Endpoint**: `GET \/admin\/submissions`\n* **Query Params**: `status=pending`, `search=...`\n\n### 5.2 Review Dokumen Berkas Pelanggan Individual\n* **Endpoint**: `PUT \/admin\/documents\/{document_id}\/review`\n* **Request Body**:\n  ```json\n  {\n    \"status\": \"approved\",\n    \"rejection_reason\": null\n  }\n  ```\n  *(Status: `approved`, `rejected`, `needs_revision`)*\n\n### 5.3 Validasi Akhir Submission Pelanggan\n* **Endpoint**: `PUT \/admin\/submissions\/{submission_id}\/validate`\n* **Request Body**:\n  ```json\n  {\n    \"status\": \"approved\",\n    \"validation_notes\": \"Seluruh berkas fisik valid dan terverifikasi.\"\n  }\n  ```\n* **Efek Business Rules**:\n  - Jika `status` = `approved`, seluruh berkas aktif **HARUS** sudah di-approve.\n  - Otomatis membuat record **Provisioning** baru berstatus `PENDING`.\n\n---\n\n## \u26a1 6. Modul Admin: Provisioning & Integrasi BFASS\n**Access Control**: `role: Admin | Superadmin`\n\n### 6.1 Check Status Kesehatan Server BFASS\n* **Endpoint**: `GET \/admin\/bfass\/health`\n* **Response (200 OK)**: `{\"status\": \"reachable\", \"latency_ms\": 42}`\n\n### 6.2 Input Parameter Kredensial BFASS & Auto Assign Tim Teknisi\n* **Endpoint**: `POST \/api\/admin\/provisionings\/{provisioning_id}\/assign-task` (alias `PUT \/admin\/provisionings\/{id}\/bfass-credentials`)\n* **Request Body**:\n  ```json\n  {\n    \"bfass_username\": \"cust_fibermedia_001\",\n    \"bfass_password\": \"SecretPassword123\",\n    \"vlan\": \"100\",\n    \"odp\": \"ODP-JKT-01\/12\",\n    \"onu_serial_number\": \"HWTC12345678\",\n    \"notes\": \"Pemasangan kabel drop core max 150m\"\n  }\n  ```\n* **Efek System**:\n  - Kredensial & parameter jaringan disimpan.\n  - Sistem mengeksekusi penugasan otomatis ke tim teknisi terdekat via *Round-Robin*.\n\n### 6.3 Retry Integration Job BFASS (Jika Gagal Connection)\n* **Endpoint**: `POST \/admin\/provisionings\/{provisioning_id}\/retry`\n* **Response (200 OK)**: `{\"message\": \"Provisioning queued for retry.\"}`\n\n---\n\n## \ud83d\udc77 7. Modul Teknisi Lapangan (Technician Mobile Workflow)\n**Access Control**: `role: Teknisi | Admin | Superadmin`\n\n### 7.1 View Task Assignment Teknisi\n* **Endpoint**: `GET \/teknisi\/tasks`\n* **Detail Task**: `GET \/teknisi\/tasks\/{task_id}`\n\n### 7.2 Update Status Perjalanan \/ Lokasi\n* **Endpoint**: `PUT \/teknisi\/tasks\/{task_id}\/status`\n* **Request Body**: `{\"status\": \"on_the_way\"}` \/ `{\"status\": \"in_progress\"}`\n\n### 7.3 Upload Foto Bukti Lapangan (Before \/ After \/ Selfie)\n* **Endpoint**: `POST \/teknisi\/tasks\/{task_id}\/upload-photo`\n* **Content-Type**: `multipart\/form-data`\n* **Form Data**:\n  - `photo_type`: `before` | `after` | `selfie`\n  - `photo`: File foto JPG\/PNG (Max 5MB)\n\n### 7.4 Upload Tanda Tangan Pelanggan\n* **Endpoint**: `POST \/teknisi\/tasks\/{task_id}\/upload-signature`\n* **Form Data**: `signature` (File Image PNG\/JPG)\n\n### 7.5 Rincian & Update Checklist Pengujian Teknisi\n* **Get Checklist**: `GET \/teknisi\/tasks\/{task_id}\/checklist`\n* **Update Checklist**: `PUT \/teknisi\/tasks\/{task_id}\/checklist`\n  ```json\n  {\n    \"items\": [\n      {\"item_id\": 1, \"is_completed\": true},\n      {\"item_id\": 2, \"is_completed\": true}\n    ]\n  }\n  ```\n\n### 7.6 Submit Phase 1 & Phase 2 Completion\n* **Submit Phase 1**: `POST \/teknisi\/tasks\/{task_id}\/phase-1`\n* **Submit Phase 2**: `POST \/teknisi\/tasks\/{task_id}\/phase-2`\n  ```json\n  {\n    \"completion_notes\": \"Pemasangan modem ONU dan pengujian internet lulus.\",\n    \"latitude\": -6.175392,\n    \"longitude\": 106.827153,\n    \"accuracy\": 10\n  }\n  ```\n\n---\n\n## \ud83d\udccb 8. Modul Admin: Approval, Return, & Export BAST PDF\n\n### 8.1 Approve Hasil Validasi Lapangan Teknisi\n* **Endpoint**: `PUT \/admin\/task-assignments\/{assignment_id}\/approve`\n* **Efek System**: Task menjadi `COMPLETED`, Provisioning menjadi `SUCCESS`, Submission menjadi `COMPLETED`.\n\n### 8.2 Reject \/ Return Bukti Pekerjaan Teknisi\n* **Endpoint**: `PUT \/admin\/task-assignments\/{assignment_id}\/return`\n* **Request Body**: `{\"notes\": \"Foto ONU tidak jelas, harap foto ulang.\"}`\n* **Efek System**: TaskAssignment berstatus `RETURNED`. Teknisi diizinkan mengunggah foto perbaikan baru dan mere-submit Phase 2.\n\n### 8.3 Download Dokumen Resmi BAST PDF\n* **Endpoint**: `GET \/admin\/reports\/submissions\/{submission_id}\/bast`\n* **Header**: `Authorization: Bearer <token>`\n* **Format**: File Download `BAST_SUB-XXXXXX.pdf`\n* **Isi BAST**: Kop Resmi PT Fibermedia, Data Pelanggan, Perangkat & SN ONU, ODP, VLAN, Koordinat GPS, Tabel Checklist Pengujian, dan Kolom Tanda Tangan.\n\n### 8.4 Download Lapran Excel & PDF Detail\n* **Export Excel**: `GET \/admin\/reports\/submissions\/excel`\n* **Export Detail PDF**: `GET \/admin\/reports\/submissions\/{submission_id}\/pdf`\n\n---\n\n## \ud83d\udcca 9. Modul Analytics, KPI, & SLA Breaches Monitoring\n\n* **KPI Summary**: `GET \/admin\/analytics\/kpi`\n* **Funnel Conversion**: `GET \/admin\/analytics\/funnel`\n* **Regional Breakdown**: `GET \/admin\/analytics\/regional`\n* **Trends Analysis**: `GET \/admin\/analytics\/trends`\n* **SLA Breaches Summary**: `GET \/admin\/sla-breaches\/summary`\n* **SLA Breaches List**: `GET \/admin\/sla-breaches`\n\n---\n\n## \u2699\ufe0f 10. Modul Superadmin: User Management & System Logs\n\n* **CRUD Users**: `GET|POST|PUT|DELETE \/superadmin\/users`\n* **Toggle User Active Status**: `PATCH \/superadmin\/users\/{user_id}\/status`\n* **Reset User Password**: `POST \/superadmin\/users\/{user_id}\/reset-password`\n* **User Activity Logs**: `GET \/superadmin\/users\/{user_id}\/activity`\n* **Audit Logs System**: `GET \/admin\/audit-logs`\n\n---\n*Spesifikasi Dokumentasi API v2.1 Frozen - PT Fibermedia Indonesia.*\n","freeze_policy":"# Fibermedia Provisioning System - API Freeze Declaration\n\n**Status**: \ud83d\udd12 **FROZEN (v2.1)**  \n**Effective Date**: 4 Agustus 2026  \n**Target Clients**: Web Admin CMS, Mobile App Sales, Mobile App Teknisi  \n\n---\n\n## 1. Pernyataan API Freeze (API Freeze Policy)\n\nDokumen ini secara resmi menyatakan bahwa seluruh antarmuka pemrograman aplikasi (**REST API v2.1**) untuk **Fibermedia Provisioning System** berada dalam status **API Freeze**.\n\n### Ketentuan API Freeze:\n1. **Kontrak API Terkunci (Contract Immutability)**:\n   Seluruh struktur URL Endpoint, Metode HTTP, Header, Format JSON Request Body, Query Parameter, dan Struktur Response JSON (termasuk tipe data dan kunci nama atribut) **TIDAK BOLEH** diubah tanpa versi mayor baru (`\/api\/v3\/`).\n2. **Tidak Ada Breaking Changes**:\n   Klien Frontend (Web Admin, Mobile Sales, Mobile Teknisi) dapat membangun dan menggunakan seluruh endpoint sesuai spesifikasi resmi tanpa khawatir adanya perubahan nama field, perubahan tipe data, atau pergeseran status code HTTP.\n3. **Penambahan Fitur (Non-breaking Additions)**:\n   Penambahan field opsional di masa mendatang pada response JSON yang bersifat *backward compatible* diperbolehkan dengan persetujuan dokumentasi terlebih dahulu.\n\n---\n\n## 2. Ringkasan Modul & Cakupan Endpoint Terkunci\n\n| Modul System | Jumlah Endpoint | Otorisasi & Middleware | Catatan Modul |\n| :--- | :---: | :--- | :--- |\n| **Auth & Profile** | 9 | Public & Sanctum | Login, Logout, Forgot & Reset Password, Profile & Notification Settings |\n| **Notifications** | 3 | Sanctum | List Notifikasi, Mark Read Single, Mark Read All |\n| **Catalog & Promos** | 2 | Public \/ Sanctum | List Paket Internet & Validasi Kode Promo |\n| **Sales Module** | 5 | `role: Sales \\| Admin \\| Superadmin` | Pengajuan Pendaftaran, Upload Dokumen Berkas Pelanggan |\n| **Admin Submission Validation** | 4 | `role: Admin \\| Superadmin` | Validasi Berkas Pelanggan, Review Dokumen Individual |\n| **Admin Provisioning & BFASS** | 6 | `role: Admin \\| Superadmin` | Input BFASS, Round-Robin Assign Task, Retry Job, Health Check |\n| **Admin Task & SLA** | 5 | `role: Admin \\| Superadmin` | Approval Hasil Teknisi, Return Task, Ringkasan SLA Breaches |\n| **Admin Analytics & Reports** | 7 | `role: Admin \\| Superadmin` | KPI, Funnel, Regional, Trends, Export Excel, Export PDF & **Export BAST PDF** |\n| **Promo & Package Admin** | 10 | `role: Admin \\| Superadmin` | CRUD Promo Code, CRUD & Sync Paket Internet |\n| **Teknisi Module** | 9 | `role: Teknisi \\| Admin \\| Superadmin` | Task List, Update Status, Upload Photo (Before\/After\/Selfie), Upload Signature, Checklist, Phase 1 & Phase 2 |\n| **Superadmin User Mgmt** | 9 | `role: Superadmin` | CRUD User, Activate\/Deactivate, Reset Password, Activity Log, Roles & Permissions |\n| **Audit Logs** | 2 | `role: Admin \\| Superadmin` | System Activity Logs Audit |\n| **TOTAL** | **71 Endpoints** | | **Semua Endpoint Terkunci dalam API Freeze v2.1** |\n\n---\n\n## 3. Standar Status Code HTTP Terkunci\n\n- `200 OK`: Request sukses (Mengembalikan data tunggal atau paginasi).\n- `201 Created`: Resource baru berhasil dibuat.\n- `400 Bad Request`: Parameter request tidak valid atau alur bisnis menyalahi syarat (*workflow transition error*).\n- `401 Unauthorized`: Token Bearer tidak valid, kadaluarsa, atau status akun non-aktif.\n- `403 Forbidden`: Pengguna tidak memiliki Role\/Permission yang sesuai.\n- `404 Not Found`: Resource tidak ditemukan di database.\n- `409 Conflict`: Konflik data unik (misal: duplikasi username BFASS atau duplikasi pendaftaran).\n- `422 Unprocessable Content`: Validasi input gagal (Format rincian error `errors: { field: [\"reason\"] }`).\n- `429 Too Many Requests`: Melebihi batas Rate Limiting (Throttle limit).\n- `500 Internal Server Error`: Kesalahan tidak terduga pada server.\n\n---\n\n## 4. Standar Amplop Response (Response Envelopes)\n\n### Single Resource Response\n```json\n{\n  \"success\": true,\n  \"message\": \"Resource action message\",\n  \"data\": {\n    \"id\": 1,\n    \"field\": \"value\"\n  }\n}\n```\n\n### Paginated Collection Response (Standard Laravel Pagination)\n```json\n{\n  \"data\": [\n    { \"id\": 1, \"field\": \"value\" }\n  ],\n  \"links\": {\n    \"first\": \"http:\/\/localhost:8000\/api\/endpoint?page=1\",\n    \"last\": \"http:\/\/localhost:8000\/api\/endpoint?page=5\",\n    \"prev\": null,\n    \"next\": \"http:\/\/localhost:8000\/api\/endpoint?page=2\"\n  },\n  \"meta\": {\n    \"current_page\": 1,\n    \"from\": 1,\n    \"last_page\": 5,\n    \"per_page\": 15,\n    \"to\": 15,\n    \"total\": 75\n  }\n}\n```\n\n### Error Response\n```json\n{\n  \"success\": false,\n  \"message\": \"Validation failed\",\n  \"errors\": {\n    \"email\": [\n      \"The email field is required.\"\n    ]\n  }\n}\n```\n\n---\n*Penutupan Spesifikasi API Freeze v2.1 - PT Fibermedia Indonesia.*\n"}