Jualan stok Premilo langsung dari bot atau web kamu

Quick start

1. Tekan tombol 🔌 API di bot Premilo (atau ketik /api).
2. Top up saldo minimal Rp 20.000 lewat bot (QRIS). Begitu saldonya cukup, akses API kamu aktif otomatis dan kamu dapet notif. Saldo ini yang dipakai buat order.
3. Tekan Buat Kunci. API key muncul sekali di chat kamu, dan pesannya kehapus sendiri 15 menit kemudian. Simpan di env server.
4. Hit GET /v1/products buat ambil product_id, terus POST /v1/order. Mau coba dulu tanpa saldo? Pakai Sandbox.

Auth

Semua request (kecuali /v1/health) wajib bawa API key di header X-API-Key. Mau pakai Authorization: Bearer <key> juga bisa.

curl https://api.premilo.id/v1/me \
  -H "X-API-Key: prm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

• Format key: prm_live_ + 32 karakter random.
• Server nggak nyimpen key mentah, cuma hash-nya. Key hilang? Generate baru lewat tombol 🔌 API, key lama langsung mati.
• Ganti key bisa dari bot (🔌 API, Ganti Kunci) atau POST /v1/keys/rotate. Tiap kali diganti, kamu dapet notif di Telegram.

Rate Limit

Default 60 request/menit per key (bisa beda per akun, cek rate_limit_per_minute di /me). Tiap response yang lolos auth bawa header ini:

Limit unit harian

Beberapa produk punya limit unit per hari per akun (lihat daily_limit_applies di /products dan daily_units_remaining di /me). Unit dari stock_ready nggak dihitung. Reset tiap 00.00 WIB. Kalau mentok, order ditolak DAILY_LIMIT_REACHED dan saldo aman.

Limit Order

Semua batas di bawah berlaku per akun API. Yang bertanda "bisa diubah" bisa dinaikkan owner kalau volume kamu memang besar.

Idempotency (ref)

Tiap POST /v1/order wajib bawa ref: ID order dari sistem kamu sendiri (6-64 karakter: huruf, angka, . _ : -). Unik per akun.

Status Order

Kalau barang yang kekirim kurang dari yang dipesan, status tetap success: qty_delivered lebih kecil dari qty_ordered, dan selisihnya langsung balik ke saldo (refunded_amount).

Response & Error

Semua response JSON. Kalau sukses: success: true + isinya di data. Kalau gagal: HTTP status yang sesuai + objek error.

{
  "success": false,
  "error": { "code": "INSUFFICIENT_BALANCE", "message": "Saldo tidak mencukupi. Top up saldo lewat bot" },
  "data": { "order_id": "API-3F9A1C0B7E", "ref": "INV-1001", "status": "failed", "required": 130000, "balance": 25000, "retryable": true },
  "request_id": "9c1e4b7a2f0d8e61"
}

Endpoints

{
  "success": true,
  "data": {
    "name": "TokoKamu",
    "telegram_id": "5670411211",
    "balance": 250000,
    "currency": "IDR",
    "key_prefix": "prm_live_AbCdEfGhIj",
    "key_created_at": "2026-11-02T03:15:00.000Z",
    "rate_limit_per_minute": 60,
    "daily_unit_limit": 50,
    "daily_units_used": 12,
    "daily_units_remaining": 38,
    "allowed_products": null,
    "webhooks": 1
  }
}

Webhooks

Order biasa udah beres di response POST /order, jadi webhook sifatnya pelengkap. Enak buat nyatet semua perubahan status di satu tempat, terutama order needs_review yang diberesin owner belakangan.

Payload

Dikirim sebagai POST JSON. Isinya ringkasan order tanpa isi produk. Ambil items lewat GET /order/{ref}, biar kalau URL atau log server kamu bocor, barangnya nggak ikut bocor.

{
  "id": "evt_5b0c2f1e9a7d4c3b8e6f1a2d",
  "type": "order.success",
  "created_at": "2026-11-02T03:21:44.010Z",
  "data": {
    "order_id": "API-3F9A1C0B7E",
    "ref": "INV-1001",
    "status": "success",
    "qty_delivered": 25,
    "total_charged": 300000
  }
}

Syarat URL

• Wajib https:// di port 443, pakai domain (bukan IP), dan resolve ke IP publik.
• Balas 2xx dalam 5 detik. Redirect nggak diikutin. Proses yang berat kerjain setelah bales.
• Gagal? Di-retry 5x: 30 detik, 2 menit, 10 menit, 30 menit, terus 2 jam. 20 gagal beruntun = webhook dimatiin, dan kamu dapet notif di Telegram.
• Event yang sama bisa dateng lebih dari sekali. Dedupe pakai id event.

Verifikasi Signature

Signature = HMAC-SHA256 pakai secret webhook (dikasih sekali pas daftar) atas string <t>.<raw body>. Pakai raw body persis kayak yang diterima, sebelum di-parse. Tolak kalau t lebih tua dari 5 menit biar nggak bisa di-replay.

const crypto = require('crypto');

// rawBody: body PERSIS seperti diterima (mis. pakai express.raw())
function verifikasiPremilo(rawBody, headerSignature, secret) {
  const bagian = Object.fromEntries(String(headerSignature).split(',').map(s => s.split('=')));
  const t = Number(bagian.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const harap = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(harap), b = Buffer.from(String(bagian.v1 || ''));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verifikasi_premilo(raw_body: bytes, header_signature: str, secret: str) -> bool:
    bagian = dict(p.split("=", 1) for p in header_signature.split(","))
    t = int(bagian.get("t", "0"))
    if abs(time.time() - t) > 300:
        return False
    harap = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(harap, bagian.get("v1", ""))

<?php
function verifikasi_premilo(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $bagian);
    $t = (int)($bagian['t'] ?? 0);
    if (abs(time() - $t) > 300) return false;
    $harap = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($harap, $bagian['v1'] ?? '');
}
// $rawBody = file_get_contents('php://input');

Prompt untuk AI

Pakai ChatGPT, Claude, Gemini, Cursor, atau Codex buat ngoding integrasinya? Copy prompt ini, ganti bagian dalam kurung siku, lalu tempel ke AI kamu. Prompt-nya udah berisi aturan penting (idempotency, retry, verifikasi webhook) biar kode yang dihasilkan nggak bikin order dobel atau bocorin key.

Kamu adalah senior backend engineer. Bantu saya integrasi Premilo Reseller API ke [BOT TELEGRAM / WEBSITE / PANEL] saya yang ditulis dengan [BAHASA & FRAMEWORK, mis. Node.js + Telegraf / PHP Laravel / Python FastAPI].

Spesifikasi lengkap (OpenAPI 3.1): https://api.premilo.id/openapi.json
Dokumentasi: https://api.premilo.id/docs

RINGKASAN API
- Base URL: https://api.premilo.id/v1
- Auth: header "X-API-Key: <key>". Baca key dari environment variable PREMILO_API_KEY. JANGAN taruh key di kode frontend/klien, log, atau repo.
- Format response: sukses {"success": true, "data": ...}; gagal {"success": false, "error": {"code", "message"}, "data"?, "request_id"}.
- GET /products: katalog (id, product, name, price, wholesale_tiers[{min_qty, price}], stock, stock_ready, max_qty). Cache 20-60 detik.
- GET /quote?product_id=&qty=: unit_price, total, can_order, reasons[] (tanpa membeli).
- POST /order body {"ref", "product_id", "qty"} (qty 1-1000): data.items (isi produk), total_charged, balance_after.
  - ref = ID order unik dari sistem saya, 6-64 karakter [A-Za-z0-9._:-]. Kirim ulang ref yang SAMA tidak pernah membeli dua kali (response lama + "replay": true). Order failed boleh di-retry dengan ref yang sama.
  - status: success | failed | processing | needs_review. needs_review (HTTP 202) = sedang dicek manual, JANGAN buat ref baru untuk barang yang sama.
- GET /order/{ref}: detail order + items. Dipakai saat timeout / koneksi putus.
- GET /me (saldo & limit), GET /orders (riwayat, tanpa items), GET /stats.
- Rate limit: 60 request/menit per key. Header X-RateLimit-Limit / -Remaining / -Reset, dan Retry-After saat 429.

ATURAN IMPLEMENTASI (WAJIB)
1. Timeout HTTP client untuk POST /order minimal 150 detik. Saat timeout atau network error: JANGAN buat ref baru. Panggil GET /order/{ref}, atau retry dengan ref yang sama.
2. Retry otomatis maksimal 3x (backoff 3 detik, hormati Retry-After) HANYA untuk: PRODUCT_BUSY, RATE_LIMITED, SERVICE_UNAVAILABLE, dan network error. Error lain langsung dilaporkan.
3. Pemetaan error ke pesan user: INSUFFICIENT_BALANCE = saldo kurang, minta top up; OUT_OF_STOCK / PRODUCT_UNAVAILABLE = stok habis; DAILY_LIMIT_REACHED = coba lagi besok (reset 00.00 WIB); INVALID_* = bug di request, perbaiki kode.
4. Simpan order_id, ref, status, total_charged, dan items ke database saya SEBELUM dikirim ke pembeli.
5. Kalau pakai webhook: verifikasi header X-Premilo-Signature (format "t=<unix>,v1=<hex>") = HMAC-SHA256(secret, "<t>.<raw body>") memakai raw body sebelum di-parse, tolak kalau t lebih tua dari 300 detik, bandingkan secara timing-safe, balas 2xx dalam 5 detik, dan dedupe berdasarkan "id" event. Payload webhook tidak memuat items; ambil lewat GET /order/{ref}.
6. Jangan pernah mencetak API key atau isi items ke log.

TUGAS
Buatkan [mis. modul klien API + fungsi beli(ref, productId, qty) + handler webhook + perintah /beli di bot saya], lengkap dengan error handling sesuai aturan di atas, struktur folder, dan contoh pemakaian. Tulis kode yang siap produksi.

OpenAPI 3.1

Spesifikasi mesin-baca untuk semua endpoint, schema request/response, kode error, dan webhook. Bisa di-import ke Postman, Insomnia, atau dipakai generator SDK (openapi-generator, openapi-typescript).

curl -o premilo-openapi.json https://api.premilo.id/openapi.json

# contoh: generate tipe TypeScript
npx openapi-typescript https://api.premilo.id/openapi.json -o premilo.d.ts

Contoh Flow Lengkap

Pola yang disaranin buat bot atau toko: quote dulu, order pakai ref dari sistem kamu, dan kalau koneksi bermasalah, cek status pakai ref yang sama.

const API = 'https://api.premilo.id/v1';
const HEADER = { 'X-API-Key': process.env.PREMILO_API_KEY, 'Content-Type': 'application/json' };

async function panggil(path, opsi = {}) {
  const res = await fetch(API + path, { ...opsi, headers: HEADER, signal: AbortSignal.timeout(150000) });
  return { status: res.status, isi: await res.json() };
}

async function beli(refOrder, productId, qty) {
  const q = await panggil(`/quote?product_id=${encodeURIComponent(productId)}&qty=${qty}`);
  if (!q.isi.success || !q.isi.data.can_order) return { ok: false, alasan: q.isi.data?.reasons || q.isi.error };

  for (let percobaan = 1; percobaan <= 3; percobaan++) {
    try {
      const o = await panggil('/order', { method: 'POST', body: JSON.stringify({ ref: refOrder, product_id: productId, qty }) });
      const d = o.isi.data;
      if (d?.status === 'success') return { ok: true, items: d.items, total: d.total_charged };
      if (d?.status === 'needs_review') return { ok: false, alasan: 'Lagi dicek owner, tunggu webhook' };
      if (o.isi.error?.code === 'PRODUCT_BUSY') { await new Promise(r => setTimeout(r, 3000)); continue; }
      return { ok: false, alasan: o.isi.error };
    } catch (e) {
      // Timeout / koneksi putus: JANGAN bikin ref baru. Cek status ref yang sama.
      const s = await panggil(`/order/${encodeURIComponent(refOrder)}`).catch(() => null);
      if (s?.isi.data?.status === 'success') return { ok: true, items: s.isi.data.items };
      if (s?.isi.data?.status === 'processing') await new Promise(r => setTimeout(r, 5000));
    }
  }
  return { ok: false, alasan: 'Belum pasti, cek lagi nanti pakai ref yang sama' };
}

Playground

Coba semua endpoint langsung dari browser. Sandbox jalan sepenuhnya di browser kamu: saldo, produk, dan order-nya palsu, aturan & kode error-nya sama persis dengan API asli. Live manggil api.premilo.id pakai API key kamu.

Kalkulator Grosir

Hitung total pakai harga grosir bertingkat. Mode Sandbox langsung pakai produk contoh; mode Live pakai katalog asli dengan API key kamu (pilih modenya di Playground).

Best Practice

• Simpan API key di env atau secret manager server, jangan di-commit ke repo.
• Pakai ref dari ID order di sistem kamu, biar retry otomatis nggak pernah beli dua kali.
• Set timeout client minimal 150 detik buat POST /order. Kalau tetep timeout, cek GET /order/{ref}.
• Cache /products 20-60 detik di sisi kamu, nggak perlu dipanggil tiap order.
• Kena PRODUCT_BUSY atau RATE_LIMITED? Tunggu bentar, terus retry pakai ref yang sama.
• Curiga key bocor? Langsung ganti lewat /api di bot. Key lama mati saat itu juga.

Changelog

Versi API ada di path (/v1). Perubahan yang bikin kode lama rusak cuma bakal dirilis di versi baru (/v2), bukan diam-diam di /v1.