Rete di distribuzione

La rete di distribuzione è lo strato partner sopra le Licenze. Un distributore è un workspace che vende prodotti Altovar ai propri clienti ed emette da solo le chiavi di licenza, dentro i limiti che gli dai tu.

Aprila dalla barra laterale: Licenze → Distributori.

Dietro non c’è un motore di licenze separato. La chiave che emette un partner è una normale chiave di licenza per tenant — la stessa che emetteresti da Licenze → Chiavi — solo attribuita al suo canale e limitata da ciò che gli hai concesso. Tutto quello che sai già su policy, scadenze e revoche vale anche qui.

L’ordine giusto

Ogni passo dipende dal precedente. Saltarne uno non dà errore subito: l’errore arriva dopo, dalla parte del partner, quando prova a vendere.

Crea il distributore

O colleghi il workspace che il partner ha già, o è Auris a crearlo e a invitare il referente. Non c’è ancora niente di vendibile.

Dagli le concessioni

Una concessione per linea di prodotto. Senza concessione la linea per il partner non esiste, e non c’è nessuna quota su cui appoggiare i suoi clienti.

Attribuiscigli i clienti

I clienti li attribuisci tu, non il partner. Finché un cliente non è attribuito, il partner non può emettergli nemmeno una chiave.

Emetti una chiave — se serve

Di norma lo fa il partner dal suo portale. Puoi farlo tu al posto suo dalla pagina del distributore, per un primo ordine o una migrazione.

Passo 1 — Crea il distributore

Nuovo distributore si apre su due modalità, perché un partner ti arriva in due stati diversi. Sbagliare modalità non rompe niente: leggi un errore che ti indica l’altra.

Collega uno spazio esistente

Il partner è già su Auris e diventa anche distributore.

Vai su Licenze → Distributori, clicca Nuovo distributore e scegli Collega uno spazio esistente
Realm del tenant — il realm del workspace che diventa distributore (per esempio acme-partner). Deve esistere, altrimenti leggi Nessun tenant con quel realm
Nome — lascialo vuoto per riusare il nome del workspace
Livello — testo libero per la tua segmentazione commerciale (gold, reseller, …). Non impone niente
Note — interne. Il partner non le vede mai
Clicca Crea

Questa modalità non manda nessun invito e non configura nessuna via d’ingresso. Attacca una riga a un workspace che ha già i suoi utenti e il suo accesso. Se in quel workspace nessuno riesce ad arrivare su partners.altovar.net, è un problema del workspace, non del distributore — e ⋮ → Rinvia invito non lo risolve, perché su quel realm non c’è nessun magic link del portale partner da rispedire. Per un partner che ancora non esiste, usa l’altra modalità.

Crea un nuovo spazio

Il partner è nuovo. Auris crea tutto lo spazio — realm Keycloak, workspace, utente proprietario — lo registra come distributore e spedisce al referente il link di primo accesso.

Nuovo distributore → Crea un nuovo spazio
Nome — la ragione sociale del partner
Slug del realm — diventa il nome dello spazio e non si potrà più cambiare. Lettere minuscole, numeri e trattini; deve cominciare con una lettera
Mail del referente — la persona di riferimento. Se non compili il campo successivo, è anche l’utente proprietario del nuovo spazio e il destinatario dell’invito
Mail di accesso (se diversa) — facoltativa. Se la compili, è lei l’identità: l’utente Keycloak, il proprietario dello spazio e il destinatario dell’invito. La mail del referente qui sopra resta allora solo un contatto, conservato sul distributore
Nome / Cognome del referente, Livello, Note — facoltativi
Clicca Crea spazio e distributore

Copia il link di primo accesso prima di chiudere il pannello. Il pannello del risultato ti dice se la mail è partita davvero e mostra sempre un Link di primo accesso: è così che consegni l’accesso a mano quando la mail non arriva. Scade 24 ore dopo essere stato coniato. Se chiudi senza copiarlo, usa ⋮ → Rinvia invito per coniarne uno nuovo; non cancellare e ricreare il partner, perché lo slug è bruciato dal momento in cui lo spazio esiste.

Un workspace può essere distributore una volta sola: al secondo tentativo leggi Quel tenant è già un distributore. Uno slug già usato da un altro spazio risponde Esiste già un tenant con questo slug, e un realm Keycloak rimasto senza il suo workspace risponde Esiste già un realm Keycloak con questo nome senza un tenant corrispondente.

Contatto e mail di accesso

Due indirizzi, una sola identità. È la distinzione che decide dove va l’invito.

Campo	Cos’è	Dove vive
Mail di accesso	L’identità: l’utente Keycloak, il proprietario dello spazio, il destinatario dell’invito e l’indirizzo con cui il portale autentica	Sul workspace, non sul distributore
Contatto	Un riferimento commerciale e nient’altro. Non autentica niente e dietro non esiste nessun utente	Sulla riga del distributore

Contatto vuoto significa uguale alla mail di accesso, non non lo sappiamo. Cambiare l’indirizzo con cui il referente entra è un’operazione sull’utente del workspace in Keycloak: da qui non si fa.

Rinvia invito

⋮ → Rinvia invito conia un link di primo accesso nuovo per il proprietario del partner e prova a spedirlo. Serve quando il primo invito non è arrivato, o quando hai chiuso il pannello senza copiare il link.

Non rifà niente: realm, workspace, utente e configurazione esistono già. Conia solo un link
Il destinatario è il proprietario attivo di quello spazio, non una tua scelta. Non c’è un campo dove scrivere un indirizzo, ed è voluto
Il link torna che la mail sia partita o no, perché consegnarlo a mano è esattamente il motivo per cui questo comando esiste
Questo spazio non ha nessun proprietario attivo (MEMBERSHIP_NOT_FOUND) e Il referente non esiste come utente nello spazio del partner (KEYCLOAK_USER_NOT_FOUND) vogliono dire che vanno prima sistemate le utenze: non è l’invito il problema

Riferimento contratto

Dalla pagina del distributore, ⋮ → Modifica porta Riferimento contratto e Data di firma. Sono un rimando al contratto firmato nell’ERP (CON-2026-0001), per chi legge la pagina: nessuna automazione li usa.

Modifica porta anche tre campi tutt’altro che decorativi: Contatto, Padre nella rete e Può creare sotto-distributori. Vedi Sotto-distribuzione qui sotto.

Passo 2 — Dagli le concessioni

Una concessione risponde a una domanda sola: questo partner cosa può vendere, e fino a che tetto? Si crea per linea, dalla pagina del distributore → Concessioni → Aggiungi concessione.

Linea	Cos’è	Produce chiavi
ERP	Altovar ERP, modulo per modulo	Sì
TALON	TALON	Sì
Cloud	Cloud	Sì
Drive	Drive	Sì
Menu	Menu	Sì
Restaurant	Restaurant	Sì
Siti	Siti per i clienti	No

Siti è una linea di servizio. I siti si evadono come progetto su contratto, quindi non esiste nessuna chiave di licenza. Concedi la linea per registrare che il partner la vende e per tenerne la quota clienti; nel modulo di emissione il partner non la troverà mai.

I moduli — la trappola

Sulla linea ERP la concessione porta l’elenco dei moduli che il partner può rivendere.

Nessun modulo selezionato significa NESSUNA restrizione. Un elenco moduli vuoto su una concessione permette al partner di vendere tutti i moduli ERP. Su una chiave lo stesso elenco vuoto significa l’opposto: una chiave senza moduli non abilita niente. Stesso controllo, due schermate, significato invertito. Il dialogo della concessione ti avvisa quando lasci tutto deselezionato: quell’avviso non è decorativo, leggilo.

In pratica:

Vuoi restringere — spunta esattamente i moduli che il partner può vendere. Tutto quello che chiede fuori da quell’elenco viene rifiutato (MODULES_NOT_GRANTED), e se non chiede niente riceve esattamente il tuo elenco, mai una chiave piena
Non vuoi restrizioni — lascia tutti i moduli deselezionati

Su un sotto-distributore, sotto un padre ristretto, «nessuna restrizione» non esiste. Un elenco vuoto è il superinsieme perfetto, quindi viene rifiutato con MODULES_NOT_IN_PARENT_GRANT: un figlio sotto un padre ristretto deve spuntare un sottoinsieme, non niente. La regola qui sopra vale solo per un partner diretto Altovar. Vedi Sotto-distribuzione.

Gli altri campi

Clienti max — il tetto di clienti per questa linea. Vuoto significa nessun limite. Sotto trovi quando morde davvero
Sconto % — è il numero da cui nasce il listino del partner. Nel suo portale, sotto Listino e margini, il partner vede il prezzo di listino di ogni piano di questa linea, lo stesso prezzo con questo sconto applicato (Il tuo prezzo) e la differenza (Il tuo margine). Non produce una fattura e non cambia una chiave, ma non è nemmeno un promemoria: non parcheggiare qui la cifra di una trattativa
Attiva — disattivare una concessione ferma l’emissione su quella linea senza cancellarla. Il partner smette di vedere la linea del tutto: al suo portale arrivano solo le concessioni attive, quindi una disattivazione non spiegata per lui è una linea sparita

Lo sconto è anche un tetto. A un sotto-distributore non si può concedere più che al padre (DISCOUNT_EXCEEDS_PARENT), e il padre non si può abbassare sotto un figlio che tiene già quella linea (CHILD_GRANT_EXCEEDS). Lo stesso vale per Clienti max. Per la stessa ragione disattivare o cancellare una concessione viene rifiutato finché un sotto-distributore tiene quella linea: il rifiuto elenca i figli da stringere prima.

Ogni linea può avere una sola concessione, quindi le linee che ne hanno già una non ti vengono più proposte: modifica quella esistente.

Passo 3 — Attribuisci i clienti

I clienti li attribuisce Altovar, mai il partner. Un partner non acquisisce un cliente emettendogli una chiave. Finché non attribuisci tu un workspace a un canale, ogni tentativo di emissione su quel workspace viene rifiutato con CUSTOMER_NOT_ATTRIBUTED, e il partner resta fermo finché non intervieni tu.

È voluto. Una chiave di tipo tenant in stato attivo è esattamente la forma che il gate ERP accetta: senza questa regola basterebbe conoscere il nome di un workspace per licenziare un cliente diretto Altovar e portarsi via la riga che lo dichiara proprio.

Dalla pagina del distributore → Clienti → Aggiungi cliente:

Realm del tenant — il realm del workspace cliente. Deve esistere già
Linea di prodotto — sono elencate solo le linee per cui il partner ha una concessione. Se non ne ha nessuna, il dialogo ti dice di aggiungere prima una concessione
Note — interne
Clicca Aggiungi

L’attribuzione è per linea

Lo stesso cliente si attribuisce una volta per linea. Un cliente che compra ERP e Cloud dallo stesso partner sono due attribuzioni, una per linea — e nell’elenco distributori continua a contare come un cliente solo.

La linea decide una cosa sola: quale quota consuma quell’attribuzione. Non decide mai l’accesso, quindi una linea sbagliata costa un posto sulla concessione sbagliata e nient’altro. Si rimedia togliendo la riga e rimettendola sulla linea giusta.

La quota morde qui

Clienti max si applica quando attribuisci, non quando il partner emette. Attribuire un cliente oltre il tetto di quella linea viene rifiutato; il partner non vede mai il muro contro cui hai sbattuto tu.

Ri-attribuire un cliente che è già su quella linea è idempotente: non consuma un secondo posto.

C’è un caso in cui è il partner a incontrare il tetto: estendere un cliente esistente a una linea nuova. Un cliente attribuito su Cloud, licenziato su ERP, è un cliente nuovo per la quota ERP, e l’emissione lo scrive.

Un cliente, un solo canale

Un workspace appartiene a un canale solo. Attribuire un cliente che è già di un altro distributore viene rifiutato con CUSTOMER_ATTRIBUTED_ELSEWHERE: il secondo canale non vince in silenzio, e il cliente non finisce condiviso.

Passare un cliente a un altro canale

⋮ → Trasferisci a un altro canale, sulla riga del cliente. Il cliente cambia partner in un colpo solo: nessuna chiave viene revocata o riemessa, quelle attive restano attive e cambiano soltanto canale, e il cliente finale non subisce nessuna interruzione.

Si sposta il cliente per intero, con tutte le linee che ha in quel canale: la riga su cui hai cliccato è solo la maniglia, non si trasferisce una linea per volta.

Il destinatario deve superare le stesse domande di un’attribuzione nuova — attivo, con la linea in concessione, catena a monte attiva, e con la sua quota clienti contata come se il cliente entrasse adesso. In più i moduli delle chiavi che eredita devono stare dentro la sua concessione: non vengono ristretti in silenzio, il trasferimento viene rifiutato (MODULES_NOT_GRANTED).

Il trasferimento è un atto del registro, e il registro è di Altovar: non esiste dal portale partner. Un partner non si porta via i clienti da solo, né li cede da solo. L’evento di audit viene scritto sul tenant di entrambi i partner: la traccia resta anche a chi perde il cliente.

Rimuovere un cliente

⋮ → Rimuovi cliente stacca il collegamento. Il workspace non viene toccato: mantiene utenti, dati e, se gliele lasci, le chiavi.

La rimozione viene rifiutata finché quel cliente ha ancora chiavi attive o sospese in quel canale, su qualunque linea (CUSTOMER_HAS_KEYS, con il conteggio nel messaggio). Prima revocale o lasciale scadere, altrimenti il canale continuerebbe a licenziare un cliente che sulla carta non è suo.

Passo 4 — Emetti una chiave per il partner

Puoi emettere al posto del partner dalla pagina del distributore → Emetti chiave. Il campo Distributore è precompilato e bloccato: la chiave finisce in quel canale.

Il resto è il normale modulo di emissione — policy, licenziatario, Piano ERP, scadenza, moduli ERP.

Il piano non è facoltativo su una chiave di canale

Sulla linea ERP, una chiave attribuita a un distributore deve dichiarare il piano venduto. Non è un campo informativo: da quello slug nascono le due cose che il prodotto legge davvero.

Cosa scrive il piano sulla chiave	Cosa succede se manca
Le quote (utenti, e-fatture al mese)	L’ERP del cliente legge nessun tetto: Free e Business diventano la stessa cosa
I moduli che quel piano contiene	L’ERP accende tutto, verticali a pagamento compresi — l’assenza è fail-open, non «nessuna restrizione»

I numeri del piano non si ritoccano. L’API confronta i limiti della chiave con quelli di listino per valore: uno Starter con gli utenti portati da 3 a 5 non è più nessun piano e viene rifiutato con ERP_CHANNEL_PLAN_REQUIRED — lo stesso codice del piano mancante, su un’emissione in cui il piano l’hai scelto. Il dialogo te lo dice prima di lasciarti inviare. Nella vendita diretta quei campi restano modificabili come sempre: il vincolo riguarda le sole chiavi con un distributore.

Su una chiave, nessun modulo selezionato significa che la chiave non abilita niente. È l’inverso della schermata della concessione. Su una chiave di canale il piano è anche il tetto dei moduli: almeno uno va spuntato (ERP_CHANNEL_MODULES_REQUIRED) e nessuno può stare fuori dal piano scelto (ERP_CHANNEL_MODULES_ABOVE_PLAN). I verticali — hotel, ristorante, POS, e-commerce, field service, flotta, noleggio — non appartengono a nessun piano: dal canale non si vendono.

Nove moduli sono spuntabili e non stanno in nessun piano, e due di essi non sono nemmeno add-on. Ai sette verticali qui sopra si aggiungono Archivio (dms) e Risorse umane (hr): il dialogo di emissione li offre — sono moduli vendibili dell’ERP — ma nessun tier di listino li concede e, a differenza dei verticali, non c’è nemmeno un add-on che li venda. Su una chiave di canale non sono quindi ottenibili in nessun modo: salire di piano non serve, e spuntarli spegne il bottone. Si emettono solo su una vendita diretta, dove i moduli non hanno tetto. Il dialogo adesso lo dice, nominando i moduli che hai spuntato. Se devono diventare vendibili dal canale, la decisione è di listino e non si prende da questa schermata: parlane con chi tiene il listino ERP.

Cosa viene confrontato e cosa no. Attribuire una chiave a un canale da Licenze → Chiavi richiede lo stesso permesso di piattaforma delle pagine distributori, e da qui passano gli stessi controlli sul cliente: non può essere già di un altro canale (CUSTOMER_ATTRIBUTED_ELSEWHERE), e se non era ancora attribuito la riga nasce qui e consuma un posto del tetto Clienti max (MAX_CUSTOMERS_REACHED). Il piano ERP è obbligatorio come sopra. L’elenco moduli della concessione invece no: quello vive nel percorso di emissione del partner, quindi da qui puoi spuntare un modulo dentro il piano ma fuori da ciò che quel partner ha il diritto di rivendere. È una tua decisione, non una svista: prendila consapevolmente.

Cambiare piano a un cliente di canale

Un cliente che passa da Starter a Business non ha più bisogno di una chiave nuova. Il piano di una chiave ERP di canale si riscrive sul posto: stessa chiave, stesso JWT, stato invariato, nessuna interruzione per il cliente finale. Prima l’unica strada era revoca e riemissione — cioè l’interruzione di servizio sull’evento più frequente che ci sia.

Il bottone ce l’ha il partner, non tu. L’operazione è una rotta dell’API partner — POST /api/partner/distribution/keys/{id}/plan, permesso manage:distribution sullo spazio del partner — e la compie il partner sul proprio cliente. Nel suo portale è Licenze → ⋮ → Cambia piano. In Console non esiste: qui non c’è nessuna rotta equivalente, e la rotta admin di emissione non misura l’elenco moduli della concessione (vedi il riquadro qui sopra). Se un partner ti chiede l’upgrade, mandalo al suo portale.

Vale quello che vale all’emissione, misurato adesso e non quando la chiave nacque: partner attivo, catena a monte viva, linea erp concessa e attiva, moduli dentro l’intersezione fra piano e concessione. L’attribuzione del cliente non viene toccata e nessun posto di Clienti max viene consumato: il cliente c’era già.

Codice	Cosa è successo	Cosa fare
`KEY_NOT_ERP`	Un cambio di piano su una chiave che non è ERP	Il piano è una nozione della sola linea ERP: sulle altre non c’è niente da cambiare
`KEY_NOT_LIVE`	La chiave è revocata o scaduta	Su una chiave morta non c’è nessun servizio da non interrompere: serve una chiave nuova
`PLAN_MODULES_NOT_GRANTED`	Il piano e la concessione non hanno un modulo in comune	Allarga la concessione, o vendi un piano che la concessione copre. Una chiave senza moduli non aprirebbe niente
`MODULES_EMPTY`	È stato spedito un elenco moduli vuoto	Ometti il campo per avere il tetto (piano ∩ concessione): l’elenco vuoto blocca tutto

Sotto-distribuzione

Un partner può rivendere attraverso un altro partner. La rete è un albero: il livello 1 è un partner diretto Altovar, il livello 2 il suo sotto-distributore, il livello 3 l’ultimo ammesso.

Tutto discende da una frase sola: quello che un figlio può fare è un sottoinsieme di quello che può fare suo padre. Quello che segue è quella frase applicata.

Chi può creare un sotto-distributore

Nessuno, per default. Il diritto è un interruttore sul partner — ⋮ → Modifica → Può creare sotto-distributori — e lo alzi solo tu. Se lo attivi, il partner apre sotto-distributori dal suo portale, senza chiedertelo: compila nome, identificativo e la mail del referente, e Auris crea lo spazio del figlio e conia il suo link di primo accesso, che è il padre a consegnare.

Le condizioni le decidi comunque tu. Il figlio nasce senza nessuna concessione e con il proprio diritto di sotto-distribuire spento, quindi finché non gli concedi una linea non vende niente. Un padre che potesse scriversi da solo le concessioni del figlio deciderebbe di fatto lo sconto che incassa Altovar.

Perché tre livelli

Il margine di un padre è la differenza fra il proprio sconto e quello del figlio. Ogni livello ritaglia una fetta dello stesso sconto, sullo stesso prezzo di listino — e il listino ERP parte da 9 EUR al mese. Un quarto livello dovrebbe stare sotto il terzo, cioè lavorare a margine circa zero. La catena si ferma a tre (MAX_DEPTH_EXCEEDED), e il controllo gira sia quando nasce un figlio sia quando ri-attacchi un partner che esisteva già: ri-attaccare un partner che ha già dei figli sprofonda anche loro, e vengono contati.

Cosa deve rispettare la concessione di un figlio

Quando scrivi una concessione su un partner che ha un padre, viene confrontata con quella del padre sulla stessa linea:

Regola	Rifiuto
Il padre deve avere quella linea, attiva	`LINE_NOT_IN_PARENT_GRANT`
I moduli devono essere un sottoinsieme. Sotto un padre ristretto l’elenco vuoto è rifiutato: significa nessuna restrizione, cioè un superinsieme	`MODULES_NOT_IN_PARENT_GRANT`
Lo sconto deve essere minore o uguale a quello del padre	`DISCOUNT_EXCEEDS_PARENT`
Il tetto clienti non deve superare quello del padre. Sotto un padre con un tetto, nessun limite è rifiutato per la stessa ragione dell’elenco vuoto	`MAX_CUSTOMERS_EXCEEDS_PARENT`

Lo stesso patto guardato dall’altra parte: non puoi stringere, disattivare o cancellare la concessione di un padre finché un figlio resta fuori dalla forma nuova (CHILD_GRANT_EXCEEDS). Al figlio non viene abbassato niente in silenzio — quei termini li ha firmati un terzo — quindi il rifiuto elenca i figli da sistemare prima.

La sospensione scende lungo la catena

Sospendere o cessare un partner ferma ogni partner sotto di lui. I discendenti restano ACTIVE per conto loro, eppure non possono più emettere, né sospendere o riattivare le chiavi dei loro clienti, né allargare la propria rete: leggono CHAIN_NOT_ACTIVE. Lo stesso succede se togli una linea a un padre: il figlio legge LINE_NOT_GRANTED_UPSTREAM su quella linea.

Ma non sapranno di chi si tratta. La risposta dell’API identifica il partner a monte, mentre il portale partner mostra di proposito solo un distributore sopra di te è sospeso o cessato e li manda al loro referente commerciale. Quindi la telefonata arriva a te, da un partner la cui pagina dice attivo — ed è l’unico caso in cui il suo stato non è la risposta.

Nessuna chiave dei clienti viene toccata da tutto questo. La catena controlla l’atto commerciale, non la licenza già consegnata: il cliente finale ha comprato un prodotto, non un canale, e spegnerlo per un contratto saltato due livelli più su lo punirebbe per qualcosa di cui non sa nulla.

All’emissione, i moduli davvero concedibili sono l’intersezione lungo tutta la catena. Quando due elenchi ristretti non hanno niente in comune la linea viene rifiutata con MODULES_NOT_GRANTED, invece di essere letta come nessuna restrizione.

Togliere un partner da una catena

L’eliminazione viene rifiutata finché un partner ha figli (DISTRIBUTOR_HAS_CHILDREN): cancellare il padre promuoverebbe ogni figlio a partner diretto Altovar, perché il tetto di sconto, il tetto clienti e il sottoinsieme di moduli vivono tutti sulla riga del padre. La via d’uscita è Cessa.

Staccare un singolo partner è un atto esplicito e voluto: ⋮ → Modifica → Padre nella rete → Nessuno. Lo promuove a diretto Altovar — sopra di lui non c’è più nessun tetto — e lascia una riga di audit. Fallo sapendolo.

Licenza operativa

Due diritti diversi, e le concessioni esprimono solo il primo:

Una concessione dice cosa il partner può vendere ai suoi clienti. Sul suo schermo non sblocca niente
La licenza operativa dice cosa può usare per lavorare. È una normale licenza ERP sul workspace del partner

Dalla pagina del distributore, la card Licenza operativa la concede e la revoca. Il profilo dei moduli lo decide la piattaforma e non si sceglie da qui: crm, documents, finance, projects, calendar, subscriptions, products, inventory, billing. La scadenza è facoltativa.

Non è una vendita di canale, ed è voluto. La chiave non è attribuita al canale del partner, quindi non compare fra le chiavi che ha venduto, non entra nei contatori del suo portale e non rende indelebile un partner che non ha mai venduto niente. Un partner che ha anche comprato l’ERP come cliente si tiene quella licenza intatta: revocare la licenza operativa tocca solo quella concessa da qui.

Cessa non la spegne. Un partner cessato si tiene l’ERP funzionante: il cambio di stato non tocca questa chiave. Il rapporto finisce sulla carta e l’ex partner continua a usare il prodotto. Se non è quello che avete concordato, revoca tu la licenza operativa: il cambio di stato non lo farà al posto tuo.

Elimina viene rifiutata finché la licenza è viva (DISTRIBUTOR_HAS_OPERATING_LICENSE). Rifiutata e non revocata d’ufficio, perché cancellare una riga di registro non deve spegnere in silenzio l’accesso di qualcuno: revocare è un atto suo, con la sua riga di audit. Quindi l’ordine è revoca, poi cessa, poi elimina.

Per cambiare profilo non c’è una modifica: revoca, poi concedi di nuovo. Una seconda concessione sopra una viva viene rifiutata (OPERATING_LICENSE_EXISTS), così «la» licenza operativa resta identificabile.

Sospendere, cessare, eliminare

Dalla pagina del distributore, il menu ⋮:

Azione	Effetto
Sospendi	Il partner è bloccato finché non lo riattivi — e con lui ogni partner sotto di lui
Cessa	Il rapporto viene segnato come chiuso. Stesso effetto a valle. Non tocca la licenza operativa
Elimina	Rimuove il distributore, le sue concessioni e i collegamenti ai clienti. Rifiutata se il canale ha chiavi, se il partner ha figli, o se tiene ancora una licenza operativa

Un distributore sospeso o cessato non può emettere chiavi, e non può nemmeno sospendere o riattivare quelle che ha già emesso (DISTRIBUTOR_NOT_ACTIVE). Cambiare stato a una chiave è un atto commerciale su un cliente vivo, quindi vuole la stessa legittimazione dell’emissione: un ex partner non deve poter staccare un cliente che non è più suo.

Le chiavi già emesse non vengono toccate da sospensione o cessazione: i clienti esistenti continuano a lavorare. Per staccare un cliente specifico, agisci sulla chiave.

L’eliminazione viene rifiutata non appena il canale ha una chiave (DISTRIBUTOR_HAS_KEYS), il partner ha sotto-distributori (DISTRIBUTOR_HAS_CHILDREN), o tiene ancora una licenza operativa (DISTRIBUTOR_HAS_OPERATING_LICENSE). La via d’uscita da un rapporto è Cessa, non Elimina.

La licenza operativa si controlla a parte, e Cessa non la controlla affatto. Quella chiave non è attribuita al canale di proposito, quindi non rientra in DISTRIBUTOR_HAS_KEYS: Elimina la cerca per conto suo. Cessa no: un partner cessato si tiene una licenza ERP viva finché non la revochi a mano. È quello il caso in cui non ti ferma niente.

Cosa fa il partner da solo

Su partners.altovar.net il partner vede il suo accordo e il suo canale, e da solo aggiunge clienti (workspace esistente o uno nuovo), emette chiavi per loro sulle linee concesse, entro i moduli ammessi, poi le sospende e le riattiva — e cambia il piano di una chiave ERP che ha già emesso, sul posto, senza staccare niente al cliente. Dalla riga cliente può generare un sito nel proprio ERP (la licenza operativa si ritira da sola se ancora mancava) oppure chiederlo ad Altovar.

Legge anche il suo listino — ma solo chi nel suo spazio ha manage:distribution, non ogni membro — e, solo se hai acceso tu il diritto, crea i propri sotto-distributori dalla pagina La mia rete.

Non può spostare un cliente a un altro canale, cambiare le proprie concessioni, alzarsi il tetto, revocare una chiave, darsi il diritto di sotto-distribuire, scrivere le concessioni dei suoi figli, ri-coniare un invito o leggere le note che scrivi su di lui. Tutto quell’elenco torna a te.

Manda i partner alla guida al Portale Partner.

Permessi

Permesso	Chi	Cosa consente
`manage:distributors`	Amministratori di piattaforma Altovar	Tutta la sezione Distributori: distributori, concessioni, clienti, attribuzione al canale in fase di emissione, licenza operativa, Rinvia invito — e collegare uno spazio esistente
`provision:distributor-tenants`	Amministratori di piattaforma Altovar	Solo la modalità Crea un nuovo spazio: coniare un realm Keycloak, un workspace e l’invito al proprietario
`read:distribution`	I membri del partner stesso	Leggere il proprio spazio di distribuzione: accordo, clienti, chiavi e sotto-distributori. Non il listino
`manage:distribution`	Gli amministratori del partner stesso	Emettere, sospendere, riattivare e cambiare piano dentro il proprio canale, aggiungere clienti, ritirare la licenza operativa, aprire una richiesta sito, leggere il listino — e, solo dove `canSubdistribute` è acceso, creare sotto-distributori

Il listino non è una lettura come le altre. read:distribution sta nei permessi che ogni membership MEMBER ha per costruzione, ed è giusto per l’accordo, i clienti, le chiavi e la rete — dati operativi. La pagina Listino e margini no: mette in chiaro il prezzo di listino accanto al prezzo scontato, cioè il margine riga per riga, che è la posizione commerciale del rapporto con Altovar. Sta quindi dietro manage:distribution, che un MEMBER non ha e che un amministratore del tenant partner non può nemmeno ri-concedersi componendo un ruolo custom. Un membro che apre quella pagina legge non hai i permessi, e nella sua barra laterale la voce Listino non compare proprio. Concedere read:distribution a un referente commerciale non gli apre il listino.

Perché provision:distributor-tenants è separato. Collegare un tenant esistente scrive una riga in un registro; creare uno spazio conia uno spazio di autenticazione che Auris servirà per sempre. Un amministratore che ha solo manage:distributors vede la modalità Crea un nuovo spazio e viene rifiutato quando la invia: Non hai il permesso di creare spazi per i distributori. È quello il permesso da chiedere.

manage:distribution è più largo di «emetti e sospendi». Su un partner con canSubdistribute acceso, quello stesso permesso crea sotto-distributori — cioè crea realm Keycloak. Pesalo prima di concederlo a un’integrazione M2M del partner: lo scope M2M arriva esattamente dove arriva una sessione del portale.

manage:distributors e provision:distributor-tenants vengono valutati solo sul workspace di piattaforma Altovar. Possedere un workspace ed esserne amministratore non permette a nessuno di gestire i distributori da casa propria, qualunque workspace dichiari.

Messaggi che puoi incontrare

Questa tabella è esaustiva per costruzione, e da adesso lo è in modo verificabile: un controllo (apps/docs/scripts/check-distribution-codes.mjs, agganciato al lint dei docs) confronta i codici citati qui con le TRE mappe che li traducono in risposte HTTP nell’API — le due tabelle di stato piu’ quella con cui la rotta che registra un partner risponde — in entrambe le direzioni e in entrambe le lingue. Un codice nuovo che nessuno documenta fa fallire il controllo. La terza mappa e’ entrata il 2026-09-06, dopo che due suoi codici erano nati senza che nessuna guida li nominasse e il controllo fosse rimasto verde: aveva la forma sbagliata per essere vista.

Codice	Cosa è successo	Cosa fare
`TENANT_NOT_FOUND`	Nessun workspace con quel realm	Crea prima il workspace, o controlla come l’hai scritto
`DISTRIBUTOR_EXISTS`	Quel workspace è già un distributore	Apri quello esistente
`TENANT_IS_CHANNEL_CUSTOMER`	Quel workspace è già cliente attribuito di un canale, e un cliente di canale non può essere anche partner	Il messaggio nomina il canale e la linea: stacca prima l’attribuzione (o trasferisci il cliente), poi registralo come partner
`SLUG_TAKEN`	Lo slug scelto per il nuovo spazio è già di un altro workspace	Scegline un altro
`SLUG_INVALID`	Lo slug non rispetta i vincoli, oppure è uno di quelli riservati	Il messaggio dice quale vincolo: lunghezza, formato o slug riservato
`REALM_EXISTS`	In Keycloak esiste già un realm con quel nome, senza il tenant corrispondente	Scegli un altro slug, oppure fai pulire il realm orfano: non è uno stato da cui la creazione possa uscire da sola
`DISTRIBUTOR_NOT_FOUND`	Il distributore indicato non esiste (più)	Ricarica la pagina: qualcuno può averlo eliminato mentre la tenevi aperta
`CUSTOMER_ATTRIBUTED_ELSEWHERE`	Il cliente è di un altro canale	Staccalo prima dall’altro canale, o trasferiscilo
`MAX_CUSTOMERS_REACHED`	Il tetto di quella linea è pieno	Alza Clienti max sulla concessione, o libera un posto
`MAX_CUSTOMERS_BELOW_CURRENT`	Hai scritto un tetto sotto i clienti già attribuiti su quella linea	Il messaggio porta il conteggio vero: togli prima qualche cliente, o alza il tetto
`CUSTOMER_HAS_KEYS`	Il cliente ha ancora chiavi vive nel canale	Revocale o lasciale scadere, poi togli l’attribuzione
`CUSTOMER_NOT_ATTRIBUTED`	Il partner ha provato a emettere per un workspace che non hai mai attribuito	Attribuisci il cliente su quella linea
`CUSTOMER_NOT_ALLOWED`	Il bersaglio non può essere cliente di un canale: è il workspace di piattaforma Altovar, oppure il distributore stesso	Un partner licenzia clienti, mai se stesso. Per l’ERP che usa lui, vedi Licenza operativa
`CUSTOMER_IS_DISTRIBUTOR`	Il bersaglio è il workspace di un altro distributore	Un partner non è un cliente di canale, nemmeno un sotto-distributore: quel rapporto si esprime con le concessioni
`CUSTOMER_NOT_ACTIVE`	Il workspace del cliente è disattivato	Riattivalo se il cliente è davvero ancora vivo: attribuire o emettere brucerebbe un posto per un tenant che Altovar considera chiuso
`CHANNEL_LICENSEE_MUST_BE_TENANT`	Hai emesso con un distributore ma un licenziatario che non è un workspace (utente, e-mail, dispositivo, organizzazione)	Una chiave di canale è sempre licenziata a un workspace: la riga cliente, il tetto e «un cliente, un canale» sono tutti definiti lì
`TRANSFER_SAME_DISTRIBUTOR`	Hai trasferito un cliente al canale che ce l’ha già	Scegli un altro destinatario: non c’è niente da spostare
`LINE_NOT_GRANTED`	La linea non ha concessione, la concessione è inattiva, oppure è `siti`. In un trasferimento è il destinatario a non averla	Aggiungi o riattiva la concessione — su chi riceve, se stai trasferendo
`MODULES_NOT_GRANTED`	Sono stati chiesti moduli fuori dalla concessione. In un trasferimento sono i moduli delle chiavi che il destinatario eredita	Allarga la concessione di chi riceve. Le chiavi non vengono ristrette in silenzio
`DISTRIBUTOR_NOT_ACTIVE`	Un partner sospeso o cessato ha provato a emettere, a cambiare stato a una chiave o a cambiarne il piano — o è il destinatario di un trasferimento	Riattiva il distributore se il rapporto è vivo
`DISTRIBUTOR_HAS_KEYS`	Hai provato a eliminare un canale che ha chiavi	Usa Cessa
`POLICY_NOT_FOUND`	La linea è concessa ed emettibile, ma la sua policy di licenza manca o è disattivata	È un problema di configurazione tuo, non un limite del partner: controlla la policy di quella linea
`MODULES_UNKNOWN`	Un id di modulo che il catalogo ERP non conosce	Correggi l’elenco moduli: un id inventato non sbloccherebbe niente
`EXPIRES_AT_IN_PAST`	Una scadenza già passata	Il cliente riceverebbe una chiave già morta. Metti una data futura, o nessuna

Il piano ERP di una chiave di canale

Codice	Cosa è successo	Cosa fare
`ERP_CHANNEL_PLAN_REQUIRED`	Una chiave ERP con un distributore senza piano, oppure con limiti che non sono più quelli di nessun piano di listino	Scegli il Piano ERP, e lascia i suoi numeri come stanno
`ERP_CHANNEL_PLAN_MISMATCH`	La chiave dichiara un piano e porta le quote di un altro	Una chiave che dice Business e vale Free è peggio di una senza piano: fai coincidere le due cose
`ERP_CHANNEL_MODULES_REQUIRED`	Nessun modulo spuntato su una chiave di canale	Un elenco assente accende tutto, uno vuoto non accende niente: spuntane almeno uno
`ERP_CHANNEL_MODULES_ABOVE_PLAN`	Moduli fuori dal piano scelto	Il piano è il tetto. Verticali, `dms` e `hr` non stanno in nessun piano: dal canale non si vendono, e un piano più alto non li contiene

Sotto-distribuzione e licenza operativa

Codice	Cosa è successo	Cosa fare
`SUBDISTRIBUTION_NOT_ALLOWED`	Un partner ha provato a creare un sotto-distributore senza averne il diritto	Accendi Può creare sotto-distributori su quel partner, se l’accordo è quello
`CHAIN_NOT_ACTIVE`	Un partner sopra questo è sospeso o cessato	Guarda a monte: lo stato del partner è a posto, la sua catena no
`CHAIN_CYCLE`	La catena a monte si avvolge su se stessa	Non è un limite di nessuno: è il registro in uno stato che va guardato. Segnalalo
`CHAIN_TOO_DEEP`	La catena a monte è più profonda dei tre livelli ammessi	Come sopra: nessuno può risolverlo riprovando
`SUBDISTRIBUTION_DEPTH_EXCEEDED`	Hai acceso Può creare sotto-distributori su un partner già all’ultimo livello	Non accenderlo: gli daresti un bottone che risponde sempre con un rifiuto
`MAX_SUBDISTRIBUTORS_REACHED`	Un partner ha già il numero massimo di figli	Il messaggio porta il conteggio e il tetto: la sua rete non si allarga oltre
`LINE_NOT_GRANTED_UPSTREAM`	Un partner sopra questo non ha una concessione attiva su quella linea	Ripristina la linea a monte, oppure toglila a valle
`LINE_NOT_IN_PARENT_GRANT`	La concessione del figlio nomina una linea che il padre non ha	Concedila prima al padre
`MODULES_NOT_IN_PARENT_GRANT`	I moduli del figlio non sono un sottoinsieme, oppure l’elenco è vuoto sotto un padre ristretto	Spunta un sottoinsieme. Sotto un padre ristretto «nessuna restrizione» non è disponibile
`DISCOUNT_EXCEEDS_PARENT`	Lo sconto del figlio supera quello del padre	Abbassa il figlio, o alza prima il padre
`MAX_CUSTOMERS_EXCEEDS_PARENT`	Il tetto del figlio supera quello del padre, o è nessun limite sotto un padre con tetto	Metti un tetto minore o uguale a quello del padre
`CHILD_GRANT_EXCEEDS`	Hai stretto, disattivato o cancellato una concessione del padre mentre dei figli restano fuori	Il messaggio elenca i figli: stringi prima loro
`DISTRIBUTOR_HAS_CHILDREN`	Hai provato a eliminare un partner che ha sotto-distributori	Usa Cessa, o ri-attacca prima i figli
`MAX_DEPTH_EXCEEDED`	La catena andrebbe oltre i tre livelli	Non c’è niente da correggere: la rete si ferma a tre
`PARENT_SELF`	Un distributore è stato messo come padre di se stesso	Scegli un altro padre
`PARENT_CYCLE`	Il padre scelto sta già sotto questo partner	Scegli un padre fuori dal sottoalbero di questo partner
`PARENT_NOT_FOUND`	Il padre non esiste più	Ricarica la pagina
`OPERATING_LICENSE_EXISTS`	Il partner ha già una licenza operativa viva	Per cambiare profilo: revoca, poi concedi di nuovo
`OPERATING_LICENSE_NOT_FOUND`	Hai provato a revocare senza nessuna licenza operativa concessa	Non c’è niente da revocare
`DISTRIBUTOR_HAS_OPERATING_LICENSE`	Hai provato a eliminare un partner con la licenza operativa ancora viva	Revocala dalla card Licenza operativa, poi elimina
`TRANSACTION_FAILED`	La transazione non è arrivata in fondo mentre registravi un partner, attribuivi un cliente o emettevi una chiave	Non è stato scritto niente. Riprova: non è uno stato sporco
`MEMBERSHIP_NOT_FOUND`	Rinvia invito su uno spazio senza nessun proprietario attivo	Sistema prima le utenze dello spazio
`KEYCLOAK_USER_NOT_FOUND`	L’indirizzo del proprietario non ha un utente Keycloak in quel realm	Sistema prima le utenze: spedire il link lo farebbe atterrare nel realm sbagliato

Correlati

Licenze — policy, chiavi, postazioni, dispositivi
Portale Partner — la guida da passare ai tuoi partner
Licenze Software — validare le chiavi dentro un prodotto