Appearance

Casi d'uso end-to-end ​

Scenari completi che combinano più funzioni, raccontati passo per passo con le chiamate API coinvolte. Ogni scenario segue lo schema obiettivo → passi → risultato atteso → riferimenti tecnici.

Attivazione di un agente (con accesso all'area riservata) ​

Obiettivo — Censire un nuovo agente e dargli l'accesso personale alla propria area riservata, dove potrà consultare profilo, contratti e posizione nella rete.

Attori — Il sistema del partner (autenticato con Chiave API rw) esegue i passi 1–3; l'agente compie il primo accesso ai passi 4–5. Vedi Accessi.

Prerequisiti

  • Chiave API del tenant con permessi di scrittura: Authorization: Bearer dmk_…
  • Base URL: https://api.base9.app

Passo 1 — (opzionale) verificare i livelli ​

La creazione richiede un livello della rete (pre-seedati L0…L4, dove L3 = Agente).

bash
curl -H "Authorization: Bearer dmk_xxxx" \
  "https://api.base9.app/v1/agenti_livelli"

Passo 2 — creare l'agente ​

Si crea l'anagrafica includendo già il contatto email (servirà per l'invito).

bash
curl -X POST "https://api.base9.app/v1/agenti" \
  -H "Authorization: Bearer dmk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "PF",
    "livello": "L3",
    "mercato": "ENTRAMBI",
    "anagrafica": {
      "nome": "Valerio",
      "cognome": "Rossi",
      "codice_fiscale": "RSSVLR80A01H501X"
    },
    "contatti": [
      { "tipo_contatto": "EMAIL", "valore": "agente@example.com", "is_primary": true }
    ]
  }'

Risposta 201 — l'id dell'agente (formato A + 8 caratteri) è nel campo id:

json
{ "object": "agente", "id": "A1B2C3D4E",
  "data": { "id": "A1B2C3D4E", "tipo": "PF", "stato": "attivo", "livello": "L3" } }

Per i tipi GIURIDICO / DI cambia il blocco anagrafica (es. ragione_sociale + partita_iva). Vedi la API Reference, sezione Agenti.

Passo 3 — abilitare l'accesso all'area riservata ​

Crea l'identità e assegnale l'area AGENTE con i moduli, tramite l'API admin grant. Questo crea l'utente, collega la risorsa e attiva l'accesso al portale.

bash
# crea l'identità (se non esiste già)
curl -X POST "https://api.base9.app/v1/admin/users" \
  -H "Authorization: Bearer $ADMIN_ID_TOKEN" -H "Content-Type: application/json" \
  -d '{ "email": "agente@example.com" }'          # → { "data": { "sub": "..." } }

# assegna l'area AGENTE (risorsa + moduli)
curl -X PUT "https://api.base9.app/v1/admin/users/<sub>/grants/AGENTE" \
  -H "Authorization: Bearer $ADMIN_ID_TOKEN" -H "Content-Type: application/json" \
  -d '{ "resource_id": "A1B2C3D4E", "modules": { "contratti": "rw", "fatturazione": "r" } }'

Da questo momento l'agente può accedere con email + password (vedi Passo 4). Guida completa: Area riservata multi-persona.

Passo 4 — primo accesso dell'agente ​

L'agente accede con email + password su POST https://api.base9.app/v1/auth/login:

  1. Login → se è il primo accesso (password provvisoria) il sistema risponde col challenge NEW_PASSWORD_REQUIRED (nessun token ancora).
  2. L'agente imposta la nuova password (POST /v1/auth/new-password) → vengono rilasciati i token (JWT). Se il tenant richiede il 2FA per gli agenti, attiva anche il TOTP.

Guida passo-passo: Area riservata multi-persona · dettagli: Autenticazione.

Passo 5 — l'agente consulta la propria area ​

Le chiamate /v1/me/* usano il token JWT (id_token); l'agente vede solo i propri dati.

bash
curl -H "Authorization: Bearer <IdToken>" "https://api.base9.app/v1/me/agente"
curl -H "Authorization: Bearer <IdToken>" "https://api.base9.app/v1/me/agente/contratti"
curl -H "Authorization: Bearer <IdToken>" "https://api.base9.app/v1/me/agente/superiori"

Risultato atteso — L'agente è censito, ha un accesso personale e sicuro, e consulta in autonomia le proprie informazioni. Lo stato del portale passa da invitato ad attivo al primo accesso.

Revoca — In qualsiasi momento: DELETE /v1/agenti/{id}/portal-access.

Riferimenti tecnici — API Reference (sezioni Agenti e Portale) · Accessi · Rete agenti.

Altri scenari (in preparazione) ​

Seguiranno, con la stessa impostazione:

  • Onboarding di un nuovo cliente — dall'anagrafica al punto di fornitura, dal contratto all'offerta applicata.
  • Subentro su un punto (voltura) — cambio di intestatario con storicizzazione.
  • Cambio fornitore (switching) — attivazione e tempistiche.
  • Abilitazione area cliente — invito e primo accesso del cliente (gemello dello scenario agente).