Creare un account POP e attivare SdI/PEPPOL parlando con un assistente AI

Obiettivo

Creare un nuovo account POP e attivare SdI (Italia/San Marino) o PEPPOL (resto UE) interamente in chat con un assistente AI collegato al server MCP remoto — senza aprire popapi.io né compilare form.

Prerequisiti

• Un client MCP collegato a https://mcp.popapi.io/mcp (vedi mcp-remote) — per questo flusso non serve ancora una license_key, quindi puoi collegarti anche senza account.
• Un indirizzo email valido, raggiungibile.

Il flusso (5 passi)

L’assistente userà, in ordine, questi 5 strumenti:

1. pop_onboarding_request_otp — chiedi all’assistente di avviare la registrazione con la tua email. Se l’account non esiste, viene creato automaticamente. Il codice OTP arriva anche via email, ma l’assistente lo riceve già nella risposta.
2. pop_onboarding_verify_otp — dai all’assistente il codice OTP (scade in 10 minuti): in cambio ottieni un onboarding_token temporaneo (valido 30 minuti), che l’assistente userà per te nei passi successivi.
3. pop_onboarding_get_status (opzionale) — per controllare a che punto sei prima di procedere.
4. pop_onboarding_get_account_setup — l’assistente recupera i campi ancora da compilare (paese, ragione sociale, partita IVA, regime fiscale, ecc.) e i valori ammessi (es. elenco regimi fiscali per il tuo paese).
5. pop_onboarding_save_account_setup — fornisci i dati mancanti (in linguaggio naturale, li traduce l’assistente); a questo punto puoi anche chiedere di attivare SdI o PEPPOL nella stessa richiesta.

Attivare SdI o PEPPOL nello stesso flusso

• SdI (solo account IT/SM) — chiedi di attivarlo: l’assistente imposta active_sdipop_integration = 1 e active_peppol_integration = 0.
• PEPPOL (altri paesi UE) — chiedi di registrare la legal entity PEPPOL: servono indirizzo, città, CAP e lo schema/identificativo PEPPOL: l’assistente li recupera dai lookup del passo 4 se non li sai a memoria.
• SdI e PEPPOL sono mutuamente esclusivi: non puoi attivarli entrambi sullo stesso account.

Dopo l’attivazione

Una volta completato il wizard, recupera la tua license_key da Account > API su popapi.io (vedi get-your-license-key) per iniziare a generare fatture — quella è la chiave che userai per autenticare le chiamate “normali” (creazione fatture), diversa dall’onboarding_token usato solo durante questo flusso.

Da sapere

• Nessuno dei 5 strumenti di onboarding richiede l’header Authorization: Bearer — usano solo onboarding_token (o niente, nel primo passo).
• Se hai un account amministratore, non ricevi un OTP: usa la tua password admin come “OTP” al passo 2.
• Una volta che wizard_completed è vero, richiamare di nuovo il salvataggio non sovrascrive nulla: torna solo lo stato attuale.
• I campi PEPPOL, una volta registrata la legal entity, restano bloccati permanentemente (non modificabili in autonomia).

Errori comuni

• OTP scaduto — hai aspettato più di 10 minuti tra richiesta e verifica: ripeti dal passo 1.
• onboarding_token scaduto — è passata più di mezz’ora dal passo 2: non esiste un refresh, si riparte dalla richiesta OTP.
• Partita IVA già in uso — errore 422 durante il salvataggio: quella partita IVA è già associata a un altro account sull’ambiente scelto (live/sandbox).
• Campo bloccato non modificabile — alcuni campi restano fissi dopo il primo salvataggio (es. paese, o tutti i campi PEPPOL dopo la registrazione): va aperto un ticket di supporto per cambiarli.

Configurazione correlata

Per il dettaglio tecnico del protocollo sottostante (stesso flusso, chiamate REST dirette) vedi api/onboarding. Per collegare l’assistente vedi mcp-remote.