# SMM API v2

Public endpoint duy nhất:

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

API tự động xác định website theo hostname. Token của domain này không thể dùng trên domain khác.

## Request

Gửi dữ liệu bằng `application/x-www-form-urlencoded` hoặc JSON. Token đặt trong field `key`; header `Api-token` vẫn được hỗ trợ để tương thích.

Mỗi request cần field `action`. Lỗi contract có dạng:

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

## Balance

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

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

## Services

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

Mỗi phần tử gồm `service`, `name`, `type`, `rate`, `min`, `max`, `refill`, `cancel` và `dripfeed`. `rate` là giá USD cho 1.000 item. `cancel` và `refill` chỉ là `true` khi provider đã được bật capability tương ứng trong admin.

## Add order

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

Với dịch vụ comment, gửi thêm field `comments` chứa một comment trên mỗi dòng.

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

Khi retry, gửi cùng header `X-Idempotency-Key`. Cùng key và cùng payload sẽ trả lại kết quả cũ mà không tạo đơn hoặc trừ tiền lần hai. Dùng lại key với payload khác sẽ bị từ chối. Nếu process bị dừng giữa chừng, API tự tìm đơn đã tạo; record không có đơn sau timeout `SMM_API_IDEMPOTENCY_TIMEOUT_SECONDS` (mặc định 300 giây) có thể được xử lý lại.

## Order status

Một đơn:

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

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

Nhiều đơn có thể gửi `orders` dạng CSV. Response là object có order ID làm key. Trạng thái chuẩn gồm `Pending`, `In progress`, `Completed`, `Partial`, `Canceled`, `Refunded` và `Failed`.

## Cancel

Gửi `order` hoặc `orders` dạng CSV:

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

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

Provider không hỗ trợ cancel sẽ trả lỗi; API không giả lập thành công.

## Refill

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

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

## Refill status

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

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

Trạng thái refill gồm `Pending`, `In progress`, `Completed` và `Failed`.

## Rate limit

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

Khi vượt giới hạn, API trả HTTP 429 với `{"error":"Rate limit exceeded"}`.