> ## 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.

# Bắt đầu nhanh

> Đăng bài đầu tiên lên nhiều nền tảng trong vòng chưa đầy năm phút.

Hướng dẫn này đưa bạn từ tài khoản mới tạo đến bài đăng trực tiếp trên Instagram và Facebook.

## 1. Lấy API key

Đăng nhập vào [hub.madiad.com](https://hub.madiad.com), mở **API Keys** và tạo một key mới. Key chỉ hiển thị một lần, hãy sao chép ngay lập tức.

```bash theme={null}
export MADIAD_API_KEY="mdc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

<Warning>
  Bảo mật API key như mật khẩu. Không commit vào git hoặc để lộ trong code phía client.
</Warning>

## 2. Kết nối một Profile

Một **Profile** đại diện cho một thương hiệu, khách hàng hoặc tài khoản con mà bạn đăng bài thay mặt. Tạo Profile và kết nối các nền tảng mạng xã hội bạn muốn đăng lên.

```bash theme={null}
curl -X POST https://api.madiad.com/v1/connections/start \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "friendly_name": "Acme Coffee" }'
```

Response:

```json theme={null}
{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "friendly_name": "Acme Coffee",
  "access_url": "https://connect.madiad.com/o/abc123def456",
  "expires_in": "48h"
}
```

Mở `access_url` trong trình duyệt và đăng nhập vào từng nền tảng bạn muốn đăng lên (Instagram, Facebook, TikTok, v.v.). Các kết nối sẽ được duy trì cho đến khi bị thu hồi.

## 3. Đăng lên nhiều nền tảng

Gửi một request duy nhất, MADIAD Hub sẽ phân phối đến từng nền tảng.

```bash theme={null}
curl -X POST https://api.madiad.com/v1/posts/photos \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Idempotency-Key: launch-2026-05-31-001" \
  -F "profile_id=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -F "platforms[]=instagram" \
  -F "platforms[]=facebook" \
  -F "caption=New blend dropping today" \
  -F "photos[]=@./launch.jpg"
```

Response:

```json theme={null}
{
  "status": "completed",
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "platforms": ["instagram", "facebook"],
  "request_id": null,
  "job_id": null,
  "results": {
    "instagram": { "success": true, "publish_id": "17912345678901234", "url": "https://instagram.com/p/abc123" },
    "facebook":  { "success": true, "publish_id": "12345_67890", "url": "https://facebook.com/12345/posts/67890" }
  }
}
```

Video (hay bất kỳ lần tải lên bất đồng bộ nào) sẽ trả về `"status": "processing"` kèm `request_id` để bạn kiểm tra sau. Xem [Bài đăng](/vi/concepts/posts) để biết đầy đủ các giá trị status.

## 4. (Tùy chọn) Lên lịch đăng bài

Thay thế thời điểm đăng ngay bằng một mốc thời gian trong tương lai.

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

## 5. (Tùy chọn) Đăng ký webhook

Nhận thông báo khi một lần tải lên hoàn thành hoặc khi kết nối thay đổi, thay vì phải kiểm tra định kỳ. Tạo endpoint trong dashboard tại [hub.madiad.com/dashboard/webhooks](https://hub.madiad.com/dashboard/webhooks): đặt URL nhận sự kiện và chọn loại sự kiện (`post.completed`, `connection.connected`, `connection.disconnected`, `connection.reauth_required`).

Hub ký mọi callback bằng HMAC-SHA256. Xem [Webhooks](/vi/concepts/webhooks) để biết cách xác minh.

## Bước tiếp theo

<CardGroup cols={2}>
  <Card title="Mô hình Profiles" icon="users" href="/vi/concepts/profiles">
    Cách các Profiles hoạt động qua nhiều thương hiệu và khách hàng.
  </Card>

  <Card title="Trường theo nền tảng" icon="sliders" href="/vi/concepts/posts">
    Ghi đè caption, thumbnail và chế độ hiển thị cho từng nền tảng.
  </Card>

  <Card title="Lên lịch" icon="calendar" href="/vi/concepts/scheduling">
    Thời điểm cụ thể so với các khung giờ trong hàng đợi lặp lại.
  </Card>

  <Card title="Idempotency" icon="shield-check" href="/vi/concepts/idempotency">
    Thực hiện retry an toàn từ bất kỳ client nào.
  </Card>
</CardGroup>