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

# Tích hợp n8n

> Xây dựng các workflow n8n gọi tới API V1 công khai của Sellfern với khóa API có phạm vi.

Sử dụng n8n để tự động hóa các quy trình Sellfern từ các tác vụ theo lịch, webhook và node HTTP Request. Trang này giữ thiết lập an toàn cho V1: dùng khóa API có phạm vi, xác nhận endpoint trong Tham chiếu API và tránh các giả định từ ví dụ workflow cũ.

## Yêu cầu trước

* Một instance n8n, dù tự host hay n8n Cloud
* Một khóa API Sellfern có phạm vi tối thiểu cần thiết cho workflow
* Bất kỳ thông tin đăng nhập đích nào workflow cần, ví dụ webhook tin nhắn nhóm

## Tạo credential Sellfern

Trong n8n, tạo credential Header Auth cho Sellfern.

* **Tên header:** `x-api-key`
* **Giá trị header:** khóa API Sellfern của bạn được lưu trong credential của n8n

Chỉ sử dụng credential này từ workflow n8n phía server. Không dán khóa API vào prompt, log, tệp workflow công khai được xuất ra, hoặc mã trình duyệt.

## Thêm node HTTP Request

Cấu hình một node HTTP Request để gọi một endpoint từ Tham chiếu API V1.

* **Method:** chọn method được hiển thị trong `/api-reference`
* **URL:** kết hợp `https://api.sellfern.com` với đường dẫn công khai được tài liệu
* **Authentication:** credential Header Auth dùng `x-api-key`
* **Query/body:** khớp với các tham số yêu cầu và schema hiển thị trong Tham chiếu API

Nếu một template trực tiếp hoặc ví dụ cũ đề cập đến endpoint không có trong `/api-reference`, đừng dùng nó cho tích hợp công khai. Hãy yêu cầu người dùng xác nhận sự khả dụng của endpoint trong Tham chiếu API trước.

## Ghi và retry

Đối với các endpoint ghi công khai, hãy thêm header `Idempotency-Key`. Sử dụng lại cùng giá trị khi retry cùng một thao tác logic sau khi hết thời gian chờ hoặc lỗi server không chắc chắn.

Tạo khóa idempotency mới cho thao tác khác.

## Xử lý các lỗi phổ biến

| Phản hồi                   | Cần làm gì                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| `401 unauthorized`         | Xác nhận workflow đang gửi khóa API Sellfern qua header `x-api-key`.                               |
| `403 missing_scope`        | Yêu cầu người dùng cung cấp khóa API có phạm vi bổ sung tối thiểu mà node yêu cầu.                 |
| `404 not_found`            | Đừng suy luận về truy cập giữa các tổ chức. Xác nhận tài nguyên thuộc về tổ chức gắn với khóa API. |
| `422 idempotency_conflict` | Chỉ tạo khóa idempotency mới nếu đây là thao tác logic khác.                                       |
| `429 rate_limited`         | Lùi lại và retry sau theo chính sách retry của workflow.                                           |

## Mẫu workflow được khuyến nghị

1. Bắt đầu với chỉ mục tài liệu Sellfern tại `https://docs.sellfern.com/llms.txt`.
2. Đọc hướng dẫn nhà phát triển liên quan về xác thực, phạm vi, lỗi và idempotency.
3. Xác nhận endpoint trong `/api-reference`.
4. Xây node HTTP Request n8n với credential `x-api-key` có phạm vi.
5. Kiểm thử workflow thủ công trước khi kích hoạt lịch trình hoặc trigger.