n8n

n8n giao tiếp với MADIAD Hub qua HTTP thuần, không cần cài node đặc biệt nào. Bạn lưu API key một lần dưới dạng credential, sau đó điều khiển Hub bằng node HTTP Request trong bất kỳ workflow nào: đăng khi có dòng mới trong bảng tính, khi có bài RSS mới, theo lịch, hoặc từ ứng dụng của bạn.

Hướng dẫn này giả định bạn đã có API key và ít nhất một profile được kết nối. Nếu chưa, hãy làm Bắt đầu nhanh trước (5 phút).

1. Lưu API key thành credential

Giữ key ngoài file workflow bằng cách lưu nó thành credential dùng lại được.

Trong n8n mở Credentials → New, chọn Header Auth.
Đặt:
- Name là Authorization
- Value là Bearer mdc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Lưu lại với tên ví dụ MADIAD Hub.

Mỗi node HTTP Request bên dưới sẽ chọn credential này ở Authentication → Generic Credential Type → Header Auth.

Tạo một key riêng cho mỗi workflow (đặt tên n8n trong dashboard). Nếu key bị lộ, bạn chỉ cần thu hồi đúng key đó mà không ảnh hưởng phần còn lại.

2. Đăng một bài chỉ có chữ

Thêm node HTTP Request:

Trường	Giá trị
Method	`POST`
URL	`https://api.madiad.com/v1/posts/text`
Authentication	Header Auth → MADIAD Hub
Send Body	Bật, JSON

Body (JSON):

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "platforms": ["facebook", "linkedin", "x"],
  "caption": "Bài viết mới đã lên sóng, đọc ngay trên blog."
}

Bài chỉ có chữ dùng JSON. Ảnh có thể gửi bằng file upload (multipart) hoặc URL ảnh công khai (JSON); video luôn dùng JSON với URL công khai, xem Đăng ảnh hoặc video bên dưới.

3. Chống trùng lặp bằng Idempotency-Key

Nếu n8n chạy lại một node (timeout, nhánh lỗi), bạn không muốn tạo ra bài đăng trùng. Thêm một header có giá trị ổn định cho mỗi item, Hub sẽ coi lần lặp lại cùng key là cùng một yêu cầu. Ở phần Headers, thêm:

Name	Value
`Idempotency-Key`	`={{ $json.id }}`

Dùng một giá trị duy nhất cho mỗi bài định đăng và không đổi khi thử lại chính bài đó. Lựa chọn tốt: một UUID bạn sinh một lần rồi ghi ngược lại vào dòng dữ liệu, hoặc một hash của chính nội dung.

Tuyệt đối không dùng giá trị bị tái sử dụng. Số dòng bảng tính sẽ dịch chuyển khi bạn xoá dòng, còn $itemIndex quay về 0 ở mỗi lần chạy. Cả hai đều khiến nội dung hôm nay mang một key mà bài hôm qua đã chiếm. Khi gặp key đã dùng, Hub trả về kết quả cũ và không đăng gì cả, nên một key hỏng trông y hệt một bài đăng thành công. Hãy để ý header Idempotent-Replayed: true, và xem Idempotency.

4. Đăng ảnh hoặc video

Endpoint là https://api.madiad.com/v1/posts/photos cho ảnh và https://api.madiad.com/v1/posts/video cho một video. Ảnh, tải file lên: chọn Send Body → Form-Data Multipart rồi thêm từng trường thành từng entry riêng. Lặp lại platforms[] một lần cho mỗi nền tảng, và gửi ảnh dưới dạng trường binary:

Tên trường	Kiểu	Giá trị
`profile_id`	Text	`prof_…`
`platforms[]`	Text	`instagram`
`platforms[]`	Text	`facebook`
`caption`	Text	`Ra mắt hương vị mới hôm nay`
`photos[]`	Binary	binary property từ node trước (ví dụ `data`)

Ảnh, dùng URL công khai: nếu ảnh đã có link https:// công khai, bỏ qua bước xử lý file luôn. Chọn Send Body → JSON và truyền link vào photo_urls[], đây là cách đơn giản nhất cho n8n vì không cần node binary nào:

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "platforms": ["instagram", "facebook"],
  "caption": "Ra mắt hương vị mới hôm nay",
  "photo_urls": ["https://cdn.example.com/launch.jpg"]
}

Video: luôn dùng JSON, không dùng multipart. Chọn Send Body → JSON và truyền một video_url công khai:

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "platforms": ["facebook", "instagram"],
  "caption": "Ra mắt hương vị mới hôm nay",
  "video_url": "https://cdn.example.com/launch.mp4"
}

Cần tải file ảnh lên thay vì dùng URL? Đặt một node HTTP Request (Response Format → File) hoặc node Read/Download trước node này, rồi tham chiếu binary property của nó trong photos[].

5. Xử lý phản hồi bất đồng bộ

Bài chỉ có chữ hoặc bài ảnh tới các nền tảng nhanh thường trả về "status": "completed" kèm results theo từng nền tảng. Video là bất đồng bộ, nó trả về "status": "processing" và một request_id. Có hai cách lấy kết quả cuối: Poll là thêm node Wait, rồi node HTTP Request:

GET https://api.madiad.com/v1/posts/status?request_id={{ $json.request_id }}

Lặp cho tới khi status là completed, partial, hoặc failed. Webhook (khuyến nghị) là nhận thông báo đẩy thay vì poll. Thêm node Webhook trong n8n, sao chép Production URL của nó, và đăng ký trong dashboard tại hub.madiad.com/dashboard/webhooks cho sự kiện post.completed. Hub ký mọi lần gửi bằng HMAC-SHA256, hãy xác thực chữ ký ở node kế tiếp. Xem Webhooks.

6. Đọc kết quả theo từng nền tảng

Một bài đăng có thể thành công một phần, hãy kiểm tra results theo từng nền tảng thay vì chỉ nhìn status tổng:

{
  "status": "partial",
  "results": {
    "facebook": { "success": true,  "url": "https://facebook.com/12345/posts/67890" },
    "x":        { "success": false, "error": "Upload rejected by the platform" }
  },
  "failed_platforms": ["x"]
}

Rẽ nhánh theo success bằng node IF để chuyển các lỗi sang một cảnh báo Slack hoặc email.

7. Xử lý lỗi mà không retry vô tận

Retry On Fail của n8n coi mọi phản hồi không phải 2xx là đáng thử lại, và điều đó sai với phần lớn lỗi ở đây. Hãy rẽ nhánh theo mã trạng thái HTTP, đừng dựa vào câu chữ của thông báo:

Trạng thái	Nghĩa là gì	Workflow nên làm gì
`400`	Nội dung hoặc request sai (caption vượt giới hạn nền tảng, URL hỏng).	Dừng lại. Gửi lại y nguyên thì không thể thành công, hãy đẩy sang nhánh lỗi.
`409 platform_not_connected`	Profile chưa có tài khoản cho nền tảng đó.	Báo cho người thật. Nếu cứ sau mỗi bài đăng được là lại gặp, nền tảng đang hạn chế tài khoản và kết nối lại không giải quyết được.
`409 idempotency_in_progress`	Lần gửi trước với cùng key vẫn đang chạy.	Đợi vài giây rồi thử lại với đúng key cũ, bạn sẽ nhận kết quả của lần gửi đầu.
`429`	Bị giới hạn tốc độ.	Chờ đủ số giây trong `Retry-After` rồi thử lại.
`5xx`	Lỗi phía Hub hoặc phía backend xuất bản.	Thử lại kèm backoff, và luôn gửi `Idempotency-Key` để lần retry không tạo bài trùng.

Trong node HTTP Request, hãy bật Never Error (hoặc đặt On Error thành Continue using error output) để đọc được $json.error.code và rẽ nhánh theo nó, thay vì để node làm hỏng cả lượt chạy.

Trước ngày 07/08/2026, mọi lỗi từ backend xuất bản đều trả về 502, nên một workflow bật Retry On Fail sẽ retry mãi những bài không bao giờ đăng được. Nếu workflow của bạn đang có vòng retry dựa trên hành vi cũ đó, hãy thay bằng bảng ở trên.

Ví dụ workflow: Google Sheets → mọi nền tảng

Một mẫu phổ biến là lịch nội dung trong Google Sheets, tự đăng khi một dòng được đánh dấu sẵn sàng:

Schedule Trigger (mỗi 15 phút) → Google Sheets (lấy các dòng có status = ready).
HTTP Request → POST /v1/posts/photos với profile_id, platforms[], caption lấy từ dòng đó, Idempotency-Key = một UUID lưu sẵn trên dòng đó (không dùng số dòng, xem cảnh báo ở trên).
IF theo phản hồi → nếu thành công, Google Sheets cập nhật dòng thành published; nếu lỗi, gửi cảnh báo.

Bước tiếp theo

Tuỳ chọn theo nền tảng

Ghi đè caption, tiêu đề và tuỳ chọn cho từng nền tảng.

Lên lịch

Để Hub tự đăng vào thời điểm tương lai.

Idempotency

Chạy lại an toàn từ mọi automation.

Webhooks

Nhận callback có chữ ký khi bài đăng hoàn tất.

Bắt đầu

Khái niệm

Tích hợp

1. Lưu API key thành credential

2. Đăng một bài chỉ có chữ

3. Chống trùng lặp bằng Idempotency-Key

4. Đăng ảnh hoặc video

5. Xử lý phản hồi bất đồng bộ

6. Đọc kết quả theo từng nền tảng

7. Xử lý lỗi mà không retry vô tận

Ví dụ workflow: Google Sheets → mọi nền tảng

Bước tiếp theo

Tuỳ chọn theo nền tảng

Lên lịch

Idempotency

Webhooks

​1. Lưu API key thành credential

​2. Đăng một bài chỉ có chữ

​3. Chống trùng lặp bằng Idempotency-Key

​4. Đăng ảnh hoặc video

​5. Xử lý phản hồi bất đồng bộ

​6. Đọc kết quả theo từng nền tảng

​7. Xử lý lỗi mà không retry vô tận

​Ví dụ workflow: Google Sheets → mọi nền tảng

​Bước tiếp theo

Tuỳ chọn theo nền tảng

Lên lịch

Idempotency

Webhooks

1. Lưu API key thành credential

2. Đăng một bài chỉ có chữ

3. Chống trùng lặp bằng Idempotency-Key

4. Đăng ảnh hoặc video

5. Xử lý phản hồi bất đồng bộ

6. Đọc kết quả theo từng nền tảng

7. Xử lý lỗi mà không retry vô tận

Ví dụ workflow: Google Sheets → mọi nền tảng

Bước tiếp theo