# MeetROAS Partner Event API

目标平台只需将业务事件发送到 MeetROAS；MeetROAS 会根据 mr_click_id 与客户设定处理流量平台回传。

- 正式端点: `POST https://api.meetroas.com/v1/events`
- 验证端点: `POST https://api.meetroas.com/v1/events/validate`
- 机器事件清单: `GET https://api.meetroas.com/v1/events/catalog`
- OpenAPI: https://developers.meetroas.com/openapi.json

## 取得凭证

客户账号 Admin 在 MeetROAS 后台进入 Conversions → Destination partner API，自助建立 Key ID 与 Secret。Secret 只显示一次，必须保存在服务器端 secrets manager；不需要联系 MeetROAS 人员。

## 签章

1. 将 JSON 序列化一次，并保留最终 raw body。
2. 产生 Unix seconds timestamp。
3. `signature = "v1=" + lowercase_hex(HMAC_SHA256(secret, timestamp + "." + raw_body))`
4. 使用标头: `Content-Type: application/json`, `X-MeetROAS-Key`, `X-MeetROAS-Timestamp`, `X-MeetROAS-Signature`.

## 请求

```json
{
  "event_id": "test-c778bd06-1cc3-4c6d-9886-23a0616b5c02",
  "mr_click_id": "mrc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "event": "purchase",
  "occurred_at": "2026-08-10T16:09:43.904Z",
  "value": 49.95,
  "currency": "USD"
}
```

- `event_id`: 1–128 字元的幂等键；同一业务事实重试必须沿用。
- `mr_click_id`: 从目标 URL 接收并保存的 opaque ID。
- `occurred_at`: 31 天内的 ISO-8601 UTC 时间。
- `value`: 选填十进位金额，0–1,000,000,000，最多六位小数，不是 minor units。
- `currency`: 选填 ISO 4217 大写三码；若提供必须同时提供 value。

## 接受事件

| event | 语义 | repeatability | monetary |
|---|---|---|---|
| `account_registration` | 使用者已完成目标平台定义的账号注册流程；仅浏览页面或送出未完成的表单不算。 | once_per_click | forbidden |
| `first_deposit` | 账号的第一笔已验证充值已成功生效；pending 或失败交易不算。 | once_per_click | optional |
| `deposit` | 一笔已验证且成功生效的充值；这是可重复事件。 | repeatable | optional |
| `purchase` | 一笔付款或购买已验证且成功结算；pending、失败或退款交易不算。 | repeatable | optional |

## 验证与上线

先对验证端点发送相同格式与签章；HTTP 200 且 valid=true 后，再使用测试访客产生的真实 mr_click_id 测试正式端点。验证端点不会建立正式事件。

## 回应

- `200`: 验证成功或重复事件已处理。
- `202`: 正式事件首次接受。
- `400/415`: 修正 body、字段或 Content-Type。
- `401`: 检查凭证、服务器时间与签署的 raw body。
- `404`: 找不到或无法归属 mr_click_id。
- `409`: event_id 对应了不同业务事实。
- `429/5xx`: 指数退避加抖动，并保留原 event_id 与 body。

## 支持的流量平台

TrafficStars, PropellerAds, RichAds, ExoClick.

预计支持：Adsterra, MGID, BidVertiser, HilltopAds, GeeMee, MGSkyAds。