# 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)
QUICK START — OPERATIVO IN 2 MINUTI
CHIAVE API (già attiva)
`nis2_mktg_8c8bd38e78fccb9faa749d8601051f42`
Scope: admin:licenses · Scade: 2028-03-07
BASE URL
`https://nis2.agile.software/api`
Tutti gli endpoint sotto questo path
TEST IMMEDIATO
`curl nis2.agile.software/api/services/status`
Nessuna auth — deve rispondere 200
FLUSSO COMPLETO — dalla vendita all'attivazione cliente
1. mktg-agile
POST /invites/create
→ token inv_xxx
2. e-commerce
consegna token al cliente
→ inv_xxx
3. lg231 / cliente
POST /services/provision
→ org + api_key
4. NIS2 attivo
fino a license_expires_at

    # Crea licenza in 1 chiamata:
    curl -X POST https://nis2.agile.software/api/invites/create \
      -H "X-API-Key: nis2_mktg_8c8bd38e78fccb9faa749d8601051f42" \
      -H "Content-Type: application/json" \
      -d '{"plan":"professional","duration_months":12,"label":"Ordine #123","channel":"ecommerce","max_users_per_org":10,"price_eur":990}'

    # Risposta → prendi invites[0].token (inv_xxx) e invites[0].invite_url
    # Consegna invite_url al cliente — lui clicca e si attiva in autonomia

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

1. Vai su nis2.agile.software/licenseExt.html → login con account super_admin
2. Naviga su Settings → API Keys → Nuova API Key
3. Nome: `mktg-agile integration` → Scope: `admin:licenses`
4. Copia la chiave — formato `nis2_xxxx...` — visibile una sola volta
5. 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