Dokumentasi Developer

OneSeller adalah platform omnichannel untuk seller Indonesia. API yang direncanakan ditujukan agar sistem Anda, misalnya ERP, aplikasi gudang, website, atau skrip internal, dapat membaca dan menyinkronkan data produk, stok, pesanan, dan toko.

Prinsip desain#

• REST dengan format JSON; nama resource berbentuk jamak, misalnya /products dan /orders.
• Setiap resource memiliki id bertipe string yang bersifat opak, jadi jangan mengurai isinya.
• Waktu memakai format ISO 8601 dalam UTC, contoh 2025-01-15T08:00:00Z.
• Nominal uang berupa bilangan bulat dalam Rupiah (IDR) tanpa desimal.
• Perubahan sebagian memakai PATCH; pembuatan data baru memakai POST.

Sumber daya yang direncanakan#

Detail setiap endpoint ada di API Reference. Untuk langkah praktis, lihat Tutorial.

API dirancang memakai token Bearer yang dikirim lewat header Authorization pada setiap request. Token rencananya diterbitkan per toko atau organisasi dari dashboard OneSeller; fitur penerbitan token belum ada.

Token Bearer#

Authorization: Bearer TOKEN_CONTOH

Request tanpa token atau dengan token tidak valid dijawab 401. Token yang valid tetapi scope-nya tidak mencukupi dijawab 403.

Scope#

Scope membatasi apa yang boleh dilakukan sebuah token. Prinsipnya: berikan scope sesempit mungkin.

Rancangan awal menaruh versi di path: /v1. Nomor versi hanya naik untuk perubahan yang merusak kompatibilitas (breaking change).

Perubahan yang dianggap kompatibel#

Kebijakan masa deprekasi (berapa lama versi lama tetap didukung) belum ditentukan dan akan diumumkan di Changelog sebelum API dirilis.

Endpoint yang mengembalikan daftar memakai pagination berbasis cursor. Berbeda dengan nomor halaman, cursor tetap stabil walau data baru (misalnya pesanan) masuk saat Anda sedang menelusuri.

Parameter#

Bentuk respons#

{
  "data": [
    {
      "id": "ord_example_001"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "CURSOR_CONTOH"
  }
}

Ulangi request dengan cursor baru selama has_more bernilai true. Perlakukan cursor sebagai string opak dan jangan menyimpannya untuk jangka panjang.

Rencananya setiap token dibatasi jumlah request per jendela waktu. Angka batas final belum ditentukan; yang dirancang lebih dulu adalah cara klien mengetahuinya.

Header respons#

Strategi percobaan ulang#

• Saat menerima 429, tunggu sesuai Retry-After sebelum mencoba lagi.
• Untuk 5xx, gunakan exponential backoff dengan jitter.
• Mengulang POST hanya aman bila memakai Idempotency-Key (lihat Idempotensi).

Jaringan bisa gagal setelah server memproses request tetapi sebelum klien menerima jawaban. Tanpa perlindungan, mengulang POST bisa membuat data ganda. Karena itu request yang mengubah data dirancang menerima header Idempotency-Key.

Cara kerja (rancangan)#

1. Klien membuat nilai unik per operasi, misalnya UUID v4, lalu mengirimkannya di header Idempotency-Key.
2. Server menyimpan hasil request pertama untuk key tersebut selama jangka waktu tertentu (rencana: 24 jam).
3. Request ulang dengan key dan body yang sama mengembalikan respons yang sama tanpa dieksekusi ulang.
4. Key yang sama dengan body berbeda dijawab 409 dengan kode idempotency_conflict.

Request GET bersifat idempoten secara alami sehingga tidak memerlukan header ini.

Yang dirancang di sisi API#

• Seluruh akses lewat HTTPS; HTTP polos ditolak.
• Token dengan scope sempit yang dapat dicabut kapan saja.
• Pembatasan request (rate limit) per token.
• Catatan audit atas akses dan perubahan data (rencana).
• Data pelanggan dikembalikan seminimal mungkin, dengan masking untuk data pribadi.

Yang perlu Anda lakukan#

• Simpan token di environment variable atau secret manager.
• Rotasi token secara berkala dan cabut token yang tidak lagi dipakai.
• Verifikasi signature setiap webhook sebelum memproses payload.
• Jangan mencatat token atau data pribadi pelanggan di log.
• Validasi data dari API sebelum dipakai di sistem Anda.

Alih-alih polling, Anda dapat berlangganan event. OneSeller akan mengirim POST berisi JSON ke URL yang Anda daftarkan setiap kali event terjadi.

Daftar event (rancangan)#

Format payload#

{
  "id": "evt_example_001",
  "type": "inventory.low_stock",
  "api_version": "v1",
  "created_at": "2025-01-15T08:00:00Z",
  "data": {
    "sku": "SKU-CONTOH-001",
    "warehouse_id": "wh_example_001",
    "available": 4,
    "threshold": 5
  }
}

Verifikasi signature (rancangan)#

Setiap pengiriman membawa header X-OneSeller-Signature berisi timestamp dan HMAC-SHA256 dari string {timestamp}.{raw_body}, dihitung dengan signing secret milik endpoint webhook Anda.

1. Ambil body mentah sebelum di-parse menjadi JSON.
2. Baca nilai t dan v1 dari header.
3. Tolak bila selisih t dengan waktu sekarang lebih dari 5 menit, untuk mencegah replay.
4. Hitung HMAC-SHA256, lalu bandingkan dengan v1 memakai perbandingan constant-time.

Pengiriman dan percobaan ulang#

• Jawab dengan status 2xx secepatnya (rencana batas 10 detik); kerjakan proses berat secara asinkron.
• Pengiriman yang gagal diulang dengan backoff; jadwal pastinya belum ditetapkan.
• Event bisa terkirim lebih dari sekali, jadi gunakan id event untuk deduplikasi.
• Urutan event tidak dijamin; gunakan created_at dan ambil data terbaru dari API bila perlu.

Error dikembalikan dengan status HTTP yang sesuai dan body JSON yang seragam. Simpan request_id di log Anda; nilai ini akan berguna saat melacak masalah.

{
  "error": {
    "code": "validation_failed",
    "message": "Satu atau lebih field tidak valid.",
    "request_id": "req_example_001",
    "details": [
      {
        "field": "price",
        "issue": "tidak boleh negatif"
      }
    ]
  }
}

Daftar kode#

Dua skenario berikut menggambarkan bagaimana rancangan API ini akan dipakai. Keduanya hanya ilustrasi untuk membahas desain.

Skenario 1: sinkronisasi stok ke sistem internal#

1. Sistem gudang Anda menjadi sumber kebenaran stok fisik.
2. Skrip berkala membaca GET /inventory dan menelusuri semua halaman dengan cursor.
3. Selisih dengan data internal dikirim sebagai POST /inventory/adjustments dengan Idempotency-Key.
4. Webhook inventory.low_stock memberi tahu sistem Anda saat stok menipis.

Langkah lengkapnya ada di Tutorial.

Skenario 2: menerima pesanan baru lewat webhook#

1. Daftarkan URL penerima dengan POST /webhooks untuk event order.created.
2. Verifikasi signature, lalu catat id event untuk deduplikasi.
3. Jawab 200 segera, lalu ambil detail dengan GET /orders/{order_id} secara asinkron.
4. Setelah dikemas, catat pengiriman dengan POST /orders/{order_id}/fulfillments.