Skip to main content
Shopee memakai alur OTP fetch-only tiga langkah: kirim OTP, verifikasi, lalu tukar hasil verifikasi menjadi sesi merchant. Untuk akun multi-merchant, loginWithOtp menyatukan langkah 2 dan 3 dengan penanganan ambiguitas.

Alur tiga langkah

ShopeeOtpChallenge, ShopeeOtpVerification, dan ShopeeSession berisi cookie atau state autentikasi sensitif. Jangan mengirim objek tersebut ke browser, mencetaknya ke log, atau menyimpannya sebagai fixture.

Langkah 1: requestOtp

Password-protected account tidak menerima OTP sampai langkah password diterima. Tanpa password, send_otp melaporkan sukses tetapi kode ditahan diam-diam. Bila akun tak berpassword, langkah kedua faktor dilewati. ShopeeOtpChallenge membawa channel, availableChannels, deviceFingerprint, dan cookie. Bila channel yang diminta tidak tersedia, requestOtp melempar ConfigError. Lihat Device risk.

Langkah 2: verifyOtp

OTP wajib 4-10 digit. verifyOtp mengembalikan ShopeeOtpVerification berisi state akun-sesi dan daftar merchants. Objek verification dapat dipakai ulang untuk memilih merchant tanpa OTP kedua.

Langkah 3: completeLogin

completeLogin menukar hasil verifikasi menjadi ShopeeSession, membaca merchant credential dari cookie, lalu mengambil profil dan seluruh store. Bila merchantId tidak diberikan dan hanya satu merchant yang dapat dipakai, merchant itu dipilih otomatis; bila ambigu, ia melempar ConfigError dengan availableMerchants.

loginWithOtp untuk multi-merchant

loginWithOtp menggabungkan langkah 2 dan 3 dalam satu panggilan dan mengembalikan ShopeeLoginOutcome.
ShopeeLoginOutcome adalah union:
  • { status: "complete", session } - merchant tidak ambigu (merchantId diberikan, atau hanya satu merchant usable).
  • { status: "merchant-selection-required", verification, merchants } - akun mengakses lebih dari satu merchant usable dan tak ada merchantId. Bawa verification reusable dan daftar merchants agar picker dapat ditampilkan lalu diselesaikan dengan completeLogin - tanpa OTP kedua.
Perilaku ini menggantikan lemparan lama pada ambiguitas. Caller yang membaca sesi langsung harus switch pada outcome.status lebih dulu. Helper usableMerchants(merchants) dan resolveSingleMerchant(merchants) diekspor untuk mendeteksi ambiguitas sebelum berkomitmen pada login.

Login lewat CLI

CLI meminta nomor telepon, password (opsional), lalu OTP. Bila akun multi-merchant, ia menampilkan pilihan merchant usable. Setelah login, ikat QRIS statis dengan set-qris shopee. Lihat Ikhtisar CLI.

CAPTCHA

Bila Shopee meminta CAPTCHA, library melempar CaptchaRequiredError dengan code CAPTCHA_REQUIRED:
Library tidak mencoba melewati CAPTCHA.

Referensi

Lihat Referensi API ShopeeProvider untuk tanda tangan lengkap dan tipe untuk ShopeeOtpChallenge, ShopeeOtpVerification, ShopeeSession, dan ShopeeLoginOutcome.