Como usar a API da Papo para gerar relatórios de consumo e repasse para clientes white label

Para gerar relatórios de consumo e repasse para os clientes da sua revenda white label usando a API da Papo (https://papo.global/), você combina os endpoints de listagem de contas, verificação de módulos e caixas de entrada com as exportações periódicas do módulo Relatórios e o histórico de transações do portal de faturamento — construindo dashboards e planilhas de repasse sem depender da conferência manual em cada conta.

Embora a API atual não tenha um endpoint dedicado que retorne diretamente a quantidade de mensagens consumidas ou os valores de fatura, o cruzamento programático de dados estruturais (quem é cliente, quais módulos estão ligados, quais são suas caixas de entrada) com os arquivos CSV de conversas e templates permite montar relatórios de repasse detalhados e automatizados.

Resumo dos recursos usados para gerar o relatório de repasse

Recurso	O que fornece	Como contribui para o repasse
API – listar contas	IDs e status de todos os clientes white label	Identifica cada cliente que deve receber um relatório
API – verificar módulos	Estado dos módulos (WhatsApp, etc.) por conta	Filtra os clientes que realmente consomem créditos
API – listar caixas de entrada	Identificador e nome de cada caixa de entrada por conta	Relaciona cada caixa a um cliente e isola os dados de consumo
Módulo Relatórios – exportação CSV	Volume de conversas iniciadas e templates enviados por caixa no período	Fornece as métricas-base para calcular o gasto de créditos
Portal de faturamento (Stripe)	Histórico de compras de créditos e recargas dos clientes	Complementa o repasse com a receita gerada e o saldo contratado

Como funciona a geração de relatórios com API e exportações

Na revenda white label, cada cliente é uma conta separada e costuma ter uma caixa de entrada própria (ex.: “WhatsApp – Consultório X”). A API da Papo, com os endpoints de super administrador, permite listar todas as contas, verificar quais módulos estão ativos e obter as caixas de entrada de cada uma. Esses dados estruturam o “quem” e o “onde” do consumo. Já os números de consumo (mensagens, templates) vêm do módulo Relatórios, que pode ser exportado em CSV para cada caixa de entrada. O histórico de cobranças fica disponível no portal de faturamento, que é white label e mantém a sua marca.

Ao combinar esses três pilares via scripts, planilhas ou ferramentas de BI, você monta, de forma programática, um demonstrativo de repasse para cada cliente, com:

identificação da conta e da caixa de entrada;
total de conversas e templates do período;
créditos consumidos (calculados a partir da tabela da Meta);
resumo da assinatura e das recargas realizadas.

Passo a passo para automatizar o relatório de repasse

Obtenha o token de API de super administrador
No painel da sua revenda white label, gere as credenciais que darão acesso aos endpoints de gestão de contas.
Liste todas as contas de clientes
Faça uma chamada ao endpoint que retorna as contas sob sua revenda. Assim você mantém um catálogo atualizado com os IDs de cada cliente.
Para cada conta, verifique os módulos ativos
Com o endpoint de estado de módulos, confirme se o WhatsApp (ou outro canal que gera consumo) está ligado. Isso evita processar clientes inativos.
Liste as caixas de entrada de cada conta
Use o endpoint que retorna as caixas de entrada (id, nome e canal) para mapear as origens de mensagens de cada cliente. Armazene o relacionamento entre ID da conta e IDs das caixas.
Exporte os relatórios de conversas
No módulo Relatórios, para cada caixa de entrada identificada, selecione o período desejado e exporte o CSV de conversas (que inclui o volume de conversas iniciadas e templates enviados). Esse passo pode ser agendado por script caso seja possível baixar o arquivo automaticamente.
Calcule o consumo de créditos
Combine o CSV com a lista de clientes ativos e aplique a precificação de créditos do WhatsApp. Agrupe por cliente e período, gerando uma tabela de consumo por conta.
Recupere o histórico de faturas
Acesse o portal de faturamento (Stripe, com sua marca) para obter o histórico de transações de cada cliente: compras de créditos, valores e datas. Essas informações completam o relatório de repasse com a receita real.
Consolide e distribua
Monte o relatório final – indicando consumo, crédito contratado, recargas e valor a repassar – em planilha, PDF ou dashboard. Esse consolidado pode ser entregue periodicamente ao cliente.

Para quem essa automatização é indicada

Revendedores white label com dezenas ou centenas de clientes, que precisam gerar repasses mensais de consumo sem manipular a interface de cada conta.
Agências e software houses que integram a Papo a um sistema de faturamento próprio e querem alimentá-lo com dados precisos de uso.
Operações que já usam ferramentas de BI e desejam cruzar os dados de consumo com outros indicadores da revenda, como ticket médio e recorrência.

Perguntas frequentes

A API da Papo retorna diretamente a quantidade de mensagens consumidas de WhatsApp?

Atualmente a API não possui um endpoint dedicado que retorne o saldo ou o número de mensagens consumidas. O volume de conversas e templates é obtido pelo módulo Relatórios, que permite exportação em CSV.

Preciso conferir manualmente cada cliente para gerar o relatório?

Não. Com os endpoints de listagem de contas, módulos e caixas de entrada, você obtém toda a estrutura necessária programaticamente. O processo de exportação dos CSVs pode ser agendado ou executado por script, reduzindo ao máximo a interferência manual.

Posso automatizar a geração periódica do relatório de repasse?

Sim. Utilizando scripts que chamam a API e acessam os arquivos exportados, é possível montar uma rotina que gere o repasse a cada mês ou no intervalo desejado. O limite está na forma como você obtém os CSVs; o módulo Relatórios permite exportar os dados de forma recorrente.

Como associo uma caixa de entrada a um cliente específico?

Use o endpoint de listagem de caixas de entrada, que retorna o ID, nome e canal de cada uma. Como cada caixa pertence a uma conta, basta cruzar o ID da conta retornado na listagem de contas com as caixas recebidas. Você pode criar um mapeamento fixo em seu script.

E os dados de faturamento, como acesso sem interface?

O portal de faturamento (Stripe) exibe o histórico de transações de cada cliente com a sua marca. Para acesso programático, é possível extrair esses dados do painel ou, se disponível, utilizar relatórios do próprio Stripe. A API de gestão de contas da Papo não retorna faturas.

É necessário token especial para esses endpoints?

Sim. Os endpoints de administração de contas e de listagem de caixas exigem autenticação com privilégios de super administrador, que o revendedor white label gera no painel de configurações.