# SMM API v2

Public endpoint duy nhat:

```text
POST https://your-domain.example/api/v2
```

API tu dong xac dinh website theo hostname. Token cua domain nay khong the dung tren domain khac.

## Request

Gui du lieu bang `application/x-www-form-urlencoded` hoac JSON. Token dat trong field `key`; header `Api-token` van duoc ho tro de tuong thich.

Moi request can field `action`. Loi contract co dang:

```json
{"error":"Error message"}
```

## Balance

```json
{"key":"TOKEN","action":"balance"}
```

```json
{"balance":"12.345","currency":"USD"}
```

## Services

```json
{"key":"TOKEN","action":"services"}
```

Moi phan tu gom `service`, `name`, `type`, `rate`, `min`, `max`, `refill`, `cancel` va `dripfeed`. `rate` la gia USD cho 1.000 item. `cancel` va `refill` chi la `true` khi provider da duoc bat capability tuong ung trong admin.

## Add order

```json
{
  "key":"TOKEN",
  "action":"add",
  "service":123,
  "link":"https://example.com/profile",
  "quantity":1000
}
```

Voi dich vu comment, gui them field `comments` chua mot comment tren moi dong.

```json
{"order":12345}
```

Khi retry, gui cung header `X-Idempotency-Key`. Cung key va cung payload se tra lai ket qua cu ma khong tao don hoac tru tien lan hai. Dung lai key voi payload khac se bi tu choi. Neu process bi dung giua chung, API tu tim don da tao; record khong co don sau timeout `SMM_API_IDEMPOTENCY_TIMEOUT_SECONDS` (mac dinh 300 giay) co the duoc xu ly lai.

## Order status

Mot don:

```json
{"key":"TOKEN","action":"status","order":12345}
```

```json
{"charge":"1.25","start_count":100,"status":"In progress","remains":900}
```

Nhieu don co the gui `orders` dang CSV. Response la object co order ID lam key. Trang thai chuan gom `Pending`, `In progress`, `Completed`, `Partial`, `Canceled`, `Refunded` va `Failed`.

## Cancel

Gui `order` hoac `orders` dang CSV:

```json
{"key":"TOKEN","action":"cancel","order":12345}
```

```json
{"cancel":1}
```

Provider khong ho tro cancel se tra loi; API khong gia lap thanh cong.

## Refill

```json
{"key":"TOKEN","action":"refill","order":12345}
```

```json
{"refill":6789}
```

## Refill status

```json
{"key":"TOKEN","action":"refill_status","refill":6789}
```

```json
{"status":"Pending"}
```

Trang thai refill gom `Pending`, `In progress`, `Completed` va `Failed`.

## Rate limit

- `balance`, `services`, `status`, `refill_status`: 60 request/phut/token.
- `add`, `cancel`, `refill`: 30 request/phut/token.

Khi vuot gioi han, API tra HTTP 429 voi `{"error":"Rate limit exceeded"}`.