Chuyển đến nội dung chính

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.

API Fulfillment phơi bày hàng đợi hoàn tất đơn và việc gán nhà cung cấp để các agent tự động hóa và quy trình có thể quản lý trạng thái sản xuất đơn hàng mà không cần can thiệp thủ công. Quyền truy cập đọc cho phép bạn kiểm tra các đơn hàng cần hành động; quyền truy cập ghi cho phép bạn gán nhà cung cấp hàng loạt.

​
GET /api/v2/fulfillment/queue

Liệt kê các đơn hàng hiện đang chờ một hành động hoàn tất đơn. Bạn có thể lọc hàng đợi theo trạng thái, nhà cung cấp hoặc cửa hàng và phân trang qua các tập kết quả lớn. Phạm vi yêu cầu: fulfillment:read

​
Tham số truy vấn

​
status
string
Lọc theo trạng thái hoàn tất đơn. Giá trị được chấp nhận: New, In Production. Bỏ qua để trả về tất cả các mục hàng đợi.
​
supplier_id
string
Lọc theo một ID nhà cung cấp cụ thể.
​
page
integer
mặc định:"1"
Số trang (chỉ mục từ 1).
​
page_size
integer
mặc định:"20"
Số kết quả mỗi trang.

​
Ví dụ

curl -X GET "https://api.sellfern.com/api/v2/fulfillment/queue?status=New&page=1" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "items": [
      {
        "order_id": 1042,
        "status": "New",
        "supplier_id": null,
        "created_at": "2026-05-20T09:14:00Z"
      },
      {
        "order_id": 1043,
        "status": "New",
        "supplier_id": null,
        "created_at": "2026-05-20T11:30:00Z"
      }
    ],
    "total": 28,
    "page": 1,
    "page_size": 20
  },
  "meta": { "request_id": "req_ful001" }
}

​
POST /api/v2/fulfillment/assign

Gán một nhà cung cấp cho một hoặc nhiều đơn hàng để hoàn tất. Sau khi gán thành công, các đơn hàng bị ảnh hưởng chuyển sang hàng đợi sản xuất của nhà cung cấp. Phạm vi yêu cầu: fulfillment:write

​
Tham số truy vấn

​
dry_run
boolean
Khi true, xác thực và xem trước kết quả gán theo từng đơn hàng mà không lưu bất kỳ thay đổi nào. Sử dụng cái này để kiểm tra lỗi trước khi commit.

​
Tiêu đề

​
Idempotency-Key
string
Khóa tùy chọn để thử lại an toàn cùng yêu cầu gán. Nếu bạn gửi cùng một khóa lần thứ hai, API trả về kết quả gốc thay vì thực thi việc gán lại.

​
Tham số body

​
order_ids
integer[]
bắt buộc
Mảng các ID đơn hàng số để gán.
​
supplier_id
string
bắt buộc
ID của nhà cung cấp để gán cho các đơn hàng này.

​
Ví dụ

curl -X POST "https://api.sellfern.com/api/v2/fulfillment/assign" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ids": [1042, 1043],
    "supplier_id": "sup_789"
  }'

{
  "success": true,
  "data": {
    "results": [
      { "order_id": 1042, "status": "ok", "supplier_id": "sup_789" },
      { "order_id": 1043, "status": "ok", "supplier_id": "sup_789" }
    ],
    "counts": { "ok": 2, "error": 0 }
  },
  "meta": { "request_id": "req_ful002" }
}

​
Trạng thái hoàn tất đơn

Các đơn hàng di chuyển qua các trạng thái hoàn tất đơn theo trình tự. Hiểu các chuyển đổi này giúp bạn lọc hàng đợi và kích hoạt đúng hành động.
Trạng tháiÝ nghĩa
Pending CostĐơn hàng đã được nhập nhưng chi phí chưa được gán. Nó không thể được gửi đi sản xuất cho đến khi chi phí được giải quyết.
NewChi phí đã được gán và đơn hàng sẵn sàng để gán nhà cung cấp. Đây là trạng thái hàng đợi chính bạn hành động qua API.
In ProductionĐơn hàng đã được gán cho một nhà cung cấp và sản xuất đã bắt đầu.
ShippedĐơn hàng đã rời nhà cung cấp và thông tin theo dõi có sẵn.
CompleteĐơn hàng đã được giao và vòng đời đã đóng.
Cách chuyển đổi trạng thái hoạt động:
  • Đánh dấu một đơn hàng là “Ready” (giải quyết chi phí của nó) chuyển nó từ Pending Cost sang New.
  • Gọi POST /api/v2/fulfillment/assign chuyển các đơn hàng từ New sang In Production sau khi một nhà cung cấp được gán.
  • Cập nhật trạng thái của một đơn hàng thành Shipped qua PATCH /api/v2/orders/:id/status chuyển nó ra khỏi hàng đợi sản xuất.