Referensi API YoSehat

API YoSehat adalah backend REST berbasis NestJS. Referensi ini merangkum kelompok endpoint dan aturan umum yang dapat diverifikasi dari implementasi. Untuk skema request dan response terkini, gunakan dokumentasi interaktif yang dihasilkan oleh API.

Dokumentasi interaktif

Saat server API berjalan, buka Scalar API Reference di http://localhost:3000/api-docs. Ganti localhost:3000 dengan host dan port API yang digunakan lingkungan Anda. Dokumentasi interaktif dibuat dari metadata OpenAPI aplikasi dan merupakan rujukan utama untuk skema endpoint yang tercakup di sana.

Alamat dan format

• Contoh alamat lokal: http://localhost:3000.
• API tidak memasang global prefix di konfigurasi NestJS. Jalur yang tercantum di bawah digunakan langsung setelah host, misalnya http://localhost:3000/public/packages.
• Respons endpoint umumnya berupa JSON. Endpoint file tertentu dapat mengembalikan konten biner, seperti gambar atau PDF.
• Kirim body JSON dengan Content-Type: application/json bila endpoint menerima body.
• Endpoint yang meminta autentikasi menggunakan header Authorization: Bearer <token>.
• CORS dikonfigurasi untuk metode GET, HEAD, PUT, PATCH, POST, DELETE, dan OPTIONS. Daftar origin berasal dari CORS_ORIGINS; jika tidak disetel, aplikasi menggunakan origin lokal yang ditentukan di backend.

Katalog endpoint

Tabel berikut memakai jalur dengan prefix public untuk endpoint katalog publik. Controller publik juga mendaftarkan alias pada jalur tanpa prefix /public untuk endpoint yang sama.

Status API

Metode	Jalur	Kegunaan
GET	/	Endpoint root yang mengembalikan pesan layanan.

Autentikasi

Semua endpoint pada tabel ini tidak memerlukan token untuk memulai proses autentikasi. Endpoint verifikasi memerlukan kode pada jalur.

Metode	Jalur	Kegunaan
POST	/user/auth/login	Masuk sebagai pengguna/pasien.
POST	/user/auth/register	Mendaftarkan pengguna/pasien.
GET	/user/auth/code-verification/:code	Memeriksa kode verifikasi akun pengguna.
GET	/user/auth/mail-verification/:code	Memverifikasi email pengguna.
POST	/user/auth/forgot-password	Meminta pemulihan kata sandi pengguna.
POST	/user/auth/reset-password/:code	Mengatur ulang kata sandi dengan kode.
POST	/professional/auth/login	Masuk sebagai profesional.
POST	/professional/auth/register	Mengirim pendaftaran profesional.
GET	/professional/auth/code-verification/:code	Memeriksa kode verifikasi profesional.
GET	/professional/auth/mail-verification/:code	Memverifikasi email profesional.
POST	/professional/auth/forgot-password	Meminta pemulihan kata sandi profesional.
POST	/professional/auth/reset-password/:code	Mengatur ulang kata sandi profesional dengan kode.
POST	/admin/auth/login	Masuk sebagai admin.
POST	/admin/auth/account-verification/:code	Memverifikasi akun admin dengan kode.
GET	/admin/auth/code-verification/:code	Memeriksa kode verifikasi admin.
GET	/admin/auth/mail-verification/:code	Memverifikasi email admin.
POST	/admin/auth/forgot-password	Meminta pemulihan kata sandi admin.
POST	/admin/auth/reset-password/:code	Mengatur ulang kata sandi admin dengan kode.

Katalog dan data publik

Endpoint berikut tidak memerlukan token:

Metode	Jalur	Kegunaan
GET	/public/gender	Daftar pilihan gender.
GET	/public/qualification-level	Daftar tingkat kualifikasi.
GET	/public/packages	Daftar paket; menerima parameter pagination.
GET	/public/packages/img/:img	Mengambil gambar paket.
GET	/public/profession	Daftar profesi.
GET	/public/professions/main	Daftar profesi utama.
GET	/public/professions/:parentId/children	Daftar profesi turunan.
GET	/public/products	Daftar produk.
GET	/public/products/:productId	Detail produk.
GET	/public/products/:productId/services	Layanan untuk produk.
GET	/public/products/:productId/service-tasks	Tugas layanan untuk produk.
GET	/public/products/images/:img	Mengambil gambar produk.
GET	/public/services	Daftar layanan.
GET	/public/services/:serviceId	Detail layanan.
GET	/public/services/:serviceId/tasks	Tugas untuk layanan.
GET	/public/services/images/:img	Mengambil gambar layanan.
GET	/public/service-tasks	Daftar tugas layanan.
GET	/public/address/provinces	Daftar provinsi.
GET	/public/address/provinces/:provinceId/regencies	Kabupaten/kota dalam provinsi.
GET	/public/address/regencies/:regencyId/districts	Kecamatan dalam kabupaten/kota.
GET	/public/address/districts/:districtId/villages	Desa/kelurahan dalam kecamatan.
GET	/public/articles	Daftar artikel publik; menerima limit (default 12).
GET	/public/article-categories	Daftar kategori artikel publik.
GET	/public/articles/:code	Detail artikel berdasarkan kode.

Profil, pasien, dan notifikasi pengguna

Endpoint di bawah memerlukan token pengguna. Data dibatasi ke akun yang terautentikasi.

Metode	Jalur	Kegunaan
GET	/user/dashboard/profile	Melihat profil dashboard.
PATCH	/user/dashboard/profile	Memperbarui profil.
GET	/user/dashboard/patients	Melihat daftar pasien milik pengguna.
POST	/user/dashboard/patients	Menambahkan pasien atau anggota keluarga.
PATCH	/user/dashboard/patients/:id	Memperbarui data pasien.
DELETE	/user/dashboard/patients/:id	Menghapus data pasien.
GET	/user/dashboard/notifications	Melihat notifikasi pengguna.
PATCH	/user/dashboard/notifications/read	Menandai semua notifikasi sebagai dibaca.
PATCH	/user/dashboard/notifications/:id/read	Menandai satu notifikasi sebagai dibaca.
GET	/user/dashboard/orders	Melihat daftar pesanan dashboard.
GET	/user/dashboard/orders/:code/medical-record	Mengambil rekam medis pesanan.

Endpoint pengguna lainnya

Endpoint di bawah juga berada di bawah guard pengguna dan memerlukan token pengguna. Beberapa rute katalog lama tetap tersedia selain endpoint katalog publik.

Metode	Jalur	Kegunaan
GET	/user/refresh	Memeriksa akses token pengguna.
GET	/user/profile	Melihat profil akun.
GET	/user/profile/photo	Mengambil foto profil.
POST	/user	Membuat data pengguna.
GET	/user/:id	Mengambil data pengguna berdasarkan ID.
GET	/user/username/:username	Mencari data berdasarkan username.
GET	/user/email/:email	Mencari data berdasarkan email.
GET	/user/charge dan /user/charge/:id	Daftar atau detail charge.
GET	/user/district, /user/district/:id	Daftar atau detail kecamatan.
GET	/user/regency/:id/districts	Kecamatan berdasarkan kabupaten/kota.
GET	/user/master-data/:id	Master data berdasarkan ID.
GET	/user/master-data/group/:group	Master data berdasarkan grup.
GET	/user/package dan /user/package/:id	Daftar paket berpaginasi atau detail paket.
GET	/user/product dan /user/product/:id	Daftar produk berpaginasi atau detail produk.
GET	/user/professional/:id	Detail profesional.
GET	/user/province dan /user/province/:id	Daftar atau detail provinsi.
GET	/user/regency dan /user/regency/:id	Daftar atau detail kabupaten/kota.
GET	/user/province/:id/regencies	Kabupaten/kota berdasarkan provinsi.
GET	/user/service-task dan /user/service-task/:id	Daftar atau detail tugas layanan.
GET	/user/village dan /user/village/:id	Daftar desa/kelurahan berpaginasi atau detail.
GET	/user/district/:id/villages	Desa/kelurahan berdasarkan kecamatan.
GET	/user/voucher	Voucher yang tersedia; menerima packageId opsional.
GET	/user/voucher/used	Voucher yang sudah digunakan.
GET	/user/voucher/:id	Detail voucher; dapat menerima packageId.

Pesanan pengguna

Endpoint pesanan pasien memerlukan token pengguna.

Metode	Jalur	Kegunaan
GET	/user/orders	Daftar pesanan dengan filter/pagination.
POST	/user/orders/quote	Menghitung ringkasan harga paket dan voucher.
POST	/user/orders	Membuat pesanan.
GET	/user/orders/:code	Melihat detail pesanan.
POST	/user/orders/:code/payment	Memulai proses pembayaran pesanan.
PATCH	/user/orders/:code/reschedule	Mengubah jadwal kunjungan.
PATCH	/user/orders/:code/cancel	Membatalkan pesanan.
PATCH	/user/orders/:code/review	Mengirim penilaian pesanan.

Bentuk request pesanan

POST /user/orders/quote menerima packageId dan voucherCode opsional. POST /user/orders menerima data pesanan, termasuk sesi kunjungan. Contoh struktur berikut menunjukkan nama field yang diterima; ganti ID contoh dengan ID yang dikembalikan API:

{
  "packageId": "507f1f77bcf86cd799439011",
  "patientId": "507f1f77bcf86cd799439012",
  "voucherCode": "PROMO",
  "address": "Alamat lengkap lokasi kunjungan",
  "note": "Catatan tambahan",
  "sessions": [
    {
      "startDate": "2026-12-10T09:00:00.000Z",
      "endDate": "2026-12-10T10:00:00.000Z"
    }
  ],
  "serviceTaskIds": ["507f1f77bcf86cd799439013"],
  "genderPreference": "any",
  "paymentPreference": "all",
  "coordinates": [106.8272, -6.1754]
}

sessions wajib berisi 1–30 rentang waktu ISO 8601. address wajib sepanjang 5–500 karakter. serviceTaskIds opsional, unik, dan maksimal 30 ID. genderPreference menerima female, male, atau any; paymentPreference menerima all, qris, bca_va, atau echannel. coordinates opsional dan jika dikirim harus berisi dua angka. Field opsional note maksimal 500 karakter dan voucherCode maksimal 100 karakter.

PATCH /user/orders/:code/reschedule menerima startDate dan endDate dalam format ISO 8601. PATCH /user/orders/:code/cancel menerima reason dan dapat menerima requestRefund; jika nilainya true, bankName, accountHolder, dan accountNumber wajib dikirim. PATCH /user/orders/:code/review menerima rating 1–5, serta tags dan komentar opsional.

Portal profesional

Endpoint profil dan dashboard profesional memerlukan token dengan jenis akun profesional. Endpoint pencarian alamat di bawah tidak memasang guard autentikasi.

Metode	Jalur	Kegunaan
GET	/professional/profile	Melihat profil profesional.
PATCH	/professional/profile	Memperbarui profil profesional.
GET	/professional/profile/photo	Mengambil foto profil.
GET	/professional/address/provinces	Daftar provinsi untuk alamat profesional.
GET	/professional/address/provinces/:provinceId/regencies	Kabupaten/kota dalam provinsi.
GET	/professional/address/regencies/:regencyId/districts	Kecamatan dalam kabupaten/kota.
GET	/professional/address/districts/:districtId/villages	Desa/kelurahan dalam kecamatan.
GET	/professional/dashboard/profile	Profil dashboard profesional.
GET	/professional/dashboard/assistants	Daftar asisten profesional.
GET	/professional/dashboard/analytics	Ringkasan analitik; dapat menerima range.
GET	/professional/dashboard/delegated-orders	Pesanan yang didelegasikan.
GET	/professional/dashboard/incoming-orders	Pesanan masuk.
GET	/professional/dashboard/order-history	Riwayat pesanan.
PATCH	/professional/dashboard/online	Mengubah status online.
GET	/professional/dashboard/notifications	Melihat notifikasi profesional.
PATCH	/professional/dashboard/notifications/read	Menandai semua notifikasi sebagai dibaca.
PATCH	/professional/dashboard/notifications/:id/read	Menandai satu notifikasi sebagai dibaca.
GET	/professional/dashboard/working-hours	Melihat jam kerja.
PATCH	/professional/dashboard/working-hours	Memperbarui jam kerja.
GET	/professional/dashboard/travel-pricing	Melihat tarif perjalanan.
PATCH	/professional/dashboard/travel-pricing	Memperbarui tarif perjalanan.
POST	/professional/orders/:code/accept	Menerima pesanan.
POST	/professional/orders/:code/reject	Menolak pesanan.
POST	/professional/orders/:code/delegate	Mendelegasikan pesanan.
GET	/professional/orders/:code/rme.pdf	Mengambil PDF rekam medis elektronik.

Portal admin dan operasional pesanan

Endpoint admin memerlukan token dengan jenis akun admin. Rute ini meliputi operasi pengelolaan dan sebaiknya hanya digunakan sesuai kewenangan admin.

Metode	Jalur	Kegunaan
GET	/admin/orders/dashboard	Ringkasan dashboard pesanan.
GET	/admin/orders/workload	Ringkasan beban kerja.
GET	/admin/orders/pending-assignment	Daftar pesanan yang menunggu penugasan manual.
GET	/admin/orders/payments	Daftar transaksi dan filter status.
GET	/admin/orders/payments/:code	Detail transaksi.
PATCH	/admin/orders/:code/refund	Mencatat transfer refund manual yang sudah dilakukan.
GET	/admin/orders/settlements	Melihat alokasi dan settlement.
PATCH	/admin/orders/settlements/:professionalId/transfer	Mencatat transfer settlement yang sudah dilakukan.
GET	/admin/orders/:code/candidates	Kandidat tenaga kesehatan untuk penugasan.
POST	/admin/orders/:code/assign	Menetapkan tenaga kesehatan secara manual.
POST	/payments/midtrans/notification	Menerima notifikasi pembayaran Midtrans.

Pencatatan refund atau settlement bukan instruksi transfer bank. Ikuti alur keuangan organisasi dan pastikan transfer telah dilakukan sebelum mencatatnya.

Filter status untuk GET /admin/orders/payments menerima all, paid, unpaid, failed, refund-eligible, atau refunded, selain parameter pagination. Untuk PATCH /admin/orders/:code/refund, body memuat transactionReference. Untuk PATCH /admin/orders/settlements/:professionalId/transfer, body memuat periodStart, periodEnd, dan transferReference. Untuk POST /admin/orders/:code/assign, body memuat professionalId.

Pengelolaan admin

Rute berikut berada di bawah /admin dan menggunakan autentikasi admin.

• Akun dan notifikasi: GET /admin/refresh, GET /admin/profile, PATCH /admin/profile, GET /admin/notifications, PATCH /admin/notifications/read, PATCH /admin/notifications/:id/read.
• Administrator: daftar, pembuatan, foto, detail, pengubahan, dan penonaktifan akun melalui /admin/admins dan subrutenya.
• Verifikasi profesional: GET /admin/professional/not_verified, GET /admin/professional/verification/summary, GET /admin/professional/:id, PATCH /admin/professional/:id, dan GET /admin/professional/document/:filename.
• Charge: /admin/charge, /admin/charge/deleted, dan /admin/charge/:id; pembuatan melalui /admin/charge/create, serta aksi hapus/pulihkan.
• Master data: /admin/master-data, /admin/master-data/deleted, /admin/master-data/group/:group, /admin/master-data/parent/:parentId, /admin/master-data/code/:code, dan /admin/master-data/:id; tersedia pembuatan, pengubahan, hapus, dan pulihkan.
• Paket dan produk: /admin/package dan /admin/product beserta detail /:id, pembuatan, pengubahan, penghapusan, pemulihan, serta daftar terhapus produk.
• Profesi: /admin/profession, /admin/profession/deleted, /admin/all-profession, /admin/main-profession, dan /admin/profession/:id, beserta pembuatan, pengubahan, penghapusan, dan pemulihan.
• Layanan dan tugas: /admin/service dan /admin/service-task beserta detail, pembuatan, pengubahan, hapus, pulihkan, daftar terhapus, serta /admin/service-task/product/:productId dan /admin/service-task/service/:serviceId.
• Geografi: endpoint admin /admin/province, /admin/regency, /admin/district, dan /admin/village, dengan operasi daftar, detail, pembuatan, perubahan, dan penghapusan sesuai sumber daya.
• Voucher: /admin/voucher, /admin/voucher/deleted, /admin/voucher/:id, /admin/voucher/code/:code, /admin/voucher/:id/usage, dan /admin/voucher/:id/status, beserta pembuatan, pengubahan, penghapusan, dan pemulihan.
• Artikel: pengelolaan artikel dan kategori melalui /admin/articles dan /admin/article-categories, termasuk daftar terhapus, pemulihan, pembuatan, pengubahan, dan penghapusan.

Lihat Scalar API Reference untuk metode dan skema body/query dari setiap rute admin. Operasi penghapusan atau pemulihan dapat memiliki perilaku berbeda menurut jenis data.

Parameter pagination

Endpoint yang menerima PaginationParamsDto menggunakan parameter query berikut. Tidak semua endpoint memakai DTO ini.

Parameter	Tipe	Default	Aturan
page	integer	1	Minimal 1.
limit	integer	10	Minimal 1.
search	string	—	Teks pencarian opsional.
sortBy	string	createdAt	Nama field pengurutan.
sortOrder	asc atau desc	desc	Arah pengurutan.

Contoh: GET /public/packages?page=1&limit=10&sortOrder=desc.

Validasi request

Backend menjalankan ValidationPipe global dengan whitelist dan transform. Field yang tidak dikenal pada DTO dapat diabaikan, dan nilai yang memiliki transformasi dapat dikonversi sebelum diproses. Setiap endpoint dapat memiliki aturan validasi tambahan; periksa skema endpoint pada dokumentasi interaktif.

Respons dan status error tidak dibungkus dalam satu skema yang dijamin untuk semua endpoint. Gunakan status HTTP serta pesan yang dikembalikan endpoint sebagai sumber informasi untuk menangani kegagalan.