Conectar o Paddle
Cole uma chave de API do Paddle somente leitura para importar vendas de software e SaaS, reembolsos e impostos por produto e país.
O Paddle é o merchant of record do software que você vende fora das lojas de apps: apps de desktop, apps web, planos SaaS e licenças. A conexão usa uma única chave de API somente leitura, em vez de OAuth. Você cria a chave no painel do Paddle, cola no Revenue Sensor e escolhe quais produtos do Paddle sincronizar. A chave é armazenada criptografada e nunca sai do nosso servidor; seu login do Paddle nunca entra em jogo.
Antes de começar
- Acesso ao painel do Paddle da conta de vendedor cujas vendas você quer acompanhar, com permissão para criar chaves de API em Developer tools.
- Saber se você quer a conta live ou o sandbox. O Paddle emite chaves separadas para cada um, e a chave decide qual deles lemos; não há mais nada a escolher.
Crie uma chave de API somente leitura
- 1
Abra Developer tools
No painel do Paddle, vá em Developer tools → Authentication e crie uma nova chave de API. Dê a ela um nome que você reconheça depois, como "Revenue Sensor".
- 2
Conceda apenas permissões de leitura
Marque acesso de leitura para Transactions, Adjustments, Products e Addresses. Addresses fica em Customers e nos dá o país do comprador, então deixe marcado mesmo que pareça não ter relação. Nenhuma permissão de escrita é necessária.
- 3
Copie a chave uma única vez
O Paddle mostra a chave uma única vez, na criação. Copie na hora; se perder, revogue e crie outra.
Conecte a conta
- 1
Cole a chave
Integrations → Paddle → Connect no console do Revenue Sensor e cole a chave de API. O Revenue Sensor lê o prefixo da chave para distinguir uma chave live de uma de sandbox e confirma qual será usada antes de você continuar.
- 2
Escolha seus produtos
As unidades sincronizadas são produtos do Paddle, não apps de loja. Escolha os produtos que você quer no razão; cada um aparece como uma linha própria na receita e pode ser mapeado para um app, se pertencer a algum. Só o que você seleciona é buscado, e só isso conta para o seu plano.
- 3
Deixe a primeira sincronização rodar
O Paddle mantém todo o seu histórico, então a primeira sincronização preenche até um ano de transações pagas e reembolsos. Costuma levar alguns minutos e você pode sair da página enquanto ela roda.
O que é importado
| Campo | Observações |
|---|---|
| Receita | Transações pagas, lançadas no dia em que o dinheiro foi capturado, e não no dia em que a fatura foi emitida. Exibidas por produto, por dia e por país do comprador, sem impostos. A taxa do próprio Paddle não é descontada, do mesmo modo que o Google Play é mostrado bruto, antes da taxa do Google. |
| Impostos | O Paddle recolhe imposto sobre vendas e IVA como merchant of record e informa o valor em cada item, então o imposto é importado separadamente e a visão com impostos fica disponível para esta fonte. |
| Reembolsos e chargebacks | Reembolsos e chargebacks aprovados reduzem a receita no dia em que são aprovados, e o valor também é registrado como cifra de reembolso para contexto. Um chargeback revertido devolve o dinheiro. Créditos e avisos de chargeback não são tratados como reembolsos. |
| País | Obtido do endereço de cobrança do cliente. Só o código do país é usado. |
Todas as moedas do Paddle são suportadas
As transações são importadas na moeda em que foram cobradas e convertidas como qualquer outra fonte. Moedas sem casas decimais, como JPY e KRW, são lidas corretamente, então uma venda no Japão não aparece com um centésimo do valor.
Atualizações em tempo real (opcional)
O Revenue Sensor sincroniza o Paddle a cada 30 minutos. Se preferir ver uma nova venda ou reembolso em um ou dois minutos, aponte um destino de notificação do Paddle para nós. Os números continuam vindo da API do Paddle; o webhook só nos avisa para sincronizar antes.
- 1
Copie a URL do webhook
Abra a conexão do Paddle no console do Revenue Sensor. O painel "Real-time updates" mostra uma URL exclusiva desta conexão; copie-a.
- 2
Crie um destino de notificação
No Paddle, vá em Developer tools → Notifications → New destination. Cole a URL, escolha Webhook como tipo e assine os eventos transaction, adjustment e subscription.
- 3
Salve o segredo
O Paddle mostra um segredo de assinatura quando o destino é criado. Cole-o no painel "Real-time updates" e salve. Nós o usamos para verificar cada entrega e descartar tudo que não estiver assinado; ele é armazenado criptografado e nunca mais é exibido.
Solução de problemas
- A chave é rejeitada: confira se ela tem acesso de leitura aos quatro escopos Transactions, Adjustments, Products e Addresses. Uma chave sem Addresses passa na verificação básica, mas falha na sincronização.
- Nenhum produto aparece: a chave pertence a outra conta, ou ao sandbox quando você esperava live (ou o contrário). O prefixo da chave diz qual é.
- Uma venda está faltando: só transações pagas e concluídas são importadas. Rascunhos, faturas não pagas e transações canceladas ainda não são receita.
- A receita parece maior que o seu repasse: isso é esperado. O imposto fica separado e a taxa do Paddle não é descontada, então o número é a receita bruta antes da parte do Paddle.
- Um reembolso aparece em um dia diferente da venda: reembolsos são lançados no dia em que são aprovados, não retroagem à compra original.