Dokumentasi API Reseller

1. Getting Started

Pengenalan API, persyaratan akses, API key, autentikasi, dan quick start. Mulai di sini bila ini pertama kalinya Anda memakai API.

1.1 Pengenalan API

Panduan ini untuk developer yang menghubungkan aplikasi reseller (bot Telegram, bot WhatsApp, website, aplikasi, atau sistem lain) ke toko tempat Anda menjadi reseller, lewat API. Dengan satu API key, aplikasi Anda bisa membaca produk, harga reseller, dan stok, mengecek saldo, lalu membeli produk dengan saldo wallet. Isi produk langsung ada di respons, dan Anda meneruskannya ke pelanggan Anda sendiri.

Pelanggan Anda ──► Aplikasi Anda (server) ──► API Reseller toko ──► saldo wallet Anda
                                                    │
                                                    └─► isi produk di respons

Semua contoh memakai data palsu: host api.contoh.example, toko tokoku, id berpola 1111…, dan key ayosel_GANTI_DENGAN_API_KEY_ANDA. Ganti dengan nilai dari toko Anda.

1.2 Persyaratan akses

API ini tidak aktif dengan sendirinya. Akses diberikan oleh toko tempat Anda menjadi reseller, jadi minta toko itu menyiapkannya. Key Anda baru berfungsi bila semua syarat berikut terpenuhi:

Akun Anda harus punya akun Telegram karena top up saldo hanya tersedia di bot Telegram. Aplikasi yang memanggil API bebas, tidak harus bot Telegram.

Cara mendapatkan akses:

1. Top up saldo lewat bot Telegram toko seperti biasa.
2. Minta toko mengaktifkan Akses API untuk akun Anda.
3. Toko menerbitkan key untuk Anda. Key utuh hanya tampil satu kali saat diterbitkan. Simpan langsung di tempat yang aman. Bila hilang, minta toko memutar key: key baru diterbitkan dan key lama langsung mati.
4. Aplikasi Anda memanggil API dengan Authorization: Bearer <API key>.

Satu reseller punya paling banyak satu key aktif, dan key itu dipakai bersama oleh semua aplikasi Anda.

1.3 Alamat dasar

https://<HOST_API>/api/v1/t/<slug>/reseller

• <HOST_API>: alamat server API yang diberikan toko.
• <slug>: kode toko, 3 sampai 32 karakter huruf kecil, angka, atau tanda hubung, diawali huruf. Key hanya berlaku di toko tempat key diterbitkan. Key toko A yang dipakai ke alamat toko B dijawab 401 invalid_api_key.

Pakai HTTPS. Semua contoh di bawah mengasumsikan:

export BASE="https://api.contoh.example/api/v1/t/tokoku/reseller"
export AYOSEL_API_KEY="ayosel_GANTI_DENGAN_API_KEY_ANDA"

1.4 Autentikasi

Kirim key di header Authorization pada setiap request:

Authorization: Bearer ayosel_GANTI_DENGAN_API_KEY_ANDA

• Bentuk key: ayosel_ diikuti 64 karakter heksadesimal huruf kecil (71 karakter total). Nama skema Bearer tidak membedakan huruf besar dan kecil.
• Key hanya boleh di header ini. Request yang membawa api_key, apikey, key, atau token di query string ditolak 400 invalid_request tanpa diproses, walau headernya benar. URL sering tercatat di log proxy dan riwayat, jadi anggap key yang pernah masuk URL sudah terekspos dan pertimbangkan untuk memutarnya.

1.5 Quick start

# 1. Tes koneksi dan key
curl -sS "$BASE/me" -H "Authorization: Bearer $AYOSEL_API_KEY"

# 2. Lihat katalog dan harga reseller Anda
curl -sS "$BASE/products?limit=5" -H "Authorization: Bearer $AYOSEL_API_KEY"

# 3. Beli 2 unit satu varian
curl -sS -X POST "$BASE/orders" \
  -H "Authorization: Bearer $AYOSEL_API_KEY" \
  -H "Idempotency-Key: pesanan-20261028-0001" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"22222222-2222-4222-8222-222222222222","quantity":2}'

Langkah 3 memotong saldo. Menjalankannya lagi dengan Idempotency-Key yang sama tidak memotong lagi dan mengembalikan order yang sama (lihat bagian 3.4).