Come usare l'API di Papo per creare e aggiornare opportunità nel Kanban

Apri in

Visualizza come Markdown

Apri in ChatGPT Apri in Claude

Vitor

Ultimo aggiornamento Oct 19, 2026

Per creare e aggiornare opportunità nel Kanban 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 creano card, spostano opportunità tra le fasi e contrassegnano risultati, integrando il funnel di vendita con sistemi esterni senza intervento manuale.

L'API di Papo espone operazioni di scrittura per il Kanban, consentendo di lavorare con funnel, fasi e card del CRM. Ciò permette di sincronizzare un ERP, una landing page o uno strumento di pagamento con il funnel di vendita, mantenendo le opportunità sempre aggiornate.

Riepilogo dell'integrazione con il Kanban

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. Conoscere i funnel e le fasi	Elencare i funnel del Kanban e le loro fasi per ottenere gli identificatori necessari.	La risposta dell'API fornisce gli identificatori utilizzati nelle chiamate successive.
4. Creare o spostare card	Inviare l'operazione per creare un card in una fase, spostare un card di un contatto in un'altra fase o contrassegnare un risultato.	Ogni operazione elabora un'azione; per molti record, automatizza l'invio in loop.
5. Convalidare la risposta	L'API restituisce `success: true` e i dati del card o dell'elenco.	In caso di errore, il corpo della risposta fornisce codice e messaggio per la correzione.

Cosa permette di fare l'API nel Kanban

Con gli endpoint del Kanban, puoi programmaticamente:

Elencare i funnel disponibili e le loro fasi, con nome e posizione.
Elencare i card del CRM.
Elencare tutti i card vinti, per report di vendite concluse.
Creare un card in una fase, opzionalmente collegato a un contatto esistente.
Spostare il card di un contatto in un'altra fase del funnel.
Contrassegnare i card come vinti o come persi.
Creare un funnel Kanban con fasi predefinite o personalizzate.

Queste operazioni consentono al funnel di riflettere automaticamente ciò che accade al di fuori di Papo, come un acquisto confermato, una riunione programmata o una registrazione proveniente dal sito.

Come funzionano l'autenticazione e le chiamate

Ogni chiamata che modifica i dati 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 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 di base dell'API è https://app.papo.global/api/v1. Da essa, gli endpoint del Kanban accettano i verbi HTTP adatti per creare, spostare, aggiornare ed elencare. Poiché la documentazione completa dettaglia i path, i parametri e i campi accettati, consigliamo di consultare il riferimento ufficiale dell'API prima di codificare.

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 utilizzato negli 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.

Flusso tipico di integrazione con sistemi esterni

Uno script in Python, Node.js o un'automazione in strumenti come n8n può eseguire il ciclo completo del funnel:

Elencare i funnel e le fasi per ottenere gli identificatori di ogni colonna.
Creare un card nella fase iniziale, collegandolo a un contatto se necessario.
Spostare il card in una nuova fase quando si verifica un evento esterno — ad esempio, pagamento confermato o riunione fissata.
Contrassegnare il card come vinto o perso quando l'opportunità è conclusa.
Elencare i card vinti per alimentare report, dashboard o sistemi di BI.

Poiché l'API è REST e utilizza JSON, qualsiasi linguaggio con supporto HTTP funziona. I dettagli del payload e dei campi di ogni operazione sono nella documentazione ufficiale.

A chi è indicata questa integrazione

Aziende che acquisiscono opportunità in sistemi esterni, come landing page, ERP o e‑commerce, e desiderano che entrino automaticamente nel funnel di Papo.
Operazioni che devono spostare card in base a eventi di pagamento, come gateway o piattaforme di fatturazione, senza aprire manualmente il CRM.
Team di BI e dati che vogliono estrarre card vinti e valori per dashboard in tempo reale.
Team IT che costruiscono integrazioni personalizzate tra Papo e strumenti interni, usando l'API come ponte tra il funnel di vendita e il resto dell'operazione.

Domande frequenti

Devo usare la chiave pubblica in tutte le chiamate?

No. La chiave pubblica è opzionale, ma, se inviata nell'header X-Papo-Public-Key, deve corrispondere allo stesso account della chiave segreta.

Come faccio a sapere quali fasi esistono nel mio funnel?

Elenca i funnel del Kanban tramite l'API. La risposta restituisce le fasi di ogni funnel con i loro identificatori, utilizzati per creare o spostare card.

Posso creare un card già collegato a un contatto?

Sì. La creazione del card permette di collegarlo opzionalmente a un contatto esistente, mantenendo la cronologia e i dati del cliente associati all'opportunità.

L'API permette di aggiornare il valore di un card?

L'API espone operazioni di scrittura per i card del Kanban. I campi esatti che possono essere aggiornati, inclusi i valori, sono dettagliati nella documentazione ufficiale dell'API.

È possibile contrassegnare un card come vinto o perso tramite l'API?

Sì. L'API permette di contrassegnare i card come vinti e come persi, oltre a elencare tutti i card vinti per report e dashboard.

Devo programmare o posso usare strumenti di automazione?

Puoi usare qualsiasi linguaggio con supporto HTTP o strumenti di automazione come n8n, eseguendo le chiamate in sequenza secondo il flusso desiderato.