📊 Analytics / Thống kê API

🧭 Giới thiệu

API Analytics cung cấp khả năng theo dõi và thống kê chi tiết về các hoạt động tích hợp giữa đối tác (Partner) và hệ thống Pay2S.
Qua đó, bạn có thể giám sát lưu lượng gọi API, thời gian phản hồi trung bình, tỷ lệ thành công/thất bại, và theo dõi hiệu năng dịch vụ.

---

🔐 Header chung

Authorization: Bearer <token>
Content-Type: application/json

Dùng Bearer Token lấy từ POST /v1/auth/authorize theo hướng dẫn xác thực. Kiểm tra thời hạn qua expires_in trong phản hồi cấp token.

Base URL: https://api-partner.pay2s.vn

---

1️⃣ Thống kê tổng quan API calls

GET /v1/metrics/calls

Trả về thông tin thống kê số lượng cuộc gọi API của đối tác theo ngày.

Phản hồi mẫu

{
  "status": true,
  "data": {
    "total_calls": 142,
    "success_calls": 136,
    "error_calls": 6,
    "average_response_ms": 215,
    "last_updated": "2025-10-14T13:20:00+07:00"
  }
}

Giải thích

Trường	Ý nghĩa
total_calls	Tổng số lần gọi API
success_calls	Số lần phản hồi thành công (HTTP 200)
error_calls	Số lần lỗi (HTTP 4xx/5xx)
average_response_ms	Thời gian phản hồi trung bình (ms)
last_updated	Thời điểm cập nhật gần nhất

---

2️⃣ Biểu đồ chi tiết theo endpoint

GET /v1/metrics/endpoints

Dùng để xem chi tiết từng endpoint API, giúp bạn nhận biết các điểm nghẽn hiệu năng hoặc tần suất sử dụng cao.

Phản hồi mẫu

{
  "status": true,
  "data": [
    {
      "endpoint": "/v1/banks",
      "method": "GET",
      "calls": 85,
      "success": 82,
      "failed": 3,
      "average_ms": 130
    },
    {
      "endpoint": "/v1/webhooks",
      "method": "POST",
      "calls": 15,
      "success": 14,
      "failed": 1,
      "average_ms": 210
    }
  ]
}

Ý nghĩa

Trường	Mô tả
endpoint	Đường dẫn API
method	Loại HTTP method (GET, POST, DELETE, v.v.)
calls	Số lần gọi tổng cộng
success	Số lần thành công
failed	Số lần lỗi
average_ms	Thời gian phản hồi trung bình

---

3️⃣ Thống kê theo ngày / tuần / tháng

GET /v1/metrics/period?range=daily

Tham số hỗ trợ

Tham số	Giá trị	Mô tả
range	daily / weekly / monthly	Chọn phạm vi thống kê

Phản hồi mẫu

{
  "status": true,
  "data": [
    { "date": "2025-10-10", "calls": 42, "average_ms": 190 },
    { "date": "2025-10-11", "calls": 55, "average_ms": 210 },
    { "date": "2025-10-12", "calls": 45, "average_ms": 230 }
  ]
}

---

4️⃣ Theo dõi tình trạng hệ thống

GET /v1/metrics/status

Kiểm tra tình trạng hoạt động của hệ thống API Pay2S (uptime, latency, trạng thái database).

Phản hồi mẫu

{
  "status": true,
  "data": {
    "uptime": "99.98%",
    "average_latency_ms": 185,
    "db_status": "OK",
    "api_gateway": "Operational",
    "last_check": "2025-10-14T13:30:00+07:00"
  }
}

---

5️⃣ Ghi log hoạt động API

GET /v1/metrics/logs

Trả về danh sách các lần gọi gần nhất của tài khoản đối tác (Partner API).

Phản hồi mẫu

{
  "status": true,
  "data": [
    {
      "id": 1001,
      "endpoint": "/v1/banks",
      "method": "GET",
      "response_ms": 132,
      "status_code": 200,
      "timestamp": "2025-10-14T13:12:03+07:00",
      "ip": "103.78.2.55"
    },
    {
      "id": 1002,
      "endpoint": "/v1/webhooks",
      "method": "POST",
      "response_ms": 254,
      "status_code": 500,
      "timestamp": "2025-10-14T13:13:05+07:00",
      "ip": "103.78.2.55"
    }
  ]
}

---

🧠 Lưu ý & Thực hành tốt

• Các endpoint /metrics/* chỉ khả dụng cho Partner có token hợp lệ.
• Số liệu được cache 30–60 giây, nên không phản ánh tức thời từng request.
• Khi response_ms = 0 → có thể do request nội bộ chưa log được thời gian phản hồi (hãy kiểm tra server clock).
• Dữ liệu này có thể dùng để vẽ biểu đồ monitor trên dashboard nội bộ.

---

🧪 cURL mẫu

Lấy thống kê tổng quan

curl -X GET https://api-partner.pay2s.vn/v1/metrics/calls \
 -H "Authorization: Bearer <token>"

Lấy danh sách log gần nhất

curl -X GET https://api-partner.pay2s.vn/v1/metrics/logs \
 -H "Authorization: Bearer <token>"

---

Gợi ý tích hợp

Bạn có thể tích hợp dữ liệu từ /metrics vào dashboard BI (như Grafana, Metabase, PowerBI) để theo dõi lưu lượng và hiệu năng API của chính bạn.