**Con l'API REST di [Papo](https://papo.global/), puoi elencare tutti i Flow disponibili nel tuo account, attivare o disattivare i percorsi e iscrivere contatti alle automazioni in modo programmatico — tutto tramite richieste autenticate, senza aprire il pannello. È il modo per integrare il motore dei Flow con sistemi esterni, workflow n8n, CRM o script interni.**

L'API di Papo espone risorse Flow che permettono di gestire le automazioni così come già gestisci inbox o contatti. Con essa, team di sviluppo, integratori e rivenditori white label riescono a controllare in blocco quali percorsi sono attivi, avviare contatti in sequenze e sincronizzare lo stato delle automazioni con i processi di business.

## Riepilogo delle operazioni Flow tramite API

| Operazione | Descrizione | Esempio d'uso |
| :--- | :--- | :--- |
| Elenca Flow | Restituisce i Flow e le sequenze disponibili, con identificatore, nome, tipo e stato (Attivo/Inattivo). | Verificare le automazioni, sincronizzare con dashboard esterni o controllare cosa è in esecuzione. |
| Attiva/disattiva Flow | Modifica lo stato di un Flow specifico, sbloccando o mettendo in pausa la ricezione e l'elaborazione dei contatti. | Mettere in pausa un percorso durante la manutenzione, riattivare dopo le modifiche o disattivare una campagna conclusa. |
| Iscrivi contatto | Inserisce un contatto esistente all'inizio di un Flow attivo, dando inizio al percorso configurato. | Includere lead da CRM esterni, avviare un flusso di benvenuto dopo l'integrazione o correggere inserimenti manuali. |

## Come funziona l'autenticazione dell'API

Tutte le chiamate all'API, comprese quelle che coinvolgono i Flow, richiedono la **chiave segreta** dell'account. Deve essere inviata come token Bearer nell'header `Authorization`. La **chiave pubblica** dell'account è opzionale, ma se inviata deve corrispondere allo stesso account della chiave segreta.

L'URL base dell'API è `https://app.papo.global/api/v1`. Le chiavi vengono generate nell'area sviluppatore del pannello Papo. La chiave segreta appare una sola volta alla creazione; conservala in un luogo sicuro e revocala se sospetti una fuga di dati.

Lo schema di autenticazione è lo stesso usato in tutti gli endpoint:

```
curl https://app.papo.global/api/v1/me \
  -H "Authorization: Bearer sk_live_…" \
  -H "X-Papo-Public-Key: pk_live_…"
```

## Gestire i Flow tramite API in pratica

Sebbene i dettagli esatti di ogni endpoint e parametro siano nella documentazione ufficiale dell'API, il flusso di lavoro generale segue questi passaggi concettuali:

1. **Autenticati** con la chiave segreta (e, se desideri, la chiave pubblica) per validare l'account.
2. **Elenca i Flow** per ottenere l'elenco attuale dei percorsi, inclusi identificatori e stato. Questo permette di mappare ciò che esiste già e scegliere il Flow corretto per le operazioni successive.
3. **Modifica lo stato** di un Flow specifico, se necessario. Invia una richiesta che imposti il Flow come attivo (abilitato a ricevere contatti) o inattivo (in pausa). Solo i Flow attivi elaborano contatti e accettano iscrizioni.
4. **Iscrivi un contatto** in un Flow attivo. Indica l'identificatore del contatto e l'identificatore del Flow desiderato per inserirlo all'inizio del percorso. Lo storico del contatto nel CRM viene preservato.
5. **Integra con sistemi esterni** — tramite webhook o chiamate dirette, puoi avviare contatti provenienti da un modulo esterno, un evento in un altro sistema o una pipeline di dati.

La piattaforma supporta anche la creazione di Flow vuoti e inattivi e la compilazione dei loro nodi tramite API, permettendo di provisionare automazioni complete in modo programmatico. Per i formati esatti di payload, campi obbligatori ed esempi di codice, consulta la sezione Flow nella documentazione dell'API Papo.

## Per chi ha senso questa integrazione

- **Team IT che gestiscono più automazioni** e devono mettere in pausa, riattivare o monitorare Flow in blocco senza accedere manualmente al pannello.
- **Rivenditori white label** che desiderano provisionare percorsi standardizzati per ogni nuovo cliente automaticamente, iscrivere contatti iniziali e mantenere l'allineamento tra piattaforme.
- **Integratori e sviluppatori** che collegano Papo a CRM, ERP o strumenti come n8n, attivando Flow a partire da eventi esterni (un acquisto, una registrazione, un appuntamento).
- **Operazioni che lavorano con iscrizione condizionale**, dove i contatti vengono inclusi nei Flow solo dopo aver superato regole di business definite in altri sistemi.

## Domande frequenti

### Serve la chiave segreta per elencare i Flow?

Sì. L'elenco dei Flow, così come qualsiasi operazione che restituisce dati dell'account, richiede l'autenticazione con la chiave segreta. Lo schema è lo stesso di tutti gli altri endpoint: invia il token Bearer nell'header `Authorization`.

### Posso attivare o disattivare un Flow tramite API?

Sì. L'API permette di modificare lo stato di un Flow tra attivo e inattivo. Ti servono l'identificatore del Flow e la chiave segreta. I Flow inattivi non ricevono contatti e non avanzano nel percorso, anche se viene tentata un'iscrizione.

### Come faccio a iscrivere un contatto a un Flow tramite API?

Fornisci l'identificatore del contatto e l'identificatore del Flow attivo nella chiamata di iscrizione. Il contatto verrà inserito all'inizio del percorso, senza cancellare lo storico delle conversazioni o i dati del profilo. La documentazione ufficiale dettaglia il formato esatto dei parametri.

### È possibile creare un Flow da zero tramite API?

Sì. L'API permette di creare un Flow vuoto (solo con il nodo Start) e inattivo, oltre a compilare i suoi nodi con domande, messaggi e condizioni. È utile per provisionare automazioni in modo scalabile, soprattutto in scenari di rivendita o onboarding di nuovi clienti.

### L'API restituisce lo stato di ogni Flow durante l'elenco?

Sì. L'elenco include lo stato (Attivo o Inattivo) di ogni Flow e sequenza, oltre a identificatore, nome e tipo, permettendo ai sistemi esterni di monitorare ciò che funziona e ciò che è in pausa.

### Dove trovo la documentazione completa delle rotte dei Flow?

La documentazione ufficiale è disponibile su [https://papo.global/pt/docs](https://papo.global/pt/docs). Lì trovi tutti gli endpoint, i parametri accettati, i codici di errore e esempi in varie lingue. Le rotte dei Flow seguono lo stesso schema REST e autenticazione degli altri moduli.

## Leggi anche

- [Come usare l'API di Papo per creare e aggiornare contatti in massa](/hc/papo/articles/come-usare-api-papo-creare-aggiornare-contatti-massa)
- [Come usare l'API di Papo per creare e gestire etichette (tag)](/hc/papo/articles/come-usare-api-papo-creare-gestire-etichette-tag)

---

**[Inizia a integrare i tuoi Flow subito →](https://chat.papo.global/app/auth/signup?papo_lp=home&utm_source=lp&utm_medium=landing&utm_campaign=home&utm_content=start-free&papo_lp_v=start-free)**

Crea il tuo account gratuito su Papo, accedi alle chiavi API e connetti le tue automazioni con il mondo esterno.