API Reference

Referensi endpoint rancangan untuk Products, Inventory, Orders, Stores, dan Webhooks. Path memakai placeholder dan seluruh schema berstatus Draft.

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.

Ringkasan

Draft

Referensi ini memetakan endpoint yang direncanakan. Seluruhnya Draft: nama field, tipe, dan perilaku masih dapat berubah sebelum kontrak disepakati.

Konvensi umum rancangan API
Hal	Rancangan
Base URL (placeholder)	`https://api.example.com/v1`
Autentikasi	Header `Authorization: Bearer TOKEN_CONTOH`. Lihat Autentikasi.
Format	JSON (`Content-Type: application/json`)
Pagination	Cursor, lihat Pagination
Request tulis	Disarankan memakai `Idempotency-Key`, lihat Idempotensi
Error	Body seragam, lihat Error Codes

Products

Draft

Katalog produk dan statusnya.

Daftar produk

Draft

GEThttps://api.example.com/v1/products

Mengambil daftar produk, terbaru lebih dulu, dengan pagination cursor.

Scope: products:read

Parameter

Parameter untuk Daftar produk
Nama	Lokasi	Tipe	Wajib	Keterangan
`limit`	query	integer	Tidak	Jumlah item per halaman, 1 sampai 100. Bawaan 20.
`cursor`	query	string	Tidak	Cursor dari `pagination.next_cursor` respons sebelumnya.
`status`	query	string	Tidak	`active` atau `archived`.
`sku`	query	string	Tidak	Filter berdasarkan SKU persis.
`updated_since`	query	string	Tidak	Waktu ISO 8601; hanya produk yang berubah sejak waktu ini.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/products?limit=20&status=active" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "data": [
    {
      "id": "prd_example_001",
      "sku": "SKU-CONTOH-001",
      "name": "Jaket Outdoor (contoh)",
      "price": 250000,
      "currency": "IDR",
      "status": "active",
      "stock_total": 120,
      "updated_at": "2025-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "CURSOR_CONTOH"
  }
}

Detail produk

Draft

GEThttps://api.example.com/v1/products/{product_id}

Mengambil satu produk berdasarkan id.

Scope: products:read

Parameter

Parameter untuk Detail produk
Nama	Lokasi	Tipe	Wajib	Keterangan
`product_id`	path	string	Ya	Id produk.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/products/prd_example_001" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "id": "prd_example_001",
  "sku": "SKU-CONTOH-001",
  "name": "Jaket Outdoor (contoh)",
  "price": 250000,
  "currency": "IDR",
  "status": "active",
  "stock_total": 120,
  "updated_at": "2025-01-15T08:00:00Z"
}

Buat produk

DraftIdempoten

POSThttps://api.example.com/v1/products

Membuat produk baru. Aman diulang bila memakai Idempotency-Key.

Scope: products:write

Parameter

Parameter untuk Buat produk
Nama	Lokasi	Tipe	Wajib	Keterangan
`Idempotency-Key`	header	string	Tidak	Nilai unik per operasi agar aman diulang.
`sku`	body	string	Ya	SKU unik di dalam organisasi.
`name`	body	string	Ya	Nama produk.
`price`	body	integer	Ya	Harga dalam Rupiah, tanpa desimal.
`currency`	body	string	Tidak	Bawaan `IDR`.
`status`	body	string	Tidak	`active` (bawaan) atau `archived`.

Contoh request dan respons

Contoh requestDraft

curl -X POST "https://api.example.com/v1/products" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b7f6c9e-6f0e-4c1a-9d38-2f1c5a8e7b10" \
  -d '{
  "sku": "SKU-CONTOH-002",
  "name": "Kaos Hiking (contoh)",
  "price": 120000,
  "currency": "IDR",
  "status": "active"
}'

Contoh respons 201 (Draft)

{
  "id": "prd_example_002",
  "sku": "SKU-CONTOH-002",
  "name": "Kaos Hiking (contoh)",
  "price": 120000,
  "currency": "IDR",
  "status": "active",
  "stock_total": 0
}

Ubah produk

DraftIdempoten

PATCHhttps://api.example.com/v1/products/{product_id}

Mengubah sebagian field produk. Field yang tidak dikirim tidak berubah.

Scope: products:write

Parameter

Parameter untuk Ubah produk
Nama	Lokasi	Tipe	Wajib	Keterangan
`product_id`	path	string	Ya	Id produk.
`Idempotency-Key`	header	string	Tidak	Nilai unik per operasi agar aman diulang.
`name`	body	string	Tidak	Nama produk.
`price`	body	integer	Tidak	Harga dalam Rupiah.
`status`	body	string	Tidak	`active` atau `archived`.

Contoh request dan respons

Contoh requestDraft

curl -X PATCH "https://api.example.com/v1/products/prd_example_001" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d2a91f4-3c55-4b8e-a0c7-9e12f4b6d8a3" \
  -d '{
  "price": 235000,
  "status": "active"
}'

Contoh respons 200 (Draft)

{
  "id": "prd_example_001",
  "sku": "SKU-CONTOH-001",
  "name": "Jaket Outdoor (contoh)",
  "price": 235000,
  "currency": "IDR",
  "status": "active",
  "stock_total": 120,
  "updated_at": "2025-01-15T08:00:00Z"
}

Inventory

Draft

Stok per SKU dan gudang, serta penyesuaian stok.

Daftar stok

Draft

GEThttps://api.example.com/v1/inventory

Mengambil stok per SKU dan gudang.

Scope: inventory:read

Parameter

Parameter untuk Daftar stok
Nama	Lokasi	Tipe	Wajib	Keterangan
`limit`	query	integer	Tidak	Jumlah item per halaman, 1 sampai 100. Bawaan 20.
`cursor`	query	string	Tidak	Cursor dari `pagination.next_cursor` respons sebelumnya.
`warehouse_id`	query	string	Tidak	Filter berdasarkan gudang.
`sku`	query	string	Tidak	Filter berdasarkan SKU persis.
`low_stock`	query	boolean	Tidak	Hanya SKU di bawah ambang batas.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/inventory?limit=100&low_stock=true" \
  -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": false,
    "next_cursor": null
  }
}

Stok per SKU

Draft

GEThttps://api.example.com/v1/inventory/{sku}

Mengambil stok satu SKU di semua gudang.

Scope: inventory:read

Parameter

Parameter untuk Stok per SKU
Nama	Lokasi	Tipe	Wajib	Keterangan
`sku`	path	string	Ya	SKU produk.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/inventory/SKU-CONTOH-001" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "sku": "SKU-CONTOH-001",
  "total_available": 112,
  "warehouses": [
    {
      "sku": "SKU-CONTOH-001",
      "warehouse_id": "wh_example_001",
      "on_hand": 120,
      "reserved": 8,
      "available": 112,
      "updated_at": "2025-01-15T08:00:00Z"
    }
  ]
}

Buat penyesuaian stok

DraftIdempoten

POSThttps://api.example.com/v1/inventory/adjustments

Menyesuaikan stok sebuah SKU di satu gudang, baik dengan selisih maupun nilai akhir.

Scope: inventory:write

Parameter

Parameter untuk Buat penyesuaian stok
Nama	Lokasi	Tipe	Wajib	Keterangan
`Idempotency-Key`	header	string	Tidak	Nilai unik per operasi agar aman diulang.
`sku`	body	string	Ya	SKU yang disesuaikan.
`warehouse_id`	body	string	Ya	Gudang tujuan.
`mode`	body	string	Ya	`set` (nilai akhir) atau `delta` (selisih).
`quantity`	body	integer	Ya	Jumlah; untuk `delta` boleh negatif.
`reason`	body	string	Tidak	Alasan penyesuaian, untuk jejak audit.

Contoh request dan respons

Contoh requestDraft

curl -X POST "https://api.example.com/v1/inventory/adjustments" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opname-SKU-CONTOH-001-0001" \
  -d '{
  "sku": "SKU-CONTOH-001",
  "warehouse_id": "wh_example_001",
  "mode": "set",
  "quantity": 112,
  "reason": "stok opname"
}'

Contoh respons 201 (Draft)

{
  "id": "adj_example_001",
  "sku": "SKU-CONTOH-001",
  "warehouse_id": "wh_example_001",
  "previous": 120,
  "current": 112,
  "reason": "stok opname"
}

Orders

Draft

Pesanan dari berbagai channel dan pencatatan pengiriman.

Daftar pesanan

Draft

GEThttps://api.example.com/v1/orders

Mengambil pesanan dari semua toko terhubung, terbaru lebih dulu.

Scope: orders:read

Parameter

Parameter untuk Daftar pesanan
Nama	Lokasi	Tipe	Wajib	Keterangan
`limit`	query	integer	Tidak	Jumlah item per halaman, 1 sampai 100. Bawaan 20.
`cursor`	query	string	Tidak	Cursor dari `pagination.next_cursor` respons sebelumnya.
`status`	query	string	Tidak	`pending`, `processing`, `shipped`, `completed`, atau `cancelled`.
`store_id`	query	string	Tidak	Filter berdasarkan toko.
`created_from`	query	string	Tidak	Waktu ISO 8601 awal rentang.
`created_to`	query	string	Tidak	Waktu ISO 8601 akhir rentang.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/orders?limit=50&status=processing" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (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": false,
    "next_cursor": null
  }
}

Detail pesanan

Draft

GEThttps://api.example.com/v1/orders/{order_id}

Mengambil satu pesanan beserta itemnya.

Scope: orders:read

Parameter

Parameter untuk Detail pesanan
Nama	Lokasi	Tipe	Wajib	Keterangan
`order_id`	path	string	Ya	Id pesanan.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/orders/ord_example_001" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "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"
}

Catat pengiriman

DraftIdempoten

POSThttps://api.example.com/v1/orders/{order_id}/fulfillments

Mencatat pengiriman sebuah pesanan beserta nomor resi.

Scope: orders:write

Parameter

Parameter untuk Catat pengiriman
Nama	Lokasi	Tipe	Wajib	Keterangan
`order_id`	path	string	Ya	Id pesanan.
`Idempotency-Key`	header	string	Tidak	Nilai unik per operasi agar aman diulang.
`carrier`	body	string	Ya	Kode kurir.
`tracking_number`	body	string	Ya	Nomor resi.

Contoh request dan respons

Contoh requestDraft

curl -X POST "https://api.example.com/v1/orders/ord_example_001/fulfillments" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kirim-ord_example_001-0001" \
  -d '{
  "carrier": "kurir-contoh",
  "tracking_number": "RESI-CONTOH-001"
}'

Contoh respons 201 (Draft)

{
  "id": "ful_example_001",
  "order_id": "ord_example_001",
  "carrier": "kurir-contoh",
  "tracking_number": "RESI-CONTOH-001",
  "status": "shipped"
}

Stores

Draft

Toko atau channel yang terhubung (hanya baca).

Daftar toko

Draft

GEThttps://api.example.com/v1/stores

Mengambil toko atau channel yang terhubung beserta status koneksinya.

Scope: stores:read

Parameter

Parameter untuk Daftar toko
Nama	Lokasi	Tipe	Wajib	Keterangan
`limit`	query	integer	Tidak	Jumlah item per halaman, 1 sampai 100. Bawaan 20.
`cursor`	query	string	Tidak	Cursor dari `pagination.next_cursor` respons sebelumnya.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/stores" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "data": [
    {
      "id": "sto_example_001",
      "name": "Toko Contoh",
      "channel": "marketplace",
      "connection_status": "connected"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Detail toko

Draft

GEThttps://api.example.com/v1/stores/{store_id}

Mengambil satu toko berdasarkan id.

Scope: stores:read

Parameter

Parameter untuk Detail toko
Nama	Lokasi	Tipe	Wajib	Keterangan
`store_id`	path	string	Ya	Id toko.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/stores/sto_example_001" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "id": "sto_example_001",
  "name": "Toko Contoh",
  "channel": "marketplace",
  "connection_status": "connected"
}

Webhooks

Draft

Langganan notifikasi event ke URL Anda.

Daftar langganan webhook

Draft

GEThttps://api.example.com/v1/webhooks

Mengambil langganan webhook yang terdaftar.

Scope: webhooks:manage

Parameter

Parameter untuk Daftar langganan webhook
Nama	Lokasi	Tipe	Wajib	Keterangan
`limit`	query	integer	Tidak	Jumlah item per halaman, 1 sampai 100. Bawaan 20.
`cursor`	query	string	Tidak	Cursor dari `pagination.next_cursor` respons sebelumnya.

Contoh request dan respons

Contoh requestDraft

curl -X GET "https://api.example.com/v1/webhooks" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Contoh respons 200 (Draft)

{
  "data": [
    {
      "id": "whk_example_001",
      "url": "https://example.com/webhooks/oneseller",
      "events": [
        "order.created",
        "inventory.low_stock"
      ],
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Buat langganan webhook

DraftIdempoten

POSThttps://api.example.com/v1/webhooks

Mendaftarkan URL penerima untuk satu atau beberapa event. Signing secret hanya ditampilkan sekali.

Scope: webhooks:manage

Parameter

Parameter untuk Buat langganan webhook
Nama	Lokasi	Tipe	Wajib	Keterangan
`Idempotency-Key`	header	string	Tidak	Nilai unik per operasi agar aman diulang.
`url`	body	string	Ya	URL HTTPS penerima.
`events`	body	string[]	Ya	Daftar event, lihat Webhook.

Contoh request dan respons

Contoh requestDraft

curl -X POST "https://api.example.com/v1/webhooks" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: daftar-webhook-0001" \
  -d '{
  "url": "https://example.com/webhooks/oneseller",
  "events": [
    "order.created",
    "inventory.low_stock"
  ]
}'

Contoh respons 201 (Draft)

{
  "id": "whk_example_001",
  "url": "https://example.com/webhooks/oneseller",
  "events": [
    "order.created",
    "inventory.low_stock"
  ],
  "status": "active",
  "signing_secret": "SECRET_CONTOH_TIDAK_NYATA"
}

Hapus langganan webhook

Draft

DELETEhttps://api.example.com/v1/webhooks/{webhook_id}

Menghentikan dan menghapus langganan webhook.

Scope: webhooks:manage

Parameter

Parameter untuk Hapus langganan webhook
Nama	Lokasi	Tipe	Wajib	Keterangan
`webhook_id`	path	string	Ya	Id langganan webhook.

Contoh request dan respons

Contoh requestDraft

curl -X DELETE "https://api.example.com/v1/webhooks/whk_example_001" \
  -H "Authorization: Bearer TOKEN_CONTOH" \
  -H "Accept: application/json"

Respons 204 (Draft)

// 204 No Content: tanpa body