> ## Documentation Index
> Fetch the complete documentation index at: https://docs-zns.adflex.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# Hạn mức gửi tin

> Hai trần giới hạn số tin gửi được, và cách đối chiếu trước khi gửi batch

Có **hai trần** độc lập. Vượt trần nào cũng dừng việc gửi, nhưng cách xử lý khác nhau.

|            | Hạn mức tài khoản        | Hạn mức ngày của OA                     |
| ---------- | ------------------------ | --------------------------------------- |
| Do ai đặt  | AdFlex                   | Zalo                                    |
| Phạm vi    | Toàn workspace           | Từng Official Account                   |
| Chu kỳ     | Không reset theo ngày    | Reset nửa đêm giờ Việt Nam              |
| Khi vượt   | API trả `400` hoặc `402` | Zalo từ chối tin                        |
| Cách xử lý | Liên hệ AdFlex           | Chờ sang ngày, hoặc nâng chất lượng gửi |
| Tra cứu    | Liên hệ AdFlex           | `GET /api/v1/quota`                     |

<Warning>
  Hạn mức ngày của OA do Zalo **tự điều chỉnh theo chất lượng gửi**. Tỉ lệ tin bị từ
  chối cao hoặc người nhận chặn nhiều sẽ làm hạn mức giảm. Ngược lại, gửi đều và ít
  lỗi thì hạn mức tăng dần.
</Warning>

## Tra hạn mức ngày

`GET /api/v1/quota` · scope `messages:read`

```bash theme={null}
curl -H "Authorization: Bearer $ADFLEX_API_KEY" \
  https://business.adflex.vn/api/v1/quota
```

```json theme={null}
{
  "quotas": [
    {
      "oa_id": "1234567890123456789",
      "oa_name": "AdFlex",
      "daily_quota": 20000,
      "remaining": 19996,
      "used": 4,
      "reset_at": "2026-08-19T17:00:00.000Z",
      "error": null
    }
  ],
  "count": 1
}
```

| Trường        | Mô tả                                                   |
| ------------- | ------------------------------------------------------- |
| `daily_quota` | Số tin OA được gửi trong ngày                           |
| `remaining`   | Số tin còn lại                                          |
| `used`        | Đã dùng trong ngày                                      |
| `reset_at`    | Thời điểm reset, ISO 8601. Luôn là nửa đêm giờ Việt Nam |
| `error`       | Lý do không lấy được hạn mức của riêng OA này           |

Truyền `?oa_id=…` để lọc một OA. Không truyền thì trả về mọi OA của workspace.

<Note>
  Một OA lỗi không làm hỏng cả phản hồi. Trường `error` xuất hiện ở đúng OA đó, các OA
  còn lại vẫn có số dùng được.
</Note>

## Đối chiếu trước khi gửi batch

Gửi batch lớn nên tra hạn mức trước và chia batch cho vừa phần còn lại. Không tra thì batch
có thể đâm vào trần giữa chừng: những tin đầu đi được, phần sau trả lỗi.

```php theme={null}
function sendBatchWithinQuota(string $oaId, array $recipients, string $templateId): void {
    $quota     = getJson("/api/v1/quota?oa_id=" . urlencode($oaId));
    $remaining = $quota['quotas'][0]['remaining'] ?? 0;

    if ($remaining < count($recipients)) {
        // Gửi phần vừa hạn mức, phần dư để sang ngày hôm sau
        $recipients = array_slice($recipients, 0, $remaining);
        logInfo("Hạn mức còn $remaining, hoãn phần dư sang ngày mai");
    }

    foreach (array_chunk($recipients, 200) as $batch) {
        postJson('/api/v1/messages/batch', [
            'template_id' => $templateId,
            'recipients'  => $batch,
        ]);
    }
}
```

Hạn mức reset nửa đêm giờ Việt Nam, nên tác vụ gửi hàng loạt đặt vào đầu ngày sẽ có
nhiều dư địa nhất.