# Emas API - Agent Integration Guide - Version 1.3.0

## 🚨 PENTING: Brand dan Source Selection

**KONSEP KRUSIAL**: Dalam pasar emas Indonesia, **satu brand bisa ada di beberapa source**. Ini sangat penting untuk pengambilan data yang akurat.

## Brand vs Source

### Brand (Produsen/Penjual):
- **ANTAM** - Perusahaan emas milik negara
- **EMASKU** / **EMASKU PRIME** - Hartadinata
- **UBS** - Produk brand UBS
- **GALERI 24** - Produk brand Galer24  
- **WARIS SAMPOERNA** - Produk brand Sampoerna
- **Multiple brands** di sistem Pegadaian

### Source (Penyedia Data/Website):
- **galeri24** - galeri24.co.id
- **antam** - logammulia.com (resmi ANTAM)
- **hartadinata** - emasku.co.id (resmi Hartadinata)
- **pegadaian** - sahabat.pegadaian.co.id
- **warissampoerna** - sampoernagold.com (resmi Waris Gold)

## 🔍 Insight Utama: Multiple Sources, Same Brands

**Satu brand bisa ada di beberapa sources:**

| Brand | Source 1 | Source 2 | Source 3 |
|-------|-----------|-----------|-----------|
| GALERI 24 | galeri24 | pegadaian | - |
| ANTAM | antam | pegadaian | - |
| UBS | galeri24 | pegadaian | - |
| EMASKU | hartadinata | - | - |
| WARIS SAMPOERNA | warissampoerna | - | - |

## 📡 Cara Pilih Kombinasi yang Tepat

### ✅ CONTOH BENAR 1: Harga UBS 1g
```bash
# BENAR: Dapatkan UBS dari source galeri24
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=UBS&resource=galeri24&weight=1"

# JUGA BENAR: Dapatkan UBS dari source pegadaian
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=UBS&resource=pegadaian&weight=1"
```

### ✅ CONTOH BENAR 2: Harga ANTAM 1g
```bash
# BENAR: Dapatkan ANTAM dari source antam (resmi)
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=antam&weight=1"

# JUGA BENAR: Dapatkan ANTAM dari source pegadaian
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=pegadaian&weight=1"
```

### ⚠️ KESALAHAN UMUM: Jangan Lakukan Ini

### ❌ SALAH: Hanya spesifikasikan brand
```bash
# INI MUNGKIN HASILKAN MULTIPLE RESULT untuk brand yang sama dari sources berbeda
curl "https://emas.maulanar.my.id/api/prices?brand=ANTAM&weight=1"

# Hasil: Anda mungkin mendapatkan:
# - ANTAM 1g dari source antam
# - ANTAM 1g dari source pegadaian
# (Mana yang Anda inginkan?)
```

### ✅ BENAR: Spesifikasikan brand DAN source
```bash
# INI MEMBERIKAN HASIL YANG TEPAT
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=antam&weight=1"

# Hasil: ANTAM 1g TEPAT dari source antam
```

## 📚 Dokumentasi API Lengkap

### Base URL
```
https://emas.maulanar.my.id/api
```

### Autentikasi
```
X-API-Key: KUNCI_API_ANDA
```

### Endpoints yang Tersedia

#### 1. Get All Prices
```bash
GET /api/prices
```

**Parameter Query:**
- `brand` (opsional) - Filter berdasarkan brand name
- `resource` (opsional) - **KRUSIAL**: Filter berdasarkan source data
- `weight` (opsional) - Filter berdasarkan berat dalam gram (contoh: 1, 0.5, 5)
- `updated_at` (opsional) - Filter berdasarkan tanggal (YYYY-MM-DD)
- `sort_by` (opsional) - Sort berdasarkan field (brand, resource, updated_at, weight)
- `order` (opsional) - Arah sort (asc, desc)
- `limit` (opsional) - Jumlah hasil per halaman
- `page` (opsional) - Nomor halaman

**Contoh Penggunaan:**
```bash
# Dapatkan semua harga ANTAM dari source antam
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=antam"

# Dapatkan semua harga 1g dari source galeri24
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?weight=1&resource=galeri24"
```

#### 2. Get Prices by Brand
```bash
GET /api/prices/brand/{brand}
```

**Contoh:**
```bash
# Dapatkan harga EMASKU dari source hartadinata
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices/brand/EMASKU?resource=hartadinata"
```

#### 2.1 Get Today's Price by Brand (NEW)
```bash
GET /api/prices/today/{brand}
```

**Deskripsi**: Mengambil SEMUA harga emas hari ini untuk brand tertentu (semua weight dan resource) beserta perubahan harga dari hari sebelumnya.

**Contoh:**
```bash
# Dapatkan semua harga ANTAM hari ini
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices/today/ANTAM"
```

**Response Format:**
```json
{
  "status": "success",
  "timestamp": "2026-04-02T10:30:00Z",
  "data": {
    "prices": [
      {
        "brand": "ANTAM",
        "resource": "antam", 
        "weight": 1.0,
        "sell_price": 1574000,
        "buyback_price": 1450000,
        "date": "2026-04-02",
        "updated_at": "2026-04-02",
        "sell_price_change": 5000,
        "buyback_price_change": -2000,
        "gramasi": 1.0
      },
      {
        "brand": "ANTAM", 
        "resource": "galeri24",
        "weight": 0.5,
        "sell_price": 787000,
        "buyback_price": 725000,
        "date": "2026-04-02",
        "updated_at": "2026-04-02",
        "sell_price_change": 3000,
        "buyback_price_change": 1000,
        "gramasi": 0.5
      }
    ]
  }
}
```

**Catatan Penting:**
- Endpoint ini mengembalikan **SEMUA kombinasi** weight-resource yang tersedia untuk brand tersebut
- **Tidak ada filter** weight=1 atau resource spesifik - semua data dikembalikan
- Setiap entry memiliki `sell_price_change` dan `buyback_price_change` dari harga sebelumnya
- Urutan hasil berdasarkan `updated_at DESC`

#### 3. Get Prices by Resource
```bash
GET /api/prices/resource/{resource}
```

**Contoh:**
```bash
# Dapatkan semua harga dari source pegadaian
curl -H "X-API-Key: KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices/resource/pegadaian"
```

#### 4. Get Available Brands
```bash
GET /api/brands
```

**Response:**
```json
{
  "status": "success",
  "data": ["ANTAM", "EMASKU", "EMASKU PRIME", "UBS", "GALERI 24", "WARIS SAMPOERNA"]
}
```

#### 5. Get Available Resources
```bash
GET /api/resources
```

**Response:**
```json
{
  "status": "success", 
  "data": ["galeri24", "antam", "hartadinata", "pegadaian", "warissampoerna"]
}
```

#### 6. Get API Version
```bash
GET /api/version
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "version": "1.0.0"
  }
}
```

## 🎯 Use Case Dunia Nyata untuk Agents

### Use Case 1: Agent Perbandingan Harga
**Scenario**: Bandingkan harga ANTAM 1g di semua sources

```bash
# Step 1: Dapatkan ANTAM dari source antam (resmi)
antam_resmi=$(curl -s -H "X-API-Key: $KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=antam&weight=1&limit=1" | \
  jq '.data[0].sell_price')

# Step 2: Dapatkan ANTAM dari source pegadaian
antam_pegadaian=$(curl -s -H "X-API-Key: $KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=pegadaian&weight=1&limit=1" | \
  jq '.data[0].sell_price')

# Step 3: Bandingkan
echo "ANTAM Resmi: Rp $antam_resmi"
echo "ANTAM Pegadaian: Rp $antam_pegadaian"
```

### Use Case 2: Agent Analisa Pasar
**Scenario**: Dapatkan semua harga 1g dari multiple brands/sources

```bash
# Dapatkan semua harga 1g dari semua sources
curl -H "X-API-Key: $KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?weight=1&limit=50" | \
  jq '.data | group_by(.brand) | map({brand: .[0].brand, prices: map(.sell_price)})'
```

### Use Case 3: Agent Riwayat Harga
**Scenario**: Lacak perubahan harga untuk kombinasi brand/source spesifik

```bash
# Dapatkan harga ANTAM 1g dari source antam untuk tanggal spesifik
curl -H "X-API-Key: $KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=ANTAM&resource=antam&weight=1&updated_at=2026-03-15"
```

### Use Case 4: Agent Kalkulator Investasi
**Scenario**: Hitung source terbaik untuk membeli brand spesifik

```bash
# Bandingkan harga beli untuk UBS 1g
ubs_galeri24=$(curl -s -H "X-API-Key: $KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=UBS&resource=galeri24&weight=1&limit=1" | \
  jq '.data[0].sell_price')

ubs_pegadaian=$(curl -s -H "X-API-Key: $KUNCI_API" \
  "https://emas.maulanar.my.id/api/prices?brand=UBS&resource=pegadaian&weight=1&limit=1" | \
  jq '.data[0].sell_price')

echo "UBS Galer24: Rp $ubs_galeri24"
echo "UBS Pegadaian: Rp $ubs_pegadaian"

# Rekomendasikan harga lebih murah
if [ "$ubs_galeri24" -lt "$ubs_pegadaian" ]; then
  echo "REKOMENDASI: Beli dari Galer24 untuk harga lebih murah"
else
  echo "REKOMENDASI: Beli dari Pegadaian untuk harga lebih murah"
fi
```

## 📊 Format Response

### Response Sukses
```json
{
  "status": "success",
  "timestamp": "2026-03-16T10:30:00Z",
  "data": [
    {
      "brand": "ANTAM",
      "resource": "antam",
      "weight": 1.0,
      "sell_price": 1574500,
      "buyback_price": 1530000,
      "updated_at": "2026-03-16"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 15,
    "total_items": 150,
    "total_pages": 10
  }
}
```

### Response Error
```json
{
  "status": "error",
  "timestamp": "2026-03-16T10:30:00Z",
  "error": "API key tidak valid"
}
```

## ⚙️ Rate Limiting

### Tier Free
- **1 requests/menit**
- **60 requests/bulan**

### Tier Lite
- **5 requests/menit**
- **270 requests/bulan**

### Tier Standard
- **30 requests/menit**
- **1300 requests/bulan**

### Tier Pro
- **100 requests/menit**
- **10000 requests/bulan**

### Tier Enterprise
- **1000 requests/menit**
- **Unlimited requests**

## 🔐 Praktik Keamanan

1. **JANGAN pernah expose API keys** di client-side code
2. **Gunakan environment variables** untuk menyimpan API keys
3. **Rotasi API keys** secara teratur
4. **Monitor usage** untuk mencegah charge tidak terduga
5. **Implement retry logic** dengan exponential backoff

## 🐛 Troubleshooting

### Issue: Multiple Results untuk Query yang Sama
**Masalah**: Mendapatkan brand ganda di hasil
**Solusi**: Selalu spesifikasikan baik parameter `brand` DAN `resource`

### Issue: Tidak Ada Hasil Ditemukan
**Masalah**: Array data kosong
**Solusi**: 
- Cek jika brand name benar (case-sensitive)
- Verifikasi resource name valid
- Cek jika data harga ada untuk tanggal yang diminta

### Issue: Rate Limit Terlampaui
**Masalah**: HTTP 429 status
**Solusi**: 
- Implement rate limiting yang proper di aplikasi Anda
- Upgrade ke tier yang lebih tinggi jika dibutuhkan
- Cache responses untuk mengurangi API calls

### Issue: Autentikasi Gagal
**Masalah**: HTTP 401 status
**Solusi**:
- Verifikasi API key benar
- Cek jika subscription aktif
- Pastikan API key belum di-regenerate

## 📞 Support

- **Documentation**: https://emas.maulanar.my.id/docs
- **Contact**: maulana.code@gmail.com
- **GitHub**: https://github.com/MaulanaR/Harga-Emas_Indonesia-API
- **Status Check**: https://emas.maulanar.my.id

## 🔄 Version History

- **v1.0.0** - Release awal dengan dukungan multi-brand, multi-source
- **v1.1.0** - Added payment integration dan advanced filtering
- **v1.2.0** - Added invoice generation dan enhanced features
- **v1.2.1** - Added new endpoint (today price by brand)

---

## 🤖 INGAT: Selalu spesifikasikan baik brand DAN resource untuk hasil yang tepat!

### Quick Reference - Kombinasi Brand/Source yang Valid:

| Brand | Source yang Valid | Deskripsi |
|-------|------------------|------------|
| ANTAM | antam | Resmi ANTAM, harga terpercaya |
| ANTAM | pegadaian | ANTAM di Pegadaian, cross-check |
| UBS | galeri24 | UBS di Galer24, harga kompetitif |
| UBS | pegadaian | UBS di Pegadaian, alternatif |
| GALERI 24 | galeri24 | Resmi Galer24, harga direct |
| GALERI 24 | pegadaian | Galer24 di Pegadaian, referensi |
| EMASKU | hartadinata | Resmi Hartadinata, harga premium |
| WARIS SAMPOERNA | warissampoerna | Resmi Sampoerna, harga luxury |

**PENTING**: Gunakan kombinasi yang tepat sesuai kebutuhan Anda!