Lewati ke konten
OneSeller
Masuk

Sinkronkan stok ke sistem internal

Panduan ini menggambarkan alur menyinkronkan stok dari sistem gudang Anda ke OneSeller memakai rancangan API. Karena API belum tersedia, anggap langkah-langkah ini sebagai gambaran alur, bukan petunjuk yang bisa dijalankan hari ini.

Dokumentasi rencana — kontrak API belum final dan belum tersedia sebagai layanan.

Semua schema berlabel Draft. Alamat https://api.example.com adalah placeholder, bukan server nyata, dan tidak ada token yang dapat diterbitkan.

Prasyarat

  • Pemahaman dasar HTTP dan JSON.
  • Sistem internal (ERP atau gudang) yang dapat mengekspor stok per SKU.
  • Token dengan scope inventory:read dan inventory:write (belum dapat diterbitkan).

  1. Langkah 1: Siapkan token dan konfigurasi

    Simpan token di environment variable agar tidak ikut ter-commit. Pada tahap rancangan ini, isi dengan nilai placeholder TOKEN_CONTOH.

    • Beri token scope inventory:read dan inventory:write saja.
    • Jangan menaruh token di kode sumber atau di aplikasi sisi klien.
    Membaca token dari environmentDraft
    # Simpan token di environment, bukan di kode atau repositori
export ONESELLER_TOKEN="TOKEN_CONTOH"

curl "https://api.example.com/v1/stores" \
  -H "Authorization: Bearer $ONESELLER_TOKEN"
    Contoh respons (Draft)
    {
  "data": [
    {
      "id": "sto_example_001",
      "name": "Toko Contoh",
      "channel": "marketplace",
      "connection_status": "connected"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

  2. Langkah 2: Ambil stok dari OneSeller

    Panggil GET /inventory untuk membaca stok. Setiap item memuat on_hand (fisik), reserved (tertahan pesanan), dan available (tersedia untuk dijual).

    Ambil daftar stokDraft
    curl -X GET "https://api.example.com/v1/inventory?limit=100" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"
    Contoh respons 200 (Draft)
    {
  "data": [
    {
      "sku": "SKU-CONTOH-001",
      "warehouse_id": "wh_example_001",
      "on_hand": 120,
      "reserved": 8,
      "available": 112,
      "updated_at": "2025-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": true,
    "next_cursor": "CURSOR_CONTOH"
  }
}

  3. Langkah 3: Telusuri semua halaman

    Respons berisi pagination.next_cursor. Kirim nilai itu pada request berikutnya sampai has_more bernilai false. Konsepnya dijelaskan di Pagination.

    Menelusuri semua halamanDraft
    # Halaman pertama
curl "https://api.example.com/v1/orders?limit=50" \
  -H "Authorization: Bearer TOKEN_CONTOH"

# Halaman berikutnya: pakai pagination.next_cursor dari respons sebelumnya
curl "https://api.example.com/v1/orders?limit=50&cursor=CURSOR_CONTOH" \
  -H "Authorization: Bearer TOKEN_CONTOH"
    Contoh respons (Draft)
    {
  "data": [
    {
      "id": "ord_example_001",
      "store_id": "sto_example_001",
      "status": "processing",
      "total": 250000,
      "currency": "IDR",
      "items": [
        {
          "sku": "SKU-CONTOH-001",
          "quantity": 1,
          "price": 250000
        }
      ],
      "created_at": "2025-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "CURSOR_CONTOH"
  }
}

  4. Langkah 4: Bandingkan dengan data internal

    Anggap sistem gudang Anda sebagai sumber kebenaran stok fisik. Bandingkan jumlahnya dengan on_hand dari OneSeller dan kumpulkan SKU yang berbeda.

    Hitung selisih stokDraft
    # Ringkas respons: hanya sku, gudang, dan stok fisik (butuh jq)
curl -s "https://api.example.com/v1/inventory?limit=100" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  | jq '[.data[] | {sku, warehouse_id, on_hand}]'

  5. Langkah 5: Kirim penyesuaian secara idempoten

    Untuk tiap selisih, kirim penyesuaian dengan mode: "set". Susun Idempotency-Key dari SKU dan nomor proses sinkronisasi supaya percobaan ulang tidak menggandakan penyesuaian.

    Hormati rate limit

    Kirim penyesuaian secara berurutan atau dalam batch kecil, dan tangani 429 dengan backoff. Lihat Rate limit.

    Kirim penyesuaian stokDraft
    curl -X POST "https://api.example.com/v1/inventory/adjustments" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sinkron-SKU-CONTOH-001-0001" \
  -d '{
  "sku": "SKU-CONTOH-001",
  "warehouse_id": "wh_example_001",
  "mode": "set",
  "quantity": 112,
  "reason": "sinkronisasi dari sistem gudang"
}'
    Contoh respons 201 (Draft)
    {
  "id": "adj_example_002",
  "sku": "SKU-CONTOH-001",
  "warehouse_id": "wh_example_001",
  "previous": 120,
  "current": 112,
  "reason": "sinkronisasi dari sistem gudang"
}

  6. Langkah 6: Dengarkan webhook untuk pembaruan langsung

    Daftarkan URL penerima dengan POST /webhooks untuk event inventory.adjusted dan inventory.low_stock. Verifikasi signature setiap pengiriman sebelum memprosesnya; rancangannya ada di Webhook.

    Verifikasi signature webhook (rancangan)Draft
    # Simulasi: hitung signature untuk payload contoh
SECRET="SECRET_CONTOH_TIDAK_NYATA"
TS=$(date +%s)
BODY='{"id":"evt_example_001","type":"inventory.low_stock"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

# Kirim ke penerima lokal Anda untuk menguji kode verifikasi
curl -X POST "http://localhost:3000/webhooks/oneseller" \
  -H "Content-Type: application/json" \
  -H "X-OneSeller-Signature: t=$TS,v1=$SIG" \
  -d "$BODY"

  7. Langkah 7: Uji dan siapkan penanganan error

    • Tangani 401, 403, 404, 422, 429, dan 5xx sesuai tabel di Error Codes.
    • Catat request_id dari setiap error.
    • Pastikan setiap operasi tulis memakai Idempotency-Key.
    • Jalankan sinkronisasi pertama pada data uji sebelum data sungguhan.

    Belum bisa dijalankan

    Karena API belum tersedia, langkah uji di atas baru dapat dilakukan setelah API dirilis dan akses sandbox disediakan.