Vardast

Dokumentasi Product API

advanced By Vardast Team

Ringkasan Persyaratan

  • Method: GET
  • Path: /api/v1/products
  • Authentication: Header X-API-Key
  • Format Response: application/json
  • Struktur Response Dasar: {"result": {"products": [...]}}
  • Encoding Karakter: UTF-8

1. Authentication

Untuk membatasi akses, tetapkan access key:

X-API-Key: <YOUR_API_KEY>

Jika tidak ada key yang disediakan, API dapat berjalan tanpa autentikasi; namun, sangat disarankan untuk selalu menggunakan key.

2. API Endpoint

Layanan kami membutuhkan endpoint GET yang mengembalikan daftar produk.

Contoh URL:

https://your-domain.com/api/v1/products

3. Struktur Response

Status Sukses: 200 OK

Body response harus berupa objek dengan key result yang berisi array products. Kami menyarankan untuk juga mengembalikan objek pagination.

{
  "result": {
    "products": [
      {
        "id": 123,
        "name": "Nama Produk",
        "url": "/product/sample-product",
        "product_categories": [
          { "name": "Kategori 1" },
          { "name": "Kategori 2" }
        ],
        "product_attributes": [
          {
            "name": "description",
            "value": "Deskripsi produk dalam HTML atau teks"
          }
        ],
        "product_variants": [
          {
            "stock_number": 10,
            "price": 250000,
            "product_attributes": [
              { "name": "color", "value": "red" },
              { "name": "size", "value": "L" }
            ]
          },
          {
            "stock_number": 5,
            "price": 260000,
            "product_attributes": [
              { "name": "color", "value": "blue" },
              { "name": "size", "value": "M" }
            ]
          }
        ]
      }
    ]
  }
}

4. Catatan Penting Kompatibilitas Field

Field Wajib:

  • id: Pengenal produk yang unik (wajib - harus integer)
  • name: Nama produk (wajib)
  • url: Harus relatif (misalnya, /product/123). Kami akan menambahkannya ke domain utama website Anda (wajib)
  • product_variants: Array variants. Setiap variant berisi:

stock_number: Integer (stok). Variant dengan stock_number <= 0 diabaikan.

price: Integer (harga) atau string "unavailable". Jika price = "unavailable", variant tersebut diabaikan.

product_attributes: Array { name, value } (seperti color, size, warranty, dll.)

Catatan: Jika sebuah produk tidak memiliki variant valid (atau tidak memiliki variant sama sekali), produk tersebut akan dihapus dari sistem kami.

Field Opsional:

  • product_categories: Array objek dengan minimal field name. Boleh array kosong.
  • product_attributes: Array objek berstruktur { name, value }, untuk menyertakan deskripsi produk.

Untuk deskripsi, pastikan mengembalikan item dengan name = "description". Nilai value boleh berupa HTML. Kami akan mengonversinya menjadi teks. Catatan: Saat ini, hanya objek description yang diterima. Objek lain pada product_attributes diabaikan dan tidak akan ditambahkan ke informasi produk.

5. Aturan Agregasi dan Validasi di Sisi Kami

  • Jika produk hanya memiliki satu variant dan variant tersebut valid (stock_number > 0 dan price != "unavailable"), kami menganggapnya produk "simple" dan menyimpan price serta stock langsung untuk produk tersebut.
  • Jika produk memiliki banyak variant:
  • Variant tidak valid dihapus.
  • Variant valid dikelompokkan berdasarkan kumpulan atributnya (misalnya, {color: red, size: L}) dan stok dari variant beratribut sama dijumlahkan.
  • Jika tidak ada grup variant valid yang tersisa setelah filtering, produk akan dibuang.

6. Status Error

  • 401 Unauthorized: Jika access key tidak dikirim atau salah.
  • 429 Too Many Requests: Jika rate limit terlampaui.
  • 500 Internal Server Error: Error tak terduga di sisi Anda.

7. Contoh Quick Test dengan cURL

  -H "Accept: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

8. Checklist Akhir untuk Anda

  • [ ] Implementasikan endpoint GET /api/v1/products
  • [ ] Kembalikan response dalam format {"result": {"products": [...]}}
  • [ ] Untuk setiap produk, sertakan key: id, name, url, product_categories, product_attributes, product_variants
  • [ ] Pada product_attributes, sertakan item dengan name = "description" (HTML diperbolehkan)
  • [ ] Variants menyertakan stock_number, price, dan product_attributes
  • [ ] Hapus variant dengan stock_number <= 0 atau price = "unavailable" dari response (atau jangan dikirim sama sekali)
  • [ ] Authentication dengan X-API-Key aktif
  • [ ] Status code error dan format error sudah didefinisikan

9. Menambahkan Website ke Platform Vardast

  • Pilih "Other" sebagai jenis website
  • Masukkan alamat website Anda
  • Pada bagian token, masukkan access key Anda

10. Contoh Produk

10.1 Produk Sederhana dengan Satu Variant Valid

{
  "result": {
    "products": [
      {
        "id": 501,
        "name": "Plain T-Shirt",
        "url": "/p/tshirt-plain",
        "product_categories": [{ "name": "Pakaian" }],
        "product_attributes": [
          {
            "name": "description",
            "value": "<p>Kaos katun berkualitas tinggi</p>"
          },
          { "name": "brand", "value": "ACME" }
        ],
        "product_variants": [
          {
            "stock_number": 15,
            "price": 249000,
            "product_attributes": [{ "name": "size", "value": "M" }]
          }
        ]
      }
    ]
  }
}

10.2 Produk Multi-Variant dengan Pengelompokan Atribut

{
  "result": {
    "products": [
      {
        "id": 777,
        "name": "Running Shoes",
        "url": "/p/run-shoe",
        "product_categories": [{ "name": "Sepatu" }, { "name": "Olahraga" }],
        "product_attributes": [
          {
            "name": "description",
            "value": "<p>Cocok untuk lari harian</p>"
          }
        ],
        "product_variants": [
          {
            "stock_number": 5,
            "price": 1899000,
            "product_attributes": [
              { "name": "color", "value": "black" },
              { "name": "size", "value": 42 }
            ]
          },
          {
            "stock_number": 2,
            "price": 1899000,
            "product_attributes": [
              { "name": "color", "value": "black" },
              { "name": "size", "value": 42 }
            ]
          },
          {
            "stock_number": 0,
            "price": 1899000,
            "product_attributes": [
              { "name": "color", "value": "black" },
              { "name": "size", "value": 43 }
            ]
          },
          {
            "stock_number": 3,
            "price": "unavailable",
            "product_attributes": [
              { "name": "color", "value": "blue" },
              { "name": "size", "value": 42 }
            ]
          }
        ]
      }
    ]
  }
}

Pada contoh di atas, hanya variant (black, 42) yang valid dan stoknya dijumlahkan (=7). Variant lainnya dihapus.

10.3 Produk Tanpa Variant Valid (Akan Dihapus)

{
  "result": {
    "products": [
      {
        "id": 888,
        "name": "Headphones",
        "url": "/p/headphone",
        "product_categories": [{ "name": "Audio" }],
        "product_attributes": [
          { "name": "description", "value": "<p>Bass yang kuat</p>" }
        ],
        "product_variants": [
          {
            "stock_number": 0,
            "price": 990000,
            "product_attributes": [{ "name": "color", "value": "black" }]
          },
          {
            "stock_number": 1,
            "price": "unavailable",
            "product_attributes": [{ "name": "color", "value": "black" }]
          }
        ]
      }
    ]
  }
}

Dalam kasus ini, tidak ada variant valid; produk ini akan dibuang.

Related Guides