Pular para o conteúdo principal

Sincronização de Receita do Stripe

Disponível

Esta integração está ativa e pronta para uso em todos os planos Pro.

Importe automaticamente suas cobranças do Stripe como faturas registradas no Frihet. Ideal para negócios SaaS que cobram com Stripe e precisam manter sua faturação em ordem.

Para que serve?​

Se você cobra com Stripe e quer que essas cobranças apareçam como faturas no Frihet sem criá-las manualmente:

  • Importação automática — Cada fatura paga no Stripe se torna uma fatura no Frihet
  • Sincronização incremental — Apenas importa novas cobranças desde a última sincronização
  • Deduplicação — Nunca uma fatura é duplicada, mesmo que você execute a importação várias vezes
  • VeriFactu compatível — As faturas importadas passam pela cadeia de hash e numeração gap-free

Diferença com a integração do Stripe​

Stripe (OAuth)Sincronização de Receita do Stripe
ConexãoOAuth (redirecionar para o Stripe)Chave de API restrita
DireçãoBidirecionalApenas Stripe → Frihet
TipoPagamentos + assinaturas + ConnectApenas faturas pagas
FaturasAutomática por webhookImportação sob demanda + auto-sync
Caso de usoReceber pagamentos do FrihetRegistrar cobranças do Stripe no Frihet

Use a Sincronização de Receita se: você cobra diretamente do Stripe (Dashboard, Billing, etc.) e quer que essas cobranças apareçam no Frihet para sua contabilidade e declarações.

Requisitos​

  • Conta Stripe ativa — Crie uma em stripe.com
  • Chave de API restrita — Com permissões de somente leitura em invoices e customers
  • Frihet Pro ou superior — Não disponível no plano Free

Configurar Sincronização de Receita do Stripe​

Passo 1: Crie uma Chave de API restrita no Stripe​

  1. Vá para Stripe Dashboard → Developers → API Keys
  2. Clique em Create restricted key
  3. Nome: Frihet Revenue Sync
  4. Permissões necessárias:
    • Invoices → Read
    • Customers → Read
  5. Copie a chave (rk_live_...)

Passo 2: Conecte no Frihet​

  1. Vá para Configurações → Integrações
  2. Procure por Stripe Revenue Sync
  3. Clique em Conectar
  4. Cole a sua Chave de API restrita
  5. Selecione a data a partir da qual você deseja importar
  6. Clique em Salvar e conectar

Passo 3: Importar faturas​

  1. Clique em Importar agora
  2. Frihet consultará as faturas pagas no Stripe desde a data selecionada
  3. Cada fatura é criada como rascunho e é marcada como paga
  4. A numeração gap-free e o hash VeriFactu são aplicados automaticamente

Passo 4: Ativar auto-sync (opcional)​

  1. Na aba de configuração, ative Auto-sync
  2. Frihet importará novas cobranças automaticamente a cada 6 horas
  3. Apenas faturas novas são importadas (sincronização incremental)

Como funciona​

Importação manual​

  1. Você clica em Importar agora
  2. Frihet consulta GET /v1/invoices?status=paid no Stripe
  3. Para cada fatura que ainda não exista no Frihet (pelo stripeInvoiceId):
    • Cria uma fatura rascunho com os dados do cliente
    • A marca como paga
    • Os triggers do Firestore são executados: numeração e hash VeriFactu
  4. Resultado: faturas prontas para seu livro de registro e declarações

Auto-sync (a cada 6 horas)​

  1. A cada 6 horas, uma função programada é executada
  2. Consulta apenas faturas desde lastSync (incremental)
  3. Importa as novas automaticamente
  4. Atualiza lastSync com a data atual
  5. Se detectar que sua Chave de API expirou, marca a integração como requiresReconnect

Deduplicação​

Cada fatura importada guarda o ID de fatura do Stripe (stripeInvoiceId) em seus metadados. Se você tentar importar a mesma fatura duas vezes, Frihet a ignora automaticamente.

Mapeamento de dados​

StripeFrihet
invoice.customer_name ou customer_emailNome do cliente
invoice.numberReferência (no conceito)
line_items[].descriptionLinhas da fatura
line_items[].amountValor por linha
invoice.taxImpostos (se aplicável)
invoice.createdData da fatura
invoice.idstripeInvoiceId (metadado)

Segurança​

  • Chave de API restrita — Somente leitura de invoices e customers. Sem acesso a dinheiro.
  • Criptografia AES-256-GCM — Sua Chave de API é armazenada criptografada no servidor
  • Desconexão instantânea — Revogue o acesso em Configurações quando quiser
  • Sem dados em trânsito — A comunicação com Stripe é HTTPS, a chave nunca é exposta ao frontend

Desconectar​

  1. Vá para Configurações → Integrações
  2. Procure por Stripe Revenue Sync
  3. Clique em Desconectar
  4. Confirme a ação

As faturas já importadas permanecem no Frihet. Não são excluídas ao desconectar.

Troubleshooting​

"Nenhuma fatura foi importada"​

  • Verifique se sua Chave de API tem permissões de leitura em Invoices e Customers
  • Certifique-se de que a data de importação é anterior às suas cobranças
  • Apenas faturas com status paid no Stripe são importadas
  • Verifique se você não está no modo de teste do Stripe (use chaves live)

"Reconecte sua conta"​

  • Sua Chave de API expirou ou foi revogada
  • Vá para Stripe Dashboard → API Keys e crie uma nova
  • Desconecte e reconecte no Frihet com a nova chave

"Fatura duplicada"​

  • Não deveria acontecer. A deduplicação por stripeInvoiceId isso o previne
  • Se você vir duplicados, contate o suporte

"Os valores não coincidem"​

  • Frihet importa o valor como reportado pelo Stripe
  • As comissões do Stripe não são deduzidas da fatura (são uma despesa separada)
  • Verifique a moeda: Stripe reporta em centavos, Frihet converte automaticamente

Próximos passos​

Próximo: Stripe Connect - Links de pagamento em suas faturas