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 Orders cung cấp cho bạn quyền truy cập theo chương trình tới các đơn hàng Sellfern của bạn, cho phép tự động hóa quản lý trạng thái, ghi chú và báo cáo. Tất cả các điểm cuối yêu cầu một bearer token hợp lệ; các thao tác ghi bổ sung yêu cầu phạm vi thích hợp trên token.

​
GET /api/v2/orders

Liệt kê đơn hàng với các bộ lọc tùy chọn. Kết quả được phân trang. Phạm vi yêu cầu: orders:read

​
Tham số truy vấn

​
q
string
Tìm kiếm toàn văn trên các trường đơn hàng như số đơn hàng và tên khách hàng.
​
status
string
Lọc theo trạng thái đơn hàng. Giá trị được chấp nhận: New, Pending Cost, In Production, Shipped, Complete, Cancelled.
​
store_id
string
Lọc theo ID cửa hàng.
​
created_after
string
Chỉ trả về các đơn hàng được tạo sau datetime này (ISO 8601, ví dụ 2026-01-01T00:00:00Z).
​
created_before
string
Chỉ trả về các đơn hàng được tạo trước datetime này (ISO 8601).
​
timezone
string
Múi giờ IANA được sử dụng để diễn giải các bộ lọc ngày (ví dụ America/New_York). Mặc định là UTC.
​
supplier_id
string
Lọc theo ID nhà cung cấp.
​
missingSku
boolean
Khi true, chỉ trả về các đơn hàng có dòng mặt hàng với SKU bị thiếu.
​
missingDesign
boolean
Khi true, chỉ trả về các đơn hàng có dòng mặt hàng với tệp thiết kế bị thiếu.
​
sort
string
Biểu thức sắp xếp ở định dạng field:direction (ví dụ created_at:desc).
​
page
integer
mặc định:"1"
Số trang (chỉ mục từ 1).
​
limit
integer
mặc định:"20"
Số kết quả mỗi trang.

​
Ví dụ

curl -X GET "https://api.sellfern.com/api/v2/orders?status=Shipped&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1042,
        "status": "Shipped",
        "store_id": "store_abc",
        "customer_name": "Jane Smith",
        "created_at": "2026-05-01T10:23:00Z"
      }
    ],
    "total": 142,
    "page": 1,
    "limit": 20
  },
  "meta": { "request_id": "req_xyz789" }
}

​
GET /api/v2/orders/:id

Lấy chi tiết đầy đủ cho một đơn hàng, bao gồm các dòng mặt hàng. Phạm vi yêu cầu: orders:read

​
Tham số đường dẫn

​
id
integer
bắt buộc
ID đơn hàng số.

​
Ví dụ

curl -X GET "https://api.sellfern.com/api/v2/orders/1042" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "id": 1042,
    "status": "Shipped",
    "customer_name": "Jane Smith",
    "store_id": "store_abc",
    "items": [
      {
        "sku": "TSHIRT-RED-M",
        "quantity": 2,
        "unit_price": 18.50
      }
    ],
    "total": 37.00,
    "created_at": "2026-05-01T10:23:00Z"
  },
  "meta": { "request_id": "req_xyz790" }
}

​
PATCH /api/v2/orders/:id/status

Cập nhật trạng thái của một đơn hàng duy nhất. Phạm vi yêu cầu: orders:status:write

​
Tham số đường dẫn

​
id
integer
bắt buộc
ID đơn hàng số.

​
Tham số body

​
status
string
bắt buộc
Trạng thái đơn hàng mới. Giá trị được chấp nhận: New, Pending Cost, In Production, Shipped, Complete, Cancelled.

​
Ví dụ

curl -X PATCH "https://api.sellfern.com/api/v2/orders/1042/status" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"status": "Shipped"}'

{
  "success": true,
  "data": {
    "id": 1042,
    "status": "Shipped"
  },
  "meta": { "request_id": "req_xyz791" }
}
Bạn có thể truyền tiêu đề Idempotency-Key để thử lại an toàn yêu cầu này mà không có rủi ro áp dụng thay đổi trạng thái hai lần.

​
POST /api/v2/orders/bulk-status

Cập nhật trạng thái của nhiều đơn hàng trong một lần gọi. Phạm vi yêu cầu: orders:status:write

​
Tham số truy vấn

​
dry_run
boolean
Khi true, xác thực và xem trước kết quả theo từng đơn hàng mà không lưu bất kỳ thay đổi nào.

​
Tham số body

​
updates
object[]
bắt buộc
Mảng các đối tượng cập nhật. Mỗi đối tượng phải bao gồm orderId (integer) và status (string).

​
Ví dụ

curl -X POST "https://api.sellfern.com/api/v2/orders/bulk-status" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "orderId": 1042, "status": "Shipped" },
      { "orderId": 1043, "status": "Shipped" }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      { "orderId": 1042, "status": "ok" },
      { "orderId": 1043, "status": "ok" }
    ],
    "counts": { "ok": 2, "error": 0 }
  },
  "meta": { "request_id": "req_xyz792" }
}

​
POST /api/v2/orders/:id/notes

Thêm một ghi chú vào một đơn hàng. Ghi chú được lưu kèm dấu thời gian và tác giả của token API. Phạm vi yêu cầu: orders:write

​
Tham số đường dẫn

​
id
integer
bắt buộc
ID đơn hàng số.

​
Tham số body

​
content
string
bắt buộc
Nội dung văn bản của ghi chú.

​
Ví dụ

curl -X POST "https://api.sellfern.com/api/v2/orders/1042/notes" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"content": "Customer requested gift wrap."}'

{
  "success": true,
  "data": {
    "id": 88,
    "content": "Customer requested gift wrap.",
    "createdBy": "api-token:my-agent",
    "createdAt": "2026-05-22T14:05:00Z"
  },
  "meta": { "request_id": "req_xyz793" }
}

​
Lỗi phổ biến

Trạng tháiÝ nghĩa
401 UnauthorizedToken bị thiếu hoặc không hợp lệ.
403 missing_scopeToken không có phạm vi yêu cầu cho điểm cuối này.
404 Not FoundKhông có đơn hàng nào tồn tại với ID đã cho, hoặc đơn hàng không thuộc về tổ chức của bạn.