Onboarding API

Base path: onboarding/v1. Flusso headless, indipendente dal login via browser/tema, pensato per MCP, LLM e integrazioni esterne.

Flusso

POST /request-otp → POST /verify-otp → GET /status → GET /account-setup → POST /account-setup

Dopo verify-otp, tutte le chiamate richiedono onboarding_token (header X-Onboarding-Token o query onboarding_token), valido 1800 secondi — non è una credenziale permanente.

Passi

1. POST /request-otp — valida l’email, crea l’account se non esiste, genera OTP.
2. POST /verify-otp — verifica OTP (o password admin), restituisce onboarding_token e next_action (se completed, l’account è già configurato).
3. GET /status — stato corrente del wizard.
4. GET /account-setup — payload completo: valori salvati, lookup, capability.
5. POST /account-setup — salva la configurazione, attiva SdI/PEPPOL/KSeF/ZUGFeRD in base al paese.

Da sapere

• il flusso copre varianti per IT/SM (SdI), altri paesi UE (PEPPOL) e Germania (corridoio ZUGFeRD/PEPPOL)
• configurations restituito da GET /account-setup contiene solo valori salvati e coerenti
• questo stesso flusso è esposto anche come 5 strumenti MCP (pop_onboarding_*) sul server MCP remoto, pensati per farsi guidare da un assistente AI invece di chiamare le route direttamente — vedi onboard-via-ai-assistant
• per i paesi GCC senza una rete di fatturazione elettronica ufficiale (AE, SA, BH, KW, OM, QA), l’unico canale di fatturazione disponibile è il connector nativo Zoho (configurations.connector) — nessun canale fiscale ufficiale SdI/PEPPOL/KSeF è previsto per questi account
• general_store_vat_number valida il formato per IT, SM e altri 33 paesi; il messaggio di errore 422 include un esempio di formato specifico per paese quando il valore non corrisponde
• attivare un’integrazione non coerente con il paese dell’account restituisce un 422 esplicito (es. active_sdipop_integration: 1 su un account non IT/SM, active_peppol_integration: 1 su un paese non PEPPOL, active_ksef_integration: 1 su un paese diverso da PL)