📖 API Sync & Upload Documentation

🌐 Base URL & Global Rules

Base URL: https://android.urice.id

Content-Type: application/json (kecuali SSE: text/event-stream, Upload: multipart/form-data)

Column	Type	Trigger Update	Kegunaan Utama
createdAt	TIMESTAMP	Saat record pertama dibuat	Audit trail, sorting berdasarkan waktu pembuatan
updatedAt	TIMESTAMP	Setiap insert/update (lokal atau server)	Conflict resolution, parameter sinceTimestamp saat pull
syncStatus	ENUM	Proses push/pull & conflict detection	State queue: PENDING → SYNCED → CONFLICT → FAILED
lastSyncedAt	TIMESTAMP	Hanya saat push/pull berhasil dikonfirmasi server	Marker keberhasilan sync, optimasi pull berikutnya

📝 Field Tambahan (Terbaru)

Tabel	Column	Type	Keterangan
projects	supervisorServerId	CHAR(36)	FK ke users.userServer. Penanggung jawab proyek
projects	location	VARCHAR(255)	Alamat/lokasi pelaksanaan proyek
project_participants	assignmentDate	DATETIME	Tanggal & waktu pelaksanaan penugasan

Sistem menggunakan pendekatan Upload-First → Sync-Second. File media harus sukses terupload ke server sebelum record database dikirim.

📍 Step-by-Step Flow

🔁 State Machine: syncStatus

Status	Pemicu	Aksi Selanjutnya
PENDING	Data diubah/dibuat saat offline	Akan di-upload & dipush saat jaringan tersedia
SYNCED	Push/Pull berhasil dikonfirmasi server	Hapus cache lokal, siap operasi offline baru
CONFLICT	Server menolak karena updatedAt lebih lama	UI menampilkan prompt resolve. Setelah pilih versi → set PENDING → push ulang
FAILED	Network error / server 5xx / FK violation	Tetap PENDING, retry otomatis dengan exponential backoff

📁 Struktur Folder Berbasis UUID

Setiap upload disimpan dalam folder unik berdasarkan {table}/{uuid}/. Client wajib generate UUID v4 di lokal sebelum upload agar server bisa menyimpan file dengan struktur yang rapi & predictable.

uploads/
├── .htaccess (Block PHP & Indexing)
├── attendance/
│   └── 550e8400-e29b-41d4-a716-446655440011/
│       └── 1715500000_a1b2c3d4.jpg      ← Single file
├── users/
│   └── ffef-bce3-0e8a-4c87-80e2/
│       └── 1715500100_e5f6g7h8.png      ← Profile photo
└── task_evidence/
    └── 550e8400-.../
        ├── img1_1715500200.jpg          ← Multiple files
        ├── img2_1715500201.jpg
        └── vid3_1715500202.mp4

📡 Endpoint: POST /api/upload

Parameter	Type	Required	Desc
type	string	Yes	Nama tabel: attendance, users, task_evidence
uuid	string	Yes	UUID v4 dari record lokal (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
photos[]	file[]	Yes	Array binary files. Support multiple upload sekaligus. Max 5MB/file, ext: jpg,jpeg,png,webp

📥 Contoh Request (Multiple Files - Task Evidence)

Gunakan multipart/form-data. Perhatikan penamaan field photos[] (dengan kurung siku) agar PHP mengenali sebagai array.

POST /api/upload HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="type"

task_evidence
------WebKitFormBoundary
Content-Disposition: form-data; name="uuid"

550e8400-e29b-41d4-a716-446655440099
------WebKitFormBoundary
Content-Disposition: form-data; name="photos[]"; filename="bukti1.jpg"
Content-Type: image/jpeg

(binary data...)
------WebKitFormBoundary
Content-Disposition: form-data; name="photos[]"; filename="bukti2.jpg"
Content-Type: image/jpeg

(binary data...)
------WebKitFormBoundary--

📤 Response Success (200)

{
  "status": 200,
  "message": "Upload completed",
  "data": {
    "files": [
      { "status": "success", "filename": "1715500200_a1b2.jpg", "path": "uploads/task_evidence/550e8400-.../1715500200_a1b2.jpg" },
      { "status": "success", "filename": "1715500201_c3d4.jpg", "path": "uploads/task_evidence/550e8400-.../1715500201_c3d4.jpg" }
    ]
  }
}

🔄 Refresh Token Strategy

Strategi	Cara Kerja	Rekomendasi
✅ Proactive	Cek exp di JWT lokal. Jika sisa < 7 hari, otomatis call /auth/refresh	WAJIB. Hindari 401 saat user bekerja.
🔁 Reactive	Interceptor tangkap 401 → call /refresh → retry request awal	BACKUP. Handle clock skew atau app lama idle.
⚠️ Deactivation	Server balikin 403 saat isActive=false	Client harus clear session & redirect login. JANGAN retry.

POST /api/auth/login

📥 Body: {"username":"superadmin","password":"123456"}

📤 ✅ (200): {"data":{"token":"eyJ...","userServer":"uuid","roleId":"R001","isActive":true}}

POST /api/auth/refresh & GET /api/auth/verify

📥 Headers: Authorization: Bearer <token>

📤 ✅ Refresh (200): {"data":{"token":"eyJ...","expiresIn":2592000}}

📤 ✅ Verify (200): {"data":{"userServer":"uuid","roleId":"R001","isActive":true,"expiresIn":2500000}}

❌ Error: 401 (invalid/expired), 403 (akun dinonaktifkan)

POST /api/sync?action=push Bearer Required

Mengirim data PENDING dari database lokal device ke server. Endpoint ini menangani insert baru, update, soft delete, dan conflict resolution secara otomatis dalam satu transaksi ACID.

📥 Request Structure

Field	Type	Required	Deskripsi
table	string	Yes	Nama tabel target. Harus terdaftar di SYNCABLE_TABLES (whitelist). Tabel master seperti users, roles, jabatan ditolak otomatis demi keamanan.
records	array	Yes	Array objek data lokal. Maksimal 100 record per request untuk menghindari timeout server.

📝 Field Rules per Record

• ✅ Primary Key wajib ada (UUID v4 valid).
• ✅ Foreign Keys harus sudah ada di server DB. Jika tidak → 409 FK Violation.
• ✅ updatedAt wajib lebih baru dari versi server agar diterima. Jika lebih lama/sama → masuk conflicts.
• 📸 File Fields: Gunakan path relatif hasil upload. Jangan kirim path lokal device.

⚙️ Server Processing Logic

📤 Response Format

✅ Success (200):

{
  "status": 200,
  "message": "Push processed",
  "data": {
    "synced": ["550e8400-e29b-41d4-a716-446655440050"],
    "conflicts": [{ "uuid": "550e8400-...", "serverData": { "updatedAt": "...", "deletedAt": null } }]
  }
}

GET /api/sync?action=pull Bearer Required

Tarik data server yang berubah sejak timestamp terakhir. Tidak menyertakan record soft-deleted.

📥 Query: ?sinceTimestamp=2026-05-01 00:00:00

📤 ✅ (200): {"data":{"records":{"attendance":[...],"kwitansi":[...]},"nextPullTimestamp":"..."}}

Master Data POST / GET / PUT / DELETE /api/users

CRUD User Management (SuperAdmin Only). TIDAK termasuk dalam sync push/pull. Password otomatis didekripsi saat ambil detail.

📥 List Users (Ringan)

GET /api/users?page=1&limit=20&search=budi&active=true

📤 ✅ (200): {"data":[{"userServer":"uuid","nama":"Budi","isActive":true}], "pagination":{...}}

📥 Detail User + Decrypted Password

GET /api/users?id=<uuid>

📤 ✅ (200):

{
            "status": 200,
            "message": "User detail retrieved successfully",
            "data": {
                "userServer": "550e8400-...",
                "nik": "3271009999999999",
                "username": "karyawan.baru",
                "password": "123456",        ← ✅ Plain text (auto-decrypt)
                "passwordHash": "U2FsdGVkX1+...",  ← Tetap ada untuk sync
                "roleId": "R004",
                "jabatanId": "J004",
                "nama": "Ahmad Fauzi",
                "handphone": "081299998888",
                "email": "ahmad@test.com",
                "dailySalary": 150000,
                "isActive": true,
                "createdAt": "2026-05-20 10:00:00",
                "updatedAt": "2026-05-20 10:00:00"
            }
            }

📥 Create / Update / Delete

• POST /api/users → Create user baru (password dienkripsi otomatis)
• PUT/PATCH /api/users?id=<uuid> → Update partial field
• DELETE /api/users?id=<uuid>[&type=hard] → Soft delete (default) atau hard delete

🧾 Kwitansi: Client-Side Generation & No-Delete Policy

Tabel kwitansi tidak akan dihapus (no soft/hard delete). Semua penomoran ditangani sepenuhnya di sisi aplikasi.

📐 Format Kode

[SEQ]/KWT/BCL/[MM]/[YY]

Contoh: 001/KWT/BCL/05/26, 002/KWT/BCL/05/26...

📱 Aturan Generate di Client

• ✅ App wajib query MAX(sequence) bulan berjalan di local DB sebelum generate.
• ✅ Sequence di-reset otomatis saat pergantian bulan (logic ada di format string, bukan DB).
• ✅ Server tidak auto-generate. Hanya menerima & menyimpan payload dari client.
• ⚠️ Jika terjadi 409 Duplicate saat push, client harus increment sequence & retry.

📥 Contoh Payload

{
  "table": "kwitansi",
  "records": [{
    "kwitansiServer": "550e8400-...",
    "milestoneServer": "550e8400-...",
    "kwitansiCode": "001/KWT/BCL/05/26",  ← Generated by App
    "tanggal": "2026-05-20",
    "nominal": 5000000,
    "isLunas": false,
    "syncStatus": "PENDING",
    "updatedAt": "2026-05-20 10:00:00"
  }]
}

• ✅ PHP 8.1+ aktif di hPanel
• ✅ composer install --no-dev --optimize-autoloader selesai
• ✅ .env dibuat manual (JANGAN commit). Kunci: JWT_SECRET, ENCRYPTION_KEY
• ✅ Folder logs/ & uploads/ writable (chmod 755)
• ✅ .htaccess aktif: blokir .env, logs/, force clean URL
• ✅ DB schema import + dummy data roles, jabatan, users terisi
• ✅ Timezone PHP & MySQL disamakan (Asia/Jakarta atau UTC)
• ✅ Upload security: .htaccess di uploads/ blokir eksekusi PHP & directory listing