Lewati ke konten utama

Customer Registration Flow

Dokumentasi ini menjelaskan urutan proses dan pemanggilan API yang dibutuhkan Frontend (FE) untuk memfasilitasi pembuatan akun Customer baru (Registrasi Mandiri). Alur pendaftaran ini melibatkan 3 langkah utama: permintaan OTP, verifikasi OTP, dan melengkapi data profil.

Diagram Alur Pendaftaran​

Berikut adalah visualisasi urutan interaksi sistem untuk registrasi.

Urutan Integrasi API untuk Frontend​

Step 1: Meminta Tautan Registrasi​

Pada tahap awal, sistem hanya meminta Email calon pengguna untuk divalidasi dan dikirimi tautan (link) registrasi yang mengandung kode OTP di baliknya.

Request
POST /api/auth/otp/request
Content-Type: application/json
Request Body
{
  "email": "newuser@frogcloud.com",
  "request_type": "REGISTER"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Backend berhasil mengirim tautan registrasi ke email pengguna. FE harus menampilkan halaman/modal instruksi "Silakan cek kotak masuk email Anda".
  • Error (400 Bad Request): Jika batasan permintaan telah terpenuhi (Max OTP Attempts berdasarkan .env), Backend akan mengembalikan kode error Rate Limit atau sejenisnya. Tampilkan pesan kesalahan untuk menunggu beberapa saat. Kemungkinan lain karena email sudah terdaftar di sistem. Tampilkan pesan error kepada pengguna (misal: "Email sudah terdaftar, silakan login").

Step 2: Verifikasi Tautan Registrasi​

Setelah pengguna mengeklik tautan yang dikirimkan ke email mereka (contoh: https://frogcloud.com/verify-registration?email=...&code=123456), pengguna akan diarahkan kembali ke Frontend. FE harus mengekstrak parameter email dan code dari URL tersebut dan mengirimkannya ke Backend.

Request
POST /api/auth/registration/verify
Content-Type: application/json
Request Body
{
  "email": "newuser@frogcloud.com",
  "code": "123456"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Tautan/Kode valid. Backend merespons sukses dan secara otomatis menanamkan HTTP-Only Cookies ke browser pengguna. Cookies ini berisi sesi sementara yang sangat krusial sebagai tiket otorisasi untuk langkah ketiga. FE dapat melanjutkan navigasi ke halaman pengisian profil.
  • Error (400 Bad Request): Kode salah atau sudah kadaluarsa. Tampilkan pesan error (misal: "Tautan tidak valid atau sudah hangus").

Step 3: Melengkapi Profil & Finalisasi (Complete Registration)​

Pada langkah terakhir, pengguna mengisi kelengkapan data pribadi, password, dan info bisnis (opsional). Pemanggilan API ini harus membawa Cookies sesi yang didapatkan dari Step 2.

Request
POST /api/auth/registration/complete
Content-Type: application/json
Request Body
{
  "account_type": "P",
  "password": "PasswordKuat123!",
  "personal": {
    "first_name": "Budi",
    "last_name": "Santoso",
    "country_id": "ID",
    "province_id": "31",
    "city_id": "3173",
    "address": "Jl. Jend. Sudirman No.1",
    "phone": "081234567890"
  }
}

Catatan Parameter:

  • account_type: "P" untuk Personal, "B" untuk Business.
  • Jika account_type adalah "B", pastikan untuk menambahkan objek business di request body.
Penting: Data Wilayah (Region)

Nilai untuk country_id, province_id, city_id, dan district_id tidak boleh diisi dengan teks bebas. Frontend wajib mengambil data ini secara berurutan melalui Endpoint Lookup API yang telah disediakan di backend:

  • GET /api/lookup/country (Mendapatkan referensi ID Negara)
  • GET /api/lookup/province (Mendapatkan referensi ID Provinsi)
  • GET /api/lookup/city?province_id={id} (Mendapatkan referensi ID Kota berdasarkan Provinsi yang dipilih)
  • GET /api/lookup/district?city_id={id} (Mendapatkan referensi ID Distrik berdasarkan Kota yang dipilih)

Pastikan form pendaftaran pada UI (User Interface) menggunakan komponen dropdown atau select yang memanggil API-API di atas agar ID yang dikirimkan selalu valid.

Kondisi & Tindakan:

  • Sukses (200 OK): Akun pengguna telah berhasil dibuat sepenuhnya dan sudah bisa digunakan. FE dapat langsung mengalihkan (redirect) pengguna ke /dashboard karena Cookies otentikasi penuh akan diperbarui oleh Backend pada respons ini.
  • Error (400 / 401): Jika 401, berarti sesi sementara dari Step 2 hilang atau kadaluarsa (pengguna harus mengulang dari Step 1). Jika 400, terdapat validasi pengisian data yang salah (misal: password kurang kuat, no HP tidak valid). Tampilkan pesan error pada form.