# MeetROAS 客戶 API

透過 REST API 查詢成效，並以 Dashboard 編輯器的完整欄位新增或編輯 App 與 Campaign。

## 快速開始

1. 到 Dashboard `/account/api` 的「API」分頁建立 Key
2. 完整 Key 只顯示一次；立即用安全方式存入環境變數（例如 `read -rs MEETROAS_API_KEY` 然後 `export MEETROAS_API_KEY`、密碼管理器或 CI secrets）
3. 複製以下命令，直接執行；shell 會自動展開環境變數

```bash
curl https://open.meetroas.com/v1/me \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

## 驗證

在 Dashboard `/account/api` 的「API」分頁建立 Key。完整 Key 只在建立時顯示一次，格式：`mrp_<id>_<secret>`

**Authorization header:**

```
Authorization: Bearer mrp_<id>_<secret>
```

**權限範圍:**

- `apps:read` — 讀取 App 列表
- `campaigns:read` — 讀取 Campaign
- `performance:read` — 讀取成效資料（含版位洞察）
- `apps:write` — 新增與編輯 App；需 apps:read
- `campaigns:write` — 新增與編輯 Campaign；需 apps:read 與 campaigns:read

既有 Key 與預設核發選項維持唯讀。

## 配額與限制

| 方案 | units/分鐘 | units/日 (UTC) |
|---|---|---|
| Free | 30 | 1,000 |
| Starter | 60 | 5,000 |
| Pro | 120 | 20,000 |
| Scale | 300 | 100,000 |

**單位消耗:**

- `GET /v1/me`, `GET /v1/apps`, `GET /v1/apps/{appSlug}/campaigns`: 1 unit
- `GET /v1/apps/{appSlug}/campaigns/{campaignId}/placement-insights`: 10 units
- `GET /v1/.../editor`, `GET /v1/media/staging/{receipt}`: 1 unit
- 新增／編輯 App 或 Campaign、暫存媒體: 5 units
## REST API 參考

**基礎網域:** `https://open.meetroas.com/v1`

### GET /v1/me

所需權限：任何有效 Key · 配額單位：1

```bash
curl "https://open.meetroas.com/v1/me" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### GET /v1/apps

所需權限：apps:read · 配額單位：1

```bash
curl "https://open.meetroas.com/v1/apps" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### GET /v1/apps/{appSlug}/campaigns

所需權限：apps:read + campaigns:read · 配額單位：1

```bash
curl "https://open.meetroas.com/v1/apps/my-game/campaigns" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### GET /v1/apps/{appSlug}/campaigns/{campaignId}/placement-insights

所需權限：apps:read + campaigns:read + performance:read · 配額單位：10

**查詢參數:**

- `range`: `today` | `7d` | `30d` (預設: `7d`)
- `dimension`: `placement` | `subPlacement` | `creative` | `upstreamCampaign` | `country` | `environment` (預設: `placement`)

```bash
curl "https://open.meetroas.com/v1/apps/my-game/campaigns/brand:brand_9f2c41ab7d0e4c518a63b2d7e04f19c5/placement-insights?range=7d&dimension=placement" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### 新增與編輯 App / Campaign

所有寫入須帶 Idempotency-Key（8–128 字元）；PATCH 也須帶對應 /editor GET 回傳的 If-Match ETag。過期回 412。

- `POST /v1/apps`, `PATCH /v1/apps/{appSlug}`: JSON，支援 Dashboard App 編輯器的 content、primary、destination、objective、media。
- `GET /v1/apps/{appSlug}/editor`: 完整可編輯資料與 ETag。
- `POST /v1/apps/{appSlug}/campaigns`, `PATCH /v1/apps/{appSlug}/campaigns/{campaignId}`: multipart，支援 Dashboard Campaign 編輯器的全部欄位；JSON {enabled:boolean} 調整一般 Campaign 狀態。
- `GET /v1/apps/{appSlug}/campaigns/{campaignId}/editor`: 完整可編輯資料與 ETag。主要 Campaign 使用 App 欄位及 apps:write。
- `POST /v1/media/staging`: 暫存圖示、截圖、主視覺或影片；新增時 target 為 new-app:{Idempotency-Key} 或 new-page:{appId}:{Idempotency-Key}。

## 錯誤與重試

| HTTP | 意義 | 處理 |
|---|---|---|
| 401 `invalid_api_key` | Key 無效、已撤銷、已到期，或帳號／建立者失效 | 不要重試；換 Key |
| 403 `forbidden_scope` | 權限範圍不足 | 不要重試；用權限足夠的 Key |
| 404 `not_found` | App slug 或 campaign id 不存在 | 先用 /v1/apps、/v1/apps/{slug}/campaigns 取正確 id |
| 409 `conflict` / `idempotency_conflict` | 方案限制或重複新增鍵的內容不同 | 後者含已建立資源的 createdId |
| 412 `precondition_failed` | 編輯快照已變更 | 重新取得 /editor 與 ETag |
| 422 `unprocessable_entity` | 編輯器欄位驗證失敗 | 檢查 fieldErrors |
| 428 `precondition_required` | 編輯缺少 If-Match | 先取得 /editor 的 ETag |
| 429 `rate_limited` / `quota_exceeded` | units 或請求次數超限 | 依 Retry-After 等待 |
| 503 `service_unavailable` | 相依服務暫時不可用 | 依 Retry-After 等待 |

## 與 Partner Event API 的差異

| 特性 | Partner Event API | 客戶 API |
|---|---|---|
| 對象 | 下游目標平台商 | MeetROAS 客戶（投手）與其開發者 |
| 主機 | `api.meetroas.com` | `open.meetroas.com` |
| 驗證 | HMAC signature | Bearer token |
| 方向 | 接收轉換事件（寫入） | 查詢帳號與成效、管理 App 與 Campaign |
## 第 2 期預告

OAuth 2.1 規劃在第 3 期。

---

完整 OpenAPI 規格： https://open.meetroas.com/openapi.json