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

# Lên lịch

> Đăng ngay lập tức, vào một thời điểm cụ thể, hoặc thông qua hàng đợi định kỳ.

Mọi endpoint đăng bài đều có thể phát hành ngay lập tức hoặc vào thời điểm sau. Bạn chọn chế độ thời gian cho từng request.

## Đăng ngay

Đây là mặc định. Bỏ qua mọi trường lên lịch và bài đăng sẽ được phát hành ngay lập tức.

## Lên lịch cho một thời điểm cụ thể

Thêm `scheduled_at` (ISO-8601) và tùy chọn `timezone` (tên IANA). MADIAD Hub giữ bài đăng và phát hành vào đúng thời điểm đó.

```bash theme={null}
  -F "scheduled_at=2026-06-01T15:00:00Z" \
  -F "timezone=Asia/Ho_Chi_Minh"
```

* `scheduled_at` được đọc theo UTC khi kết thúc bằng `Z`. Cung cấp `timezone` để xử lý chính xác giờ địa phương và giờ mùa hè.
* Các bài đăng đã lên lịch trả về `status: "scheduled"`. Chúng sẽ được đăng sau, bạn có thể theo dõi kết quả qua [webhooks](/vi/concepts/webhooks).
* Bạn có thể lên lịch trước tối đa một năm.

## Dùng hàng đợi định kỳ

Thay vì một mốc thời gian cụ thể, hãy đưa bài đăng vào hàng đợi của Profile bằng `add_to_queue=true`. Bài sẽ được phát hành vào khe thời gian mở tiếp theo theo lịch đăng đó.

```bash theme={null}
  -F "add_to_queue=true"
```

<Warning>
  `scheduled_at` và `add_to_queue` **loại trừ lẫn nhau**: chỉ đặt một trong hai, không dùng cả hai cùng lúc.
</Warning>

### Cấu hình hàng đợi

Mỗi Profile có cấu hình hàng đợi riêng (timezone, ngày hoạt động, khe thời gian). Đọc cấu hình:

```bash theme={null}
curl "https://api.madiad.com/v1/queue/settings?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

Cập nhật bằng cách gửi ID của Profile kèm các trường bạn muốn đổi:

```bash theme={null}
curl -X POST https://api.madiad.com/v1/queue/settings \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "timezone": "Asia/Ho_Chi_Minh", "days": ["mon","wed","fri"], "slots": ["09:00","18:00"] }'
```

## Quản lý bài đã lên lịch

Liệt kê các bài đang chờ lên lịch của một Profile:

```bash theme={null}
curl "https://api.madiad.com/v1/schedule?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

Lên lịch lại hoặc sửa một bài trước khi phát hành, truyền bất kỳ trong `scheduled_at`, `timezone`, hoặc `caption`:

```bash theme={null}
curl -X PATCH https://api.madiad.com/v1/schedule/$JOB_ID \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-07-01T09:00:00Z", "timezone": "Asia/Ho_Chi_Minh" }'
```

Hủy một bài:

```bash theme={null}
curl -X DELETE https://api.madiad.com/v1/schedule/$JOB_ID \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

`$JOB_ID` là `job_id` mà lệnh đăng trả về khi `status` là `scheduled`.

<Note>
  Hủy một bài đã lên lịch không xoá lượt đăng đã được ghi nhận từ lúc đó. Vì đăng bài không giới hạn trên các gói trả phí nên điều này không gây thiệt hại gì, khe đã hủy chỉ đơn giản vẫn nằm trong số liệu sử dụng của bạn.
</Note>