Developer · API

Akun & preferensi

Identitas sesi, pembaruan nama/username, dan pengaturan notifikasi serta tampilan ringkas.

Sebelum mengirim request

Endpoint ini bukan pengganti Better Auth. Penggantian email/password dan pengelolaan role tidak tersedia melalui PATCH /api/me. Profil dan preferensi disimpan di server untuk akun bersesi.

Kontrak nyata, nilai contoh

Endpoint, field, dan status HTTP mengikuti implementasi. Nilai ID, nomor, OTP, waktu, saldo, serta quote di contoh adalah ilustrasi, bukan data akun atau pilihan yang bisa langsung dibeli. Ganti dengan data dari instalasimu. Halaman ini tidak mengirim request atau menjalankan transaksi.

JavaScript dijalankan pada origin aplikasi setelah login. Contoh cURL memakai PING_ORIGIN dan cookie jar PING_COOKIE_JAR dari panduan autentikasi. Sukses memakai { ok: true, data }; create juga HTTP 200, bukan 201. Semua endpoint di halaman ini memerlukan sesi aktif dan dapat mengembalikan 401, 403, atau 500.

Pulihkan intent transaksi

GET/api/request-intentsSession cookie

Membaca satu intent akun yang belum diakui. UUID, nominal, dan pilihan tetap tersimpan lintas dialog, reload, dan sesi. result berasal dari order milik akun atau audit koreksi yang berhasil. Scope wallet-adjustment memerlukan admin aktif; data akun lain tidak dapat dibaca.

Pulihkan intent transaksi
Parameter	Tipe	Wajib	Keterangan
scope (query)	IntentScope	Ya

GET /api/request-intents · JavaScript

const response = await fetch("/api/request-intents?scope=purchase", {
  credentials: "same-origin",
  cache: "no-store",
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Pulihkan intent transaksi
Kode error	HTTP	Tindakan
VALIDATION_ERROR	400	Periksa tipe, field wajib, format UUID, dan field tambahan.

Simpan intent sebelum transaksi

POST/api/request-intentsSession cookie

Menyimpan intent sebelum pembelian atau koreksi saldo dikirim. Satu intent belum diakui per akun/scope; request bersamaan dan detail baru mengembalikan intent awal, bukan UUID baru. Pembelian menerima quantity 1–100 (default 1) dalam sisa batas pesanan aktif akun, memeriksa kapasitas seluruh jumlah, dan menyimpan requestIds tetap. Kirim satu POST /api/orders per UUID dengan pilihan dan harga per nomor yang sama. Hentikan sisa pembelian saat terjadi penolakan; hasil tidak pasti dipulihkan dengan UUID awal. Gunakan requestId untuk koreksi admin dan pengakuan intent. Penyimpanan intent sendiri tidak membeli nomor atau memindahkan uang.

Simpan intent sebelum transaksi
Body JSON	Tipe	Wajib	Keterangan
scope	IntentScope	Ya	Lihat schema IntentScope pada OpenAPI.
payload	IntentPayload	Ya	Lihat schema IntentPayload pada OpenAPI.

POST /api/request-intents · JavaScript

const response = await fetch("/api/request-intents", {
  method: "POST",
  credentials: "same-origin",
  cache: "no-store",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "scope": "purchase",
    "payload": {
      "provider": "v3",
      "serviceId": "service-example",
      "countryId": "country-example",
      "priceOptionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "expectedPriceIdr": 1500
    }
  }),
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Simpan intent sebelum transaksi
Kode error	HTTP	Tindakan
VALIDATION_ERROR	400	Periksa tipe, field wajib, format UUID, dan field tambahan.
NOT_FOUND	404	Periksa ID dan akun; ID resource tidak memberi akses lintas pengguna.
PROVIDER_MISMATCH	422	Pertahankan server asal. Resend tersedia pada semua server (v1–v4) saat provider mengizinkan; jangan memindahkan aktivasi ke provider lain.
CONFLICT	409	Baca pembayaran aktif, jangan terus membuat top-up baru. Untuk konflik profil, pilih username lain; kapitalisasi berbeda tetap dianggap username yang sama.
ACTIVE_ORDER_LIMIT	429	Selesaikan order yang ada; limit mengikuti pengaturan operator.
ORDER_RATE_LIMIT	429	Jeda percobaan. Jangan membuat loop POST.
INSUFFICIENT_BALANCE	422	Tampilkan available dari server dan tawarkan top-up.

Akui hasil intent awal

DELETE/api/request-intentsSession cookie

Menandai intent akun/scope dengan requestId yang sama sebagai telah diakui setelah hasil diterima atau penolakan definitif. Timeout, error jaringan, atau hasil belum diketahui bukan alasan mengakui intent. Tidak membatalkan order atau mengubah ledger; request tidak cocok tidak menghapus intent lain.

Akui hasil intent awal
Body JSON	Tipe	Wajib	Keterangan
scope	IntentScope	Ya	Lihat schema IntentScope pada OpenAPI.
requestId	string · uuid	Ya	Sesuai tipe yang ditampilkan.

DELETE /api/request-intents · JavaScript

const response = await fetch("/api/request-intents", {
  method: "DELETE",
  credentials: "same-origin",
  cache: "no-store",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "scope": "purchase",
    "requestId": "f41c29d8-967d-469d-ae4f-0114c38bf715"
  }),
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Baca akun & saldo

GET/api/meSession cookie

Mengembalikan identitas sesi dan ringkasan dompet. username dapat null. role berasal dari server; client tidak dapat menentukan role sendiri.

GET /api/me · JavaScript

const response = await fetch("/api/me", {
  credentials: "same-origin",
  cache: "no-store",
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Ubah profil

PATCH/api/meSession cookie

Memperbarui nama dan username. Kedua field wajib dikirim bersama. Username unik tanpa membedakan huruf besar/kecil; username yang sudah digunakan akun lain menghasilkan CONFLICT / 409. Endpoint ini bukan untuk mengganti email, password, role, atau userId.

Ubah profil
Body JSON	Tipe	Wajib	Keterangan
name	string	Ya	Nama 1–60 karakter setelah trim. Wajib bersama username.
username	string	Ya	3–24 karakter: huruf, angka, titik, atau underscore; input di-trim. Unik tanpa membedakan huruf besar/kecil; kapitalisasi tampilan dipertahankan. Username yang dipakai akun lain menghasilkan CONFLICT / 409.

PATCH /api/me · JavaScript

const response = await fetch("/api/me", {
  method: "PATCH",
  credentials: "same-origin",
  cache: "no-store",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Developer",
    "username": "developer"
  }),
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Ubah profil
Kode error	HTTP	Tindakan
VALIDATION_ERROR	400	Periksa tipe, field wajib, format UUID, dan field tambahan.
CONFLICT	409	Baca pembayaran aktif, jangan terus membuat top-up baru. Untuk konflik profil, pilih username lain; kapitalisasi berbeda tetap dianggap username yang sama.

Baca preferensi

GET/api/profile/settingsSession cookie

Membaca preferensi akun. Jika belum ada pengaturan tersimpan, notifications, compact, globalActivity dan shareActivity bernilai true. globalActivity sudah usang dan tidak lagi berpengaruh sejak aktivitas global pindah ke halaman Feed; shareActivity=false menghentikan publikasi aktivitas anonim akun di feed.

GET /api/profile/settings · JavaScript

const response = await fetch("/api/profile/settings", {
  credentials: "same-origin",
  cache: "no-store",
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Simpan preferensi

PATCH/api/profile/settingsSession cookie

Kirim minimal satu boolean. Field yang tidak dikirim tetap dipertahankan; body {} dan field tambahan ditolak.

Simpan preferensi
Body JSON	Tipe	Wajib	Keterangan
notifications	boolean	Tidak	Sesuai tipe yang ditampilkan.
compact	boolean	Tidak	Sesuai tipe yang ditampilkan.
globalActivity	boolean	Tidak	Sesuai tipe yang ditampilkan.
shareActivity	boolean	Tidak	Sesuai tipe yang ditampilkan.

PATCH /api/profile/settings · JavaScript

const response = await fetch("/api/profile/settings", {
  method: "PATCH",
  credentials: "same-origin",
  cache: "no-store",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "compact": false
  }),
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Simpan preferensi
Kode error	HTTP	Tindakan
VALIDATION_ERROR	400	Periksa tipe, field wajib, format UUID, dan field tambahan.

Schema · Me

Schema · Me
Field	Tipe	Wajib	Keterangan
user	object	Ya	Sesuai tipe yang ditampilkan.
balance	integer	Ya	Rupiah utuh, bukan sen atau string berformat.
held	integer	Ya	Rupiah utuh, bukan sen atau string berformat.
available	integer	Ya	Rupiah utuh, bukan sen atau string berformat.

Schema · Profile

Schema · Profile
Field	Tipe	Wajib	Keterangan
name	string	Ya	Sesuai tipe yang ditampilkan.
username	string \| null	Ya	Sesuai tipe yang ditampilkan.
email	string	Ya	Sesuai tipe yang ditampilkan.

Schema · UserSettings

Schema · UserSettings
Field	Tipe	Wajib	Keterangan
notifications	boolean	Ya	Notifikasi SMS; default true jika belum disimpan.
compact	boolean	Ya	Tampilan ringkas; default true jika belum disimpan.
globalActivity	boolean	Ya	Usang: notifikasi aktivitas global di island sudah dipensiunkan dan digantikan halaman Feed. Nilai tetap disimpan untuk kompatibilitas tetapi tidak lagi berpengaruh; default true jika belum disimpan.
shareActivity	boolean	Ya	Tampilkan aktivitas akun di feed, dengan username disamarkan; default true jika belum disimpan. Pilihan false yang tersimpan tetap dihormati.