Sincronização de Dados Stripe
A Sincronização de Dados Stripe permite importar cobranças do Stripe e clientes para o Levy Fleets. Isso é útil para reconciliação, migração de dados e preenchimento de lacunas no histórico de pagamentos.
Visão Geral
Por que Sincronizar Dados do Stripe
| Caso de Uso | Descrição |
|---|---|
| Reconciliação | Combinar registros do Stripe com dados internos |
| Migração | Importar histórico de pagamentos para novo sistema |
| Auditoria | Garantir que todos os pagamentos estejam contabilizados |
| Relatórios | Preencher lacunas em relatórios financeiros |
O que Pode Ser Importado
- Cobranças Stripe - Registros de pagamento individuais
- Clientes Stripe - IDs e e-mails de clientes
Acessando Importação Stripe
Navegue até Admin > Ferramentas de Banco de Dados > Importação Stripe.
Requisitos:
- Acesso de Super Admin ou Global Admin
- Arquivo CSV de exportação do Stripe
Preparação da Exportação Stripe
Exportando Cobranças do Stripe
Faça Login no Dashboard Stripe
Acesse o dashboard do Stripe em dashboard.stripe.com
Navegue até Pagamentos
Vá para Pagamentos > Todos os pagamentos
Defina o Intervalo de Datas
Selecione o intervalo de datas que deseja exportar
Exporte CSV
Clique em Exportar e selecione formato CSV
Baixe o Arquivo
Salve o arquivo exportado no seu computador
Colunas Esperadas no CSV
O formato de exportação do Stripe inclui estas colunas:
| Coluna | Descrição |
|---|---|
id | Identificador único da cobrança Stripe |
Amount | Valor da cobrança em centavos |
Amount Refunded | Valor reembolsado em centavos |
Currency | Código da moeda (ex: "usd") |
Converted Amount | Valor convertido (se aplicável) |
Converted Amount Refunded | Reembolso convertido |
Fee | Taxa de processamento Stripe |
Tax | Imposto cobrado (se aplicável) |
Converted Currency | Moeda do valor convertido |
Mode | "live" ou "test" |
Status | Status da cobrança (succeeded, failed, etc.) |
Statement Descriptor | Descrição no extrato |
Customer ID | ID do cliente Stripe |
Customer Email | E-mail do cliente |
Created date (UTC) | Data de criação |
Captured date (UTC) | Data de captura |
Card ID | ID do cartão usado |
Card Last Four | Últimos 4 dígitos do cartão |
Card Brand | Bandeira do cartão (Visa, Mastercard, etc.) |
Card Funding | Tipo de financiamento (credit, debit) |
Card Exp Month | Mês de expiração |
Card Exp Year | Ano de expiração |
Card Name | Nome no cartão |
Card Address Line1 | Endereço linha 1 |
Card Address Line2 | Endereço linha 2 |
Card Address City | Cidade |
Card Address State | Estado |
Card Address Country | País |
Card Address Zip | CEP |
Card Issue Country | País de emissão |
Card Fingerprint | Fingerprint do cartão |
Card CVC Status | Status de verificação CVC |
Card AVS Zip Status | Status AVS do CEP |
Card AVS Line1 Status | Status AVS da linha 1 |
Card Tokenization Method | Método de tokenização |
Disputed Amount | Valor disputado |
Description | Descrição da cobrança |
Transfer | ID de transferência (se aplicável) |
Metadata | Metadados personalizados |
Processo de Importação
Fazendo Upload do Arquivo
Selecione Tipo de Importação
Escolha Importação Stripe no menu de Ferramentas de Banco de Dados
Faça Upload do Arquivo CSV
Arraste e solte ou clique para selecionar seu arquivo de exportação CSV do Stripe
Inicie a Importação
Clique em Importar para iniciar o processamento
Monitore o Progresso
Acompanhe a barra de progresso para arquivos grandes
Resultados da Importação
O sistema exibe resultados em tempo real:
| Métrica | Descrição |
|---|---|
| Processados | Total de linhas lidas do CSV |
| Importados | Novas cobranças criadas |
| Atualizados | Cobranças existentes atualizadas |
| Ignorados | Linhas ignoradas (duplicatas) |
| Erros | Linhas que falharam |
Processamento em Segundo Plano
Para arquivos grandes (4+ MB):
- A importação é processada em segundo plano
- O status do job é mostrado na página
- O progresso atualiza a cada 2 segundos
- Você pode navegar para outras páginas e voltar
Vinculação de Dados
Vinculação Automática de Clientes
Durante a importação, o sistema tenta vincular cobranças a clientes existentes:
- Correspondência por Stripe Customer ID: Se o cliente tem
stripe_customer_idcorrespondente - Correspondência por E-mail: Se o e-mail da cobrança corresponde ao e-mail do cliente
- Sem Correspondência: Cobrança permanece vinculada apenas ao registro de cobrança
Vinculação a Corridas
Cobranças podem ser vinculadas a corridas através de:
- Metadados da cobrança contendo ID da corrida
- Correspondência de data/hora com corridas do mesmo cliente
Vinculação Manual
A vinculação automática funciona melhor quando os metadados do Stripe incluem IDs de corrida. Se sua integração não inclui esses dados, a vinculação manual pode ser necessária para relatórios precisos.
Dados Importados
Tabela stripe_charges
As cobranças importadas são armazenadas na tabela stripe_charges:
stripe_charges (
id UUID PRIMARY KEY,
charge_id TEXT UNIQUE,
amount INTEGER,
amount_refunded INTEGER,
currency TEXT,
fee INTEGER,
status TEXT,
customer_id TEXT,
customer_email TEXT,
created_at TIMESTAMP,
metadata JSONB
)
Uso dos Dados
Após a importação, os dados estão disponíveis para:
- Relatórios financeiros
- Reconciliação de pagamentos
- Análise de clientes
- Auditoria de reembolsos
Melhores Práticas
Antes da Importação
- Exporte intervalos incrementais: Evite re-importar dados antigos
- Verifique o formato do arquivo: Confirme que é CSV do Stripe padrão
- Anote cobranças existentes: Registre contagem atual para verificação
Durante a Importação
- Monitore o progresso: Acompanhe erros em tempo real
- Não cancele: Deixe a importação completar para evitar dados parciais
Após a Importação
- Verifique contagens: Compare totais importados com exportação do Stripe
- Reconcilie valores: Some valores e compare com dashboard do Stripe
- Teste relatórios: Verifique se novos dados aparecem em relatórios
Solução de Problemas
Arquivo Não É Reconhecido
Possíveis Causas:
- Formato de arquivo incorreto
- Arquivo corrompido
- Codificação errada
Soluções:
- Confirme que é exportação CSV do Stripe
- Reexporte o arquivo do Stripe
- Verifique codificação UTF-8
Muitos Erros de Importação
Possíveis Causas:
- Dados inválidos no arquivo
- Conflitos de ID de cobrança
- Problemas de formato de data
Soluções:
- Revise os primeiros 10 erros mostrados
- Verifique se cobranças já existem
- Valide formatos de data
Vinculação de Cliente Não Funciona
Possíveis Causas:
- Cliente não existe no sistema
- Stripe Customer ID diferente
- E-mails não correspondem
Soluções:
- Importe clientes primeiro
- Atualize Stripe Customer IDs nos clientes
- Normalize e-mails antes da importação
Valores Não Correspondem
Possíveis Causas:
- Valores em centavos vs. reais
- Moeda diferente
- Reembolsos não contabilizados
Soluções:
- Lembre que Stripe usa centavos
- Verifique a moeda de cada cobrança
- Considere
amount - amount_refundedpara valor líquido
Considerações de Segurança
Dados Sensíveis
Os CSVs do Stripe contêm dados sensíveis:
- E-mails de clientes
- Últimos 4 dígitos de cartões
- Informações de endereço
Recomendações
- Delete arquivos após importação: Não mantenha CSVs localmente
- Limite acesso: Apenas admins devem fazer importações
- Audite importações: Registre quem importou e quando
- Use conexão segura: Sempre HTTPS para uploads
Conformidade PCI
Embora os CSVs do Stripe não contenham números completos de cartão, eles contêm dados de clientes. Trate esses arquivos com cuidado e siga as políticas de segurança de dados da sua organização.
Próximos Passos
- Ferramentas de Importação de Dados - Importe outros tipos de dados
- Recursos de Super Admin - Explore todas as ferramentas de admin
- Processamento de Pagamentos - Configure integração de pagamentos
Sincronização Concluída
Com seus dados do Stripe importados, você agora tem uma visão completa do histórico de pagamentos dentro do Levy Fleets. Use esses dados para reconciliação, relatórios e análise de receita.