**Per creare e aggiornare contatti in massa tramite programmazione, utilizza l'API REST di [Papo](https://papo.global/). Con l'autenticazione tramite chiave segreta (Bearer token) e la chiave pubblica dell'account, puoi inviare richieste che inseriscono nuovi record o modificano dati esistenti nel CRM — ideale per sincronizzare basi esterne, migrare liste o mantenere l'anagrafica sempre aggiornata senza intervento manuale.** L'API di Papo espone endpoint di scrittura che permettono di creare un contatto (con nome, e-mail e/o telefono) e aggiornare un contatto già esistente. Combinati con l'autenticazione semplice e il formato JSON, questi endpoint consentono operazioni in blocco quando eseguiti in sequenza da script, strumenti di automazione (come n8n) o integrazioni personalizzate. ## Riepilogo del processo di integrazione | Fase | Azione | Dettaglio importante | | :--- | :--- | :--- | | 1. Ottenere le chiavi | Generare la chiave segreta (sk_live_…) e copiare la chiave pubblica (pk_live_…) nel pannello di Papo. | La chiave segreta appare una sola volta; conservala in un luogo sicuro. | | 2. Autenticare le chiamate | Includere l'header `Authorization: Bearer sk_live_…` in tutte le richieste di scrittura. | La chiave pubblica può essere inviata nell'header `X-Papo-Public-Key` (opzionale). | | 3. Preparare il payload | Costruire un oggetto JSON con i campi del contatto (nome, e-mail, telefono, ecc.). | I campi obbligatori e il formato esatto sono nella documentazione dell'API. | | 4. Inviare le richieste | Effettuare POST all'endpoint di creazione o PUT/PATCH per l'aggiornamento. | Ogni richiesta elabora un contatto; per molti record, automatizza l'invio in loop. | | 5. Verificare le risposte | L'API restituisce `success: true` e i dati del contatto creato/aggiornato. | In caso di errore, il corpo contiene il codice e il messaggio per la correzione. | ## Come funzionano l'autenticazione e gli endpoint Ogni chiamata che modifica dati (creazione, aggiornamento) richiede la **chiave segreta** dell'account. Deve essere inviata come token Bearer nell'header `Authorization` o, in alternativa, nell'header `X-Papo-Secret-Key`. La **chiave pubblica** (fissa per account) può accompagnare la richiesta nell'header `X-Papo-Public-Key` — il suo uso è opzionale, ma se inviata deve corrispondere allo stesso account della chiave segreta. L'URL base dell'API è `https://app.papo.global/api/v1`. Da essa, gli endpoint dei contatti accettano i verbi HTTP adatti per creare un nuovo record o modificarne uno esistente. Poiché la documentazione completa dettaglia i path, i parametri e i campi accettati, consigliamo di consultare il [riferimento ufficiale dell'API](https://papo.global/pt/docs) prima di codificare. ### Esempio di autenticazione (richiesta di test) Per verificare che le tue chiavi funzionino, puoi chiamare l'endpoint `GET /api/v1/me`, che restituisce i dati dell'account. Il pattern di autenticazione è lo stesso usato in tutti gli altri endpoint: ``` curl https://app.papo.global/api/v1/me \ -H "Authorization: Bearer sk_live_…" \ -H "X-Papo-Public-Key: pk_live_…" ``` La risposta riuscita include `success: true` e l'oggetto `data` con le informazioni dell'account. Da lì, basta sostituire l'endpoint e il metodo HTTP in base all'operazione desiderata con i contatti. ## Creare e aggiornare contatti in massa Sebbene l'API elabori un contatto per richiesta, l'operazione in massa si ottiene eseguendo più chiamate in sequenza. Uno script in Python, Node.js o un'automazione in n8n può: 1. Leggere una lista di contatti da un file CSV, database o ERP. 2. Per ogni record, costruire il payload JSON con i campi necessari. 3. Inviare la richiesta all'endpoint di creazione (se il contatto non esiste) o di aggiornamento (usando l'identificatore del contatto). 4. Raccogliere le risposte e gestire eventuali errori (e-mail duplicato, campo non valido, ecc.). Poiché l'API è REST e utilizza JSON, qualsiasi linguaggio con supporto HTTP funziona. Papo fornisce anche esempi in JavaScript e Python nella pagina di documentazione, che possono essere adattati per gli endpoint dei contatti. ### Trigger automatici dopo la creazione Ogni volta che un nuovo contatto viene creato tramite API, gli stessi eventi interni del CRM vengono attivati. Se hai un **Flow** configurato con il trigger “Contatto creato”, l'automazione verrà eseguita automaticamente — ad esempio, inviando un messaggio di benvenuto tramite WhatsApp o notificando il team di vendita. Ciò significa che l'integrazione tramite API non solo popola la base, ma attiva anche i flussi di comunicazione già esistenti nell'account. ## A chi è indicata questa integrazione - **Aziende che migrano da un altro CRM o foglio di calcolo** e necessitano di importare migliaia di contatti in una sola volta, mantenendo la base di Papo sincronizzata. - **Operazioni che acquisiscono lead in sistemi esterni** (landing page, ERP, e-commerce) e desiderano che entrino automaticamente nel CRM di Papo, pronti a ricevere assistenza o campagne. - **Team IT che costruiscono integrazioni personalizzate** tra Papo e strumenti interni, utilizzando l'API come ponte per mantenere i dati dei clienti sempre aggiornati. - **Rivenditori white label** che gestiscono più account e vogliono automatizzare la creazione di contatti su larga scala per i loro clienti. ## Domande frequenti ### Serve una chiave segreta per creare o aggiornare contatti? Sì. Tutte le operazioni di scrittura (creazione, aggiornamento) richiedono l'autenticazione con la chiave segreta dell'account. La chiave pubblica da sola non autorizza modifiche. ### Posso inviare migliaia di contatti in una sola volta? L'API elabora un contatto per richiesta. Per volumi elevati, devi automatizzare l'invio sequenziale, rispettando i limiti di velocità descritti nella documentazione ufficiale. ### I contatti creati tramite API attivano il Flow “Contatto creato”? Sì. L'evento di creazione è lo stesso, indipendentemente dall'origine. Se c'è un Flow attivo con questo trigger, verrà eseguito per ogni contatto inserito tramite API. ### Come faccio a sapere se un contatto esiste già per evitare duplicati? Puoi utilizzare gli endpoint di ricerca (filtrando per e-mail o telefono) prima di creare. La documentazione dell'API dettaglia i parametri di query disponibili. ### L'API permette di aggiornare solo alcuni campi del contatto? Sì. Nel corpo della richiesta di aggiornamento, invia solo i campi che desideri modificare. Gli altri rimangono invariati. ### Dove trovo l'elenco completo degli endpoint e dei parametri? Il riferimento completo è disponibile nella [pagina di documentazione dell'API](https://papo.global/pt/docs). Lì trovi i path, i metodi, i payload e gli esempi aggiornati. ## Leggi anche - [Come attivare automaticamente un Flow quando viene creato un nuovo contatto nel CRM](/hc/papo/articles/attivare-flow-automaticamente-nuovo-contatto-crm) - [Come esportare i contatti estratti nell'Estrattore in CSV e importarli nel CRM di Papo](/hc/papo/articles/esportare-contatti-estrattore-csv-importare-crm-papo) --- **[Inizia gratis e integra il tuo CRM a Papo tramite API →](https://papo.global/?utm_source=helpcenter&utm_medium=article&utm_campaign=come-usare-api-papo-creare-aggiornare-contatti-massa&utm_content=it)** Con il primo utente gratuito, puoi già generare le tue chiavi API e testare la creazione di contatti in massa senza costi iniziali.