Guida: l'API V-CISO spec-driven

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 (Elenca attività tabella) 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": [ /* l'insieme di colonne normalizzato */ ],
    "rows": [ /* normalizzate, pronte per l'invio */ ],
    "current": [ /* le righe che la tabella contiene oggi */ ],
    "errors": [ /* {row, column, message, code} per ogni problema */ ] } }

Correggi eventuali errors (un id di colonna che non è nella specifica, 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. Messaggi ed etichette delle colonne seguono ?lan=en|it (inglese per impostazione predefinita); un valore obbligatorio mancante porta "code": "required", così uno script lo riconosce senza leggere il testo. current ti permette di confrontare ciò che invii con ciò che la tabella contiene prima di inviare. Riporta le celle come le mostra la console (testo localizzato, scelte come etichette), quindi non rimandarlo come rows: costruisci le righe a partire dalla specifica. Il body JSON deve contenere un array rows: senza, la richiesta fallisce con 400 e Missing 'rows' array. dry_run vale solo se è true, 1 o yes (nel body o come parametro di query); qualsiasi altro valore significa invio.

Sostituisci la tabella, o mantieni le righe che non invii

Per impostazione predefinita le righe che invii sostituiscono l’intera tabella. Aggiungi "keep_rows": true (oppure ?keep_rows=1, o un campo keep_rows nel form con un caricamento XLSX) per aggiornarla invece: una riga la cui prima colonna corrisponde a una riga già presente la sostituisce, le righe nuove vanno in fondo e le righe che non hai inviato restano. Si legge come dry_run (true, 1 o yes).

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

Il dry run restituisce anche kept_count, il numero di righe attuali che restano.

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 } }

Con keep_rows, la risposta contiene anche kept_rows. 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. Un id che non è una domanda dell’attività è un errore (Unknown id: not a question of this task or step (see /spec)).

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: deve essere un file caricato per la stessa organizzazione, lo stesso workflow e la stessa domanda, altrimenti la risposta viene rifiutata. Ogni id di nota deve essere una delle notes della domanda in /spec; per una domanda di un’attività è <question_id>_justification:

{ "answers": {
    "task-nisAnnual-q1": {
      "value": "Yes",
      "evidence": ["media/docs/frameworks/123/oJJ…/task-nisAnnual-q1/tok_x.pdf"],
      "note": [{ "id": "task-nisAnnual-q1_justification", "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>.

# Contratto: id del controllo, type, choices, weight, step
curl -H "X-Aegister-Token: $TOKEN" \
  ".../workflows/oJJ…/framework/spec?lan=en&step=E"

# Specifica + risposte correnti indicizzate per id del controllo
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), notes (i campi di giustificazione, ciascuno con il suo id), step, subframework, category e weight. Un id di controllo che non è nello step è un errore. 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": { /* normalizzate */ }, "errors": [] } }

Allega evidenza e giustificazione nello stesso modo delle attività a domande, con un valore composito. L’id della nota è quello indicato nelle notes del controllo (per i controlli NIS 2, ad esempio 2.1.1_justification):

{ "answers": {
    "nis2-req-E - 2.1.1": {
      "value": "Implemented",
      "evidence": ["media/docs/frameworks/123/oJJ…/nis2-req-E - 2.1.1/tok_x.pdf"],
      "note": [{ "id": "2.1.1_justification", "response": "Reviewed by the board on 2026-01-10." }] } } }

Invia sempre il value insieme alla nota. Su ISO 27001 una risposta che contiene solo la giustificazione, senza valore, cancella il livello del controllo. Rimuovendo dry_run valida e poi invia tramite /evaluate (Aegister calcola il punteggio e persiste), restituendo { "submitted": <numero di risposte>, "step": "E", "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/123/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 (Elenca documenti nella barra laterale). La cronologia e i download per-artefatto usano gli altri endpoint del gruppo Virtual CISO → Cyber Posture → Documenti.

6. Compila un’attività dai tuoi documenti (AI)

Se le risposte sono già nei tuoi documenti (una policy, un elenco di asset, un registro), lascia che l’AI li legga e proponga cosa inserire in un’attività tabella o a domande. È la stessa proposta di Compila dai tuoi documenti nella console. Non viene salvato nulla: rivedi la proposta e la invii tramite /import come nelle sezioni 2 e 3. Passo 1, avvia il job con da 1 a 5 documenti in base64 (al massimo 10 MB ciascuno, 20 MB in totale, altrimenti 413). Puoi avviare 20 job all’ora; oltre, la chiamata risponde 429:

curl -H "X-Aegister-Token: $TOKEN" -H "Content-Type: application/json" \
  ".../workflows/oJJ…/tasks/task-nis-inv-hardware/prefill?lan=it" \
  -d '{ "documents": [
        { "name": "asset.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "content": "UEsDBBQABgAIAAAAIQ…" } ] }'

{ "error": 0, "messages": [], "data": {
    "job": "resp_…",
    "documents": { "used": ["asset.xlsx"], "skipped": [] } } }

L’AI legge PDF, Word (.docx), Excel (.xlsx, .xlsm), immagini (.png, .jpg, .gif, .webp) e file di testo (.txt, .md, .csv, .tsv, .json, .xml, .log). Ogni altro file finisce in skipped con il motivo. La chiamata fallisce con 400 quando nessun documento è leggibile e con 502 quando il servizio AI non è raggiungibile. Passo 2, interroga il job finché status è done:

curl -H "X-Aegister-Token: $TOKEN" \
  ".../workflows/oJJ…/tasks/task-nis-inv-hardware/prefill/resp_…"

{ "error": 0, "messages": [], "data": {
    "status": "done", "kind": "table",
    "columns": [ /* le colonne dell'attività, come in /spec */ ],
    "rows": [ /* le righe proposte, come le accetta /import */ ],
    "current": [ /* le righe che la tabella contiene oggi */ ],
    "responses": [ /* la stessa proposta, come la salva la console */ ],
    "ai": { "summary": "…", "filled": 12, "details": [ /* … */ ], "skipped_rows": [ /* … */ ] } } }

Mentre l’AI legge ricevi { "status": "running" }. Quando i documenti non contengono nulla per l’attività, il risultato porta un msg invece di una proposta. Per un’attività a domande, kind è questions e la proposta è in answers, indicizzata per id della domanda. ai spiega la proposta: un riepilogo, quanti elementi sono stati compilati, per ogni risposta la confidenza e il documento da cui viene, e le righe escluse con il motivo (per esempio un valore che manca in un elenco collegato, da aggiungere prima lì). Passo 3, invia la proposta: manda rows (tabelle) o answers (domande) a /import, prima con dry_run. Solo chi ha avviato il job può leggerlo, e i documenti non vengono conservati.

Per iniziare

Virtual CISO

Protezione perimetrale

Virtual Private Network

Organizzazioni

Amministrazione

Impostazioni / Profilo

Altro

Guida: l'API V-CISO spec-driven

Prima di iniziare

1. Individua cosa compilare

2. Attività tabella (righe)

Leggi la specifica (il contratto)

Valida senza scrivere (dry_run)

Sostituisci la tabella, o mantieni le righe che non invii

Invia

3. Attività a domande (risposte)

4. Controlli del framework

5. Evidenze: il caricamento in due passi

6. Compila un’attività dai tuoi documenti (AI)

​Prima di iniziare

​1. Individua cosa compilare

​2. Attività tabella (righe)

​Leggi la specifica (il contratto)

​Valida senza scrivere (dry_run)

​Sostituisci la tabella, o mantieni le righe che non invii

​Invia

​3. Attività a domande (risposte)

​4. Controlli del framework

​5. Evidenze: il caricamento in due passi

​6. Compila un’attività dai tuoi documenti (AI)

Prima di iniziare

1. Individua cosa compilare

2. Attività tabella (righe)

Leggi la specifica (il contratto)

Valida senza scrivere (dry_run)

Sostituisci la tabella, o mantieni le righe che non invii

Invia

3. Attività a domande (risposte)

4. Controlli del framework

5. Evidenze: il caricamento in due passi

6. Compila un’attività dai tuoi documenti (AI)