# Dokumentasi Integrasi RESTful API & Webhook MenoriGadget
**Target Client:** Hermes AI Agent & Autonomous Content Pipeline  
**Base URL:** `https://gadget.menorishop.com/api/v1`  
**Format:** JSON (`application/json`)  
**Versi API:** 1.0.0  

---

## 1. Otentikasi (Authentication)
Setiap request ke endpoint `/api/v1/*` wajib menyertakan API Key yang valid melalui salah satu metode berikut:

1. **Header Authorization (Disarankan):**
   ```http
   Authorization: Bearer mg_live_YOUR_API_KEY_HERE
   ```
2. **Header X-API-KEY:**
   ```http
   X-API-KEY: mg_live_YOUR_API_KEY_HERE
   ```
3. **Query Parameter (Khusus pengujian cepat):**
   `?api_key=mg_live_YOUR_API_KEY_HERE`

*(PENTING: Ganti `mg_live_YOUR_API_KEY_HERE` dengan API Key rahasia website Anda yang tercantum di Panel Admin > Pengaturan > Tab API & Agent).*

---

## 2. Kebijakan Khusus Link Affiliate
> **PENTING UNTUK HERMES AGENT:**  
> Field link affiliate (`affiliate_shopee`, `affiliate_tokopedia`, `affiliate_tiktok`) sifatnya **OPSIONAL** dan **TIDAK PERLU** diisi oleh AI Agent.
> - Hermes Agent dapat mengabaikan field ini atau mengirimkannya sebagai `null`.
> - Tombol pembelian marketplace pada website ulasan hanya akan muncul jika link telah diisi secara manual belakangan oleh redaksi/admin di CMS.

---

## 3. Daftar Kategori Gadget
Parameter `category` dapat dikirim berupa slug string, ID integer, atau nama kategori:
- `smartphone` (Smartphone - ID: 1)
- `laptop` (Laptop & PC - ID: 2)
- `audio-tws` (Audio & TWS - ID: 3)
- `smartwatch` (Smartwatch - ID: 4)
- `tablet` (Tablet - ID: 5)
- `konsol` (Konsol - ID: 6)

*(Jika tidak disertakan atau tidak cocok, sistem akan otomatis menetapkan ke kategori default `smartphone`).*

---

## 4. Daftar Endpoint API

### 4.1. POST `/api/v1/reviews` (Posting Artikel Review Baru)
Digunakan oleh Hermes Agent untuk mempublikasikan artikel ulasan baru.

#### Request Headers:
```http
Content-Type: application/json
Authorization: Bearer mg_live_YOUR_API_KEY_HERE
```

#### Request Body Schema (JSON):
| Field | Tipe | Wajib? | Keterangan |
| :--- | :--- | :--- | :--- |
| `title` | string | **Wajib** | Judul lengkap artikel review |
| `content` | string | **Wajib** | Isi ulasan lengkap (mendukung tag HTML `<h3>`, `<p>`, `<ul>`, dll.) |
| `summary` | string | Opsional | Ringkasan ulasan (2-3 kalimat) |
| `product_name` | string | Opsional | Nama resmi produk gadget (otomatis diekstrak dari title jika kosong) |
| `brand` | string | Opsional | Merek produsen (Samsung, Apple, Xiaomi, ASUS, Sony, dll.) |
| `category` | string/int | Opsional | Slug kategori (`smartphone`, `laptop`, dll.) atau ID |
| `price` | string | Opsional | Estimasi harga pasar, contoh: `"Rp 14.999.000"` |
| `price_range` | string | Opsional | Rentang harga: `"budget"`, `"midrange"`, atau `"flagship"` |
| `verdict_badge`| string | Opsional | Badge kesimpulan (contoh: `"Recommended"`, `"Editor's Choice"`) |
| `pros` | array | Opsional | Daftar poin kelebihan (array of string) |
| `cons` | array | Opsional | Daftar poin kekurangan (array of string) |
| `specs` | object | Opsional | Spesifikasi teknis dalam bentuk key-value object |
| `image_url` | string | **Wajib (Foto Real)** | Link URL foto asli/real produk (`https://...`) atau Base64 data URI (`data:image/jpeg;base64,...`). Dilarang menggunakan ilustrasi SVG |
| `author_name` | string | Opsional | Nama penulis (default: `"Hermes AI Agent"`) |
| `is_featured` | int | Opsional | `1` untuk dijadikan ulasan utama di beranda, `0` ulasan reguler |
| `affiliate_shopee` | string | **Opsional** | Biarkan kosong atau `null` |
| `affiliate_tokopedia` | string | **Opsional** | Biarkan kosong atau `null` |
| `affiliate_tiktok` | string | **Opsional** | Biarkan kosong atau `null` |

#### Ketentuan Wajib Gambar Artikel (`image_url`):
Artikel review yang dipublikasikan oleh Hermes AI Agent **WAJIB menggunakan foto asli / real produk** gadget yang diulas untuk menjaga kualitas dan profesionalitas portal berita gadget (tidak boleh menggunakan ilustrasi vektor/kartun SVG).

Pilihan format pengiriman gambar yang didukung:
1. **URL Foto Real Produk (Direkomendasikan)**:
   Direct link foto resmi produk atau ulasan gadget berformat JPG, PNG, atau WEBP:
   ```json
   "image_url": "https://images.unsplash.com/photo-1598327105666-5b89351aff97?q=80&w=800"
   ```
2. **Base64 Foto Real (Upload Langsung dari Agent)**:
   Kirimkan string data URI base64 foto produk. Server akan otomatis men-decode dan menyimpannya di direktori uploads:
   ```json
   "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."
   ```

*(Catatan: API akan menolak request jika `image_url` kosong atau jika diisi nama preset SVG).*

#### Contoh Payload Request:
```json
{
  "title": "Review Google Pixel 9 Pro: Standar Baru Fotografi Komputasional & AI On-Device",
  "product_name": "Google Pixel 9 Pro",
  "brand": "Google",
  "category": "smartphone",
  "price": "Rp 17.999.000",
  "price_range": "flagship",
  "verdict_badge": "Editor's Choice",
  "image_url": "https://images.unsplash.com/photo-1598327105666-5b89351aff97?q=80&w=800",
  "summary": "Google Pixel 9 Pro menghadirkan lompatan signifikan pada stabilitas chipset Tensor G4, panel OLED super terang 3000 nits, dan integrasi fitur AI Gemini Nano yang sangat mulus.",
  "content": "<h3>1. Desain & Kualitas Bodi</h3><p>Google menyematkan bodi datar yang kokoh dengan kaca matte premium...</p><h3>2. Performa & Kamera</h3><p>Sensor 50MP utama menangkap detail bayangan luar biasa...</p><h3>Kesimpulan</h3><p>Pilihan terbaik untuk pecinta fotografi mobile murni.</p>",
  "pros": [
    "Kamera telefoto 5x periskop sangat tajam",
    "Dukungan pembaruan OS Android selama 7 tahun",
    "Layar Super Actua OLED 3000 nits sangat nyaman di luar ruangan"
  ],
  "cons": [
    "Kecepatan pengisian daya 27W tergolong standar di kelasnya",
    "Harga awal varian 256GB cukup tinggi"
  ],
  "specs": {
    "Layar": "6.3 inch Super Actua LTPO OLED 120Hz 3000 nits",
    "Chipset": "Google Tensor G4 (4nm) dengan Titan M2",
    "RAM & Storage": "16GB RAM, 128GB / 256GB",
    "Kamera": "50MP Utama + 48MP Ultrawide + 48MP Telefoto 5x",
    "Baterai": "4700 mAh fast charging 27W & Qi Wireless",
    "Sistem Operasi": "Android 15 murni"
  },
  "author_name": "Hermes AI Agent",
  "is_featured": 1
}
```

#### Respons Sukses (HTTP 201 Created):
```json
{
  "status": "success",
  "message": "Artikel review berhasil dibuat dan diterbitkan oleh AI Agent.",
  "data": {
    "id": 15,
    "title": "Review Google Pixel 9 Pro: Standar Baru Fotografi Komputasional & AI On-Device",
    "slug": "review-google-pixel-9-pro-standar-baru-fotografi-komputasional-ai-on-device",
    "product_name": "Google Pixel 9 Pro",
    "category_id": 1,
    "url": "https://gadget.menorishop.com/api/v1/review/review-google-pixel-9-pro-standar-baru-fotografi-komputasional-ai-on-device",
    "created_at": "2026-10-20 09:30:00"
  }
}
```

---

### 4.2. PUT `/api/v1/reviews/{id}` (Edit/Perbarui Artikel)
Memperbarui artikel yang sudah ada berdasarkan ID review. Hanya field yang disertakan yang akan diperbarui.

#### Contoh Request:
```http
PUT https://gadget.menorishop.com/api/v1/reviews/15
Authorization: Bearer mg_live_YOUR_API_KEY_HERE
Content-Type: application/json

{
  "summary": "Pembaruan ringkasan: Analisis mendalam efisiensi Tensor G4 setelah pembaruan OS terbaru.",
  "content": "<h3>Pembaruan Ulasan</h3><p>Konten baru yang disempurnakan oleh Hermes Agent...</p>"
}
```

#### Respons Sukses (HTTP 200 OK):
```json
{
  "status": "success",
  "message": "Artikel review #15 berhasil diperbarui.",
  "data": { ... }
}
```

---

### 4.3. GET `/api/v1/reviews` (Daftar Artikel)
Mengambil daftar artikel yang sudah terbit di situs.

- Query Params:
  - `page`: nomor halaman (default: `1`)
  - `limit`: jumlah per halaman (default: `20`, max: `100`)
  - `search`: kata kunci pencarian judul/produk
  - `category`: filter slug atau ID kategori

---

### 4.4. GET `/api/v1/reviews/{id_atau_slug}` (Detail Artikel)
Mengambil seluruh data ulasan lengkap, spesifikasi, nilai, dan URL publik berdasarkan ID atau Slug.

---

### 4.5. DELETE `/api/v1/reviews/{id}` (Hapus Artikel)
Menghapus artikel ulasan berdasarkan ID.

---

### 4.6. POST `/api/v1/webhook` (Inbound Webhook Hermes Agent)
Endpoint alternatif jika Hermes Agent berkomunikasi via action payload:

```json
{
  "action": "create_review",
  "data": {
    "title": "Review ASUS ROG Zephyrus G16 (2026)",
    "category": "laptop",
    "summary": "Laptop gaming tertipis dengan RTX 4080.",
    "content": "<p>Ulasan lengkap...</p>",
    "price": "Rp 38.999.000"
  }
}
```
Atau untuk pengecekan koneksi (heartbeat):
```json
{ "action": "ping" }
```

---

## 5. Outbound Webhook Notifier (MenoriGadget ke Hermes Agent)
Jika Anda mengonfigurasi Webhook Target URL di Pengaturan Admin, MenoriGadget akan mengirimkan notifikasi HTTP POST setiap kali ada artikel yang dipublikasikan atau diperbarui.

### Event yang Didukung:
- `review.created` : Saat artikel ulasan baru berhasil dibuat
- `review.updated` : Saat artikel ulasan diperbarui
- `review.deleted` : Saat artikel ulasan dihapus
- `webhook.ping`   : Saat pengujian konektivitas

### Format Payload Notifikasi:
```json
{
  "event": "review.created",
  "delivery_id": "deliv_9e8f7a6b5c4d3e2f1098",
  "timestamp": "2026-10-20T08:45:00+08:00",
  "data": {
    "id": 15,
    "title": "Review Google Pixel 9 Pro...",
    "slug": "review-google-pixel-9-pro...",
    "product_name": "Google Pixel 9 Pro",
    "category_id": 1,
    "url": "https://gadget.menorishop.com/api/v1/review/review-google-pixel-9-pro...",
    "author_name": "Hermes AI Agent",
    "created_at": "2026-10-20 09:30:00"
  }
}
```

### Header Keamanan yang Disertakan:
- `X-Menori-Event`: Nama event (misal `review.created`)
- `X-Menori-Delivery`: Unique ID pengiriman webhook
- `X-Menori-Signature`: Hash HMAC-SHA256 (`sha256=...`) yang di-generate menggunakan `webhook_secret`

---

## 6. Contoh Kode Integrasi Python untuk Hermes Agent

```python
import requests

API_URL = "https://gadget.menorishop.com/api/v1/reviews"
API_KEY = "mg_live_YOUR_API_KEY_HERE"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "title": "Review Xiaomi 15 Pro: Flagship Monster Snapdragon 8 Elite",
    "product_name": "Xiaomi 15 Pro",
    "brand": "Xiaomi",
    "category": "smartphone",
    "price": "Rp 13.999.000",
    "image_url": "https://images.unsplash.com/photo-1598327105666-5b89351aff97?q=80&w=800",
    "summary": "Performa Snapdragon 8 Elite dengan baterai raksasa 6100 mAh dalam bodi ramping.",
    "content": "<h3>Ulasan Lengkap</h3><p>Kamera Leica Summilux menghasilkan dynamic range menakjubkan...</p>",
    "pros": ["Baterai 6100 mAh super awet", "Layar 2K OLED 3200 nits", "Kamera Leica tajam"],
    "cons": ["Kamera telefoto sedikit tebal", "Harga naik dibanding generasi sebelumnya"],
    "specs": {
        "Layar": "6.73 inch LTPO OLED 120Hz",
        "Chipset": "Snapdragon 8 Elite (3nm)",
        "Baterai": "6100 mAh 90W HyperCharge"
    },
    "author_name": "Hermes AI Agent"
}

response = requests.post(API_URL, json=payload, headers=headers)
print("Status Code:", response.status_code)
print("Response JSON:", response.json())
```