Facebook Reporting Dashboard

Real-time web analytics and advertising performance.

07/04/2026
📖 API Documentation
Tài liệu hướng dẫn sử dụng các Endpoint API của hệ thống. Dành cho việc kết nối Frontend Dashboard hoặc các công cụ bên thứ ba.

1. API Báo Cáo Hiệu Suất Quảng Cáo Từ Database

Endpoint: https://ezhr.io.vn/hanxen/api/report_ads_daily_performance.php

Mô tả: Trả về dữ liệu hiệu suất chạy quảng cáo lấy từ Database đã được đồng bộ trước đó. Thích hợp để xem báo cáo thống kê lịch sử và đã được tính toán.

Tham số (Query Parameters):
  • account_id (Bắt buộc): ID tài khoản quảng cáo (Ví dụ: 1095292754969625)
  • date (Không bắt buộc): Ngày muốn lấy dữ liệu. Hệ thống quản lý linh hoạt:
    • Theo ngày tĩnh: YYYY-MM-DD (Ví dụ: 2026-03-29)
    • Theo Preset: Có thể gọi các mốc thời gian động như last2, last7, last14, last30, mtd, prev30, week, last_week, month, last_month, quarter, year.
Ví dụ Request:
GET https://ezhr.io.vn/hanxen/api/report_ads_daily_performance.php?account_id=1095292754969625&date=last2
Cấu trúc Response Mẫu (JSON):
    {
        "success": true,
        "message": "Xử lý API thành công",
        "filters": {
            "account_id": "1095292754969625",
            "date": "2026-03-30",
            "start_date": "2026-03-30",
            "end_date": "2026-03-30"
        },
        "total": 4,
        "data": [
            {
                "id": 12,
                "report_date": "2026-03-30",
                "campaign_id": "120239452756330018",
                "account_id": "1095292754969625",
                "campaign_name": "27032026+PURCHASE+VN>28+LEDPIANO+LEDPLAY",
                "impressions": 4305,
                "reach": 3467,
                "clicks": 70,
                "ctr": "1.6260",
                "inline_link_click_ctr": "0.8827",
                "spend": "307529.00",
                "cpm": "71435.31",
                "cpc": "4393.27",
                "conversions": 2,
                "conversion_value": "1980000.00",
                "cost_per_conversion": "153764.50",
                "results": 0,
                "cost_per_result": "0.00",
                "frequency": "1.24",
                "landing_page_view": 44,
                "link_clicks": 38,
                "cost_per_link_click": "8092.87",
                "cost_per_landing_page_view": "13978.59",
                "roas": "6.44",
                "quality_ranking": "UNKNOWN",
                "engagement_rate_ranking": "UNKNOWN",
                "conversion_rate_ranking": "UNKNOWN",
                "created_at": "2026-03-31 11:59:06",
                "updated_at": "2026-03-31 23:59:06"
            }
        ]
    }

2. API Báo Cáo Hiệu Suất Quảng Cáo Thời Gian Thực (Realtime)

Endpoint: https://ezhr.io.vn/hanxen/api/report_ads_realtime.php

Mô tả: Lấy dữ liệu tức thì trực tiếp từ Facebook Business Manager (BM) theo thời gian thực (realtime) dựa trên Token. Dữ liệu trả về sẽ tương đồng cấu trúc bảng với API lịch sử bên trên để Frontend dễ dàng tương thích.

Tham số (Query Parameters):
  • account_id (Bắt buộc): ID tài khoản quảng cáo. Hệ thống tự động tra cứu Page ID và Token tương ứng dựa vào ID này từ tệp tin cấu hình config.php
  • date (Không bắt buộc): Ngày hoặc Preset (giống hoàn toàn API Daily ở trên). Mặc định nếu không cung cấp là today.
  • level (Không bắt buộc): Cấp độ hiển thị dữ liệu của chiến dịch. Mặc định là campaign. (Có thể là adset, ad)
Ví dụ Request:
GET https://ezhr.io.vn/hanxen/api/report_ads_realtime.php?account_id=1095292754969625&date=today
Cấu trúc Response Mẫu (JSON):
    {
        "success": true,
        "message": "Lấy dữ liệu thời gian thực từ Facebook API thành công",
        "filters": {
            "account_id": "1095292754969625",
            "date": "today",
            "start_date": "2026-04-03",
            "end_date": "2026-04-03",
            "level": "campaign"
        },
        "total": 1,
        "data": [
            {
            "report_date": "2026-04-03",
            "campaign_id": "120239095413300018",
            "account_id": "1095292754969625",
            "campaign_name": "Gộp|11032026+PURCHASES...",
            "impressions": 2013,
            "reach": 1818,
            "clicks": 34,
            "ctr": 1.69,
            "inline_link_click_ctr": 0.65,
            "spend": 194972,
            "cpm": 96856,
            "cpc": 5734,
            "conversions": 0,
            "conversion_value": 0,
            "cost_per_conversion": 0,
            "results": 0,
            "cost_per_result": 0,
            "frequency": 1.107,
            "roas": 0
            }
        ]
    }