Per creare e aggiornare contatti in massa tramite programmazione, utilizza l'API REST di Papo. 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 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ò:
- Leggere una lista di contatti da un file CSV, database o ERP.
- Per ogni record, costruire il payload JSON con i campi necessari.
- Inviare la richiesta all'endpoint di creazione (se il contatto non esiste) o di aggiornamento (usando l'identificatore del contatto).
- 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. 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
- Come esportare i contatti estratti nell'Estrattore in CSV e importarli nel CRM di Papo
Inizia gratis e integra il tuo CRM a Papo tramite API →
Con il primo utente gratuito, puoi già generare le tue chiavi API e testare la creazione di contatti in massa senza costi iniziali.