API và Webhooks Báo cáo SonarQube

Bài viết này mô tả cách truy cập lập trình các báo cáo bảo mật SonarQube được lưu trữ trên nền tảng Procurize. Nó bao phủ API REST để liệt kê và truy xuất báo cáo, tải xuống các lưu trữ báo cáo, và đăng ký nhận thông báo webhook khi các báo cáo mới được nhập.

Tổng quan

Phân mô-đun Báo cáo SonarQube cho phép các tổ chức lưu trữ và quản lý tập trung các báo cáo bảo mật và chất lượng mã được tạo bởi SonarQube. Nền tảng Procurize cung cấp dữ liệu này thông qua:

API REST để truy xuất siêu dữ liệu về các báo cáo đã lưu
Endpoint để tải xuống các artefact báo cáo dưới dạng tệp ZIP
Webhooks để nhận thông báo gần thời gian thực khi các báo cáo mới trở nên khả dụng

Những khả năng này hỗ trợ việc tích hợp với các pipeline CI/CD, hệ thống GRC, bảng điều khiển nội bộ và công cụ quản lý rủi ro bên thứ ba.

Xác thực và Ủy quyền

Tất cả các yêu cầu API được mô tả trong bài viết này không yêu cầu xác thực.

ID Tổ chức

ID tổ chức là bắt buộc cho mọi yêu cầu được mô tả ở đây.
Bạn có thể tìm thấy nó trong bảng điều khiển cài đặt của Tổ chức tại https://dashboard.procurize.ai.
Lưu ý rằng việc truy cập bảng điều khiển cài đặt yêu cầu ủy quyền, và để truy cập bảng cài đặt của tổ chức bạn phải có vai trò người dùng ít nhất là Quản trị viên trong tổ chức đó.

Nút sao chép ID

URL Cơ sở

Tất cả các endpoint API REST được phục vụ dưới URL cơ sở sau:

https://api.procurize.com

API REST Báo cáo SonarQube

Liệt kê Báo cáo

Truy xuất một danh sách có phân trang các báo cáo bảo mật SonarQube được lưu trong nền tảng.

Endpoint

GET /security/report/list

Tham số Truy vấn

org (bắt buộc): ID Tổ chức.
version (tùy chọn): Phiên bản chính xác của sản phẩm theo định dạng Semantic Versioning.
minver (tùy chọn): Phiên bản tối thiểu của sản phẩm theo định dạng Semantic Versioning.
maxver (tùy chọn): Phiên bản tối đa của sản phẩm theo định dạng Semantic Versioning.

Lưu ý rằng ít nhất một trong các tham số version, minver hoặc maxver là bắt buộc cho yêu cầu.

Ví dụ Yêu cầu

curl "https://api.procurize.com/security/report/list?org=00000000-0000-0000-0000-000000000001&version=1.0"

Ví dụ Phản hồi

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Tải xuống Lưu trữ Báo cáo

Tải xuống một tệp ZIP chứa toàn bộ artefact báo cáo SonarQube. Kho lưu trữ bao gồm các báo cáo HTML và PDF.

Endpoint

GET /security/report/files

org (bắt buộc): ID Tổ chức.
reports (bắt buộc): Mảng các ID báo cáo.

Ví dụ Yêu cầu

curl "https://api.procurize.com/security/report/files?org=00000000-0000-0000-0000-000000000001&reports=00000000-0000-0000-0000-000000000002&reports=00000000-0000-0000-0000-000000000003"

Phản hồi

Content-Type: application/zip
Thân phản hồi chứa tệp ZIP nhị phân

Các client nên stream phản hồi và lưu nó vào đĩa.

Xử lý Lỗi

API sử dụng các mã trạng thái HTTP tiêu chuẩn.

200 OK: Yêu cầu thành công
204 No Content: Báo cáo không tồn tại
400 Bad Request: Tham số không hợp lệ hoặc yêu cầu sai định dạng
500 Internal Server Error: Lỗi máy chủ không mong muốn

Phản hồi lỗi bao gồm một mã lỗi có thể đọc được bởi máy và một thông điệp có thể đọc được bởi con người.

Webhooks

Webhook của Procurize cho phép hệ thống bên ngoài nhận thông báo khi các báo cáo SonarQube mới được nhập hoặc cập nhật.

Cấu hình webhook

Webhook có thể được thêm hoặc chỉnh sửa trong bảng điều khiển cài đặt của Tổ chức, phần Báo cáo bảo mật tại https://dashboard.procurize.ai.
Lưu ý rằng việc truy cập bảng điều khiển cài đặt yêu cầu ủy quyền, và để truy cập bảng cài đặt của tổ chức bạn phải có vai trò người dùng ít nhất là Quản trị viên trong tổ chức đó.

Trình chỉnh sửa Webhooks

Để kiểm tra webhook, bạn có thể sử dụng các dịch vụ trực tuyến phổ biến như https://webhook-test.com

Nội dung Webhook

Sự kiện webhook được giao dưới dạng yêu cầu HTTP POST kèm theo payload JSON.

Ví dụ Payload

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Bảo mật Webhook

Để đảm bảo tính xác thực, các yêu cầu webhook bao gồm một header chữ ký được tạo bằng một secret chia sẻ.

Chữ ký được tính toán bằng HMAC‑SHA256
Các client nên xác thực chữ ký trước khi xử lý payload

Điều này ngăn chặn việc gửi webhook không được ủy quyền hoặc giả mạo.

Giao hàng và Thử lại

Webhook mong đợi phản hồi 2xx để được coi là đã giao thành công
Các lần giao không thành công sẽ tự động được thử lại mỗi giờ.
Sự kiện có thể được giao hơn một lần; người tiêu dùng nên triển khai xử lý không gây trùng lặp (idempotent).

Các trường hợp sử dụng điển hình

Tự động nhập các phát hiện SonarQube vào bảng điều khiển bảo mật nội bộ
Kích hoạt quy trình tuân thủ khi các cổng chất lượng không đạt
Lưu trữ báo cáo bảo mật để kiểm toán và đánh giá rủi ro nhà cung cấp
Đồng bộ hệ thống bên thứ ba với trạng thái bảo mật mã nguồn mới nhất