Nota bene: la traduzione in italiano di questo articolo è fornita solo per comodità. La traduzione viene creata automaticamente tramite un software di traduzione e potrebbe non essere stata revisionata. Pertanto, la versione inglese di questo articolo deve essere considerata come la versione di governo contenente le informazioni più recenti. È possibile accedervi qui.

Trasferire i contratti su HubSpot

Ultimo aggiornamento: 23 luglio 2026

Disponibile con uno qualsiasi dei seguenti abbonamenti, tranne dove indicato:

Revenue Hub Professional, Enterprise

Postazioni richieste

Abbonamento richiesto A Revenue Hub è necessario un abbonamento a Revenue Hub per migrare i contratti.

Postazioni richieste È necessario disporre di un Revenue Hub per eseguire la migrazione dei contratti.

Autorizzazioni richieste Per eseguire la migrazione sono necessari i permessi di Super Admin.

Esegui la migrazione dei contratti esistenti da un sistema legacy a HubSpot per gestire la fatturazione, l’emissione delle fatture e la rendicontazione dei ricavi. La migrazione conserva i metodi di pagamento, la cronologia dei contratti e i piani di fatturazione futuri. Dopo la migrazione, potrai utilizzare HubSpot come fonte centralizzata e attendibile dei ricavi confermati. Scopri di più sull’utilizzo dei contratti in HubSpot.

Prima di iniziare

Prima di iniziare a utilizzare questa funzionalità, assicurati di aver compreso appieno quali passaggi è necessario compiere in anticipo, nonché i limiti della funzionalità e le potenziali conseguenze del suo utilizzo.

Comprendere i requisiti

Nota bene: se sei un Super Amministratore, puoi attivare per il tuo account le Migrazione della fatturazione verso i contratti di Revenue Hub .
Il tuo account HubSpot deve utilizzare Stripe come opzione di elaborazione dei pagamenti. Se utilizzi HubSpot Payments e desideri migrare i metodi di pagamento da un account Stripe esterno a HubSpot Payments, compila questo modulo.
Formatta il file CSV in base al processo di riscossione dei pagamenti e all’opzione di continuità dei ricavi che selezioni. Scopri di più su come scegliere il formato di migrazione più adatto alla tua attività.

Comprendere i limiti e le considerazioni

Se si utilizza la continuità dei ricavi, testare l’importazione in un ambiente sandbox. Se nel proprio account vengono importati dati errati, non sarà possibile correggere i dati storici nei report a cascata dell’MRR.
Una volta attivato un contratto, HubSpot diventa il sistema di riferimento per la fatturazione. La migrazione non può essere annullata.
Qualsiasi aggiornamento del contratto deve essere effettuato in HubSpot. Scopri di più su come visualizzare e gestire i contratti.
Dopo l’attivazione, è possibile aggiornare la “Sostituzione della data di inizio fatturazione” e l’“ID del metodo di pagamento” solo se il contratto non presenta fatture pagate o pagamenti.

Scegli il formato di migrazione

Prima di procedere alla migrazione, seleziona un formato di migrazione in base a come desideri che HubSpot gestisca i contratti dopo la migrazione. Il formato di migrazione dipende dal processo di raccolta e dal fatto che tu voglia includere gli eventi storici relativi alle modifiche contrattuali (ad esempio, aggiornamenti o estensioni).

Processo di riscossione dei pagamenti

Pagamenti manuali: dopo la migrazione, vengono generate fatture che gli acquirenti devono pagare manualmente.
Pagamenti automatici: dopo la migrazione, le fatture vengono addebitate automaticamente utilizzando un metodo di pagamento registrato.

Continuità dei ricavi

Nessuna continuità dei ricavi: i contratti vengono importati senza eventi di variazione dei ricavi.
Continuità dei ricavi: utilizza le chiavi di rampa per raggruppare le voci in fasi e visualizzare gli eventi di variazione (ad es. upgrade, espansioni, downgrade) nel grafico a cascata dell’MRR in HubSpot. Se utilizzi la continuità dei ricavi, testa l’importazione in un ambiente sandbox. Se nel tuo account vengono importati dati errati, non potrai correggere i dati storici nei report del grafico a cascata dell’MRR.

Ramp

Chiavi di rampa

Le chiavi di rampa raggruppano più righe di voci di linea in fasi. Le righe con la stessa chiave di rampa vengono trattate come un'unica rampa continua.

In HubSpot, ogni fase di rampa genera eventi MRR (ad es. nuovo business, upgrade, espansione) all'inizio di ciascuna fase. La chiave di rampa può essere una stringa di testo qualsiasi (ad es. ramp-a). La stessa stringa deve essere condivisa tra tutte le righe di quella rampa.

Strutturazione di una rampa

Per migrare correttamente le rampe, strutturale come segue:

Intervalli di date non sovrapposti: la durata di ciascuna riga non deve sovrapporsi a quella di un’altra riga. Se le fasi di rampa devono essere continue, ciascuna fase dovrebbe iniziare al termine della fase precedente.
Durata per fase: la durata di ciascuna riga copre solo quella fase del contratto, non l’intera durata contrattuale.
Quantità totale in ogni riga: inserisci la quantità totale per la voce di riga durante quella fase
ID chiave di importazione della rampa: raggruppa le voci sotto la stessa rampa. Scopri di più sulla creazione di una proprietà di rampa personalizzata.

Nota bene:

Un contratto può includere voci con rampa e senza rampa. Per le voci senza rampa, lascia vuoto il campo ` ramp_key_import_id e utilizza lo stesso ` import_unique_id delle righe del contratto correlate.
Un contratto può comprendere più prodotti con rampe indipendenti. Ogni prodotto deve avere il proprio ` ramp_key_import_id`. Ogni rampa genera i propri eventi MRR.

Ad esempio, per un contratto di 12 mesi con una variazione di prezzo dopo tre mesi:

Voce di riga	Prezzo unitario	Quantità	Durata	Data di inizio	ramp_key_import_id
Servizio mensile	100 $	1	3 mesi	1 gennaio 2026	`ramp-a`
Servizio mensile	100 $	2	9 mesi	1 aprile 2026	`ramp-a`

Possibili formati di migrazione

Formato di migrazione	Processo di raccolta	Continuità delle entrate
Pagamenti manuali senza continuità delle entrate	Pagamenti manuali	Non incluso
Pagamenti manuali con continuità di ricavi	Pagamenti manuali	Include
Pagamenti automatici senza continuità di fatturazione	Pagamenti automatici	Non inclusi
Pagamenti automatici con continuità di ricavi	Pagamenti automatici	Inclusi

Prepararsi alla migrazione

Prima di iniziare la migrazione, configura il tuo account e prepara il file CSV in base al formato di migrazione selezionato.

Creare proprietà personalizzate

Crea le proprietà personalizzate richieste prima di importare il file CSV. Le proprietà da creare dipendono dal formato di migrazione selezionato. Scopri di più sulla creazione di proprietà personalizzate.

Formato di migrazione	Oggetto	Nome della proprietà personalizzata	Tipo di proprietà personalizzata	Regole di convalida	Utilizzato per
Tutte le opzioni	Contratti	`import_unique_id`	Testo su una sola riga	Richiede valori univoci	Raggruppa tutte le righe appartenenti allo stesso contratto.
Pagamenti manuali con continuità di ricavi o Pagamenti automatici con continuità di ricavi	Voci di riga	`ramp_key_import_id`	Testo su una sola riga	Nessuna	Raggruppa più righe di voci in fasi.

Configurare il file CSV

Configura il file CSV da utilizzare con lo strumento di importazione per migrare i contratti su HubSpot.

File CSV di esempio

Utilizza i file CSV di esempio riportati di seguito, a seconda del formato di migrazione che stai utilizzando.

Formato di migrazione	Link CSV
Pagamenti manuali, nessuna continuità delle entrate	Scarica
Pagamenti manuali con continuità delle entrate	Scarica
Pagamenti automatici, nessuna continuità delle entrate	Scarica
Pagamenti automatici con continuità delle entrate	Scarica
Misto: un prodotto con tariffa progressiva e un prodotto a tariffa fissa (senza chiave di progressione)	Scarica
Ramp multiple indipendenti: il Prodotto A (`ramp-a`) e il Prodotto B (`ramp-b`) seguono ramp separate	Scarica

Formato CSV

Il file CSV deve includere le seguenti colonne e proprietà di HubSpot.

Nome colonna	Oggetto	Proprietà	Dettagli
Data di entrata in vigore del contratto	Contratto	`hs_contract_effective_date`	La data in cui il contratto acquista efficacia giuridica.
Codice valuta	Contratto	`hs_currency_code`	Codice valuta, ad esempio USD.
Nome	Contratto	`hs_name`	Nome del contratto.
Fatturazione HubSpot abilitata	Contratto	`hs_hubspot_billing_enabled`	Deve essere `TRUE` per tutti i contratti oggetto di migrazione.
Processo di raccolta	Contratto	`hs_collection_process`	Manuale o automatico. Deve essere in linea con il formato di migrazione.
Sovrascrittura della data di inizio fatturazione	Contratto	`hs_billing_start_date_override`	La data a partire dalla quale HubSpot inizia la fatturazione. In caso di migrazione, deve trattarsi di una data futura. Obbligatorio per tutti i formati di migrazione.
ID del metodo di pagamento	Contratto	`hs_external_payment_method_reference_id`	Lasciare vuoto per i pagamenti manuali. Obbligatorio per i pagamenti automatici.
E-mail	Contatto	`email`	L'indirizzo e-mail del referente di fatturazione.
Nome	Contatto	`firstname`	Nome del referente per la fatturazione.
Cognome	Contatto	`lastname`	Cognome del referente di fatturazione.
Prodotto	Voce d'ordine	`hs_product_id`	ID del record del prodotto. La migrazione fa riferimento a un record di prodotto esistente e non crea un nuovo prodotto
Nome della voce d'ordine	Voce	`name`	Nome della voce d'ordine.
Prezzo unitario	Voce	`price`	Prezzo unitario nella valuta del contratto.
Quantità	Posizione	`quantity`	Quantità della voce di riga durante una fase.
import_unique_id	Voce	Proprietà personalizzata	ID condiviso per tutte le righe dello stesso contratto.
Termine	Voce di riga	`hs_recurring_billing_period`	Durata della voce di fatturazione. Quando si utilizzano le rampe, inserire la durata per ciascun segmento.
Frequenza di fatturazione ricorrente	Voce	`recurringbillingfrequency`	Frequenza di fatturazione (ad es. mensile).
Data di inizio della voce	Voce	`hs_recurring_billing_start_date`	Data di inizio della fatturazione per la voce.
ramp_key_import_id	Voce	Proprietà personalizzata	Raggruppa le fasi delle voci di fatturazione in un unico percorso graduale. Obbligatorio per la continuità dei ricavi. Lasciare vuoto per i formati di migrazione senza continuità dei ricavi.

Avvia la migrazione

Dopo aver configurato il file CSV, puoi avviare la migrazione dei contratti su HubSpot.

Nel tuo account HubSpot, fai clic su Altro, quindi vai a Ricavo > Contratti. Se Altro non compare nel tuo account, vai direttamente a Ricavo > Contratti.
In alto a destra, fare clic su Importa.
Nella sezione Importa un file, fare clic su Importa dati.
Fare clic su Importazioni avanzate (tutti gli oggetti).
In " Oggetti", fare clic su "Contratti". L'oggetto "Voci" verrà selezionato automaticamente.
In basso a destra, fare clic su Avanti.
Configura le modalità di importazione dei dati:
- Carica un file: trascina e rilascia, oppure fai clic su "Scegli un file", quindi seleziona il file da importare.
- Copia e incolla: clicca su "Incolla direttamente dal foglio di calcolo " e incolla i dati. I dati devono essere copiati da un file di foglio di calcolo (ad es. Numbers, Fogli Google).
- Lingua: se stai importando dati in una lingua diversa da quella predefinita, clicca sul menu a tendina "Seleziona la lingua delle intestazioni delle colonne nel tuo file " e seleziona la lingua. Selezionando la lingua corretta, HubSpot potrà abbinare meglio le intestazioni delle colonne alle proprietà predefinite esistenti. Se non c'è corrispondenza nella lingua selezionata, HubSpot cercherà una proprietà in inglese con cui effettuare l'abbinamento.
In basso a destra, clicca su " Avanti".
Associa le colonne del file di importazione alle proprietà di HubSpot. Scopri di più sulle mappature delle proprietà CSV.
In basso a destra, clicca su Avanti.
Nel campo " Nome importazione ", inserisci un nome per l’importazione.
Fai clic sul menu a discesa " Seleziona la base giuridica per il trattamento dei dati di un contatto " e seleziona una base giuridica. Scopri di più sul monitoraggio della base giuridica del trattamento in HubSpot.
Fai clic sul menu a discesa " Formato data " e seleziona un formato data.
Fai clic sul menu a discesa " Fuso orario " e seleziona un fuso orario.
Fai clic sul menu a discesa " Formato numero " e seleziona un formato numerico.
Seleziona la casella di controllo Imposta questi contatti come contatti di marketing se desideri coinvolgere i contatti importati utilizzando gli strumenti di marketing di HubSpot. Scopri di più sui contatti di marketing.
Seleziona la casella di controllo " Arricchisci record " per arricchire i record durante l'importazione. Scopri di più sull'arricchimento dei contatti e delle aziende.
In basso a destra, fai clic su " Completa l'importazione".

Risoluzione dei problemi

Esamina gli errori di importazione più comuni e i passaggi per risolverli. Se riscontri un altro errore, controlla la formattazione del file CSV e le mappature delle proprietà, quindi riprova a eseguire l’importazione.

Sovrascrittura della data di inizio fatturazione nel passato

L'errore " Data di inizio fatturazione impostata su una data passata " si verifica quando la data di inizio fatturazione di una voce nel file CSV è precedente alla data corrente.

Per risolvere questo errore:

Aggiorna eventuali date di fatturazione indicando una data futura.
Salva il file CSV e avvia nuovamente l'importazione.

ID del metodo di pagamento Stripe non valido o mancante

Questo errore si verifica quando l’opzione “Pagamenti automatici” è selezionata come processo di riscossione, ma l’ID del metodo di pagamento Stripe non è stato aggiunto al file CSV.

Per risolvere questo errore, procedere in uno dei seguenti modi:

Modifica le voci relative ai pagamenti automatici in pagamenti manuali.
Aggiungi un ID del metodo di pagamento Stripe per le voci relative ai pagamenti automatici nel file CSV.

Duplicare l'import_unique_id da un tentativo precedente

Se un'importazione non va a buon fine, HubSpot potrebbe comunque registrare i valoriimport_unique_id relativi all'importazione non riuscita.