Endpoint TikTok Ads¶

Base URL:

https://api.logidata.vn/v1/tiktok-ads{đường dẫn TikTok}

Đường dẫn, tham số và response giống hệt TikTok Business API v1.3. Chuyển từ gọi thẳng sang gọi qua Logidata chỉ cần đổi hai thứ:

	Gọi thẳng TikTok	Qua Logidata
Base URL	`https://business-api.tiktok.com/open_api`	`https://api.logidata.vn/v1/tiktok-ads`
Xác thực	`Access-Token: <token của bạn>`	`X-API-Key` + `X-Account-Id`

Danh sách được phép¶

Allowlist mặc định chỉ đọc. Mọi đường dẫn ghi (/create/, /update/, /delete/, /status/update/) bị chặn ngay tại Logidata — request không bao giờ chạm tới TikTok.

Endpoint	Dùng để
`GET /v1.3/oauth2/advertiser/get/`	Liệt kê advertiser account mà kết nối nhìn thấy
`GET /v1.3/advertiser/info/`	Thông tin chi tiết một/nhiều advertiser
`GET /v1.3/report/integrated/get/`	Báo cáo hiệu quả — endpoint dùng nhiều nhất
`GET /v1.3/campaign/get/`	Danh sách campaign
`GET /v1.3/adgroup/get/`	Danh sách ad group
`GET /v1.3/ad/get/`	Danh sách quảng cáo
`GET /v1.3/gmv_max/store/list/`	Danh sách store GMV Max
`GET /v1.3/gmv_max/report/get/`	Báo cáo GMV Max

Gọi endpoint ngoài danh sách → 403 path_not_allowed. Cần thêm endpoint? Báo Logidata — việc mở thêm chỉ tốn một dòng cấu hình, nhưng chúng tôi cố ý không mở sẵn đường ghi.

Tham số nhạy cảm bị loại bỏ

app_id, secret, access_token bạn gửi lên luôn bị bỏ và thay bằng giá trị của Logidata. Bạn không cần (và không thể) tự truyền chúng.

`GET /v1.3/oauth2/advertiser/get/`¶

Không có tham số. Trả về các advertiser account thuộc kết nối.

curl -H "X-API-Key: $KEY" -H "X-Account-Id: $ACC" \
  "https://api.logidata.vn/v1/tiktok-ads/v1.3/oauth2/advertiser/get/"

{
  "code": 0, "message": "OK",
  "data": { "list": [
    { "advertiser_id": "7001234567890", "advertiser_name": "Acme VN" }
  ]}
}

`GET /v1.3/report/integrated/get/`¶

Endpoint chính để kéo số liệu.

Tham số	Bắt buộc	Ghi chú
`advertiser_id`	✓	Lấy từ `oauth2/advertiser/get/`
`report_type`	✓	`BASIC`, `AUDIENCE`, `PLAYABLE_MATERIAL`
`data_level`	✓ với `BASIC`	`AUCTION_AD`, `AUCTION_ADGROUP`, `AUCTION_CAMPAIGN`, `AUCTION_ADVERTISER`
`dimensions`	✓	Mảng JSON, VD `["campaign_id","stat_time_day"]`
`metrics`		Mảng JSON, VD `["spend","impressions","clicks"]`
`start_date` / `end_date`	✓	`YYYY-MM-DD`
`page` / `page_size`		Mặc định 1 / 10, tối đa 1000

curl -G "https://api.logidata.vn/v1/tiktok-ads/v1.3/report/integrated/get/" \
  -H "X-API-Key: $KEY" -H "X-Account-Id: $ACC" \
  --data-urlencode "advertiser_id=7001234567890" \
  --data-urlencode "report_type=BASIC" \
  --data-urlencode "data_level=AUCTION_CAMPAIGN" \
  --data-urlencode 'dimensions=["campaign_id","stat_time_day"]' \
  --data-urlencode 'metrics=["spend","impressions","clicks","conversion"]' \
  --data-urlencode "start_date=2026-08-01" \
  --data-urlencode "end_date=2026-08-07" \
  --data-urlencode "page_size=1000"

{
  "code": 0, "message": "OK",
  "data": {
    "list": [{
      "dimensions": { "campaign_id": "1790000000000", "stat_time_day": "2026-08-01 00:00:00" },
      "metrics": { "spend": "1250000.00", "impressions": "84213", "clicks": "1902", "conversion": "37" }
    }],
    "page_info": { "page": 1, "page_size": 1000, "total_number": 1, "total_page": 1 }
  }
}

dimensions và metrics là chuỗi JSON, không phải danh sách lặp

Phải là dimensions=["campaign_id"], không phải dimensions=campaign_id&dimensions=stat_time_day. Với httpx/requests trong Python, dùng json.dumps([...]).

Phân trang

Đọc data.page_info.total_page rồi lặp page từ 1 tới hết. Dùng page_size=1000 để giảm số request — hạn mức tính theo số request, không theo số dòng dữ liệu.

`GET /v1.3/campaign/get/`, `/adgroup/get/`, `/ad/get/`¶

Cùng khuôn: bắt buộc advertiser_id, tuỳ chọn filtering (chuỗi JSON), page, page_size.

curl -G "https://api.logidata.vn/v1/tiktok-ads/v1.3/campaign/get/" \
  -H "X-API-Key: $KEY" -H "X-Account-Id: $ACC" \
  --data-urlencode "advertiser_id=7001234567890" \
  --data-urlencode 'filtering={"primary_status":"STATUS_DELIVERY_OK"}' \
  --data-urlencode "page_size=100"

Dùng các endpoint này để lấy tên campaign/adgroup/ad, rồi ghép với số liệu từ report/integrated/get/ (báo cáo chỉ trả về ID).

`GET /v1.3/advertiser/info/`¶

curl -G "https://api.logidata.vn/v1/tiktok-ads/v1.3/advertiser/info/" \
  -H "X-API-Key: $KEY" -H "X-Account-Id: $ACC" \
  --data-urlencode 'advertiser_ids=["7001234567890"]'

Trả về tên, đơn vị tiền tệ, múi giờ, trạng thái tài khoản. Cần đơn vị tiền tệ và múi giờ trước khi diễn giải số liệu spend.

GMV Max¶

GET /v1.3/gmv_max/store/list/ liệt kê store; GET /v1.3/gmv_max/report/get/ trả báo cáo. Tham số theo đúng tài liệu TikTok.

Endpoint TikTok Ads¶

Danh sách được phép¶

GET /v1.3/oauth2/advertiser/get/¶

GET /v1.3/report/integrated/get/¶

GET /v1.3/campaign/get/, /adgroup/get/, /ad/get/¶

GET /v1.3/advertiser/info/¶