NIS2 Agile — License API

Documentazione completa per l'integrazione da mktg-agile e sistemi e-commerce.
Risponde alle domande del team marketing su endpoint, autenticazione e risposta API.

REST / JSON HTTPS API Key v1.0 ⬇ Postman Collection (JSON) 🖥 Pannello Licenze (web)

1 API di creazione licenza

POST https://nis2.agile.software/api/invites/create

// Header richiesti:
Content-Type: application/json
X-API-Key: nis2_LA_TUA_CHIAVE  ← vedi sezione 2

// Body (tutti i campi disponibili):
{
  "plan":               "professional",  // essentials | professional | enterprise
  "duration_months":    12,               // durata licenza dopo attivazione
  "invite_expires_days": 30,               // giorni per attivare l'invito
  "max_uses":           1,                // n. aziende che possono usarlo (1=singolo)
  "max_users_per_org":  10,               // max utenti per azienda (ometti = illimitato)
  "label":             "NIS2 Pro — Ordine MKT-001",  // etichetta interna
  "channel":           "ecommerce",      // ecommerce|lg231|direct|reseller|manual
  "issued_to":         "cliente@co.it",  // email o nome destinatario
  "reseller_name":     "Partner XYZ",    // riferimento reseller (solo vostro)
  "price_eur":         990.00,           // prezzo applicato (solo riferimento)
  "notes":             "Campagna Q1 2026", // note interne marketing
  "quantity":          1,                // genera N token in batch (default 1, max 50)
  // OPZIONALE — restrizioni di sicurezza:
  "restrict_vat":      "02345678901",    // solo questa P.IVA può usarlo
  "restrict_email":    "ciso@co.it"      // solo questo admin può usarlo
}

Campi obbligatori: plan, label. Tutti gli altri sono opzionali con valori di default ragionevoli.

2 Autenticazione

Ogni chiamata da mktg-agile deve includere l'header X-API-Key con una chiave dedicata.

Come ottenere la chiave API

Vai su nis2.agile.software/licenseExt.html → login con account super_admin
Naviga su Settings → API Keys → Nuova API Key
Nome: mktg-agile integration → Scope: admin:licenses
Copia la chiave — formato nis2_xxxx... — visibile una sola volta
Salvala in mktg-agile come variabile d'ambiente: NIS2_API_KEY=nis2_xxxx...

# Chiamata da mktg-agile (curl):
curl -X POST https://nis2.agile.software/api/invites/create \
  -H "X-API-Key: nis2_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"plan":"professional","duration_months":12,"label":"Test"}'

Scope	Tipo	Permessi
`admin:licenses` CONSIGLIATO	Lettura + Scrittura	Crea, lista, revoca, rigenera licenze
`read:all` SOLA LETTURA	Solo lettura	Lista e dettaglio licenze, nessuna modifica

Alternativa JWT: se preferisci usare un JWT (es. per test manuali), fai prima POST /api/auth/login con le credenziali super_admin e usa il token restituito come Authorization: Bearer eyJ.... Valido 2 ore.

3 Response alla creazione

HTTP 201. JSON. Array invites — uno per token generato.

{
  "success": true,
  "data": {
    "invites": [
      {
        "id":              42,
        "token":          "inv_a1b2c3d4e5f6...",   ← SALVA SUBITO — non recuperabile
        "token_prefix":  "inv_a1b2c3...",          ← riferimento visivo (non il token completo)
        "plan":          "professional",
        "duration_months": 12,
        "max_uses":        1,
        "max_users_per_org": 10,
        "price_eur":      990.00,
        "expires_at":     "2026-04-07 14:00:00",   ← entro cui attivare
        "channel":        "ecommerce",
        "label":          "NIS2 Pro — Ordine MKT-001",
        "issued_to":      "cliente@co.it",
        "invite_url":     "https://nis2.agile.software/onboarding.html?invite=inv_a1b2...",
        "provision_hint": "POST /api/services/provision con invite_token: ..."
      }
    ],
    "count":   1,
    "warning": "Salva i token subito — non saranno più visibili in chiaro."
  }
}

Campo	Uso
`token`	Il token completo `inv_xxx` — consegnarlo al cliente / lg231. Non viene mai restituito di nuovo.
`invite_url`	URL diretto per onboarding browser — il cliente apre questo link e si registra
`expires_at`	Entro quando il cliente deve attivare. Dopo questa data il token non funziona.
`id`	ID numerico per revoca / dettaglio successivo

Export CSV

Il pannello licenseExt.html ha un bottone Esporta CSV che scarica tutte le licenze generate nella sessione. In alternativa, esporta programmaticamente da GET /api/invites/list e converti.

4 Lista licenze

GET https://nis2.agile.software/api/invites/list

# Parametri query (tutti opzionali):
?status=pending       // pending | used | expired | revoked
&channel=ecommerce    // ecommerce | lg231 | direct | reseller | manual
&limit=50             // default 50, max 100
&offset=0             // paginazione

# Esempio — tutte le licenze ecommerce attive:
GET /api/invites/list?channel=ecommerce&status=pending
X-API-Key: nis2_LA_TUA_CHIAVE

Risposta: { invites: [...], total: N, limit: 50, offset: 0 }
Ogni licenza include tutti i campi tranne il token in chiaro (non recuperabile dopo creazione).

GET https://nis2.agile.software/api/invites/{id}

Dettaglio singola licenza. Se è stata usata, include used_by_org con nome azienda e settore.

5 Revoca / modifica

DELETE https://nis2.agile.software/api/invites/{id}

Revoca la licenza (status → revoked). Il record rimane in DB per audit.

POST https://nis2.agile.software/api/invites/{id}/regenerate

Genera un nuovo token invalidando il precedente. Stessa configurazione (piano, durata, scadenza). Usare se il token è stato inviato per errore o compromesso prima dell'uso.

Stato licenza	Revocabile	Rigenerabile	Note
`pending`	✓ Sì	✓ Sì	Normale
`used`	✗ No	✗ No	Già attivata — azienda rimane attiva
`expired`	✓ Sì	✓ Sì	Scaduta ma non usata
`revoked`	—	✓ Sì	Già revocata

Importante: revocare una licenza blocca solo future attivazioni. Le aziende già provisionate con quella licenza rimangono operative fino a license_expires_at. La revoca non disattiva retroattivamente nessun cliente.

6 La seconda pagina (licenseExt.html)

È il pannello admin lato marketing — non il cliente.

Pagina	Audience	Funzione
licenseExt.html	Marketing / Admin NIS2	Genera licenze, vede stats (aziende provisionate, utenti coinvolti), revoca, esporta CSV
`onboarding.html?invite=inv_xxx`	Cliente finale	Usa il token ricevuto per attivare la propria azienda in NIS2 (wizard 5 step)
integrazioniext.html	Partner tecnici (lg231, e-commerce)	Documentazione flow completo, provisioning automatico B2B, webhook

licenseExt.html richiede login con credenziali super_admin. Non è pubblica — accedervi comunicando l'URL ai soli membri del team autorizzati.

→ Riepilogo rapido

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 BASE URL  https://nis2.agile.software/api
 AUTH       X-API-Key: nis2_xxxx  (scope: admin:licenses)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
POST   /invites/create              Crea licenza/e
GET    /invites/list                Lista licenze (filtri: status, channel)
GET    /invites/{id}                Dettaglio singola
DELETE /invites/{id}                Revoca
POST   /invites/{id}/regenerate    Nuovo token (stesso config)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 PUBBLICO (no auth):
GET    /invites/validate?token=inv_ Anteprima invito (piano, scadenza)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 COSA CONTROLLA NIS2 (non il mktg):
 ✓ N. aziende attivabili  → max_uses
 ✓ Tempo validità invito  → invite_expires_days → expires_at
 ✓ Durata licenza         → duration_months → license_expires_at
 ✓ N. utenti per azienda  → max_users_per_org → license_max_users
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 PROVA IN 30 SECONDI:
curl https://nis2.agile.software/api/services/status

NIS2 Agile v1.0 · Pannello Licenze · Guida Partner · Postman Collection