API Reference

Semua contoh memakai header Authorization: Bearer $AYOSEL_API_KEY.

2.1 Daftar endpoint

Path lain di bawah /reseller dijawab 404 not_found.

2.2 Format respons

Sukses:

{ "success": true, "data": { } }

Daftar menambahkan meta:

{ "success": true, "data": [ ], "meta": { "total": 42, "limit": 20, "offset": 0 } }

Galat:

{
  "success": false,
  "error": { "code": "insufficient_balance", "message": "Saldo tidak cukup." },
  "request_id": "66666666-6666-4666-8666-666666666666"
}

• Ambil keputusan dari error.code dan status HTTP. error.message untuk dibaca manusia dan teksnya bisa berubah.
• request_id sama dengan header X-Request-Id. Sertakan saat melapor ke toko.
• Format yang sama dipakai untuk semua galat, termasuk galat toko, autentikasi, dan rate limit.
• Abaikan field yang tidak Anda kenal di respons.

Daftar lengkap kode galat ada di bagian 5.

2.3 Konvensi data

• Uang berupa bilangan bulat rupiah (tanpa desimal). Contoh: 18000 berarti Rp 18.000.
• Waktu berformat ISO 8601 UTC, bisa memuat pecahan detik, contoh 2026-10-28T03:15:07.482913Z.
• Id berupa UUID. Id yang bukan UUID di path dijawab 422 invalid_request.
• Body request berupa JSON (Content-Type: application/json).

2.4 Paginasi

Endpoint daftar menerima limit dan offset. Nilai di luar batas dipotong, bukan ditolak: limit kurang dari 1 menjadi nilai bawaan, limit di atas maksimum menjadi maksimum, dan offset negatif menjadi 0. Nilai yang benar-benar dipakai ada di meta.limit dan meta.offset. Nilai yang bukan bilangan bulat dijawab 422 invalid_request.

2.5 GET /me

Menampilkan identitas key yang sedang dipakai. Cocok untuk tes koneksi.

curl -sS "$BASE/me" -H "Authorization: Bearer $AYOSEL_API_KEY"

{
  "success": true,
  "data": {
    "name": "Reseller Contoh",
    "key_hint": "ayosel_000000…0000",
    "ip_allowlist": ["203.0.113.10"],
    "rate_limits": {
      "read":   { "limit": 120, "window_seconds": 60 },
      "orders": { "limit": 20,  "window_seconds": 60 }
    }
  }
}

2.6 GET /products

Daftar produk yang boleh Anda lihat, masing-masing dengan varian aktifnya. Aturan harga, stok, dan produk private ada di bagian 2.9.

curl -sS "$BASE/products?category=Streaming&limit=20" -H "Authorization: Bearer $AYOSEL_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Akun Streaming Contoh",
      "category": "Streaming",
      "variants": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "product_id": "11111111-1111-4111-8111-111111111111",
          "name": "1 Bulan",
          "description": "Akun sharing, garansi 30 hari",
          "price": 18000,
          "price_tier": "reseller",
          "stock": 42,
          "is_available": true,
          "bulk_discount": { "min_qty": 5, "percent": 10 }
        }
      ]
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0 }
}

Field varian:

2.7 GET /products/{id}

Satu produk dengan varian aktifnya, bentuknya sama dengan satu elemen data di /products.

curl -sS "$BASE/products/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $AYOSEL_API_KEY"

Produk yang tidak ada, tidak aktif, atau private tanpa izin untuk Anda dijawab 404 product_not_found, tanpa membedakan penyebabnya.

2.8 GET /variants/{id}

Satu varian, tanpa pembungkus produk. Bentuk data sama dengan satu elemen variants.

curl -sS "$BASE/variants/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer $AYOSEL_API_KEY"

{
  "success": true,
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "product_id": "11111111-1111-4111-8111-111111111111",
    "name": "1 Bulan",
    "description": "Akun sharing, garansi 30 hari",
    "price": 18000,
    "price_tier": "reseller",
    "stock": 42,
    "is_available": true,
    "bulk_discount": null
  }
}

Varian yang tidak bisa Anda lihat dijawab 404 variant_not_found.

2.9 Harga, stok, dan produk private

Harga dan price_tier

price di katalog adalah harga satuan yang Anda bayar lewat API.

Harga yang tampil di katalog sama dengan harga yang ditagih saat beli, untuk varian dan jumlah yang sama. price_tier yang dipakai tercatat di setiap order.

Diskon grosir, bila ada, berlaku saat quantity mencapai bulk_discount.min_qty. Potongannya percent persen dari subtotal, dibulatkan ke bawah ke rupiah penuh. Contoh: 5 unit × Rp 18.000 = Rp 90.000, diskon 10% = Rp 9.000, jadi bulk_discount_amount: 9000 dan final_amount: 81000.

Stok

stock adalah stok fisik dikurangi jumlah yang sedang ditahan order pending pembeli lain (misalnya pembayaran QRIS yang belum selesai), minimal 0. is_available bernilai true hanya bila stock lebih dari 0.

Stok bisa berubah antara Anda membaca katalog dan membeli. is_available: true bukan jaminan pembelian berhasil. Siapkan penanganan insufficient_stock dan stock_reserved.

Produk private dan izin (grant)

• Produk publik tampil untuk semua reseller.
• Produk private hanya tampil dan hanya bisa dibeli oleh reseller yang sudah mendapat izin (grant) yang disetujui untuk produk itu.
• Tanpa izin, produk tidak muncul di /products, dan GET /products/{id} dijawab 404 product_not_found, GET /variants/{id} dan POST /orders dijawab 404 variant_not_found. Jawabannya sama persis dengan produk yang tidak ada, sehingga keberadaan produk private tidak bocor.
• Bila izin dicabut, produk hilang dari katalog Anda mulai request berikutnya.
• Produk atau varian yang nonaktif atau terhapus tidak tampil.