Tài liệu Marketing Insight API

Tài liệu API Marketing Insight

1. Mục đích của API

Marketing Insight API được sử dụng để truy xuất dữ liệu phân tích marketing (insight) theo từng khoảng thời gian, tài khoản quảng cáo, chiến dịch, quảng cáo, nền tảng, hoặc theo các tiêu chí phân tích khác.

API này phù hợp cho:

• Tổng hợp báo cáo marketing

• Phân tích hiệu quả quảng cáo

2. Thông tin API cơ bản

Thuộc tính	Giá trị
Module	Java API
Path	/marketing/insights
Method	POST
Content-Type	application/json
Authorization	Bearer Token

---

3. Cấu trúc Body Request

3.1. Danh sách trường trong Body

Trường	Kiểu dữ liệu	Bắt buộc	Mô tả
since	String	Có	Thời gian bắt đầu, định dạng dd-MM-yyyy
until	String	Có	Thời gian kết thúc, định dạng dd-MM-yyyy
breakdowns	Array[String]	Có	Các tiêu chí phân tích dữ liệu
fields	Array[String]	Không	Các trường dữ liệu muốn lấy, mặc định lấy tất cả (trừ breakdown)
filters	Array[Object]	Không	Điều kiện lọc dữ liệu
page	Number	Không	Trang dữ liệu, mặc định là 1
limit	Number	Không	Số lượng kết quả/trang, tối đa 200, mặc định 20

---

3.2. Trường breakdowns (Bắt buộc)

breakdowns dùng để chia nhỏ dữ liệu theo từng tiêu chí phân tích.

Danh sách giá trị có thể sử dụng:

• traffic_type

• platform

• facebook_page_id

• page_name

• ad_account_id

• ad_account_name

• ad_campaign_id

• ad_campaign_name

• adset_id

• adset_name

• ad_id

• ad_name

• objective

• day

• week

• month

Lưu ý:

• Có thể truyền nhiều giá trị breakdown cùng lúc

• Nên kết hợp breakdown theo thời gian (day, week, month) để dễ làm báo cáo

3.3. Trường fields (Không bắt buộc)

• Xác định chỉ lấy các trường dữ liệu cần thiết

• Nếu không truyền, hệ thống sẽ trả về toàn bộ các trường mặc định (không bao gồm breakdown)

Ví dụ:

"fields": ["impressions", "clicks", "spend"]

4. Cấu trúc Filters (Điều kiện lọc)

4.1. Các trường trong filters

Trường	Kiểu dữ liệu	Bắt buộc	Mô tả
field	String	Có	Tên trường cần lọc
operator	String	Có	Toán tử so sánh
value	String	Có	Giá trị lọc

4.2. Ví dụ Filter

{
  "field": "ad_account_id",
  "operator": "=",
  "value": "123456789"
}

Có thể truyền nhiều điều kiện lọc trong mảng filters.

5. Phân trang dữ liệu

• page: số trang cần lấy (mặc định 1)

6. Ví dụ Request hoàn chỉnh (cURL)

curl --location '{API_URL}/marketing/insights' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Content-Type: application/json' \
--data '{
  "since": "01-01-2026",
  "until": "10-01-2026",
  "breakdowns": ["ad_name", "day"],
  "page": 1,
  "limit": 200,
  "filters": [
    {
      "field": "ad_account_id",
      "operator": "=",
      "value": "123456789"
    }
  ]
}'

7. Lưu ý quan trọng khi sử dụng

• since và until bắt buộc đúng định dạng dd-MM-yyyy

• breakdowns là trường bắt buộc, nếu thiếu API sẽ không trả dữ liệu

• Không nên đặt limit quá lớn nếu không cần thiết để tránh tải dữ liệu nặng

• Khi dùng filter, cần đảm bảo field tồn tại trong hệ thống insight