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 Analytics cung cấp quyền truy cập theo chương trình tới cùng các chỉ số tài chính được hiển thị trong bảng điều khiển Sellfern Analytics, bao gồm doanh thu, COGS, biên và số đơn hàng. Sử dụng nó để xây dựng tự động hóa báo cáo, đưa dữ liệu vào các công cụ BI bên ngoài hoặc cung cấp tóm tắt do agent điều khiển. Tất cả các điểm cuối phân tích yêu cầu phạm vi analytics:read khi được gọi bằng token API.

​
GET /api/v2/analytics/summary

Lấy tóm tắt doanh thu và lợi nhuận tổng hợp cho một khoảng thời gian. Điểm cuối này trả về một phản hồi có hình dạng cố định mà các script và agent có thể phân tích đáng tin cậy. Phạm vi yêu cầu: analytics:read

​
Tham số truy vấn

​
period
string
mặc định:"last_30_days"
Một khoảng thời gian cài sẵn. Giá trị được chấp nhận: last_7_days, last_30_days, mtd (từ đầu tháng), ytd (từ đầu năm).
​
start_date
string
Bắt đầu của một khoảng ngày tùy chỉnh (ISO 8601, ví dụ 2026-01-01). Sử dụng start_date và end_date cùng nhau như một thay thế cho period.
​
end_date
string
Kết thúc của một khoảng ngày tùy chỉnh (ISO 8601, ví dụ 2026-01-31).
​
store_id
integer
Lọc kết quả theo một cửa hàng cụ thể theo ID số của nó.
​
timezone
string
mặc định:"UTC"
Chuỗi múi giờ IANA được sử dụng để diễn giải ranh giới ngày (ví dụ America/New_York).

​
Ví dụ

curl -X GET "https://api.sellfern.com/api/v2/analytics/summary?period=last_7_days" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "period": "last_7_days",
    "start_date": "2026-04-19",
    "end_date": "2026-04-26",
    "revenue": 12450.00,
    "order_count": 87,
    "cogs": 6225.00,
    "gross_profit": 6225.00,
    "margin_pct": 50.0
  },
  "meta": { "request_id": "req_abc123" }
}

​
Các trường phản hồi

​
period
string
Nhãn kỳ được trả về (khớp với tham số period, hoặc custom cho các yêu cầu khoảng ngày).
​
start_date
string
Ngày bắt đầu của cửa sổ báo cáo (ISO 8601).
​
end_date
string
Ngày kết thúc của cửa sổ báo cáo (ISO 8601).
​
revenue
number
Tổng doanh thu gộp cho kỳ.
​
order_count
integer
Số lượng đơn hàng được bao gồm trong kỳ.
​
cogs
number
Tổng giá vốn hàng bán cho kỳ.
​
gross_profit
number
Lợi nhuận gộp (doanh thu trừ COGS).
​
margin_pct
number
Biên gộp dưới dạng phần trăm (gross_profit / revenue × 100).
Điểm cuối tóm tắt chỉ phản ánh COGS sản phẩm. Các chi phí vận hành như phí Etsy, chi tiêu quảng cáo và chi phí chung khác được theo dõi riêng trong giao diện Sellfern không được bao gồm trong cogs hoặc gross_profit trừ khi chúng đã được gán làm chi phí cấp đơn hàng.

​
GET /api/v2/analytics/by-store

Lấy phân tích được phân tách theo từng cửa hàng riêng lẻ. Trả về một mảng phẳng trong đó mỗi mục đại diện cho các chỉ số của một cửa hàng cho kỳ được yêu cầu. Phạm vi yêu cầu: analytics:read

​
Tham số truy vấn

​
period
string
mặc định:"last_30_days"
Một khoảng thời gian cài sẵn. Giá trị được chấp nhận: last_7_days, last_30_days, mtd, ytd.
​
timezone
string
mặc định:"UTC"
Chuỗi múi giờ IANA được sử dụng để diễn giải ranh giới ngày (ví dụ America/Chicago).

​
Ví dụ

curl -X GET "https://api.sellfern.com/api/v2/analytics/by-store?period=last_30_days" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": [
    {
      "storeName": "Sunrise Prints",
      "revenue": 8200.00,
      "orders": 54,
      "profit": 3100.00
    },
    {
      "storeName": "Pine & Oak Goods",
      "revenue": 4250.00,
      "orders": 33,
      "profit": 1540.00
    }
  ],
  "meta": { "request_id": "req_abc456" }
}