API-ul de Rapoarte SonarQube și Webhooks

Acest articol descrie cum să accesați programatic rapoartele de securitate SonarQube stocate în platforma Procurize. Acoperă API-ul REST pentru listarea și recuperarea rapoartelor, descărcarea arhivelor de rapoarte și abonarea la notificări webhook când noi rapoarte sunt ingestate.

Prezentare generală

Submodulul Rapoarte SonarQube permite organizațiilor să stocheze și să gestioneze central rapoartele de securitate și calitate a codului generate de SonarQube. Platforma Procurize expune aceste date prin:

• Un API REST pentru recuperarea metadatelor despre rapoartele stocate
• Un endpoint pentru descărcarea artefactelor rapoartelor ca arhive ZIP
• Webhook-uri pentru notificări aproape în timp real când noi rapoarte devin disponibile

Aceste capabilități permit integrarea cu pipe-urile CI/CD, sistemele GRC, tablourile de bord interne și instrumentele terțe de management al riscurilor.

Autentificare și Autorizare

Toate cererile API descrise în acest articol nu necesită autentificare.

ID-ul Organizației

Un ID de organizație este necesar pentru toate cererile descrise aici. Îl puteți găsi în panoul de setări al organizației la https://dashboard.procurize.ai. Rețineți că accesul la panoul de setări necesită autorizare, iar accesul la panoul de setări al organizației necesită un rol de utilizator de cel puțin Administrator în acea organizație.

URL de Bază

Toate endpoint-urile API REST sunt disponibile la următorul URL de bază:

https://api.procurize.com

API REST de Rapoarte SonarQube

Listarea Rapoartelor

Recuperează o listă paginată a rapoartelor de securitate SonarQube stocate în platformă.

Endpoint

GET /security/report/list

Query Parameters

• org (obligatoriu): ID-ul organizației.
• version (opțional): versiunea exactă a produselor în formatul Semantic Versioning.
• minver (opțional): versiunea minimă a produselor în formatul Semantic Versioning.
• maxver (opțional): versiunea maximă a produselor în formatul Semantic Versioning.

Vă rugăm să rețineți că cel puțin unul dintre parametrii version, minver sau maxver este necesar pentru cerere.

Request Example

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

Response Example

{
  "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"
    }
  ]
}

Descărcarea Arhivei de Raport

Descarcă o arhivă ZIP care conține artefactele complete ale raportului SonarQube. Arhiva include rapoarte în format HTML și PDF.

Endpoint

GET /security/report/files

• org (obligatoriu): ID-ul organizației.
• reports (obligatoriu): Matrice de ID-uri de rapoarte.

Request Example

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"

Response

• Content-Type: application/zip
• Corpul răspunsului conține fișierul ZIP binar

Clienții ar trebui să transcode răspunsul și să-l salveze pe disc.

Gestionarea Erorilor

API-ul folosește coduri de stare HTTP standard.

• 200 OK: Cerere cu succes
• 204 No Content: Raportul nu există
• 400 Bad Request: Parametri invalizi sau cerere malformată
• 500 Internal Server Error: Eroare internă neașteptată a serverului

Răspunsurile de eroare includ un cod de eroare lizibil de mașină și un mesaj lizibil de om.

Webhook-uri

Webhook-urile Procurize permit sistemelor externe să primească notificări când noi rapoarte SonarQube sunt ingestate sau actualizate.

Configurarea webhook-urilor

Webhook-urile pot fi adăugate sau editate în panoul de setări al organizației, secțiunea Rapoarte de securitate la https://dashboard.procurize.ai. Rețineți că accesul la panoul de setări necesită autorizare, iar accesul la panoul de setări al organizației necesită un rol de utilizator de cel puțin Administrator în acea organizație.

Pentru a verifica webhook-urile, puteți folosi servicii online populare precum https://webhook-test.com

Payload-ul Webhook-ului

Evenimentele webhook sunt livrate ca cereri HTTP POST cu un payload JSON.

Example 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"
    }
  ]
}

Securitatea Webhook-ului

Pentru a asigura autenticitatea, cererile webhook includ un antet de semnătură generat utilizând un secret comun.

• Semnătura este calculată utilizând HMAC-SHA256
• Clienții ar trebui să verifice semnătura înainte de a procesa payload-ul

Acest lucru previne livrările neautorizate sau falsificate ale webhook-urilor.

Livrare și Reîncercări

• Webhook-urile așteaptă un răspuns 2xx pentru a fi considerate livrate cu succes
• Livrările eșuate sunt reîncercate automat la fiecare oră.
• Evenimentele pot fi livrate de mai multe ori; consumatorii ar trebui să implementeze procesare idempotentă

Cazuri de Utilizare Tipice

• Ingestați automat constatări SonarQube în tablourile de bord interne de securitate
• Declanșați fluxuri de lucru de conformitate când porțile de calitate eșuează
• Arhivați rapoartele de securitate pentru audituri și revizuiri ale riscurilor furnizorilor
• Mențineți sistemele terțe sincronizate cu cea mai recentă postură de securitate a codului