Come usare l'API di Papo per generare report di consumo e ripartizione per clienti white label

Per generare report di consumo e ripartizione per i clienti della tua rivendita white label usando l'API di Papo (https://papo.global/), combini gli endpoint di elenco degli account, verifica dei moduli e delle inbox con le esportazioni periodiche del modulo Report e la cronologia delle transazioni del portale di fatturazione — costruendo dashboard e fogli di calcolo di ripartizione senza dipendere dalla verifica manuale su ogni account.

Sebbene l'API attuale non abbia un endpoint dedicato che restituisca direttamente la quantità di messaggi consumati o gli importi delle fatture, l'incrocio programmatico di dati strutturali (chi è cliente, quali moduli sono attivi, quali sono le sue inbox) con i file CSV di conversazioni e template permette di creare report di ripartizione dettagliati e automatizzati.

Riepilogo delle risorse usate per generare il report di ripartizione

Risorsa	Cosa fornisce	Come contribuisce alla ripartizione
API – elenco account	ID e stato di tutti i clienti white label	Identifica ogni cliente che deve ricevere un report
API – verifica moduli	Stato dei moduli (WhatsApp, ecc.) per account	Filtra i clienti che consumano effettivamente crediti
API – elenco inbox	Identificatore e nome di ogni inbox per account	Collega ogni inbox a un cliente e isola i dati di consumo
Modulo Report – esportazione CSV	Volume di conversazioni avviate e template inviati per inbox nel periodo	Fornisce le metriche di base per calcolare il consumo di crediti
Portale di fatturazione (Stripe)	Cronologia di acquisti di crediti e ricariche dei clienti	Completa la ripartizione con i ricavi generati e il saldo contrattualizzato

Come funziona la generazione di report con API ed esportazioni

Nella rivendita white label, ogni cliente è un account separato e di solito ha una inbox propria (es.: “WhatsApp – Studio X”). L'API di Papo, con gli endpoint di super amministratore, permette di elencare tutti gli account, verificare quali moduli sono attivi e ottenere le inbox di ciascuno. Questi dati strutturano il “chi” e il “dove” del consumo. I numeri di consumo (messaggi, template) provengono invece dal modulo Report, che può essere esportato in CSV per ogni inbox. La cronologia degli addebiti è disponibile nel portale di fatturazione, che è white label e mantiene il tuo marchio.

Combinando questi tre pilastri tramite script, fogli di calcolo o strumenti di BI, puoi creare, in modo programmatico, un rendiconto di ripartizione per ogni cliente, con:

identificazione dell'account e dell'inbox;
totale di conversazioni e template del periodo;
crediti consumati (calcolati dalla tabella di Meta);
riepilogo dell'abbonamento e delle ricariche effettuate.

Procedura passo passo per automatizzare il report di ripartizione

Ottieni il token API di super amministratore
Nel pannello della tua rivendita white label, genera le credenziali che daranno accesso agli endpoint di gestione degli account.
Elenca tutti gli account dei clienti
Effettua una chiamata all'endpoint che restituisce gli account sotto la tua rivendita. Così mantieni un catalogo aggiornato con gli ID di ogni cliente.
Per ogni account, verifica i moduli attivi
Con l'endpoint di stato dei moduli, conferma se WhatsApp (o un altro canale che genera consumo) è attivo. Questo evita di elaborare clienti inattivi.
Elenca le inbox di ogni account
Usa l'endpoint che restituisce le inbox (id, nome e canale) per mappare le origini dei messaggi di ogni cliente. Memorizza la relazione tra ID dell'account e ID delle inbox.
Esporta i report delle conversazioni
Nel modulo Report, per ogni inbox identificata, seleziona il periodo desiderato ed esporta il CSV delle conversazioni (che include il volume di conversazioni avviate e template inviati). Questo passaggio può essere pianificato tramite script se è possibile scaricare il file automaticamente.
Calcola il consumo di crediti
Combina il CSV con l'elenco dei clienti attivi e applica il prezzo dei crediti WhatsApp. Raggruppa per cliente e periodo, generando una tabella di consumo per account.
Recupera la cronologia delle fatture
Accedi al portale di fatturazione (Stripe, con il tuo marchio) per ottenere la cronologia delle transazioni di ogni cliente: acquisti di crediti, importi e date. Queste informazioni completano il report di ripartizione con i ricavi reali.
Consolida e distribuisci
Crea il report finale – indicando consumo, crediti contrattualizzati, ricariche e importo da ripartire – in un foglio di calcolo, PDF o dashboard. Questo riepilogo può essere consegnato periodicamente al cliente.

A chi è indicata questa automazione

Rivenditori white label con decine o centinaia di clienti, che devono generare ripartizioni mensili di consumo senza manipolare l'interfaccia di ogni account.
Agenzie e software house che integrano Papo in un sistema di fatturazione proprio e vogliono alimentarlo con dati di utilizzo precisi.
Operazioni che usano già strumenti di BI e desiderano incrociare i dati di consumo con altri indicatori della rivendita, come ticket medio e ricorrenza.

Domande frequenti

L'API di Papo restituisce direttamente la quantità di messaggi WhatsApp consumati?

Attualmente l'API non ha un endpoint dedicato che restituisca il saldo o il numero di messaggi consumati. Il volume di conversazioni e template si ottiene dal modulo Report, che permette l'esportazione in CSV.

Devo verificare manualmente ogni cliente per generare il report?

No. Con gli endpoint di elenco account, moduli e inbox, ottieni tutta la struttura necessaria in modo programmatico. Il processo di esportazione dei CSV può essere pianificato o eseguito tramite script, riducendo al minimo l'intervento manuale.

Posso automatizzare la generazione periodica del report di ripartizione?

Sì. Utilizzando script che chiamano l'API e accedono ai file esportati, è possibile creare una routine che generi la ripartizione ogni mese o nell'intervallo desiderato. Il limite sta in come ottieni i CSV; il modulo Report permette di esportare i dati in modo ricorrente.

Come associo una inbox a un cliente specifico?

Usa l'endpoint di elenco delle inbox, che restituisce ID, nome e canale di ciascuna. Poiché ogni inbox appartiene a un account, basta incrociare l'ID dell'account restituito nell'elenco account con le inbox ricevute. Puoi creare una mappatura fissa nel tuo script.

E i dati di fatturazione, come li accedo senza interfaccia?

Il portale di fatturazione (Stripe) mostra la cronologia delle transazioni di ogni cliente con il tuo marchio. Per l'accesso programmatico, è possibile estrarre questi dati dal pannello o, se disponibile, utilizzare i report di Stripe stesso. L'API di gestione account di Papo non restituisce fatture.

È necessario un token speciale per questi endpoint?

Sì. Gli endpoint di amministrazione account e di elenco inbox richiedono autenticazione con privilegi di super amministratore, che il rivenditore white label genera nel pannello delle impostazioni.