Come usare l'API di Papo per creare un modulo di registrazione e popolare il CRM automaticamente

Q: È possibile creare attributi personalizzati direttamente durante la creazione del contatto?

Sì. L'API di Papo permette di definire i custom_attributes del contatto al momento della creazione o di aggiornarli successivamente. Consulta la documentazione per il formato esatto del payload e per verificare se le definizioni degli attributi esistono già nell'account.

Q: Cosa fare se l'API restituisce un errore?

L'API di Papo restituisce risposte standardizzate con success: false e un oggetto error contenente il codice e il messaggio. Gestisci questi errori nel tuo codice: verifica che i campi obbligatori siano stati inviati, controlla che la chiave sia attiva e che il formato del payload sia corretto. La documentazione elenca i principali codici di errore.

Con l'API REST di Papo, puoi costruire un endpoint nel tuo sito che riceve i dati del modulo di registrazione e chiama l'API dei contatti per creare record nel CRM automaticamente, inclusi attributi personalizzati — eliminando l'inserimento manuale e accelerando l'integrazione dei lead.

Invece di esportare fogli di calcolo o copiare dati tra sistemi, questa integrazione fa sì che ogni nuova registrazione sul tuo sito diventi un contatto nel CRM di Papo in tempo reale. Il flusso è semplice: il modulo invia i dati a un backend che controlli, quel backend si autentica sull'API di Papo e crea il contatto con nome, e-mail, telefono e qualsiasi campo personalizzato di cui la tua operazione abbia bisogno.

Riepilogo dell'integrazione

Componente	Cosa fa	Esempio
Modulo sul sito	Raccoglie nome, e-mail, telefono e campi extra del lead.	Pagina di acquisizione, landing page, checkout.
Endpoint intermedio	Riceve i dati del modulo e chiama l'API di Papo.	Script in Node.js, Python o automazione in n8n/Zapier.
API dei contatti di Papo	Crea il contatto nel CRM con i dati inviati.	Richiesta POST autenticata con chiave segreta.
Attributi personalizzati	Aggiunge campi come origine, interesse o punteggio al contatto.	`custom_attributes` con `"origem": "site"`, `"plano_interesse": "gold"`.

Come funziona: passo dopo passo

Genera le chiavi API nel pannello di Papo
Accedi all'area sviluppatore del tuo account Papo e crea una chiave segreta. Anche la chiave pubblica dell'account è visibile in questa schermata. La chiave segreta appare una sola volta; conservala in un luogo sicuro e non esporla mai nel frontend.
Crea il modulo sul tuo sito
Crea il modulo con i campi che desideri inviare al CRM: nome, e-mail, telefono e qualsiasi dato aggiuntivo (interesse, origine, città ecc.). Il modulo deve fare una richiesta HTTP (POST) all'endpoint che costruirai nel passaggio successivo.
Costruisci l'endpoint intermedio
Sul tuo server o in una funzione serverless (Node.js, Python, PHP ecc.), crea una rotta che riceva i dati del modulo. Questo codice sarà responsabile di:
- Validare i campi ricevuti.
- Costruire il payload JSON per l'API di Papo.
- Autenticarsi con la chiave segreta (Bearer token) e, opzionalmente, inviare la chiave pubblica nell'header X-Papo-Public-Key.
- Chiamare l'endpoint di creazione dei contatti di Papo.
Chiama l'API dei contatti di Papo
Utilizza l'endpoint di creazione dei contatti (consulta la documentazione ufficiale su https://papo.global/pt/docs per il percorso esatto e il formato del payload). Invia, come minimo, nome e e-mail o telefono. La risposta dell'API confermerà la creazione con i dati del nuovo contatto.
Aggiungi attributi personalizzati
Se il tuo account ha definizioni di attributi personalizzati (come “origine”, “utm_source”, “score”), puoi inviarli nello stesso payload o in una chiamata complementare. L'API permette di definire/unire custom_attributes nel contatto, eliminando la necessità di compilare questi campi manualmente in seguito.
Gestisci la risposta e restituisci all'utente
Dopo la creazione riuscita, il tuo endpoint può reindirizzare il lead a una pagina di ringraziamento o mostrare un messaggio di successo. In caso di errore (chiave non valida, dati mancanti), registra il log e restituisci un messaggio amichevole.

Poiché l'API di Papo è REST e utilizza JSON, qualsiasi linguaggio con supporto HTTP può essere utilizzato. La documentazione ufficiale fornisce esempi in JavaScript, Python e curl, oltre ai dettagli di autenticazione e ai codici di errore.

A chi è adatta questa integrazione

Siti e landing page che catturano lead e vogliono eliminare il trasferimento manuale dei dati al CRM.
E-commerce e SaaS che desiderano creare automaticamente un contatto al momento della registrazione o dell'acquisto.
Agenzie e consulenze che gestiscono campagne di acquisizione e hanno bisogno che i lead entrino nel CRM in tempo reale per un follow-up immediato.
Rivendite white label e integratori che costruiscono flussi personalizzati per i clienti, collegando i moduli dei siti a Papo senza intervento manuale.
Team di marketing e vendite che utilizzano attributi personalizzati per la segmentazione e desiderano che questi campi siano compilati automaticamente all'origine.

Domande frequenti

È necessaria una conoscenza avanzata della programmazione per implementare questa integrazione?

Sì. È necessario sviluppare un endpoint sul tuo server o utilizzare strumenti di automazione (n8n, Zapier) che facciano da ponte tra il modulo e l'API di Papo. Il codice in sé è semplice, ma richiede nozioni di base di HTTP e manipolazione di JSON.

Posso usare qualsiasi linguaggio di programmazione?

Sì. L'API di Papo è REST e risponde in JSON. Qualsiasi linguaggio con supporto a richieste HTTP (Python, Node.js, PHP, Ruby, ecc.) può essere utilizzato. La documentazione ufficiale fornisce esempi in JavaScript e Python.

È possibile creare attributi personalizzati direttamente durante la creazione del contatto?

Sì. L'API di Papo permette di definire i custom_attributes del contatto al momento della creazione o di aggiornarli successivamente. Consulta la documentazione per il formato esatto del payload e per verificare se le definizioni degli attributi esistono già nell'account.

Come garantire la sicurezza della chiave segreta?

La chiave segreta non deve mai essere esposta nel frontend (HTML/JavaScript pubblico). Deve rimanere solo sul server, in variabili d'ambiente. Utilizza HTTPS in tutte le comunicazioni e revoca la chiave immediatamente se sospetti una fuga di dati.

Cosa fare se l'API restituisce un errore?

L'API di Papo restituisce risposte standardizzate con success: false e un oggetto error contenente il codice e il messaggio. Gestisci questi errori nel tuo codice: verifica che i campi obbligatori siano stati inviati, controlla che la chiave sia attiva e che il formato del payload sia corretto. La documentazione elenca i principali codici di errore.

Posso usare questa integrazione con moduli di piattaforme come WordPress, Typeform o RD Station?

Sì. Puoi configurare webhook su queste piattaforme per inviare i dati del modulo al tuo endpoint intermedio, che poi chiamerà l'API di Papo. Un'altra alternativa è utilizzare integrazioni pronte tramite Zapier o n8n, creando un flusso che riceve l'evento del modulo e attiva la creazione del contatto in Papo.