---
name: madiad-hub
description: >-
  Đăng bài và quản lý nội dung trên 22 kênh mạng xã hội qua MADIAD Hub API.
  Dùng khi người dùng muốn đăng bài, lên lịch, tra trạng thái bài đã gửi, đọc số liệu,
  trả lời bình luận hoặc tin nhắn, hay kiểm tra hạn mức gói.
  Cần biến môi trường MADIAD_HUB_API_KEY.
---

# MADIAD Hub

Một API để đăng lên 22 kênh. Bạn gọi một lần, Hub gửi tới từng kênh theo đúng định
dạng mỗi nền tảng chấp nhận.

## Trước khi gọi bất cứ thứ gì

1. Đọc khoá từ biến môi trường `MADIAD_HUB_API_KEY`. **Không bao giờ in khoá ra, không viết nó
   vào file, không đưa nó vào ví dụ.** Nếu biến chưa có thì dừng và bảo người dùng đặt nó.
2. Xác định `profile_id` bằng `GET /v1/profiles`. Một tài khoản có thể có nhiều hồ sơ,
   mỗi hồ sơ là một thương hiệu hoặc một khách hàng. Đừng đoán.
3. Kiểm hạn mức bằng `GET /v1/usage` nếu sắp gửi nhiều bài.

## Ba điều làm sai thường xuyên nhất

**Đọc `success: false`, không đọc "có trường success hay không".** Phản hồi thiếu thông tin
thành công KHÔNG phải là thất bại. Rất nhiều kênh nhận bài rồi mới xử lý.

**Một `Idempotency-Key` mới cho mỗi bài, sinh TRƯỚC khi gọi.** Gửi lại một khoá đã hoàn tất thì
API trả về kết quả của lần trước và không đăng gì thêm. Đừng lấy số dòng hay chỉ số vòng lặp làm
khoá: chạy lại là trùng.

**Trang được ghim thắng `facebook_page_id` bạn gửi.** Nếu hồ sơ đã ghim một Trang, mọi bài của hồ
sơ đó đi vào Trang ấy. Kiểm bằng `GET /v1/connections/status` trước khi hứa với người
dùng bài sẽ lên đâu.

## Việc hay làm

Đăng một bài chữ:

```bash
curl -sS -X POST https://api.madiad.com/v1/posts/text \
  -H "Authorization: Bearer $MADIAD_HUB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F profile_id=<id> \
  -F 'platforms[]=facebook' -F 'platforms[]=linkedin' \
  -F title='Nội dung bài đăng'
```

Đăng ảnh dùng `/v1/posts/photos` với `photo_urls[]`; video dùng
`/v1/posts/video` với `video_url`. Link phải là `https://` công khai.

Tra lại bài đã gửi: `GET /v1/posts/status`. Danh sách bài đã đăng:
`GET /v1/posts/history`.

Lịch đăng: `GET /v1/schedule`, huỷ bằng `DELETE /v1/schedule/:job_id`,
dời giờ bằng `PATCH /v1/schedule/:job_id`.

Chi tiết từng nhóm endpoint: `reference/api.md`. Danh sách kênh và loại bài mỗi kênh nhận:
`reference/channels.md`.

## Đừng làm

- Đừng in, log, hay ghi API key vào bất cứ đâu.
- Đừng đăng thật khi người dùng chỉ hỏi thử. Đăng bài là việc **không lùi được** ở phía nền tảng.
  Hỏi lại trước lần gọi đăng đầu tiên trong một phiên.
- Đừng bịa `profile_id`, tên kênh, hay endpoint. Kênh hợp lệ nằm ở `reference/channels.md`,
  endpoint hợp lệ nằm ở `reference/api.md`.
- Đừng cắt tiêu đề cho vừa giới hạn rồi gửi. Viết lại cho đúng độ dài; cắt giữa chừng ra chữ cụt.