# AksesSaham

> API proxy ber-API-key untuk data pasar saham Indonesia. Sumber data: Stockbit
> (exodus.stockbit.com). Setiap permintaan wajib menyertakan API key.

Base URL: https://aksessaham.pages.dev/api/v1

## Autentikasi

Kirim salah satu:
- Header: `X-API-Key: ask_xxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- Header: `Authorization: Bearer ask_xxx`
- Query: `?apikey=ask_xxx`

## Endpoint

- GET /api/v1/ping — cek hidup & sisa kuota
- GET /api/v1/sectors — daftar sektor
- GET /api/v1/info/{code} — profil emiten
- GET /api/v1/orderbook/{code} — bid/offer + harga terakhir (near real-time)
- GET /api/v1/historical/{code} — OHLCV harian + foreign flow
- GET /api/v1/keystats/{code} — PER/PBV/ROE, hingga 10 tahun
- GET /api/v1/broker/{code} — bandarmologi / broker summary
- GET /api/v1/raw/{path} — teruskan ke path upstream (butuh scope `raw`)

{code} = kode saham IDX, mis. BBCA, TLKM, GOTO. Huruf besar-kecil tidak berpengaruh.

## Aturan parameter yang sering meleset

- `limit` pada historical MAKSIMAL 50. Nilai lebih besar ditolak upstream (HTTP 400)
  dan otomatis diturunkan ke 50 oleh AksesSaham.
- Rentang tanggal historical MAKSIMAL ~365 hari.
- 1 tahun data harian ≈ 239 baris ≈ 5 permintaan:
  `/api/v1/historical/BBCA?days=365&limit=50&page=1` … `page=5`
- historical menerima `days`, `start`, `end`, `limit`, `page`, `period`.
- Jika `end` lebih awal dari hari ini, data bersifat final dan di-cache 24 jam.

## Bentuk respons

- Default: payload asli upstream, tidak dibungkus.
- Tambahkan `?envelope=1` untuk `{ ok, data, meta }`.
- Header berguna: `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Upstream-Cache`
  (`HIT` | `MISS` | `STALE`), `X-Request-Id`.

## Kode error

- 401 `missing_key` — tidak ada API key
- 401 `invalid_key` — key tidak dikenal
- 403 `key_revoked` / `key_expired` — key dicabut atau kedaluwarsa
- 403 `scope_denied` — key tidak punya scope yang diperlukan
- 429 `rate_limited` — kuota per menit habis, lihat `Retry-After`
- 503 `no_token` — kredensial upstream belum diset (urusan admin, bukan pemakai)
- 400 `invalid_parameter` — parameter ditolak Stockbit, biasanya `limit` > 50
  atau rentang tanggal > 365 hari

## Contoh

```
curl -H "X-API-Key: ask_xxx" "https://aksessaham.pages.dev/api/v1/orderbook/BBCA"
```

```javascript
const r = await fetch('https://aksessaham.pages.dev/api/v1/broker/BBCA?days=30', {
  headers: { 'X-API-Key': process.env.AKSESSAHAM_KEY }
});
const data = await r.json();
```

## Dokumentasi lain

- OpenAPI 3.1: https://aksessaham.pages.dev/openapi.json
- Halaman web: https://aksessaham.pages.dev/docs
- Ringkasan mesin: https://aksessaham.pages.dev/api/v1