Dokumentasi REST API YNA-PREM

API publik ini memungkinkan developer (bot WhatsApp, website, atau aplikasi milik Anda sendiri) membuat & mengecek pesanan Alight Motion Premium secara otomatis, tanpa harus membuka dashboard web secara manual.

Pengantar

Semua endpoint API publik berada di bawah base URL berikut:

https://prem.ynastore.my.id/api/v1

Setiap request WAJIB menyertakan header autentikasi X-Api-Key (lihat bagian Autentikasi di bawah). Seluruh body request dikirim sebagai JSON (Content-Type: application/json), dan seluruh response juga selalu dalam format JSON — lihat bagian Format Response & Error.

Autentikasi

Seluruh endpoint /api/v1/* dilindungi API key pribadi milik akun Anda. Sertakan API key itu di setiap request lewat header berikut:

X-Api-Key: yna-premxxxxxxxxxxxxxxxxxxxx

Cara mendapatkan API key

1. Login/daftar akun di dashboard YNA-PREM.
2. Buka menu Profil di sidebar, lalu gulir ke bagian API Saya (atau buka langsung /dashboard/profil#api-saya).
3. API key Anda akan tampil di sana. Kalau perlu diganti (mis. merasa API key lama bocor), gunakan tombol Regenerate API Key — key lama langsung tidak berlaku begitu diganti, jadi pastikan langsung memperbarui key di aplikasi/bot Anda setelah regenerate.

Response saat autentikasi gagal

Format Response & Error

Seluruh response API (sukses maupun gagal) selalu berbentuk objek JSON dengan 3 field yang sama:

Contoh response sukses

{
  "status": "success",
  "message": "Status order berhasil diambil.",
  "data": { "...": "..." }
}

Contoh response error

{
  "status": "error",
  "message": "API key tidak valid.",
  "data": null
}

Kode HTTP status yang umum dipakai

Rate Limit

Untuk menjaga kestabilan layanan bagi semua pengguna, setiap API key dibatasi maksimal 60 request per 60 detik di seluruh endpoint /api/v1/* (batas ini dihitung per API key, bukan per IP — jadi tidak terpengaruh API key lain yang berbagi jaringan/server yang sama dengan Anda).

Kalau batas ini terlampaui, request akan ditolak dengan:

HTTP 429 Too Many Requests

{
  "status": "error",
  "message": "Terlalu banyak permintaan API dalam waktu singkat untuk API key ini. Coba lagi beberapa saat lagi.",
  "data": null
}

Info sisa kuota juga dikirim lewat header response standar (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) di setiap request — pantau header ini untuk menghindari request Anda ditolak.

Endpoint AM (Create / Verify / Status)

Ketiga endpoint di bawah ini memakai logika yang sama persis dengan alur order satuan di dashboard — tidak ada aturan bisnis kedua yang berbeda. Hasilnya, kalau alur order di dashboard sudah bisa dipercaya, alur lewat API ini pasti identik hasilnya.

POST /am/create

Membuat pesanan AM Prem baru & langsung mengirim link verifikasi ke email tujuan dalam satu kali panggilan.

Body request (JSON)

Contoh curl

curl -X POST https://prem.ynastore.my.id/api/v1/am/create \
  -H "X-Api-Key: yna-premxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "pembeli@contoh.com"
  }'

Contoh response sukses (201 Created)

{
  "status": "success",
  "message": "Order berhasil dibuat & magic link verifikasi sudah dikirim ke email tujuan. Buka email tersebut, salin link verifikasinya, lalu kirim ke POST /api/v1/am/verify dengan field \"rawUrl\".",
  "data": {
    "order_id": "ord_a1b2c3d4e5f6",
    "status": "menunggu_verifikasi_user",
    "email_target": "pembeli@contoh.com",
    "payment_method": "saldo",
    "amount_charged": 1500,
    "fail_reason": null,
    "created_at": "2026-08-13T04:10:00.000Z",
    "updated_at": "2026-08-13T04:10:02.000Z"
  }
}

Contoh response error (402 — saldo tidak cukup)

{
  "status": "error",
  "message": "Saldo tidak cukup untuk membuat order ini. Isi saldo terlebih dahulu lewat dashboard, lalu coba lagi.",
  "data": null
}

POST /am/verify

Melanjutkan proses verifikasi & pembelian setelah link verifikasi dari email dibuka. Endpoint ini menyelesaikan alur sampai tuntas (verifikasi → pembelian) dan langsung mengembalikan status final.

Body request (JSON)

Contoh curl

curl -X POST https://prem.ynastore.my.id/api/v1/am/verify \
  -H "X-Api-Key: yna-premxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_a1b2c3d4e5f6",
    "rawUrl": "https://link-verifikasi-dari-email.contoh/xxxxx"
  }'

Contoh response sukses (200 — akun berhasil dibuat)

{
  "status": "success",
  "message": "Alight Motion Premium berhasil diaktifkan ke email tujuan.",
  "data": {
    "order_id": "ord_a1b2c3d4e5f6",
    "status": "sukses",
    "email_target": "pembeli@contoh.com",
    "payment_method": "saldo",
    "amount_charged": 1500,
    "fail_reason": null,
    "created_at": "2026-08-13T04:10:00.000Z",
    "updated_at": "2026-08-13T04:10:09.000Z"
  }
}

Contoh response error (409 — sudah pernah diverifikasi)

{
  "status": "error",
  "message": "Order tidak dalam status menunggu_verifikasi_user.",
  "data": null
}

GET /am/status/:order_id

Mengecek status sebuah order kapan saja tanpa mengubah apapun — cocok dipakai untuk polling dari sisi bot/aplikasi Anda.

Contoh curl

curl -X GET https://prem.ynastore.my.id/api/v1/am/status/ord_a1b2c3d4e5f6 \
  -H "X-Api-Key: yna-premxxxxxxxxxxxxxxxxxxxx"

Contoh response sukses (200)

{
  "status": "success",
  "message": "Status order berhasil diambil.",
  "data": {
    "order_id": "ord_a1b2c3d4e5f6",
    "status": "menunggu_verifikasi_user",
    "email_target": "pembeli@contoh.com",
    "payment_method": "saldo",
    "amount_charged": 1500,
    "fail_reason": null,
    "created_at": "2026-08-13T04:10:00.000Z",
    "updated_at": "2026-08-13T04:10:02.000Z"
  }
}

Semua nilai data.status yang mungkin muncul

Endpoint Account (Balance / History)

GET /account/balance

Mengecek saldo akun pemilik API key saat ini.

Contoh curl

curl -X GET https://prem.ynastore.my.id/api/v1/account/balance \
  -H "X-Api-Key: yna-premxxxxxxxxxxxxxxxxxxxx"

Contoh response sukses (200)

{
  "status": "success",
  "message": "Saldo berhasil diambil.",
  "data": {
    "saldo": 48500,
    "saldo_hold": 1500,
    "total": 50000
  }
}

GET /account/history?page=&limit=

Mengambil riwayat seluruh order milik akun pemilik API key (dibuat lewat API maupun lewat dashboard web), terurut dari yang terbaru.

Query parameter

Contoh curl

curl -X GET "https://prem.ynastore.my.id/api/v1/account/history?page=1&limit=10" \
  -H "X-Api-Key: yna-premxxxxxxxxxxxxxxxxxxxx"

Contoh response sukses (200)

{
  "status": "success",
  "message": "Riwayat order berhasil diambil.",
  "data": {
    "orders": [
      {
        "order_id": "ord_a1b2c3d4e5f6",
        "status": "sukses",
        "email_target": "pembeli@contoh.com",
        "payment_method": "saldo",
        "amount_charged": 1500,
        "fail_reason": null,
        "created_at": "2026-08-13T04:10:00.000Z",
        "updated_at": "2026-08-13T04:10:09.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "total_pages": 1
    }
  }
}

Contoh Alur Integrasi Lengkap

Berikut narasi lengkap integrasi dari nol sampai akun AM Prem aktif, memakai ketiga endpoint AM secara berurutan.

Langkah 1 — Pastikan saldo cukup

Panggil GET /account/balance dan pastikan field saldo lebih besar atau sama dengan harga produk. Kalau kurang, arahkan pengguna Anda untuk deposit dulu lewat dashboard /dashboard/deposit.

Langkah 2 — Buat pesanan

Panggil POST /am/create dengan email tujuan. Simpan data.order_id dari response — ini dipakai di semua langkah berikutnya. Kalau data.status yang kembali adalah gagal, hentikan alur di sini (dana sudah otomatis kembali, buat order baru kalau ingin coba lagi).

Langkah 3 — Tunggu & ambil link verifikasi dari email

Sistem mengirim email berisi link verifikasi ke alamat yang Anda kirim di Langkah 2. Link ini biasanya perlu diambil manual oleh pengguna Anda (buka email, salin link) — alur API ini TIDAK membaca email secara otomatis.

Langkah 4 — Kirim link verifikasi

Begitu link didapat, panggil POST /am/verify dengan order_id dari Langkah 2 dan rawUrl persis seperti di email. Response ini SUDAH final — cek data.status: sukses berarti akun AM Prem sudah aktif di email tujuan, gagal berarti ada masalah di tengah jalan (dana sudah otomatis kembali).

Langkah 5 — (Opsional) Cek ulang status kapan saja

Kalau ingin memverifikasi ulang hasil akhir sebuah order (mis. untuk sinkronisasi database internal aplikasi Anda), panggil GET /am/status/:order_id kapan saja — endpoint ini aman dipanggil berkali-kali karena hanya membaca data, tidak mengubah apapun.

GET  /account/balance        -> pastikan saldo cukup
POST /am/create               -> dapat order_id, magic link terkirim
     (ambil link dari email tujuan, di luar API ini)
POST /am/verify                -> status akhir: sukses / gagal
GET  /am/status/:order_id     -> (opsional) cek ulang kapan saja