Vai al contenuto principale
Gestisci i workflow V-CISO interamente dall’API. Tabelle (inventari, registri), attività a domande e controlli del framework condividono tutti lo stesso schema: individua, leggi la specifica, valida con dry_run, quindi invia. Il server valida esattamente come un salvataggio nella web app, poi calcola il punteggio e persiste una nuova valutazione. Tutte le richieste si autenticano con un header X-Aegister-Token (vedi Autenticazione e API token). L’organizzazione deve possedere la licenza v_ciso. La lettura richiede il ruolo view; la scrittura richiede il ruolo edit (security_officer, owner o super_admin).
I percorsi qui sotto sono abbreviati come .../workflows/{wid}/.... La base completa è https://app.aegister.com/api/v1/v-ciso/organizations/{oid}. Tutte le risposte usano l’envelope standard { "error": 0|1, "messages": [], "data": {…} } (più "total" negli elenchi).

​
Prima di iniziare

Questa guida parte da un’organizzazione esistente che possiede già la licenza v_ciso e ha il framework che vuoi compilare associato e configurato. Ti servono solo il suo id organizzazione ({oid}) e un token con il ruolo edit (security_officer, owner o super_admin).
Per NIS 2, il profilo dell’organizzazione deve dichiarare il suo tipo di soggetto (Essenziale o Importante). Finché non lo fa, il framework restituisce nessun controllo e nessuna attività, e le chiamate qui sotto tornano vuote. Impostalo prima nel profilo NIS 2 dell’organizzazione.

​
1. Individua cosa compilare

Elenca ogni attività (tabella e a domande) dell’organizzazione, ciascuna con il suo type, così che uno script possa localizzare su cosa lavorare. Filtra con ?type=table o ?type=questions. 
curl -H "X-Aegister-Token: $TOKEN" \
  "https://app.aegister.com/api/v1/v-ciso/organizations/123/tasks"

{ "error": 0, "messages": [], "total": 2,
  "data": [
    { "workflow_id": "oJJ…", "task_id": "task-nis-inv-hardware",
      "title": { "en": "Hardware inventory", "it": "Inventario hardware" },
      "type": "table", "required": true, "status": "Not started" },
    { "workflow_id": "oJJ…", "task_id": "task-nisAnnual",
      "title": { "en": "Annual review", "it": "Revisione annuale" },
      "type": "questions", "required": true, "status": "In progress" } ] }
Usa il workflow_id + task_id restituiti per le chiamate per-attività. Il più datato GET .../table-tasks (List table tasks) restituisce solo le attività tabella; /tasks le copre entrambe.

​
2. Attività tabella (righe)

​
Leggi la specifica (il contratto)

curl -H "X-Aegister-Token: $TOKEN" \
  ".../workflows/oJJ…/tasks/task-nis-inv-hardware/spec?lan=en"
Ogni colonna dichiara type, required, un format dichiarativo (per esempio { "kind": "date", "pattern": "YYYY-MM-DD" }) e i valori ammessi in choices (con sia l’id value sia il label localizzato). Le colonne dipendenti riportano depends_on + choices_by_parent; le colonne cross-attività riportano source. Invia il label della scelta oppure il suo value id; le colonne a valori multipli accettano un array o una stringa unita da |.

​
Valida senza scrivere (dry_run)

curl -H "X-Aegister-Token: $TOKEN" -H "Content-Type: application/json" \
  ".../workflows/oJJ…/tasks/task-nis-inv-hardware/import?lan=en" \
  -d '{ "dry_run": true, "rows": [
        { "asset_id": "HW-001", "device_input": "Physical servers",
          "criticality": "High", "status": "Updated" } ] }'

{ "error": 0, "messages": [], "data": {
    "valid_count": 1, "error_count": 0,
    "columns": [ /* the normalized column set */ ],
    "rows": [ /* normalized, ready to submit */ ],
    "errors": [ /* {row, column, message} per problem */ ] } }
Correggi eventuali errors (scelta errata, data/numero non validi, un valore figlio non ammesso per il suo genitore, un valore cross-attività sconosciuto) e ripeti finché error_count è 0.

​
Invia

Rimuovi dry_run per persistere. Il server valida di nuovo, invia al motore di calcolo del punteggio e registra una nuova valutazione, esattamente come un salvataggio nella web app. 
{ "error": 0, "messages": [], "data": { "imported_rows": 1, "evaluation_id": 3780 } }
Una richiesta con un qualsiasi errore di validazione restituisce 400 con error: 1 e la lista data.errors; non viene scritto nulla.
GET .../template restituisce un XLSX arricchito (menu a tendina + menu a tendina dipendenti + legenda value/label) e GET .../export lo restituisce precompilato con i dati correnti: comodo per le persone, mentre gli script usano il contratto JSON descritto sopra.

​
3. Attività a domande (risposte)

Le attività a domande usano gli stessi endpoint /spec e /import; la chiave del payload è answers invece di rows. Leggi la specifica e le risposte correnti in un’unica chiamata per il prefill, quindi invia. 
curl -H "X-Aegister-Token: $TOKEN" \
  ".../workflows/oJJ…/tasks/task-nisAnnual/answers?lan=en"
Restituisce la specifica delle domande insieme alle ultime risposte memorizzate, indicizzate per id della domanda. Le risposte a scelta accettano il label o il value id; le risposte a valori multipli vanno come array o come stringa unita da virgola/pipe. 
curl -H "X-Aegister-Token: $TOKEN" -H "Content-Type: application/json" \
  ".../workflows/oJJ…/tasks/task-nisAnnual/import?lan=en" \
  -d '{ "dry_run": true, "answers": {
        "task-nisAnnual-q1": "Yes",
        "task-nisAnnual-q2": ["Email", "Phone"] } }'
Per allegare un’evidenza o una giustificazione, invia una risposta composita { "value", "evidence": [<path>], "note": [{ "id", "response" }] }. Carica prima il file (vedi sezione 5) e usa il path restituito: 
{ "answers": {
    "task-nisAnnual-q1": {
      "value": "Yes",
      "evidence": ["media/docs/frameworks/65/oJJ…/task-nisAnnual-q1/tok_x.pdf"],
      "note": [{ "id": "note-1", "response": "Notified ACN on 2026-01-10." }] } } }
Rimuovi dry_run per persistere; la risposta riporta il nuovo evaluation_id, come per le tabelle.

​
4. Controlli del framework

Il framework di un workflow (l’insieme di controlli dietro il punteggio) ha il proprio trio spec/answers/submit, raggruppato in step. Lavora uno step alla volta con ?step=<stepId>. 
# Contract: control id, type, choices, weight, step
curl -H "X-Aegister-Token: $TOKEN" \
  ".../workflows/oJJ…/framework/spec?lan=en&step=E"

# Spec + current answers keyed by control id
curl -H "X-Aegister-Token: $TOKEN" \
  ".../workflows/oJJ…/framework/answers?lan=en&step=E"
Ogni controllo riporta id, label, description, type (radio|select|checkbox|date|number|text|…), choices, required, un flag evidence (se è possibile allegare file), step, subframework, category e weight. Invia le risposte di uno step con controls-import: prima dry_run, poi persisti. 
curl -H "X-Aegister-Token: $TOKEN" -H "Content-Type: application/json" \
  ".../workflows/oJJ…/framework/controls-import?step=E&lan=en" \
  -d '{ "dry_run": true, "answers": { "nis2-req-E - 2.1.1": "Implemented" } }'

{ "error": 0, "messages": [], "data": {
    "valid_count": 1, "error_count": 0,
    "answers": { /* normalized */ }, "errors": [] } }
Allega l’evidenza nello stesso modo delle attività a domande, con un valore composito: 
{ "answers": {
    "nis2-req-E - 2.1.1": {
      "value": "Implemented",
      "evidence": ["media/docs/frameworks/65/oJJ…/nis2-req-E - 2.1.1/tok_x.pdf"] } } }
Rimuovendo dry_run valida e poi invia tramite /evaluate (Aegister calcola il punteggio e persiste), restituendo { "submitted": true, "evaluation_id": … }.

​
5. Evidenze: il caricamento in due passi

Carica le evidenze separatamente, non inline. Invia il file al suo artefatto, quindi riferisci il path restituito nella risposta. Passo 1, carica il file come JSON base64 verso l’artefatto (un id di controllo o di domanda): 
curl -H "X-Aegister-Token: $TOKEN" -H "Content-Type: application/json" \
  ".../workflows/oJJ…/documents/nis2-req-E%20-%202.1.1/versions" \
  -d '{ "filename": "policy.pdf",
        "content": "JVBERi0xLjQK…",
        "content_type": "application/pdf",
        "source": "evidence_upload" }'

{ "error": 0, "messages": [], "data": {
    "id": 91, "artifact_id": "nis2-req-E - 2.1.1", "original_name": "policy.pdf",
    "size": 51234, "content_type": "application/pdf",
    "path": "media/docs/frameworks/65/oJJ…/nis2-req-E - 2.1.1/tok_x.pdf" } }
Vincoli: al massimo 10 MB (decodificato, altrimenti 413); i formati ammessi sono PDF, Word (.doc/.docx), Excel (.xls/.xlsx), immagini e video (qualsiasi altro restituisce 400). I caricamenti vengono deduplicati per SHA-256 (un contenuto identico restituisce la versione esistente, 200, invece di una nuova 201), e per ogni artefatto vengono conservate solo le ultime 10 versioni. Passo 2, riferisci il path restituito nell’array evidence della risposta che invii (sezioni 3 e 4). Per elencare le evidenze esistenti in un workflow (ogni artefatto con la sua ultima versione e l’intera cronologia), chiama GET .../workflows/{wid}/documents (List Documents nella barra laterale). La cronologia e i download per-artefatto usano gli altri endpoint Documents sotto V-CISO.